Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
3aa7dea
docs(nodeApi): the guide, the example packs, and end-to-end coverage
benjcooley Sep 3, 2026
181871f
docs(nodeApi): add the custom-node conversion skill
benjcooley Sep 9, 2026
cc56556
docs(nodeApi): check in the generated type contract
benjcooley Sep 9, 2026
cd69886
fix: register and simplify node API examples
benjcooley Sep 15, 2026
f40dbd5
fix(nodeApi): satisfy current API lint rules
benjcooley Sep 24, 2026
c6a830c
fix(nodeApi): run generators under current lint rules
benjcooley Sep 24, 2026
af2a307
fix(nodeApi): refresh example lint directives and ADR guidance
benjcooley Oct 15, 2026
cf9728f
docs(nodeApi): publish pack-relative endpoint security contract
benjcooley Oct 15, 2026
adea2ef
docs(nodeApi): publish the named model catalogue contract
benjcooley Oct 15, 2026
a1f99aa
docs(nodeApi): document storage list round trips
benjcooley Oct 15, 2026
4fe8d94
docs(nodeApi): name the public model folder contract
benjcooley Oct 15, 2026
7d01a45
test(nodeApi): retain current unordered prompt assertions
benjcooley Oct 19, 2026
df88794
fix: lint browser examples and API contract tools in their execution …
benjcooley Oct 26, 2026
626f8ca
test: verify public storage persistence against local ComfyUI
benjcooley Oct 26, 2026
eaaf82b
docs: explain local extension authority and optional host isolation
benjcooley Oct 26, 2026
969655a
test: exercise the public API in both node renderers
benjcooley Oct 26, 2026
af010f9
test: preserve renderer switching and fixture isolation
benjcooley Nov 9, 2026
34d29f1
fix(nodeApi): synchronize the documentation stack with API repairs
benjcooley Nov 11, 2026
f96502d
fix(nodeApi): carry the wiring repairs into the documentation branch
benjcooley Nov 11, 2026
4fe336b
docs(nodeApi): teach the right replacement for a serializeValue override
benjcooley Nov 11, 2026
80dc522
fix(nodeApi): carry the document-lifetime repair into the docs branch
benjcooley Nov 11, 2026
bce7840
docs(nodeApi): say when a kept handle stops resolving
benjcooley Nov 11, 2026
84d3ec5
fix(nodeApi): carry the surface repairs into the docs branch
benjcooley Nov 11, 2026
56e1a1b
docs(nodeApi): describe the repaired lifetimes, boundary links and ve…
benjcooley Nov 11, 2026
2efe9cb
fix(nodeApi): carry the subscription repair into the docs branch
benjcooley Nov 11, 2026
540c0c2
merge: carry current main and node API repairs into docs
benjcooley Nov 12, 2026
a15a8d0
fix(nodeApi): scope generated contract types to the public module
benjcooley Nov 12, 2026
33a53e7
docs(nodeApi): correct widget, lifecycle and host recipes
benjcooley Nov 12, 2026
af88fae
refactor(nodeApi): separate tuple recognition from declaration rendering
benjcooley Nov 12, 2026
f58b96d
Merge API validation cleanup into documentation stack
benjcooley Nov 12, 2026
2bd4397
fix(nodeApi): accept a dragged file in the drop example's dragover
benjcooley Nov 12, 2026
10cfa1e
fix(nodeApi): stage the example packs as the launcher stages devtools
benjcooley Nov 12, 2026
68d0195
test(nodeApi): run the storage round trip once and always clean up
benjcooley Nov 12, 2026
9ed99af
test(nodeApi): cover staged example packs in the launcher test
benjcooley Nov 12, 2026
76bc85d
merge: carry pack compatibility additions into docs
benjcooley Nov 12, 2026
23b405d
merge: carry generator-friendly types into docs
benjcooley Nov 12, 2026
02a4e68
docs(nodeApi): document the members added for converted packs
benjcooley Nov 12, 2026
8d47833
merge: carry document sessions into docs
benjcooley Nov 12, 2026
d869c43
docs(nodeApi): describe document sessions
benjcooley Nov 12, 2026
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
11 changes: 11 additions & 0 deletions .agents/skills/converting-custom-nodes/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
name: converting-custom-nodes
description: 'Converts third-party custom-node JS off deprecated/unpublished ComfyUI APIs onto the published node API. Use for Magic Patch conversion work, migrating a pack, or reviewing a generated patch. Triggers on: convert custom node, magic patch, migrate pack, port to node API, output.links, input.link, widgets.splice, converted-widget.'
---

# Converting Custom Nodes

The canonical cross-agent instructions live at
`../../../.claude/skills/converting-custom-nodes/SKILL.md`. Read that file
completely before converting or reviewing a pack, and resolve its pattern
references from the canonical skill directory.
556 changes: 556 additions & 0 deletions .claude/skills/converting-custom-nodes/SKILL.md

Large diffs are not rendered by default.

223 changes: 223 additions & 0 deletions .claude/skills/converting-custom-nodes/references/draw-callbacks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,223 @@
# Converting draw callbacks

`onDrawForeground`, `onDrawBackground`, `onDrawTitle*`, `onDrawCollapsed`.

**420 packs / 34.3M downloads / 32.2% of registry installs** touch these. They
are canvas-only, so they silently do nothing in Nodes 2.0 — no warning, no
error, no visible failure. That silence is why this cohort needs care.

## The hook name is misleading — most of it is not drawing

Measured over all **2,787 draw-callback bodies** in the corpus:

| What the body actually does | Bodies | % | Packs |
| ---------------------------------------- | ------ | ----- | ----- |
| Draws something | 1,468 | 52.7% | 289 |
| Prototype-patch plumbing | 901 | 32.3% | 198 |
| Layout / size enforcement — _no drawing_ | 178 | 6.4% | 39 |
| State sync / polling — _no drawing_ | 169 | 6.1% | 46 |
| DOM element sync — _no drawing_ | 71 | 2.5% | 37 |

**47.3% never touch a drawing primitive. 127 packs hook a draw callback and
never draw at all.** They are using it as the only recurring callback available.

## Decide which of four things it is — before writing anything

```
Does the body call ctx.fillText/fillRect/drawImage/arc/... ?
├─ no
│ ├─ only calls the original (`orig?.apply(this, arguments)`) → DELETE (plumbing)
│ ├─ assigns this.size / ensureMinimumSize / computeSize → setSizeConstraints
│ ├─ compares state and rebuilds on difference → widget.on('change') / onConnectionsChanged
│ └─ toggles .hidden / .style / wrapperEl → widget.setHidden() / mount's own element
└─ yes
├─ small status label or badge → node.addBadge()
├─ custom text, bar, border, tint, image, or icon → widgets.canvas()
├─ interactive (hit-testing, dragging, mouse handling) → widgets.mount() + own DOM/canvas
└─ arbitrary composition → widgets.mount()
```

## 1. Prototype plumbing — 32.3%, just delete it

```js
// before
const onDrawForeground = nodeType.prototype.onDrawForeground
nodeType.prototype.onDrawForeground = function (ctx) {
const r = onDrawForeground?.apply?.(this, arguments)
/* ...actual work... */
return r
}
```

The capture-and-chain wrapper exists only because prototype patching has no
composition. Registered callbacks compose by construction, so the wrapper
disappears entirely — keep only the body.

This is the highest-volume, lowest-risk transform in the whole programme.

## 2. Size enforcement — 39 packs

```js
// before — re-asserted on every repaint
if (Number.isFinite(desired) && Math.abs(this.size?.[1] - desired) > 1) {
this.size[1] = desired
}

// after — declared once
node.setSizeConstraints({ minHeight: desired })
```

`autoHeight: true` is usually what the pack actually wants: it added a DOM
widget of unknown height and hand-computed the node size to fit. In a
DOM-rendered node that is just layout, and needs no pack code at all.

## 3. Polling — 46 packs

```js
// before — string-joins every group title on every repaint, and mouse
// movement marks the canvas dirty, so this ran constantly
const titles = (app.graph._groups?.map((g) => g.title) || []).join()
if (this.lastKnownGroupTitles !== titles) {
this.lastKnownGroupTitles = titles
rebuildUI(this)
}

// after — for the cases the API reaches
node.widgets.get('mode').on('change', () => rebuildUI(node))
```

Pick the **narrowest** event that exists. `widget.on('change')` covers polling
for a widget's own value, and `b.onConnectionsChanged` covers polling for
wiring.

**Polling for graph structure — group titles, node counts, anything outside the
node — is a gap.** There is no `graph.onChange`; do not emit one. Punt the file
and name the event you needed.

## 4. DOM visibility sync — 37 packs

```js
// before
node.painter.canvas.wrapperEl.hidden = this.flags.collapsed
```

A mounted DOM widget's lifecycle handles this. If you find yourself syncing an
element's visibility to node state, the element should be a widget.

## 5. Actual decoration — the informational half

For a small status label that belongs in node chrome, use `node.addBadge()`:

```js
const removeBadge = node.addBadge(() => ({
text: currentStatus(node)
}))
```

Keep the returned removal function when the badge has a shorter lifetime than
the node. The callback runs during drawing, so it must remain fast.

Every canvas primitive in use has an exact DOM equivalent, so this is a
translation rather than a redesign:

| Canvas (packs using) | DOM/CSS |
| --------------------------------------------------- | --------------------------------------- |
| `fillText` 326, `measureText` 206 | a text node — measurement becomes free |
| `fillRect` 234 / `roundRect` 193 / `strokeRect` 159 | `background`, `border-radius`, `border` |
| `drawImage` 203 | `<img>` |
| `arc` 181 / `ellipse` 58 | `border-radius: 50%` |
| `translate` 170 / `rotate` 136 | `transform` |
| `globalAlpha` 150 | `opacity` |
| `clip` 138 | `overflow: hidden` |
| `setLineDash` 115 | `border-style: dashed` |
| `shadowBlur` 95 | `box-shadow` |
| `createLinearGradient` 79 | `linear-gradient()` |

For custom drawing, the shipped destination is **`node.widgets.canvas()`** — a
per-node drawing surface that works under both renderers, because the canvas is
a DOM element the legacy renderer positions over the graph and Nodes 2.0
renders natively:

```js
// before — ComfyUI-Custom-Scripts mathExpression.js, ran every repaint
nodeType.prototype.onDrawForeground = function (ctx) {
const v = app.nodeOutputs?.[this.id]
if (!this.flags.collapsed && v) {
ctx.save()
ctx.font = 'bold 12px sans-serif'
ctx.fillText(v.value[0], x, y)
ctx.restore()
}
}

// after — same drawing code, but event-driven
b.onCreated((node) => {
const surface = node.widgets.canvas({
name: 'result',
height: 22,
draw(ctx) {
ctx.font = 'bold 12px sans-serif'
ctx.fillText(stateFor(node).value ?? '', 4, 15)
}
})
stateFor(node).surface = surface
})
b.onExecuted((node, result) => {
const values = result.raw.value
stateFor(node).value = Array.isArray(values) ? String(values[0] ?? '') : ''
stateFor(node).surface?.redraw()
})
```

`draw` runs on mount, on resize, and on `redraw()` — never per frame. Keep the
pack's `ctx` code as close to verbatim as you can; the conversion is _when_ it
runs, not _what_ it draws. The collapsed check disappears (a hidden widget is
not drawn), and pixel positions are relative to the surface, not the node.

`node.addBadge()` is the declarative destination for simple labels;
`widgets.canvas()` remains the destination for arbitrary pack drawing.

## 6. Interactive controls — becomes a widget

```js
// mxtoolkit Slider2D.js — a full draggable 2D slider painted by hand
this.node.onDrawForeground = function (ctx) {
ctx.fillStyle = 'rgba(20,20,20,0.8)'
ctx.beginPath()
ctx.roundRect(shiftLeft - 4, shiftLeft - 4, ...)
ctx.fill()
// dots, handles, hit-testing...
}
```

This is not decoration. It was painted by hand because no custom-widget API
existed. It becomes **`node.widgets.mount({ name, render, destroy })`** — the
pack appends its own `<canvas>` (or any DOM) to the container and keeps its
drawing code, but pointer events now land on a real element, so hand-rolled
hit-testing against bounding boxes mostly disappears. kjnodes' `editor_base.js`
already works exactly this way and needs only the mount call swapped.

## The trap: frame to event

A draw callback recomputes from current state on every repaint, so **nothing
ever needs to announce a change**. After conversion, the drawing must be
refreshed _when the value changes_.

A naive port that calls `redraw()` from inside a per-frame path will appear to
work — and quietly run on every repaint forever. Redraw from the event that
changes the data: `onExecuted`, `widget.on('change')`, `onConnectionsChanged`.

## What you can stop doing

- **LOD checks.** rgthree hand-rolls `canvas.ds.scale < 0.6` to skip drawing
when zoomed out. Handled centrally now.
- **Collapsed checks.** `if (this.flags.collapsed) return` — layout's problem.
- **Defensive try/catch around drawing.** Several packs wrap draw calls to avoid
breaking node rendering; a `canvas()` surface draws into its own element, so
a throw cannot take node rendering down with it.

## Source data

Measured over the 4,969-pack registry corpus used when this reference was
authored. Counts are grep-derived and have a known false-positive rate —
sample-verify before citing any individual number.
Loading
Loading