From 9cb07df0a195f2076853cda288616e2c95f3fc00 Mon Sep 17 00:00:00 2001 From: Alexander Brown Date: Mon, 2 Nov 2026 20:36:45 +0000 Subject: [PATCH 1/3] docs(custom-nodes): publish frontend extension migration guides and canvas pointer API Amp-Thread-ID: https://ampcode.com/threads/T-01a19df1-12f1-7428-a314-3b9547d383b9 --- custom-nodes/js/canvas-pointer-api.mdx | 88 +++++++++++ .../js/connection-callbacks-migration.mdx | 145 ++++++++++++++++++ .../js/link-registration-migration.mdx | 52 +++++++ custom-nodes/js/node-geometry-migration.mdx | 76 +++++++++ custom-nodes/js/node-id-migration.mdx | 19 +++ .../js/primevue-removal-migration.mdx | 70 +++++++++ .../js/serialization-callbacks-migration.mdx | 69 +++++++++ custom-nodes/js/widgets-migration.mdx | 134 ++++++++++++++++ docs.json | 8 + 9 files changed, 661 insertions(+) create mode 100644 custom-nodes/js/canvas-pointer-api.mdx create mode 100644 custom-nodes/js/connection-callbacks-migration.mdx create mode 100644 custom-nodes/js/link-registration-migration.mdx create mode 100644 custom-nodes/js/node-geometry-migration.mdx create mode 100644 custom-nodes/js/node-id-migration.mdx create mode 100644 custom-nodes/js/primevue-removal-migration.mdx create mode 100644 custom-nodes/js/serialization-callbacks-migration.mdx create mode 100644 custom-nodes/js/widgets-migration.mdx diff --git a/custom-nodes/js/canvas-pointer-api.mdx b/custom-nodes/js/canvas-pointer-api.mdx new file mode 100644 index 0000000000..c22df41b25 --- /dev/null +++ b/custom-nodes/js/canvas-pointer-api.mdx @@ -0,0 +1,88 @@ +--- +title: "Canvas Pointer API for Widgets and Cursors" +sidebarTitle: "Canvas pointer API" +description: "Handle clicks, double-clicks and drags on custom canvas widgets with onPointerDown, and control canvas cursors from a ComfyUI frontend extension." +--- + +The canvas routes pointer input through a `CanvasPointer`. It decides whether a +press becomes a click, a double-click or a drag, and runs the callbacks you +assign for that press. Widgets drawn on the canvas use it through +`onPointerDown`. + +## Default behavior + +- Dragging several selected items no longer requires holding Shift. Clicking + one item while several are selected still deselects the others. +- Clicking a connected link on an input no longer disconnects and reconnects + it. +- A small amount of movement between pointer down and pointer up still counts + as a click. Once the pointer travels past the click drift limit, the press + becomes a drag. Time does not affect the decision. +- A double-click needs two presses within the double-click time, at most three + times the click drift apart. Only a press that assigns `onDoubleClick` can + complete a double-click. + +Users set the click drift and double-click time in the settings +(`Comfy.Pointer.ClickDrift` and `Comfy.Pointer.DoubleClickTime`). + +### Selecting multiple items + +- `Ctrl` + drag: begin a multi-select +- `Ctrl` + `Shift` + drag: add to the selection +- `Ctrl` + drag, then `Shift`: add to the selection +- `Ctrl` + drag, then `Alt`: remove from the selection + +## Handle pointer input on a widget + +Assign `onPointerDown` on a widget. It runs on pointer down and receives the +pointer, the node and the canvas. Assign the callbacks you need on the pointer; +the canvas runs the right ones when the press resolves: + +```js +widget.onPointerDown = function (pointer, node, canvas) { + const e = pointer.eDown + const offsetFromNode = [e.canvasX - node.pos[0], e.canvasY - node.pos[1]] + + pointer.onClick = (upEvent) => { + console.log(pointer.eDown, pointer.eMove, pointer.eUp) + } + pointer.onDoubleClick = (upEvent) => this.customFunction(upEvent) + + pointer.onDragStart = () => {} + pointer.onDrag = (moveEvent) => {} + pointer.onDragEnd = (upEvent) => {} + pointer.onDragCancel = () => {} + + pointer.finally = () => {} + + return true +} +``` + +- Click and drag callbacks never both run for one press. +- `onDragStart` runs once, when the pointer first moves past the click drift + limit. `onDrag` receives every movement, including movement inside that + limit, so it can run before `onDragStart`. +- `onDragEnd` receives the pointer up event of a drag. `onDragCancel` runs + instead when the drag is interrupted, for example when pointer capture is + lost. +- `finally` always runs once the press ends, like a `finally` block. Prefer it + for cleanup. +- `pointer.eDown`, `pointer.eMove` and `pointer.eUp` give every callback access + to the whole sequence of events. +- Return `true` to stop the canvas from handling the press itself. + +The canvas resolves double-clicks and drags for you, so a widget no longer needs +to time or measure separate pointer events. It also honors the user's click +drift and double-click settings. + +## Control the canvas cursor + +`canvas.state.hoveringOver` holds bit flags for the item types under the +pointer, such as a node, group, reroute or link. Set +`canvas.state.shouldSetCursor` to `false` to stop the canvas from setting the +cursor style, then set it yourself: + +```js +canvas.state.shouldSetCursor = false +``` diff --git a/custom-nodes/js/connection-callbacks-migration.mdx b/custom-nodes/js/connection-callbacks-migration.mdx new file mode 100644 index 0000000000..6c80c83520 --- /dev/null +++ b/custom-nodes/js/connection-callbacks-migration.mdx @@ -0,0 +1,145 @@ +--- +title: "Connection Callback Migration for Frontend Extensions" +sidebarTitle: "Connection callbacks migration" +description: "Ordering of onConnectionsChange and node removal callbacks, SubgraphIO at subgraph boundaries, and graph.events in ComfyUI extensions." +--- + +Callback signatures did not change. `onConnectionsChange`, `onConnectInput`, +`onConnectOutput`, and `onBeforeConnectInput` keep their existing arguments +and timing. For link registration and `LinkNetwork` API changes, see +[Link registration migration](/custom-nodes/js/link-registration-migration). + +## Check for SubgraphIO at subgraph boundaries + +At a subgraph boundary (a `SubgraphInput` or `SubgraphOutput`), +`onConnectionsChange` still fires, but its fifth argument is a `SubgraphIO`, +not the usual `INodeInputSlot`/`INodeOutputSlot`. Check for it before +treating the argument as a normal slot. The frontend's own `isSubgraphInput` +and `isSubgraphOutput` guards are not exposed to extensions, so check for the +`linkIds` array and `parent` node that every `SubgraphIO` has and node slots +do not: + +```js +function isSubgraphIO(slot) { + return slot != null && Array.isArray(slot.linkIds) && 'parent' in slot +} + +nodeType.prototype.onConnectionsChange = function ( + type, + index, + isConnected, + link, + slotOrIO +) { + if (isSubgraphIO(slotOrIO)) return + // slotOrIO is INodeInputSlot | INodeOutputSlot +} +``` + +## Subscribe to node lifecycle events with graph.events + +`graph.events` dispatches `node:added`, `node:before-removed`, and +`node:removed`. Use these when more than one part of your extension needs to +observe a node being added or removed: + +```ts +graph.events.addEventListener('node:added', (e) => { + console.log('added', e.detail.node.id) +}) +``` + +`node.onAdded`, `node.onRemoved`, and the single-slot +`graph.onNodeAdded`/`graph.onNodeRemoved` still work, but assigning +`graph.onNodeAdded` replaces any existing handler: a second subscriber +silently drops the first. Prefer `graph.events` unless you need to veto or +mutate during add/remove. There's no multi-subscriber equivalent for +connect/disconnect; `onConnectionsChange` is still the only per-connection +hook. + +## Node removal fires callbacks in this order (partially tested) + +Removing a node fires, in order: + +1. `node:before-removed`: the node is still fully attached. +2. `onConnectionsChange(..., false, ...)` on the removed node and on each + connected peer, while the removed node is still in the graph. +3. `node.onRemoved()`: `node.graph` is still set. +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. + +Tests cover `node:before-removed → node.onRemoved() → onNodeRemoved(node)` and +separately verify that `node:removed` sees a detached node. The complete +sequence, including step 2, is observed from source rather than guaranteed by +one end-to-end test. + +To resolve the removed node from a peer's `onConnectionsChange` handler, do it +at step 2 via `graph.getNodeById()`. By `node:removed`, the node is gone. + +## Workflow load resolves peer nodes before onConnectionsChange runs + +`graph.configure()` creates every node in the workflow before any node's own +`configure()` runs and fires `onConnectionsChange` for its restored links. +So when your `onConnectionsChange` callback fires during load, every peer +node already exists and its link is already registered, so `graph.getNodeById()` +and link lookups from inside that callback resolve correctly. + +## API prompt import does not reconnect resolved inputs + +`app.loadApiJson()` connects each resolvable input without running a second +disconnect/reconnect pass. Extensions should not rely on duplicate +`onConnectionsChange` notifications during API prompt import. Make each +connection handler perform its work on the first notification; move work that +requires the complete imported graph to `afterConfigureGraph` or `afterLoadGraph`. + +Inputs whose source output or destination slot does not exist yet are retried +while a pass makes progress. This preserves dynamic-input behavior: a successful +connection can create the slot needed by a later pending connection. Already +resolved connections are not repeated, and a connection rejected by an +extension is not retried once its endpoints are available. + +This changes API prompt import only. Regular workflow loading still uses +`graph.configure()` as described above, and connection callback signatures are +unchanged. + +## Disconnecting inside the output callback skips the input callback + +Connecting a link calls the output side's `onConnectionsChange` first, then +the input side's. If the output-side handler disconnects that same link (or +otherwise invalidates it) before returning, the input-side call is skipped: + +```js +nodeType.prototype.onConnectionsChange = function (type, index, isConnected, link) { + if (type === LiteGraph.OUTPUT && shouldReject(link)) { + this.disconnectOutput(index) + } +} +``` + +Don't assume both sides always fire for one `connect()` call; check that the +link you were handed is still connected if your handler re-enters the graph. +This is observed behavior, not a tested contract: no test currently +exercises the skip path. + +## Replace removed slot events + +`node:slot-links:changed` and `node:slot-errors:changed` were removed, with +no replacement event of the same name. Migrate to: + +- `node.isInputConnected()`, `node.isOutputConnected()`, or + `node.getOutputNodes()` for a reactive read of connectivity state, or +- `onConnectionsChange` when you need to run code at the exact moment a slot + connects or disconnects. + +## Read connection state from callback arguments or node methods + +`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 `LGraphNode` +instance methods that read the link store directly: +`node.isInputConnected()`, `node.getInputLink()`, `node.isOutputConnected()` +and `node.getOutputNodes()`. Don't read `input.link` or `output.links`. + +The store functions behind these methods are internal and not part of the +extension API. Use the node methods. diff --git a/custom-nodes/js/link-registration-migration.mdx b/custom-nodes/js/link-registration-migration.mdx new file mode 100644 index 0000000000..7cce7aafe3 --- /dev/null +++ b/custom-nodes/js/link-registration-migration.mdx @@ -0,0 +1,52 @@ +--- +title: "Link Registration Migration for Frontend Extensions" +sidebarTitle: "Link registration migration" +description: "Handle addFloatingLink returning undefined, store-backed graph.links views, and link ID collisions in ComfyUI frontend extensions." +--- + +`LinkNetwork.addFloatingLink(link)` now returns `LLink | undefined`. + +For a new runtime link, pass the unassigned link id and use the returned link: + +```ts +const registeredLink = graph.addFloatingLink(link) +if (!registeredLink) return +``` + +Registration returns the stored link when it succeeds or when the same link is +already present in the topology store. If another runtime link already owns the +id, registration logs an error, leaves the incoming link detached, and returns +`undefined`. It does not silently replace the live link or assign the incoming +link another identity. `graph.floatingLinks` remains the filtered compatibility +view for one-ended links. + +`graph.links` and `graph.floatingLinks` are owner-filtered, store-backed +compatibility views rather than independent native `Map` storage. Their normal +`Map` read methods use a cached membership snapshot; acquire a new iterator +after topology membership changes instead of retaining an existing iterator. +Both views require an active Pinia and no longer represent a missing store as +an empty graph. + +Like native `Map.set()`, `view.set(id, link)` returns the view, not a registration +result. Registration can reject an ID or target collision while preserving the +incumbent, so extensions that insert through a view should confirm success with +`get()` or `has()`. Prefer graph connection and floating-link APIs when they +cover the operation because those APIs coordinate the surrounding lifecycle. +Do not invoke `Map.prototype` methods directly against either view or depend on +native `Map` internal storage. + +Input replacement commits the new link before old-link disconnect callbacks, +so callback queries see the replacement rather than an empty input. Normal +connection callbacks follow. + +Extensions that previously ignored the return value should handle +`undefined` before retaining, rendering, or mutating the incoming link. Do not +preselect a positive link id for a new runtime link; allow the graph to mint +one. + +Persisted-id collision repair belongs to workflow import and +deserialization. Extensions importing serialized topology should normalize +conflicting ids at that boundary before using the runtime registration API. + +Constructing a root `LGraph`, or configuring one from serialized data, requires +an active Pinia because graph topology is store-backed throughout its lifecycle. diff --git a/custom-nodes/js/node-geometry-migration.mdx b/custom-nodes/js/node-geometry-migration.mdx new file mode 100644 index 0000000000..a42048a244 --- /dev/null +++ b/custom-nodes/js/node-geometry-migration.mdx @@ -0,0 +1,76 @@ +--- +title: "Node Geometry Migration for Frontend Extensions" +sidebarTitle: "Node geometry migration" +description: "Node size versus rendered bounds, the applyNodePositions rename and draw-order z-order for ComfyUI frontend extensions after the layout store change." +--- + +## Migration checklist + +1. Keep using `node.pos`, `node.size`, `boundingRect`, `getBounding()`, + `setPos()`, `setSize()`: no signature changes required. +2. Replace `repositionNodesVueMode()` calls with `applyNodePositions()`. +3. If you relied on `node.size` reflecting measured/rendered content, switch + to `getBounding()` / `boundingRect`: `size` now strictly reflects the + requested value. +4. Use the node/group geometry APIs, not the backing store; don't import + `layoutStore` or depend on its internal format. +5. Writes through a removed reference update the detached object, not shared + layout state. + +## What changed + +`LGraphNode.pos`, `size`, `boundingRect`, `getBounding()`, `setPos()`, and +`setSize()` keep the same signatures. These calls remain source-compatible. +Behavior changed in the three cases below. + +```ts +node.pos = [100, 200] +node.pos[0] += 50 +node.setSize([320, 200]) +const box = node.getBounding() +``` + +Node and group geometry now lives in a shared layout store instead of +per-instance fields. Use the APIs above, not the store directly: it's an +internal implementation detail. + +### `size` vs. rendered bounds + +`node.size` is the size you requested, and what gets serialized. +`getBounding()` and `boundingRect` return the node's rendered bounds, which +can be larger than `size` when widget content forces the node to grow. Use +rendered bounds when you need the node's actual on-screen footprint. + +```ts +// Before: a rendered-content resize could overwrite size, so collapsing a +// node and re-expanding it lost the original size. +node.size // could silently become the rendered footprint + +// After: size always stays what you set; ask for rendered bounds explicitly. +node.size // the requested size, unchanged by rendering +node.getBounding() // the actual rendered bounds, may be larger +``` + +### `repositionNodesVueMode()` renamed to `applyNodePositions()` + +```ts +// Before +canvas.repositionNodesVueMode(newPositions) +// After +canvas.applyNodePositions(newPositions) +``` + +`repositionNodesVueMode()` remains callable as a deprecated alias. + +### Z-order is now unambiguous + +Z-order used to come from two sources that could disagree: a node's position +in the node list, and its execution order. It's now always draw order. If +your extension inferred stacking or hit-test order from execution order, +switch to draw order. + +## Writes through removed references stay local + +After removal, geometry setters update only the detached node, group, or +reroute object. They do not update shared layout state or another entity that +now owns the same ID. diff --git a/custom-nodes/js/node-id-migration.mdx b/custom-nodes/js/node-id-migration.mdx new file mode 100644 index 0000000000..7daf90c274 --- /dev/null +++ b/custom-nodes/js/node-id-migration.mdx @@ -0,0 +1,19 @@ +--- +title: "Node ID Migration for Frontend Extensions" +sidebarTitle: "Node ID migration" +description: "Migrate ComfyUI frontend extensions to branded string node IDs and the string subgraph boundary sentinels SUBGRAPH_INPUT_ID and SUBGRAPH_OUTPUT_ID." +--- + +ComfyUI frontend now normalizes local node IDs to the branded `NodeId` string +type at internal boundaries. Serialized workflows and API payloads may still +contain numeric IDs, but litegraph node and link fields should be treated as +strings after they enter the frontend. + +Extension authors should avoid numeric comparisons against node IDs. In +particular, subgraph boundary sentinels are exposed as branded string IDs: + +- `SUBGRAPH_INPUT_ID` serializes from `-10` +- `SUBGRAPH_OUTPUT_ID` serializes from `-20` + +Compare against the strings `'-10'` and `'-20'`, or normalize both sides to +strings before comparing legacy values. diff --git a/custom-nodes/js/primevue-removal-migration.mdx b/custom-nodes/js/primevue-removal-migration.mdx new file mode 100644 index 0000000000..d25752c269 --- /dev/null +++ b/custom-nodes/js/primevue-removal-migration.mdx @@ -0,0 +1,70 @@ +--- +title: "PrimeVue Removal Migration for Frontend Extensions" +sidebarTitle: "PrimeVue removal migration" +description: "Replace $primevue, PrimeVue components, --p-* CSS variables and PrimeVue tooltip selectors after the ComfyUI frontend removed PrimeVue." +--- + +ComfyUI frontend no longer installs PrimeVue. The host app does not call +`app.use(PrimeVue)`, so extensions lose three things they may have relied on: + +- the `$primevue` global property on the host Vue app; +- the PrimeVue theme stylesheet, so PrimeVue components that an extension + renders inside the host app render unstyled; and +- every global `--p-*` CSS variable, such as `--p-primary-color`, + `--p-surface-*`, `--p-text-color`, `--p-content-background` and + `--p-form-field-border-color`. + +## Extensions that render PrimeVue components + +Do not rely on the host app's PrimeVue instance. Either replace the PrimeVue +components with your own markup, or create your own Vue app for your UI and +install PrimeVue and its theme on that app. + +## Extensions that read `--p-*` variables + +Replace them with the design system theme variables, which follow the active +light or dark theme and the active color palette: + +| PrimeVue variable | Theme variable | +| --------------------------------------------------------- | -------------------- | +| `--p-primary-color` | `--primary` | +| `--p-text-color` | `--foreground` | +| `--p-text-muted-color` | `--muted-foreground` | +| `--p-content-background` | `--background` | +| `--p-surface-*` (panels, elevated areas) | `--secondary` | +| `--p-content-border-color`, `--p-form-field-border-color` | `--border` | + +## Tooltips + +The global `v-tooltip` directive is gone, and tooltips no longer render the PrimeVue DOM: + +- `.p-tooltip` and `.p-tooltip-text` +- the `data-pd-tooltip` attribute +- the `$_ptooltip*` element properties + +An open tooltip now renders one element with `data-slot="tooltip-content"`, +portaled to the end of `document.body`. It exists only while the tooltip is +open. Extensions that hide tooltips during their own UI should target +`[data-slot="tooltip-content"]` instead of `.p-tooltip`. + +The `--node-component-tooltip*` CSS variables are also removed from the design +system stylesheet. Use the theme variables instead: +`--background`, `--foreground` and `--border`. The older names `--base-background`, `--base-foreground` and +`--border-default` are deprecated; see [Deprecated variable names](#deprecated-variable-names). + +## Deprecated variable names + +Earlier versions of these notes pointed at older design system names. They +still resolve, but they are deprecated and will be removed in a future +release. Move to the theme variable now: + +| Deprecated name | Theme variable | +| ----------------------------- | -------------- | +| `--base-background` | `--background` | +| `--base-foreground` | `--foreground` | +| `--border-default` | `--border` | +| `--primary-background` | `--primary` | +| `--secondary-background` | `--secondary` | +| `--component-node-background` | `--node` | + +PrimeIcons are still loaded, so existing `pi pi-*` icon classes keep working, but they are being phased out. Don't add new uses. diff --git a/custom-nodes/js/serialization-callbacks-migration.mdx b/custom-nodes/js/serialization-callbacks-migration.mdx new file mode 100644 index 0000000000..1cd804c241 --- /dev/null +++ b/custom-nodes/js/serialization-callbacks-migration.mdx @@ -0,0 +1,69 @@ +--- +title: "Serialization Callback Migration for Frontend Extensions" +sidebarTitle: "Serialization callbacks migration" +description: "How onSerialize and onConfigure behave with store-backed graphs, and where ComfyUI frontend extensions should persist custom data." +--- + +Configuring a root `LGraph` from serialized data now requires an active +Pinia instance. `LGraph.configure()` clears and rebuilds the graph directly +against the ECS stores, so a test harness, worker, or standalone LiteGraph +consumer that calls `new LGraph(data)` or `graph.configure(data)` without an +active Pinia now fails outright instead of silently producing an empty +graph. This is the same requirement documented in +[Link registration migration](/custom-nodes/js/link-registration-migration). + +Extensions running in ComfyUI use the application's active Pinia instance. +Do not create or activate a separate Pinia instance from extension code. + +`node.onConfigure`, `node.onSerialize`, `graph.onConfigure`, and +`graph.onSerialize` keep their existing signatures and firing order. For +connection-timing hooks see +[Connection callbacks migration](/custom-nodes/js/connection-callbacks-migration); for +`node.widgets` and widget value storage see +[Widget system migration](/custom-nodes/js/widgets-migration). + +`onConfigure` now receives a shallow copy of the serialized data rather than +the caller's own object. Adding, removing, or reassigning top-level keys on the +callback argument does not change the caller's workflow JSON and is not +persisted. Nested objects (for example `inputs`, `pos`, `properties`) are still +shared with the caller, so mutating them in place still leaks; extensions that +relied on either kind of mutation must store custom state on `node.properties` +or `graph.extra` instead. + +## Store custom data in properties or extra + +Use `node.properties` for per-node extension data and `graph.extra` for +per-graph extension data. These remain the stable, intended extension +surfaces for persisted data. + +`onSerialize` and `onConfigure` are called with `this` bound to the live +node/graph object; the argument passed to the callback is the serialized +data object (`ISerialisedNode`/`ISerialisedGraph`), not the live node/graph. +Because `this` is still the live object, a hook can mutate any field on it, +including fields that are now store-backed. Don't use these hooks to +overwrite core fields: a write via `this` from inside +`onSerialize`/`onConfigure` goes straight through to the store, with no +schema, ownership, or undo boundary of its own. + +If you write graph-level extension data from `graph.onSerialize`, keep it +under `graph.extra`. A custom top-level key added anywhere else survives +`LGraph.asSerialisable()` but is silently dropped by the legacy +`LGraph.serialize()` entry point, which only carries a fixed set of known +keys forward. `graph.extra` is preserved by both. + +## Serialize nodes instead of enumerating properties + +If your extension builds a serialized or debug representation of a node by +enumerating its own properties, switch it to `node.serialize()`. + +`id`, `type`, `title`, `flags`, `mode`, `color`, `bgcolor`, `shape`, and +`showAdvanced` are now accessor properties over the node data store instead +of own data properties on the node instance. `Object.keys(node)`, +`for...in`, and `{ ...node }` no longer surface these fields, though direct +reads and writes (`node.title`, `node.mode = ...`) keep working unchanged. +`inputs`, `outputs`, and `widgets` remain own-enumerable, so +spread/enumeration still picks those three up. + +For widget-level `serializeValue`, a separate serialization layer that +builds the API prompt payload, not the workflow JSON, see +[Widget system migration](/custom-nodes/js/widgets-migration). diff --git a/custom-nodes/js/widgets-migration.mdx b/custom-nodes/js/widgets-migration.mdx new file mode 100644 index 0000000000..70822bdcd8 --- /dev/null +++ b/custom-nodes/js/widgets-migration.mdx @@ -0,0 +1,134 @@ +--- +title: "Widget System Migration for Frontend Extensions" +sidebarTitle: "Widget system migration" +description: "Store-backed widget values in the ComfyUI frontend: unique widget names, undefined node.widgets, BaseWidget registration and setValue calls." +--- + +Widget values now live in a Pinia-backed store instead of directly on the +widget instance. Two hazards follow: widget names must be unique per node, +and renaming a widget after it's added leaves its stored value behind. +`node.widgets` can also be `undefined` until it's first assigned, and only +registered widgets participate in the store. + +## Gallery values after the PrimeVue replacement + +The Vue `galleria` widget accepts an array of image URL strings, matching the +`GALLERIA` input schema. Multiple images show thumbnails and previous/next +buttons. Navigation stops at the first and last image. + +PrimeVue image objects with `itemImageSrc` or `thumbnailImageSrc` are no longer +supported. Convert them to URL strings. The widget no longer reads PrimeVue +options such as `showThumbnails`, `showItemNavigators`, `circular`, `autoPlay`, +`transitionInterval`, `showIndicators`, `numVisible`, or `responsiveOptions`. +Extensions that need these controls must supply their own gallery widget. + +## Widget names must be unique and stable + +Two widgets on the same node cannot share a name. Adding a second widget with +a name that's already in use overwrites the first widget's stored value: + +```ts +node.addWidget('number', 'strength', 0, () => {}) +node.addWidget('number', 'strength', 1, () => {}) // overwrites the first widget's value +``` + +Renaming a widget after it's registered has the same effect in reverse: the +store keeps the value filed under the old name, and nothing re-keys it for +you. Don't rename a widget after registration. Remove it and add a new one +with the name you want instead. + +## `node.widgets` may be undefined + +`node.widgets` returns `undefined` until it's been assigned at least once. +Initialize the array before adding widgets: + +```ts +export function nodeCreated(node: LGraphNode) { + node.widgets ??= [] + node.widgets.push(myWidget) +} +``` + +Guard reads the same way: + +```ts +const widgetCount = node.widgets?.length ?? 0 +``` + +**Setting `node.widgets = undefined` clears it.** A later read returns +`undefined` again, not `[]`. + +**Mutations made before the node is attached to a graph are picked up +automatically.** You don't need to call anything yourself for the common +case of building widgets in a constructor or `onNodeCreated`. + +`node.widgets` shows up in `Object.keys(node)` and object spreads like +`{...node}`. + +## Add widgets through the node, not by pushing to `node.widgets` + +Widgets added with `node.addWidget()`, `node.addCustomWidget()` or +`node.addDOMWidget()` are registered in the store automatically. +`addCustomWidget()` accepts a plain widget object and wraps it for you. An +object pushed straight onto `node.widgets` is not registered and won't +participate in the store: + +```js +// Registered +node.addCustomWidget({ + name: 'my_widget', + type: 'custom', + value: '', + options: {}, + draw(ctx, node, width, y, height) {}, + mouse(event, pos, node) {} +}) + +// Not registered: the store never sees this widget +node.widgets.push({ name: 'my_widget', type: 'custom', value: '' }) +``` + +If you read or write `widget.value` before the node is attached to a graph, +the value is held locally and synced to the store on attachment. No values +are lost, but store-driven UI (such as the right-side panel) won't see the +value until then. + +## Remove widgets with `node.removeWidget()` + +Use `node.removeWidget(widget)` to remove a widget. Splicing `node.widgets` +directly skips slot cleanup, and the removed widget's value stays in the +store until the node itself is removed from the graph. + +## Agent edits call `setValue` without a pointer event + +When the in-app Agent changes a widget on a `BaseWidget` subclass, the +frontend calls `widget.setValue(value, { node, canvas })`, the same method a +user edit goes through. Before, it assigned `widget.value` directly and then +called `callback` and `onWidgetChanged` itself. Plain-object widgets, +DynamicGroup row-count controllers and promoted subgraph-host widgets still get +that direct write. + +If you override `setValue`, accept options shaped `{ node, e?, canvas? }`: `e` +is never set for these calls, and `canvas` can be missing too. Don't read `options.e` +or `options.canvas` without checking them first. A wrapper that calls the +original `setValue` with only the value still works: the options default to +`{ node: widget.node }`. + +`callback` and `onWidgetChanged` now receive the value the widget accepted, not +the value the Agent sent. A number widget clamps to `min`/`max` and converts a +numeric string to a number. In `callback`, `e` is `undefined`, and so is +`pos` when there is no canvas. + +`setValue` returns without a change when the value, after a number widget +clamps and converts it, is already identical (`===`) to the current value, so +`'5'` on a number widget at `5` changes nothing. It also returns when a number +widget receives a value for which `Number(value)` is `NaN`. Neither `callback` +nor `onWidgetChanged` fires, and the graph version doesn't change. A numeric +string such as `'7'` is converted and applied. + +## Don't call `useWidgetValueStore()` from extension code + +Do not call `useWidgetValueStore()` from extensions. Use `node.widgets`, +`node.addWidget()` / `addCustomWidget()` / `removeWidget()`, and +`widget.value` instead. The store's internal keying and its dependency on +Pinia are not a supported extension surface. diff --git a/docs.json b/docs.json index 8c3993d854..fb9bd17dbc 100644 --- a/docs.json +++ b/docs.json @@ -3996,6 +3996,7 @@ "custom-nodes/js/javascript_commands_keybindings", "custom-nodes/js/javascript_topbar_menu", "custom-nodes/js/subgraphs", + "custom-nodes/js/canvas-pointer-api", "custom-nodes/js/javascript_examples" ] }, @@ -4005,6 +4006,13 @@ "pages": [ "custom-nodes/v3_migration", "custom-nodes/js/context-menu-migration", + "custom-nodes/js/node-id-migration", + "custom-nodes/js/link-registration-migration", + "custom-nodes/js/widgets-migration", + "custom-nodes/js/connection-callbacks-migration", + "custom-nodes/js/serialization-callbacks-migration", + "custom-nodes/js/node-geometry-migration", + "custom-nodes/js/primevue-removal-migration", "custom-nodes/backend/node-replacement" ] } From d241c6a9c4cbe78d2e5d7947538ee5571f03f61c Mon Sep 17 00:00:00 2001 From: Alexander Brown Date: Mon, 2 Nov 2026 20:57:28 +0000 Subject: [PATCH 2/3] fix(custom-nodes): correct frontend migration guides against current behavior Amp-Thread-ID: https://ampcode.com/threads/T-01a19df1-12f1-7428-a314-3b9547d383b9 --- custom-nodes/js/canvas-pointer-api.mdx | 24 ++++++-- .../js/connection-callbacks-migration.mdx | 15 +++-- .../js/link-registration-migration.mdx | 3 +- custom-nodes/js/node-geometry-migration.mdx | 24 +++++--- custom-nodes/js/node-id-migration.mdx | 5 +- .../js/serialization-callbacks-migration.mdx | 23 ++++++-- custom-nodes/js/widgets-migration.mdx | 56 ++++++++++--------- 7 files changed, 97 insertions(+), 53 deletions(-) diff --git a/custom-nodes/js/canvas-pointer-api.mdx b/custom-nodes/js/canvas-pointer-api.mdx index c22df41b25..6bd21279e8 100644 --- a/custom-nodes/js/canvas-pointer-api.mdx +++ b/custom-nodes/js/canvas-pointer-api.mdx @@ -59,18 +59,29 @@ widget.onPointerDown = function (pointer, node, canvas) { } ``` -- Click and drag callbacks never both run for one press. -- `onDragStart` runs once, when the pointer first moves past the click drift - limit. `onDrag` receives every movement, including movement inside that - limit, so it can run before `onDragStart`. +- `onClick` and `onDoubleClick` never run in the same press as `onDragStart`, + `onDragEnd` or `onDragCancel`. `onDrag` can run in a press that ends as a + click, because it also receives movement inside the click drift limit. +- `onDragStart` runs once per drag, when the pointer first moves past the click + drift limit. If the pointer is released past the limit before any movement + event is reported, `onDragStart` runs on release, `onDragEnd` runs right + after it, and `onDrag` does not run. +- When a press assigns both `onClick` and `onDoubleClick`, releasing the first + press of a double-click runs `onClick`. The second press runs + `onDoubleClick` instead of `onClick`, so make `onClick` safe to run first. - `onDragEnd` receives the pointer up event of a drag. `onDragCancel` runs instead when the drag is interrupted, for example when pointer capture is lost. -- `finally` always runs once the press ends, like a `finally` block. Prefer it - for cleanup. +- `finally` runs once when the press ends. Assigning `pointer.finally` runs the + callback it replaces immediately. If `onPointerDown` does not return `true`, + the canvas assigns its own `finally`, so yours runs during pointer down. + Return `true` when you rely on `finally` for cleanup. - `pointer.eDown`, `pointer.eMove` and `pointer.eUp` give every callback access to the whole sequence of events. - Return `true` to stop the canvas from handling the press itself. +- Remove any legacy `widget.mouse` handler when you add `onPointerDown`. If + `onPointerDown` returns `true`, the canvas keeps tracking the widget after + release and keeps calling `widget.mouse` on every pointer move. The canvas resolves double-clicks and drags for you, so a widget no longer needs to time or measure separate pointer events. It also honors the user's click @@ -85,4 +96,5 @@ cursor style, then set it yourself: ```js canvas.state.shouldSetCursor = false +canvas.canvas.style.cursor = 'pointer' ``` diff --git a/custom-nodes/js/connection-callbacks-migration.mdx b/custom-nodes/js/connection-callbacks-migration.mdx index 6c80c83520..b03d9c14f3 100644 --- a/custom-nodes/js/connection-callbacks-migration.mdx +++ b/custom-nodes/js/connection-callbacks-migration.mdx @@ -106,13 +106,13 @@ unchanged. ## Disconnecting inside the output callback skips the input callback Connecting a link calls the output side's `onConnectionsChange` first, then -the input side's. If the output-side handler disconnects that same link (or -otherwise invalidates it) before returning, the input-side call is skipped: +the input side's. If the output-side handler removes that same link with +`this.graph.removeLink(link.id)` before returning, the input-side call is skipped: ```js nodeType.prototype.onConnectionsChange = function (type, index, isConnected, link) { - if (type === LiteGraph.OUTPUT && shouldReject(link)) { - this.disconnectOutput(index) + if (type === LiteGraph.OUTPUT && isConnected && shouldReject(link)) { + this.graph.removeLink(link.id) } } ``` @@ -134,8 +134,11 @@ no replacement event of the same name. Migrate to: ## Read connection state from callback arguments or node methods -`input.link` and `output.links` are deprecated: writes through them no -longer drive topology, and reads can drift from the current graph. Use the +`input.link` and `output.links` are deprecated, and reads can drift from the +current graph. Writes only remove links: assigning `null` to `input.link` +disconnects the input, and assigning or mutating `output.links` disconnects +every link missing from the new array. Writes never create links; use +`node.connect()`, `node.disconnectInput()` or `node.disconnectOutput()`. Use the `link_info` argument your callback already receives, or the `LGraphNode` instance methods that read the link store directly: `node.isInputConnected()`, `node.getInputLink()`, `node.isOutputConnected()` diff --git a/custom-nodes/js/link-registration-migration.mdx b/custom-nodes/js/link-registration-migration.mdx index 7cce7aafe3..2749abd3ce 100644 --- a/custom-nodes/js/link-registration-migration.mdx +++ b/custom-nodes/js/link-registration-migration.mdx @@ -30,7 +30,8 @@ an empty graph. Like native `Map.set()`, `view.set(id, link)` returns the view, not a registration result. Registration can reject an ID or target collision while preserving the incumbent, so extensions that insert through a view should confirm success with -`get()` or `has()`. Prefer graph connection and floating-link APIs when they +`view.get(link.id) === link`. After a collision, `has()` returns `true` and +`get()` returns the incumbent link. Prefer graph connection and floating-link APIs when they cover the operation because those APIs coordinate the surrounding lifecycle. Do not invoke `Map.prototype` methods directly against either view or depend on native `Map` internal storage. diff --git a/custom-nodes/js/node-geometry-migration.mdx b/custom-nodes/js/node-geometry-migration.mdx index a42048a244..b7571087a4 100644 --- a/custom-nodes/js/node-geometry-migration.mdx +++ b/custom-nodes/js/node-geometry-migration.mdx @@ -10,8 +10,9 @@ description: "Node size versus rendered bounds, the applyNodePositions rename an `setPos()`, `setSize()`: no signature changes required. 2. Replace `repositionNodesVueMode()` calls with `applyNodePositions()`. 3. If you relied on `node.size` reflecting measured/rendered content, switch - to `getBounding()` / `boundingRect`: `size` now strictly reflects the - requested value. + to `getBounding()` / `boundingRect`. With the Vue renderer, `size` now + strictly reflects the requested value. The legacy renderer still grows + `size` to fit widgets. 4. Use the node/group geometry APIs, not the backing store; don't import `layoutStore` or depend on its internal format. 5. Writes through a removed reference update the detached object, not shared @@ -27,6 +28,7 @@ Behavior changed in the three cases below. node.pos = [100, 200] node.pos[0] += 50 node.setSize([320, 200]) +node.updateArea() const box = node.getBounding() ``` @@ -36,17 +38,25 @@ internal implementation detail. ### `size` vs. rendered bounds -`node.size` is the size you requested, and what gets serialized. -`getBounding()` and `boundingRect` return the node's rendered bounds, which -can be larger than `size` when widget content forces the node to grow. Use -rendered bounds when you need the node's actual on-screen footprint. +`node.size` is the size you requested, and what gets serialized. With the Vue +renderer, rendering never changes it. `getBounding()` and `boundingRect` return +the rendered bounds, which can be larger than `size` when widget content needs +more room. With the legacy canvas renderer, the node still grows to fit its +widgets by calling `setSize()`, so `node.size` and the saved size can change +after a draw. Use rendered bounds when you need the node's actual on-screen +footprint. + +The canvas recalculates `getBounding()` and `boundingRect` at the start of each +frame. After you change `pos` or `size`, call `node.updateArea()` before you +read them in the same frame. With the Vue renderer, growth from DOM content +appears only after the node has been measured. ```ts // Before: a rendered-content resize could overwrite size, so collapsing a // node and re-expanding it lost the original size. node.size // could silently become the rendered footprint -// After: size always stays what you set; ask for rendered bounds explicitly. +// After (Vue renderer): size stays what you set; ask for rendered bounds explicitly. node.size // the requested size, unchanged by rendering node.getBounding() // the actual rendered bounds, may be larger ``` diff --git a/custom-nodes/js/node-id-migration.mdx b/custom-nodes/js/node-id-migration.mdx index 7daf90c274..ae6e64b96f 100644 --- a/custom-nodes/js/node-id-migration.mdx +++ b/custom-nodes/js/node-id-migration.mdx @@ -6,8 +6,9 @@ description: "Migrate ComfyUI frontend extensions to branded string node IDs and ComfyUI frontend now normalizes local node IDs to the branded `NodeId` string type at internal boundaries. Serialized workflows and API payloads may still -contain numeric IDs, but litegraph node and link fields should be treated as -strings after they enter the frontend. +contain numeric IDs, but node IDs in litegraph, such as `node.id`, +`LLink.origin_id` and `LLink.target_id`, should be treated as strings after +they enter the frontend. Link IDs (`LLink.id`) and reroute IDs remain numbers. Extension authors should avoid numeric comparisons against node IDs. In particular, subgraph boundary sentinels are exposed as branded string IDs: diff --git a/custom-nodes/js/serialization-callbacks-migration.mdx b/custom-nodes/js/serialization-callbacks-migration.mdx index 1cd804c241..1050450f1c 100644 --- a/custom-nodes/js/serialization-callbacks-migration.mdx +++ b/custom-nodes/js/serialization-callbacks-migration.mdx @@ -45,11 +45,24 @@ overwrite core fields: a write via `this` from inside `onSerialize`/`onConfigure` goes straight through to the store, with no schema, ownership, or undo boundary of its own. -If you write graph-level extension data from `graph.onSerialize`, keep it -under `graph.extra`. A custom top-level key added anywhere else survives -`LGraph.asSerialisable()` but is silently dropped by the legacy -`LGraph.serialize()` entry point, which only carries a fixed set of known -keys forward. `graph.extra` is preserved by both. +`onSerialize` runs after the frontend has copied `graph.extra` and +`node.properties` into the data object, so a key that the hook adds to +`this.extra` or `this.properties` is missing from the current save. Inside +`onSerialize`, write to the callback argument instead: `data.extra` for a +graph, `data.properties` for a node. Otherwise, update `graph.extra` or +`node.properties` before serialization starts. + +```js +graph.onSerialize = function (data) { + data.extra.myExtension = { version: 1 } +} +``` + +A custom top-level key that a hook adds to `data` stays at the top level in +`LGraph.asSerialisable()`. The legacy `LGraph.serialize()` entry point moves it +under `data.extensions` instead, and leaves out values that are not +JSON-compatible. When the workflow loads, `onConfigure` receives the key at the +top level again. Keys under `extra` keep their place in both entry points. ## Serialize nodes instead of enumerating properties diff --git a/custom-nodes/js/widgets-migration.mdx b/custom-nodes/js/widgets-migration.mdx index 70822bdcd8..008126875e 100644 --- a/custom-nodes/js/widgets-migration.mdx +++ b/custom-nodes/js/widgets-migration.mdx @@ -1,14 +1,13 @@ --- title: "Widget System Migration for Frontend Extensions" sidebarTitle: "Widget system migration" -description: "Store-backed widget values in the ComfyUI frontend: unique widget names, undefined node.widgets, BaseWidget registration and setValue calls." +description: "Store-backed widget values in the ComfyUI frontend: unique widget names, undefined node.widgets, widget renames, addCustomWidget and Agent setValue calls." --- Widget values now live in a Pinia-backed store instead of directly on the -widget instance. Two hazards follow: widget names must be unique per node, -and renaming a widget after it's added leaves its stored value behind. -`node.widgets` can also be `undefined` until it's first assigned, and only -registered widgets participate in the store. +widget instance. Widget names must be unique per node, and renaming a widget +succeeds only when the new name is free. `node.widgets` can also be +`undefined` until it's first assigned. ## Gallery values after the PrimeVue replacement @@ -24,18 +23,25 @@ Extensions that need these controls must supply their own gallery widget. ## Widget names must be unique and stable -Two widgets on the same node cannot share a name. Adding a second widget with -a name that's already in use overwrites the first widget's stored value: +Two widgets on the same node cannot share a name. If you add a second widget +with a name that's already in use, the frontend renames the new widget with a +numbered suffix, such as `strength#1`, when the node is in a graph. A lookup by +the original name finds only the first widget: -```ts +```js node.addWidget('number', 'strength', 0, () => {}) -node.addWidget('number', 'strength', 1, () => {}) // overwrites the first widget's value +const second = node.addWidget('number', 'strength', 1, () => {}) +second.name // 'strength#1' once the node is in a graph ``` -Renaming a widget after it's registered has the same effect in reverse: the -store keeps the value filed under the old name, and nothing re-keys it for -you. Don't rename a widget after registration. Remove it and add a new one -with the name you want instead. +Give each widget a unique name. + +Assigning a new `widget.name` to a registered widget moves its stored value to +the new name. If another widget on the node already uses that name, the +assignment is ignored and `widget.name` keeps its old value, so check +`widget.name` afterwards. Input slots that refer to the widget by name are not +updated. Don't remove a widget and add a new one to rename it: `removeWidget()` +deletes the stored value and clears the input slots bound to the widget. ## `node.widgets` may be undefined @@ -65,16 +71,16 @@ case of building widgets in a constructor or `onNodeCreated`. `node.widgets` shows up in `Object.keys(node)` and object spreads like `{...node}`. -## Add widgets through the node, not by pushing to `node.widgets` +## Prefer `node.addCustomWidget()` to pushing onto `node.widgets` Widgets added with `node.addWidget()`, `node.addCustomWidget()` or -`node.addDOMWidget()` are registered in the store automatically. -`addCustomWidget()` accepts a plain widget object and wraps it for you. An -object pushed straight onto `node.widgets` is not registered and won't -participate in the store: +`node.addDOMWidget()` are registered in the store automatically. A plain object +pushed straight onto `node.widgets` is also converted in place into a widget +instance and registered once the node is in a graph. `addCustomWidget()` is +still the recommended call: it returns the widget, and it restores the +widget's saved value when a workflow loads. ```js -// Registered node.addCustomWidget({ name: 'my_widget', type: 'custom', @@ -83,9 +89,6 @@ node.addCustomWidget({ draw(ctx, node, width, y, height) {}, mouse(event, pos, node) {} }) - -// Not registered: the store never sees this widget -node.widgets.push({ name: 'my_widget', type: 'custom', value: '' }) ``` If you read or write `widget.value` before the node is attached to a graph, @@ -101,12 +104,13 @@ store until the node itself is removed from the graph. ## Agent edits call `setValue` without a pointer event -When the in-app Agent changes a widget on a `BaseWidget` subclass, the +When the in-app Agent changes a widget that is a `BaseWidget` instance, the frontend calls `widget.setValue(value, { node, canvas })`, the same method a user edit goes through. Before, it assigned `widget.value` directly and then -called `callback` and `onWidgetChanged` itself. Plain-object widgets, -DynamicGroup row-count controllers and promoted subgraph-host widgets still get -that direct write. +called `callback` and `onWidgetChanged` itself. This includes plain objects +added with `addCustomWidget()` or pushed onto `node.widgets`, because the +frontend converts them into `BaseWidget` instances. DynamicGroup row-count +controllers and promoted subgraph-host widgets still get the direct write. If you override `setValue`, accept options shaped `{ node, e?, canvas? }`: `e` is never set for these calls, and `canvas` can be missing too. Don't read `options.e` From 87e8cc6d134e0f24344dff7e52bef36b65a4c5e8 Mon Sep 17 00:00:00 2001 From: Alexander Brown Date: Mon, 2 Nov 2026 21:07:45 +0000 Subject: [PATCH 3/3] fix(custom-nodes): reject connections up front and cover serialization and widget edge cases Amp-Thread-ID: https://ampcode.com/threads/T-01a19df1-12f1-7428-a314-3b9547d383b9 --- custom-nodes/js/canvas-pointer-api.mdx | 5 +++ .../js/connection-callbacks-migration.mdx | 38 +++++++++++++------ .../js/link-registration-migration.mdx | 4 +- .../js/serialization-callbacks-migration.mdx | 9 +++++ custom-nodes/js/widgets-migration.mdx | 14 ++++--- 5 files changed, 51 insertions(+), 19 deletions(-) diff --git a/custom-nodes/js/canvas-pointer-api.mdx b/custom-nodes/js/canvas-pointer-api.mdx index 6bd21279e8..f66f9609ae 100644 --- a/custom-nodes/js/canvas-pointer-api.mdx +++ b/custom-nodes/js/canvas-pointer-api.mdx @@ -69,6 +69,8 @@ widget.onPointerDown = function (pointer, node, canvas) { - When a press assigns both `onClick` and `onDoubleClick`, releasing the first press of a double-click runs `onClick`. The second press runs `onDoubleClick` instead of `onClick`, so make `onClick` safe to run first. + The first click can also land on a nearby item instead of your widget, so + `onDoubleClick` can run without your `onClick` having run. - `onDragEnd` receives the pointer up event of a drag. `onDragCancel` runs instead when the drag is interrupted, for example when pointer capture is lost. @@ -98,3 +100,6 @@ cursor style, then set it yourself: canvas.state.shouldSetCursor = false canvas.canvas.style.cursor = 'pointer' ``` + +Starting a node resize still sets a resize cursor while `shouldSetCursor` is +`false`. Set your cursor again after the resize ends. diff --git a/custom-nodes/js/connection-callbacks-migration.mdx b/custom-nodes/js/connection-callbacks-migration.mdx index b03d9c14f3..97d87f79cc 100644 --- a/custom-nodes/js/connection-callbacks-migration.mdx +++ b/custom-nodes/js/connection-callbacks-migration.mdx @@ -103,24 +103,38 @@ This changes API prompt import only. Regular workflow loading still uses `graph.configure()` as described above, and connection callback signatures are unchanged. -## Disconnecting inside the output callback skips the input callback +## Reject connections before they are made -Connecting a link calls the output side's `onConnectionsChange` first, then -the input side's. If the output-side handler removes that same link with -`this.graph.removeLink(link.id)` before returning, the input-side call is skipped: +To refuse a connection, return `false` from `onConnectOutput` on the source +node or `onConnectInput` on the target node. Both run before the graph changes +anything, so an existing link on the target input stays in place: ```js -nodeType.prototype.onConnectionsChange = function (type, index, isConnected, link) { - if (type === LiteGraph.OUTPUT && isConnected && shouldReject(link)) { - this.graph.removeLink(link.id) - } +nodeType.prototype.onConnectOutput = function ( + slot, + type, + input, + targetNode, + targetSlot +) { + return !shouldReject(type, targetNode) } ``` -Don't assume both sides always fire for one `connect()` call; check that the -link you were handed is still connected if your handler re-enters the graph. -This is observed behavior, not a tested contract: no test currently -exercises the skip path. +Don't reject from `onConnectionsChange`. By the time it runs, the new link has +already replaced any link the target input had, so removing the new link +leaves the input disconnected. + +## Removing a link inside the output callback skips the input callback + +Connecting a link calls the output side's `onConnectionsChange` first, then +the input side's. If the output-side handler removes that same link before +returning, the input side gets an `isConnected === false` callback from the +removal, and its `isConnected === true` callback for the new link is skipped. +Don't assume both sides always see the connection; check that the link you +were handed is still connected if your handler re-enters the graph. This is +observed behavior, not a tested contract: no test currently exercises the skip +path. ## Replace removed slot events diff --git a/custom-nodes/js/link-registration-migration.mdx b/custom-nodes/js/link-registration-migration.mdx index 2749abd3ce..172df5ad7e 100644 --- a/custom-nodes/js/link-registration-migration.mdx +++ b/custom-nodes/js/link-registration-migration.mdx @@ -30,8 +30,8 @@ an empty graph. Like native `Map.set()`, `view.set(id, link)` returns the view, not a registration result. Registration can reject an ID or target collision while preserving the incumbent, so extensions that insert through a view should confirm success with -`view.get(link.id) === link`. After a collision, `has()` returns `true` and -`get()` returns the incumbent link. Prefer graph connection and floating-link APIs when they +`view.get(link.id) === link`. After an ID collision with a link in the same +view, `has()` returns `true` and `get()` returns the incumbent link. Prefer graph connection and floating-link APIs when they cover the operation because those APIs coordinate the surrounding lifecycle. Do not invoke `Map.prototype` methods directly against either view or depend on native `Map` internal storage. diff --git a/custom-nodes/js/serialization-callbacks-migration.mdx b/custom-nodes/js/serialization-callbacks-migration.mdx index 1050450f1c..a332da5b70 100644 --- a/custom-nodes/js/serialization-callbacks-migration.mdx +++ b/custom-nodes/js/serialization-callbacks-migration.mdx @@ -52,12 +52,21 @@ schema, ownership, or undo boundary of its own. graph, `data.properties` for a node. Otherwise, update `graph.extra` or `node.properties` before serialization starts. +`onSerialize` holds one callback, so keep any hook another extension already +installed: + ```js +const previous = graph.onSerialize graph.onSerialize = function (data) { + previous?.call(this, data) data.extra.myExtension = { version: 1 } } ``` +Only the root graph runs `onSerialize`. Subgraph definitions are saved without +calling a hook on the subgraph, so store subgraph data in `subgraph.extra` +before the workflow is saved. + A custom top-level key that a hook adds to `data` stays at the top level in `LGraph.asSerialisable()`. The legacy `LGraph.serialize()` entry point moves it under `data.extensions` instead, and leaves out values that are not diff --git a/custom-nodes/js/widgets-migration.mdx b/custom-nodes/js/widgets-migration.mdx index 008126875e..967f5a7325 100644 --- a/custom-nodes/js/widgets-migration.mdx +++ b/custom-nodes/js/widgets-migration.mdx @@ -41,7 +41,8 @@ the new name. If another widget on the node already uses that name, the assignment is ignored and `widget.name` keeps its old value, so check `widget.name` afterwards. Input slots that refer to the widget by name are not updated. Don't remove a widget and add a new one to rename it: `removeWidget()` -deletes the stored value and clears the input slots bound to the widget. +deletes the stored value and clears input slots bound directly to the widget. +Input slots that refer to it only by name keep that name. ## `node.widgets` may be undefined @@ -75,10 +76,13 @@ case of building widgets in a constructor or `onNodeCreated`. Widgets added with `node.addWidget()`, `node.addCustomWidget()` or `node.addDOMWidget()` are registered in the store automatically. A plain object -pushed straight onto `node.widgets` is also converted in place into a widget -instance and registered once the node is in a graph. `addCustomWidget()` is -still the recommended call: it returns the widget, and it restores the -widget's saved value when a workflow loads. +pushed straight onto `node.widgets` is also converted into a widget instance +and registered once the node is in a graph. The conversion usually happens in +place, but a frozen object or one with non-configurable properties is replaced +by a separate widget, so keep the widget that `addCustomWidget()` returns or +read it back from `node.widgets`. `addCustomWidget()` is still the recommended +call: it returns the widget, and it restores the widget's saved value when a +workflow loads. ```js node.addCustomWidget({