Skip to content

docs(extensions): add ECS migration notes for widgets, serialization, connection callbacks, and node geometry - #15857

Merged
DrJKL merged 7 commits into
mainfrom
docs/ecs-extension-migration-notes
Aug 26, 2026
Merged

DrJKL merged 7 commits into
mainfrom
docs/ecs-extension-migration-notes

Conversation

@claude

@claude claude Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Requested by Christian Byrne · Slack thread

Summary

Adds migration guidance docs for four more extension surfaces affected by the ECS refactor (#14246): widget value storage, connection callbacks, serialization callbacks, and node/group geometry.

Changes

  • What: Four new docs under docs/extensions/ — widgets-migration.md, connection-callbacks-migration.md, serialization-callbacks-migration.md, node-geometry-migration.md — plus matching entries in docs/extensions/README.md.
  • Why: The community soak-test announcement for the ECS refactor referenced only the link-registration migration notes as complete. This fills in the remaining extension-surface guidance so custom-node authors have a single place to check what changed in node.widgets, connection-timing callbacks, onSerialize/onConfigure, and node/group geometry (pos/size/boundingRect).

Review Focus

  • The widgets/connection-callbacks/serialization-callbacks/node-geometry content was drafted by investigating the current codebase and the existing ECS audit docs (docs/architecture/ecs/), then cross-checked against source line citations for accuracy. Treat it as a starting point — community reports on real custom nodes may surface behavior these notes don't cover yet, and a few claims are explicitly flagged in the docs as not independently verified against pre-refactor history (this checkout only has a shallow clone).
  • The node-geometry doc's stale-instance-safety note correctly cites refactor: centralize layout ownership and command submission #15017 (the merged ownership check) rather than fix(layout): enforce per-instance geometry ownership #14480 (an earlier, unmerged attempt).

Generated by Claude Code

… connection callbacks, and node geometry

Adds four migration-note docs covering extension-surface changes from the
ECS refactor (#14246): widget value storage, onConnectionsChange/onConnectInput/
onConnectOutput timing and graph lifecycle events, onSerialize/onConfigure
persistence hooks, and node/group geometry (pos/size/boundingRect). Indexes
them in docs/extensions/README.md alongside the existing link-registration
migration notes.
@christian-byrne christian-byrne self-assigned this Aug 25, 2026
@github-actions github-actions Bot added risk:R1 PR risk grade (advisory shadow check; grader-owned) risk:R2 PR risk grade (advisory shadow check; grader-owned) and removed risk:R1 PR risk grade (advisory shadow check; grader-owned) labels Aug 25, 2026
Style-only pass: replaced ~50 em dashes across the four ECS extension
migration docs with periods, colons, semicolons, commas, or parentheses.
No technical claims changed.
@claude
claude Bot force-pushed the docs/ecs-extension-migration-notes branch from 039d1ca to 6f4d5ff Compare August 25, 2026 00:29
@github-actions github-actions Bot added risk:R1 PR risk grade (advisory shadow check; grader-owned) and removed risk:R2 PR risk grade (advisory shadow check; grader-owned) labels Aug 25, 2026

@DrJKL DrJKL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

High-level review

This is not ready to publish as migration guidance. It reads like a codebase audit pasted into four Markdown files: exhaustive, defensive, implementation-heavy, and almost completely unwilling to decide what extension authors actually need.

Across the four new guides there are 4,191 words, 30 second-level headings, and 121 prose sentences. The serialization guide averages roughly 34 words per sentence. The vocabulary confirms the structural problem: “still” appears 28 times, “unchanged” 13 times, “rather than” 18 times, and “compatibility” 14 times. The writing spends extraordinary effort proving what did not change while burying the handful of actions a reader must take.

The useful migration rules are much smaller:

  • widget names must be unique and stable;
  • initialize or guard node.widgets where it may be undefined;
  • use the public widget APIs rather than widgetValueStore;
  • use graph.events for multiple lifecycle subscribers;
  • account for callback ordering where it is a supported contract;
  • initialize Pinia before configuring a root graph;
  • store extension data in node.properties or graph.extra;
  • call node.serialize() instead of enumerating node properties;
  • replace repositionNodesVueMode() with applyNodePositions();
  • use rendered bounds instead of size when measured dimensions matter;
  • expect writes through removed geometry instances to be ignored.

Those rules need before/after examples and a small amount of supporting explanation. They do not need private store tours, raw source line ranges, copied internal implementation, unmerged-PR history, speculative future adapters, repeated “unchanged” sections, or disclaimers about research that was not completed.

The largest credibility problem is the repeated “not independently verified” language. A shallow checkout is a solvable tooling condition. Fetch the history and verify the before/after claims before publishing them. Do not transfer the author's uncertainty to extension developers and then tell them to file reproductions.

Please rewrite these as migration guides rather than patching individual sentences. Lead with required actions, keep only observable supported behavior, show extension-facing examples, and cut at least half of the current prose. The inline comments identify each recurring violation and cite the requested editing guidelines:

Comment thread docs/extensions/README.md Resolved
Comment thread docs/extensions/widgets-migration.md Resolved
Comment thread docs/extensions/widgets-migration.md Resolved
Comment thread docs/extensions/widgets-migration.md Resolved
Comment thread docs/extensions/widgets-migration.md Resolved
Comment thread docs/extensions/widgets-migration.md Resolved
@claude
claude Bot requested a review from DrJKL August 25, 2026 02:15

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Three migration claims are inaccurate.

Full context for agent readers

Detached geometry writes mutate the detached object even though live/store state is protected; the five-step removal sequence exceeds the test-backed contract; and slotLinks.ts helpers are not exported from the supported extension surface. Exact-head R1 review.

If you hold a node, group, or reroute reference after it's removed from the
graph (a detached clone, or a reference captured before an async callback
resolves), calling `setPos()` or `setSize()` on it is a no-op. It does not
throw, and it does not affect whatever entity now owns that ID.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: removed-reference geometry writes are not literal no-ops.

Full context for agent readers

setPos() and setSize() update the detached node object’s local _pos / _size before the missing-graph guard prevents store propagation. The safety guarantee is that live/shared state is unchanged, not that the detached object is unchanged. Please document that narrower contract.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 96882c7: the section now documents the narrower contract — setPos()/setSize() write the detached object's local _pos/_size fields before the missing-graph guard blocks store propagation, so only live/shared layout state is protected, not the detached instance itself.

4. The node detaches from graph indexes and stores; `node.graph` becomes
`null`.
5. `onNodeRemoved(node)`, then `node:removed`, both seeing an already-detached
node.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: source currently follows this sequence, but tests do not establish the entire five-step order.

Full context for agent readers

The lifecycle test covers before-removed → onRemoved → onNodeRemoved; a separate test checks detached state at node:removed. Neither jointly orders disconnect callbacks and node:removed with every listed step. Please narrow “fixed, tested order” to what is guaranteed, or add one discriminating sequence test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 96882c7: narrowed the claim to what the two tests actually establish (the before-removed → onRemoved → onNodeRemoved order, and node:removed firing post-detachment separately), and flagged onConnectionsChange's position and the full five-step order as observed-from-source rather than test-guaranteed.

`input.link` and `output.links` are deprecated: writes through them no
longer drive topology, and reads can drift from the current graph. Use the
`link_info` argument your callback already receives, or the public helpers
exported from `slotLinks.ts` (`inputHasLink`, `outputHasLinks`,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: these helpers are exported only from the internal slotLinks.ts module.

Full context for agent readers

The supported litegraph.ts extension surface does not re-export them, so calling them public directs extension authors to an internal source path. Please either export them through the supported surface or document only APIs that extensions can import.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 96882c7: the guide now points to the LGraphNode instance methods (isInputConnected(), getInputLink(), isOutputConnected(), getOutputNodes()) as the supported surface, and notes slotLinks.ts is internal/not re-exported from litegraph.ts rather than presenting its helpers as public API.

@claude

claude Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor Author

@christian-byrne All three inaccuracies from your review are fixed in 96882c7: detached geometry writes now documented as landing locally (only the shared layout store write is guarded), the node-removal callback order narrowed to what the two lifecycle tests actually establish, and the connection-state guidance repointed to the public LGraphNode methods with slotLinks.ts called out as internal/not re-exported. Verified each against source (LGraphNode.ts pos/size setters and _positionUpdated/_sizeUpdated guards, the lifecycle tests, and litegraph.ts's exports) before pushing. Replied on each of the three inline threads individually as well.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Three contract errors:

  • Callback receiver/payload conflated.
  • Widget sample fails its types.
  • Group/reroute APIs overstated.
Full context for agent readers

Exact head 96882c759ad9ff3ac15b59df363d3249cfcd28a8 was checked against the current LiteGraph callback, widget, group, and reroute contracts. The prior removed-node wording, callback-order evidence, and public-API blockers are addressed; the three current-head findings below remain.

per-graph extension data. These remain the stable, intended extension
surfaces for persisted data.

`onSerialize` and `onConfigure` still receive the live node/graph object, so

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: separate callback receiver and payload.

Full context for agent readers

The live node/graph is the callback receiver (this); the callback argument is serialized data. LGraphNode declares onConfigure(this: LGraphNode, serialisedNode) and onSerialize(this: LGraphNode, serialised), then calls onSerialize(o). LGraph likewise calls both hooks with serialized graph data. As written, “receive the live node/graph object” can send extension authors to mutate the wrong object. Please state the receiver and payload contracts explicitly.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in eedb879: the section now states this is the live node/graph receiver while the callback argument is the serialized payload, and scopes the "don't overwrite core fields" guidance to writes via this.

Comment thread docs/extensions/widgets-migration.md Outdated
}

node.addCustomWidget(
new MyWidget({ name: 'my_widget', type: 'custom', value: '' }, node)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: this example does not type-check.

Full context for agent readers

BaseWidget<TWidget> requires TWidget extends IBaseWidget, and its constructor accepts that complete widget shape. IBaseWidget requires both options and y; this object supplies neither. Define MyWidgetState against the supported interface and include the required fields (plus the abstract implementations), or show a supported factory call that constructs them.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in eedb879: the example now defines MyWidgetState against IBaseWidget, implements the abstract drawWidget/onClick methods, and constructs the widget with options/y included so it type-checks.


If you hold a node, group, or reroute reference after it's removed from the
graph (a detached clone, or a reference captured before an async callback
resolves), calling `setPos()` or `setSize()` on it still updates that

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: these methods are node-only.

Full context for agent readers

Only LGraphNode exposes setPos() and setSize(). LGraphGroup exposes pos/size setters, while Reroute exposes only pos; neither has the two methods named here. Scope this detached-write contract to nodes, or document each entity through the API it actually supports.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in eedb879: the section now scopes setPos()/setSize() to LGraphNode and documents that LGraphGroup has pos/size setters only while Reroute has only a pos setter, no size.

@claude

claude Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor Author

@christian-byrne All three contract errors from this review (callback receiver/payload conflation, the non-type-checking widget example, and the overstated group/reroute geometry API) are verified and fixed in eedb879. Replied inline on each of the three threads with specifics.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prior blockers fixed. Exact-head docs accurate.

Full context for agent readers

R1 changed-head re-review at eedb87930510424a17a630d39dc4642986a2514c. The callback receiver/payload, BaseWidget example, and group/reroute geometry blockers from the prior review are fixed. Current source confirms the callback, widget-constructor, abstract-method, geometry API, and detached local-vs-store behavior now documented. The prior reviewed head is an ancestor, git diff --check passed, and rerere-disabled synthetic integration with current main was clean. One CI check remained in progress with no failures; this approval does not assert CI completion. Existing human threads remain unresolved and reviewer-owned.

@christian-byrne
christian-byrne marked this pull request as ready for review August 25, 2026 18:51
@christian-byrne
christian-byrne requested a review from a team August 25, 2026 18:51
@dosubot dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Aug 25, 2026

@DrJKL DrJKL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed current head f6dd582b against all 78 review threads opened before child PR #15926. The 72 migration-guide structure and prose comments and all six accuracy follow-ups are addressed. Required checks pass. The remaining edits in #15926 are non-blocking wording improvements.

@DrJKL DrJKL removed their assignment Aug 25, 2026
@christian-byrne
christian-byrne added this pull request to the merge queue Aug 26, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Aug 26, 2026
@DrJKL
DrJKL added this pull request to the merge queue Aug 26, 2026
Merged via the queue into main with commit 23d9990 Aug 26, 2026
121 checks passed
@DrJKL
DrJKL deleted the docs/ecs-extension-migration-notes branch August 26, 2026 01:25
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Aug 26, 2026
## Summary

Tightens three passages in the ECS extension migration guides so readers
can reach the required action faster.

## Changes

- **What**: Condenses the callback test-coverage note and
detached-geometry behavior, and clarifies that extensions use ComfyUI's
active Pinia instance rather than creating their own.

## Review Focus

This is a child of Comfy-Org#15857. Please verify that the shorter callback and
geometry wording preserves the documented contracts and that the Pinia
guidance keeps extensions on the host application's instance.

---------

Co-authored-by: Amp <amp@ampcode.com>
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 1, 2026
Adds five tests for detached geometry, lifecycle ordering, hook
identity, and API boundaries.
Three assigned widget contracts were already covered, so this avoids
duplicate tests.

<details><summary>Full context for agent readers</summary>

## Covered checklist items

This tests-only pull request covers five checklist items from [the ECS
follow-on coverage
tracker](Comfy-Org#15973):

- [Detached node position and size writes remain
local](Comfy-Org#15857 (comment)).
- [Node removal preserves the complete callback
order](Comfy-Org#15857 (comment)).
- [Serialize and configure hooks receive live-instance receivers and
plain data
arguments](Comfy-Org#15857 (comment)).
- [Detached geometry APIs differ intentionally by entity
type](Comfy-Org#15857 (comment)).
- [Internal slot-link helpers remain outside the public LiteGraph
API](Comfy-Org#15857 (comment)).

## Already covered

Verification against current `main`, Comfy-Org#16381, and corrective pull request
Comfy-Org#16441 found existing coverage for widget registration return values,
widget ID percent encoding, and null widget-value slots. The [claim
comment](Comfy-Org#15973 (comment))
records the exact evidence.

## Validation

- Targeted Vitest: 137 tests passed across five touched files.
- Formatting: passed.
- ESLint: passed with pre-existing restricted-path warnings only.
- Typecheck and type-aware lint: passed in the commit hook.

<!-- authored-by:agent -->
</details>
@huang47 huang47 added the risk:medium PR risk grade (advisory shadow check; grader-owned) label Sep 2, 2026 — with ChatGPT Codex Connector
@huang47 huang47 removed the risk:R1 PR risk grade (advisory shadow check; grader-owned) label Sep 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:medium PR risk grade (advisory shadow check; grader-owned) size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants