Repository navigation
docs(extensions): add ECS migration notes for widgets, serialization, connection callbacks, and node geometry - #15857
Conversation
… 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.
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.
039d1ca to
6f4d5ff
Compare
DrJKL
left a comment
There was a problem hiding this comment.
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.widgetswhere it may be undefined; - use the public widget APIs rather than
widgetValueStore; - use
graph.eventsfor 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.propertiesorgraph.extra; - call
node.serialize()instead of enumerating node properties; - replace
repositionNodesVueMode()withapplyNodePositions(); - use rendered bounds instead of
sizewhen 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:
christian-byrne
left a comment
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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`, |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
…tes, internal API, test coverage claim)
|
@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 |
christian-byrne
left a comment
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| } | ||
|
|
||
| node.addCustomWidget( | ||
| new MyWidget({ name: 'my_widget', type: 'custom', value: '' }, node) |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
…etry API scope per review
|
@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
left a comment
There was a problem hiding this comment.
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.
## 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>
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>
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
docs/extensions/—widgets-migration.md,connection-callbacks-migration.md,serialization-callbacks-migration.md,node-geometry-migration.md— plus matching entries indocs/extensions/README.md.node.widgets, connection-timing callbacks,onSerialize/onConfigure, and node/group geometry (pos/size/boundingRect).Review Focus
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).Generated by Claude Code