diff --git a/custom-nodes/js/canvas-pointer-api.mdx b/custom-nodes/js/canvas-pointer-api.mdx new file mode 100644 index 0000000000..f66f9609ae --- /dev/null +++ b/custom-nodes/js/canvas-pointer-api.mdx @@ -0,0 +1,105 @@ +--- +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 +} +``` + +- `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. + 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. +- `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 +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 +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 new file mode 100644 index 0000000000..97d87f79cc --- /dev/null +++ b/custom-nodes/js/connection-callbacks-migration.mdx @@ -0,0 +1,162 @@ +--- +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. + +## Reject connections before they are made + +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.onConnectOutput = function ( + slot, + type, + input, + targetNode, + targetSlot +) { + return !shouldReject(type, targetNode) +} +``` + +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 + +`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, 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()` +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..172df5ad7e --- /dev/null +++ b/custom-nodes/js/link-registration-migration.mdx @@ -0,0 +1,53 @@ +--- +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 +`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. + +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..b7571087a4 --- /dev/null +++ b/custom-nodes/js/node-geometry-migration.mdx @@ -0,0 +1,86 @@ +--- +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`. 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 + 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]) +node.updateArea() +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. 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 (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 +``` + +### `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..ae6e64b96f --- /dev/null +++ b/custom-nodes/js/node-id-migration.mdx @@ -0,0 +1,20 @@ +--- +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 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: + +- `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..a332da5b70 --- /dev/null +++ b/custom-nodes/js/serialization-callbacks-migration.mdx @@ -0,0 +1,91 @@ +--- +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. + +`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. + +`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 +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 + +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..967f5a7325 --- /dev/null +++ b/custom-nodes/js/widgets-migration.mdx @@ -0,0 +1,142 @@ +--- +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, widget renames, addCustomWidget and Agent setValue calls." +--- + +Widget values now live in a Pinia-backed store instead of directly on the +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 + +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. 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: + +```js +node.addWidget('number', 'strength', 0, () => {}) +const second = node.addWidget('number', 'strength', 1, () => {}) +second.name // 'strength#1' once the node is in a graph +``` + +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 input slots bound directly to the widget. +Input slots that refer to it only by name keep that name. + +## `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}`. + +## Prefer `node.addCustomWidget()` to pushing onto `node.widgets` + +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 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({ + name: 'my_widget', + type: 'custom', + value: '', + options: {}, + draw(ctx, node, width, y, height) {}, + mouse(event, pos, node) {} +}) +``` + +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 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. 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` +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" ] }