Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions custom-nodes/js/canvas-pointer-api.mdx
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)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

pointer.onDragStart = () => {}
pointer.onDrag = (moveEvent) => {}
pointer.onDragEnd = (upEvent) => {}
pointer.onDragCancel = () => {}

pointer.finally = () => {}

return true
Comment thread
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.
Comment thread
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:
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

```js
canvas.state.shouldSetCursor = false
canvas.canvas.style.cursor = 'pointer'
Comment thread
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.
162 changes: 162 additions & 0 deletions custom-nodes/js/connection-callbacks-migration.mdx
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."

Check warning on line 4 in custom-nodes/js/connection-callbacks-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/connection-callbacks-migration.mdx#L4

Did you really mean 'subgraph'?
---

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

Check warning on line 12 in custom-nodes/js/connection-callbacks-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/connection-callbacks-migration.mdx#L12

Did you really mean 'subgraph'?

At a subgraph boundary (a `SubgraphInput` or `SubgraphOutput`),

Check warning on line 14 in custom-nodes/js/connection-callbacks-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/connection-callbacks-migration.mdx#L14

Did you really mean 'subgraph'?
`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`

Check warning on line 17 in custom-nodes/js/connection-callbacks-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/connection-callbacks-migration.mdx#L17

Did you really mean 'frontend's'?
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.

Check warning on line 86 in custom-nodes/js/connection-callbacks-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/connection-callbacks-migration.mdx#L86

Did you really mean 'lookups'?

## 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.
53 changes: 53 additions & 0 deletions custom-nodes/js/link-registration-migration.mdx
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

Check warning on line 27 in custom-nodes/js/link-registration-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/link-registration-migration.mdx#L27

Did you really mean 'Pinia'?
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

Check warning on line 49 in custom-nodes/js/link-registration-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/link-registration-migration.mdx#L49

Did you really mean 'deserialization'?
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.

Check warning on line 53 in custom-nodes/js/link-registration-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/js/link-registration-migration.mdx#L53

Did you really mean 'Pinia'?
Loading
Loading