Repository navigation
docs(custom-nodes): publish frontend extension migration guides and canvas pointer API #2223
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
DrJKL
merged 3 commits into
main
from
drjkl/front-3790-frontend-extension-migration-notes
Nov 3, 2026
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| } | ||
| ``` | ||
|
|
||
| - `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. | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| 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: | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
|
|
||
| ```js | ||
| canvas.state.shouldSetCursor = false | ||
| canvas.canvas.style.cursor = 'pointer' | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| ``` | ||
|
|
||
| Starting a node resize still sets a resize cursor while `shouldSetCursor` is | ||
| `false`. Set your cursor again after the resize ends. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.