lifecycle.ts: clarify that defineNodeExtension, defineExtension, and
defineWidgetExtension are type-only exports for the npm package surface.
Runtime implementations are in extension-api-service.ts.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Prefix unused variable with _ (cleanups → _cleanups)
- Use globalThis.setInterval for portable timer type
- Prefix unused nodeType param with _
Note: Pre-existing TS errors in other files remain (lazy-serialize, bc-04, etc.)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Change widget.hidden from a plain property to a getter/setter that
proxies to options.hidden. This ensures Vue and canvas renderers
see the same visibility state.
Fixes the dual-hidden bug where Vue renderer reads options.hidden
and canvas renderer reads widget.hidden, causing visibility desync.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unused _nextLinkId property from MockGraph interface
- Add test for out-of-bounds slot index edge case
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- knip.config.ts: drop `treatConfigHintsAsErrors` to false in tf only —
tf adds test consumers of foundation's @publicAPI-tagged symbols
(`_setDispatchImplForTesting`, `NodeExtensionOptions`, etc.) which
makes those tags 'redundant' from knip's POV. The tags are still
correct on foundation alone, so we keep the tag definition and just
downgrade hint→warning here.
- knip.config.ts: extend vitest config glob to include .mts (project is
"type": "module" so vitest configs use the .mts extension).
- bc-08/28/29/30 test files + ADR 0010: oxfmt formatting fixes after
rebase onto restacked ext.
Cascade follow-up to STACK-HYGIENE restratification. --no-verify used
because pre-commit runs full typecheck on staged TS files and tf has 61
pre-existing typecheck errors (same count with or without this commit);
per AGENTS.md rule #8, only lint/format/knip must pass during Phase A
on the ext-api stack.
Implement all 15 test stubs for BC.08 (programmatic linking) using synthetic
mock harnesses that verify the v2 API contract without requiring Phase B ECS:
bc-08.v2.test.ts (8 tests):
- NodeHandle.connect() creates links between output/input slots
- LinkHandle with stable id and isValid() tracking
- Replacing occupied input slot invalidates old LinkHandle
- TypeMismatchError thrown for incompatible slot types
- on('connectionChange') fires on both source and target handles
- disconnectInput() removes link and invalidates handle
- disconnectInput() on empty slot is no-op
bc-08.migration.test.ts (7 tests):
- v1/v2 connect() produce identical graph state
- Link IDs match between v1 and v2
- v2 throws TypeMismatchError where v1 returns null
- v1/v2 disconnectInput() leave identical state
- onConnectionsChange/connectionChange fire with equivalent payloads
- NodeHandle-based API vs raw node references
- Handle wraps same conceptual node as v1
This brings the test suite from 800 passed / 101 failed to 916 passed / 0 failed.
Note: --no-verify used because 207 pre-existing typecheck errors in other
test files (documented in RFR-12145) would fail the hook. Tests all pass.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The CR-12142-3 fix moved DOM element storage from command options to a
side table for serializability. Update test to verify:
- Element NOT in command options (__domElement undefined)
- Element retrievable via getDOMWidgetElement(widgetId)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Delete truly unused variables and functions
- Prefix intentionally unused parameters with underscore
- Use void for side-effect-only expressions
Build now passes with vue-tsc --noEmit.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes applied:
- defineNodeExtension → defineNode (all test files)
- widgetCreated → created (WidgetExtensionOptions hook name)
- Added apiVersion field to ExtensionOptions
- Fixed entity ID casts (number → as unknown as NodeEntityId/SlotEntityId)
- Harness barrel re-exports all types from harness/index.ts
Remaining errors (~61):
- Size type mismatch ([number,number] vs {width,height})
- WidgetValue/Handler type mismatches
- Unused variable warnings
- AppEvents constraint issues
- VirtualNode.isVirtualNode property access
See I-TF.9.K* tasks in todo.md for detailed breakdown.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Resolves remaining lint errors blocking lint-and-format CI on PR #12145:
- Removes unused vitest imports (afterEach, beforeEach, vi) flagged by
unused-imports/no-unused-imports across ~12 bc-*.test.ts files
- Replaces let with const where reassignment never occurred (prefer-const)
- Applies oxfmt line-width reflow across bc-* test files
CI's lint-and-format step runs lint:fix then tries to auto-commit through
husky, which triggers the full-repo typecheck. By committing the auto-fixes
locally, 'Check for changes' returns false in CI, skipping the broken
auto-commit step.
--no-verify used because husky pre-commit runs the full-repo typecheck
which still has 192 pre-existing errors documented as out-of-scope for
this PR.
CI's pnpm lint:fix step exits non-zero on:
- bc-02.migration.test.ts: prefer-const on v1Handle (assigned once)
- bc-35.v1.test.ts: typescript-eslint/no-unsafe-function-type on the
Function cast — replace with an explicit signature
Both errors block the [automated] auto-format push back to the PR.
oxlint's import/no-duplicates rule errored on bc-12, bc-31, bc-32
(both .v2 and .migration variants) because describe/it/expect and
expectTypeOf were imported from 'vitest' on separate lines. The CI
lint:fix step exits non-zero on these errors, blocking the
[automated] auto-format push back to the PR branch.
Targeted fixes for typecheck errors in 3 files. The remaining ~193
pre-existing errors live in other bc-* test files and are out of scope
for this branch (they will be addressed by sibling PRs in the stack).
- harness/runV2.ts: import WidgetExtensionOptions from
@/extension-api/lifecycle (the deprecated re-export shim in
@/types/extensionV2 doesn't include it).
- bc-37.migration.test.ts: prefix unused 'event' param with underscore;
widen 'eagerVueRef' literal-null type to VueComponentRef|null so the
optional-chain access type-checks; tighten 'intervalId' to const to
satisfy prefer-const lint that flagged after the file was touched.
- bc-36.v2.test.ts: drop unused 'beforeEach' import; drop unused
InputTextOptions interface; convert SelectOptions/SliderOptions to
type aliases that intersect Record<string, unknown> so the
'as unknown as ...Options' casts are assignable to setOptions().
Net: 10 typecheck errors removed (203 -> 193). Test intent preserved.
Pre-commit hook bypassed (--no-verify) because it runs full-repo
typecheck, which fails on pre-existing errors in non-scoped files.
Internal-only types were exported but never consumed outside their
source modules. Tighten the surface to satisfy `pnpm exec knip` so
the pre-push hook stays green:
- worldMocks: drop unused createWorldMockHandles helper (vi.hoisted
block is inlined per-consumer); demote WorldMockHandles to internal.
- v1App: demote V1NodeLike / V1Extension / V1App to internal types.
- v2Runtime: demote NodeRecord / V2Runtime / V2RuntimeOptions to
internal types.
F2: ~96 BC test files inline near-identical `createTestRuntime` /
`createV2Runtime` blocks (and ~30 `*.migration.test.ts` files inline
`createV1App`). Land the shared harness with bc-01 as the pilot:
- harness/v2Runtime.ts — canonical createV2Runtime({ idPrefix }) with
register / addNode / mountNode(id) / clear surface.
- harness/v1App.ts — canonical createV1App with simulateNodeCreated.
- harness/README.md — incremental migration tracker (which files have
adopted, which surfaces remain) and conventions for hoist-safe
vi.mock / vi.hoisted use against this harness.
bc-01.v2 keeps a thin local createTestRuntime alias to minimise churn
inside the test bodies; bc-01.migration bridges the legacy
`mountNode(comfyClass)` shape to the canonical `addNode + mountNode(id)`
without rewriting every assertion.
Verified: bc-01.v2 (13/14) + bc-01.migration (6/7) pass under vitest run
(1 it.todo each, pre-existing).
F3: bc-05.v2, bc-05.migration, bc-11.v2, bc-11.migration each duplicated
the same vi.mock('@/world/...') block (worldInstance + widgetComponents +
entityIds + componentKey + 3 extension-api stubs). Centralise the factory
bodies in src/extension-api-v2/__tests__/harness/worldMocks.ts and have
the four files consume them.
vi.hoisted handles stay inline because the hoisted factory runs before
imports resolve; vi.mock factories wrap the imported helpers in arrows
so the import binding is read lazily.
Verified: 4/4 files pass under vitest run with the shared module.
F5: D9 places several deferred behaviors in Phase C (canvas/menu
extension points), not strictly Phase B. Single-pass cosmetic relabel
to keep todos honest about which phase unblocks them.
F6: harness World was exposed without provenance, encouraging tests to
reach past the v1 `app` shape. Mark with @internal JSDoc so the
escape-hatch is documented and discouraged from public use. Existing
test usages (bc-15.*) continue to compile.
Restratified i-tf. Adds:
- src/extension-api-v2/__tests__/bc-XX.{v1,v2,migration}.test.ts triplets
for 41 behavior categories (BC.01-41) — real test bodies, not stubs
- src/extension-api-v2/harness/{comfyApp,index,loadEvidenceSnippet,runV1,
runV2,world}.ts and __fixtures__/touch-point-database.json
- vitest.extension-api.config.mts (test runner config)
- package.json — adds test:extension-api{,:watch,:coverage} scripts
Original (pre-restratify) branch tip backed up at
refs/backup/restratify-20260511/ext-api-i-tf.
Per workspace executive decision (option a) on F-12144-1: v1 + v2 conversions
in dynamicPrompts/imageCrop/previewAny coexist as Phase A demos following the
strangler-fig migration pattern (D6). Both register, but only one path runs
per node — guards skip v2 when v1 is already registered to prevent:
- dynamicPrompts: double processDynamicPrompt() on serialize
- previewAny: duplicate preview_markdown/preview_text/previewMode widgets
- imageCrop: redundant setSize call (idempotent but cleaner)
Guard pattern: 1-line useExtensionStore().isExtensionInstalled('<v1-name>') check
at the top of nodeCreated.
See workspace AGENTS.md rule #8 — CI failures on the ext-api stack do not
block flips during Phase A; full CI green required only at rebase point onto
PR #11939.
Per D-no-node-widget-access (2026-05-19, bilateral A1 closure), nodes
can no longer enumerate widgets — `node.getWidgets()` was removed
from NodeHandle. The previous dynamicPrompts.v2 implementation
iterated node widgets to attach per-widget `beforeSerialize`
handlers; that pattern is now forbidden.
Stubbed pending a follow-up public API (`defineWidgetAugmenter` or
per-widget `setup` on `defineWidget`) that lets extensions attach
behavior to existing widget types matching a predicate. v1
(`Comfy.DynamicPrompts`) continues to work — this is a v2 surface
gap only, not a user-visible regression.
Refs: decisions/D-no-node-widget-access.md
Strangler-pattern v2 example demonstrating the single-coordinate-space policy from D-coord-space (ACCEPTED 2026-05-18, option iii) and Axiom A13 (Single Coordinate Space — Canvas).
Three sections: (1) default path — every NodeHandle spatial accessor speaks canvas units; (2) escape-hatch path — globalThis.app.canvas.{ds,canvas} + window.devicePixelRatio with the required '// escape-hatch — see D-coord-space.md' annotation comment on every use site; (3) cliff documentation — what's NOT on the public surface (no getScreenPosition, no space param, no branded ClientPoint type).
Serves as the executable canary that the documented pattern actually works. Authors and AI agents reading the v2 extensions/core/*.v2.ts directory see the policy demonstrated alongside the existing dynamicPrompts/previewAny/imageCrop/noteNode/slotDefaults/rerouteNode/webcamCapture examples.
knip.config.ts: add new file to strangler ignore list. Phase A gates: format clean / lint 0 errors 3 pre-existing warnings / knip 6 pre-existing tag hints + 1 pre-existing config hint.
Strangler-pattern port of the WEBCAM custom widget type from the v1 webcamCapture extension to the v2 mount-lifecycle seam (Axiom A12 / D-widget-converge §Decision).
- Registers WEBCAM via defineWidget({type:'WEBCAM',mount}). The mount body constructs the <video> + container, captures them via closure (no widget.element accessor exposed per A12), and returns a cleanup that stops MediaStream tracks on widget destruction. - Uses ctx.onAfterRemount to re-attach the cached container when the host is swapped (graph ↔ app mode swap, subgraph promotion) per D-widget-converge §Clarification 1 — mount body is NOT re-invoked. - Companion defineNode stays a placeholder: GAP-2 (no type-construction addWidget('button',…)) and GAP-11 (no async setSerializedValue path; v2's WidgetBeforeSerializeEvent doesn't yet promise async resolution) block the full node-side port. v1 webcamCapture.ts remains authoritative until those gaps close.
knip.config.ts: add the new file to ignore list (matches existing v2 strangler entries; not wired into bootstrap).
Phase A gates: lint 0 errors / 3 pre-existing warnings; format:check clean; knip 6 pre-existing tag hints + 1 pre-existing config hint / 0 new failures.
F-12144-2: rewrite shell.ts header to say 're-exported from' (matches the
re-export code; the original 'moved from' wording was ambiguous).
F-12144-3: tag SlotDefaults v2 extension as '(DEMO — incomplete migration)'
and add a JSDoc @remarks block listing the v1 features (beforeRegisterNodeDef
node metadata, settings-dialog contribution, slot-type registry mutation)
that remain TBD. Intentionally NOT porting them — staging-demo intent per the
GAP-4/5/6 feedback to Simon/Austin.
F-12144-4: drop the redundant 'as string' cast in dynamicPrompts.v2; the
immediate 'typeof value === "string"' check makes the cast self-contradicting.
Defensive runtime check stays.
F-12144-10: add a 3-line @example to defineWidgetExtension JSDoc to match the
defineNodeExtension/defineExtension docs.
F-12144-11: reorder DOMWidgetOptions and NodeHandle JSDoc blocks so each
docblock immediately precedes its declaration.
Per D9 strangler-bridge taxonomy, every direct globalThis.app access in
v2 conversion files must carry a 'strangler-bridge:Phase-B' marker so
the bridge audit can enumerate remaining touch-points before Phase-B
removes the global.
Tag the three sites in rerouteNode.v2.ts (configuringGraph guard in
onConnectionsChange, configuringGraph guard in updateLink, and the
canvas.setDirty call from the context-menu callback).
Known-stubbed channels (executed/connected/disconnected/configured)
dispatch to a Phase-A stub bus that does not deliver events. Previously
these registrations were silent — extensions saw no warning that their
handlers were dead until #11939 lands the dispatch substrate.
Add a DEV console.warn (eslint-disable-next-line no-console, matching
the established pattern in this file) for each known-stubbed channel
registration so authors know to wait on #11939.
Restratified i-ext. Adds v2 conversions for 6 core extensions:
- dynamicPrompts.v2.ts
- imageCrop.v2.ts
- previewAny.v2.ts
- noteNode.v2.ts
- rerouteNode.v2.ts
- slotDefaults.v2.ts
And registers the first 3 in src/extensions/core/index.ts.
Note: noteNode.v2, rerouteNode.v2, slotDefaults.v2 are NOT yet
registered in index.ts (pre-existing issue from original i-ext branch).
Filed as a follow-up TODO.
Original (pre-restratify) branch tip backed up at
refs/backup/restratify-20260511/ext-api-i-ext.
Cascade of D20 (decisions/D20-id-type-convergence.md) from foundation:
- Rebuild packages/extension-api/build/index.d.ts via vite build so the
published .d.ts ships the new id/equals surface and drops the three
demoted brand re-exports.
- src/types/extensionV2.ts: stop re-exporting NodeEntityId, WidgetEntityId,
SlotEntityId — they are no longer in the @/extension-api barrel per D20.
Use node.id/widget.id (string) and equals(other) for the public surface.
typedoc renders re-exported type pages from the original-declaration
site (src/types/extensionTypes.ts), not from the @comfyorg/extension-api
barrel re-export. The shell-UI type aliases (ToastMessageOptions,
HotkeyExtension, AboutBadgeExtension, ToolbarButtonExtension) therefore
shipped to the dashboard without any @example blocks even though their
matching defineX entry points carry full examples in registrations.ts /
imperatives.ts.
Lift the canonical @example from each defineX onto the source
declaration so the dashboard type page renders with a working snippet.
Pure JSDoc — zero exported-type diff. Phase A freeze respected.
Wave-18 W18.J. Closes W17.N.2.
- W17.C: refresh 5 stale @example blocks (types.ts, lifecycle.ts, node.ts,
imperatives.ts ×2) — replace deprecated `async setup()` with
`setup() { onMounted(...) }`; remove A1-removed `node.getWidget` from
defineNode + NodeHandle.on migration examples; align imperatives examples
with W17.B notify-toast verdict.
- W17.D: author ~37 new @example blocks across 9 files for sparse exports
surfaced by W17.A audit. Pure JSDoc — zero exported-type diff.
- W17.E: add @deprecated JSDoc to notify() + NotifyOptions per
D-notify-toast-consolidation (W17.B verdict (a) soft-deprecate).
Pure JSDoc — no signature, type, or export changes.
Phase A surface remains FROZEN at ee0537fdb5 (foundation surface SHA
unchanged; only @example / @deprecated text differs).
See research/dashboard-snippet-audit-2026-05-21.md (W17.A) for full
per-edit rationale.
Address PR #12142 review thread PRRT_kwDOMIrOxs6BQjVr —
remove '(I-SR.3 / MIG1.E5)' internal task-tracker reference from the
startExtensionSystem() comment. Wave-11 hygiene cleanup did the same
across src/extension-api/**; this completes the same hygiene for the
single call site in src/scripts/app.ts.
Review: https://github.com/Comfy-Org/ComfyUI_frontend/pull/12142#discussion_r3222947433
Wave-10 follow-up to D-widget-serialization-simplification (wave-9). Closes
the v1 enforcement loop on AXIOMS.md A15 (Widget Declarativity).
User direction 2026-05-20: "we dont need soft deprecate for beforeSerialize
OR addWidget — they just simply shouldnt be present in the new API. for the
old api surfaces, we can just add deprecations with the suggested
remediation."
## v2 surface — absent (no soft-deprecate)
- Delete dead `addWidget` + `addDOMWidget` shims in
`src/services/extension-api-service.ts` (~30 lines), along with the
`domWidgetElements` side-table and `getDOMWidgetElement` accessor.
With the public NodeHandle no longer exposing these methods, all of
this is unreachable.
- Drop `DOMWidgetOptions` import from the service.
- Scrub 5 v2 JSDoc `@example` blocks that still referenced
`node.addWidget(...)` as if it were a valid call:
node.ts (NodeBeforeSerialize migration example), widget.ts (3 spots:
name doc, label doc, WidgetOptions doc), types.ts (defineWidget doc),
lifecycle.ts (defineNode example).
- Replace each example with one of A15's three remediation paths
(boxed widget / non-widget UI primitive / schema input).
## v1 surface — @deprecated + once-per-session console.warn
- Add @deprecated JSDoc + `warnDeprecated` (session-deduped via the
existing `./utils/feedback` mechanism) on:
- `LGraphNode.addWidget` (LGraphNode.ts)
- `LGraphNode.addCustomWidget` (same file)
- `LGraphNode.prototype.addDOMWidget` (src/scripts/domWidget.ts)
- Shared message constant `ADD_WIDGET_DEPRECATION_MESSAGE` so all three
warn paths dedupe to one console line per session. Message text cites
AXIOMS.md A15 + decisions/D-ban-runtime-addwidget.md and enumerates
the three migration paths.
## First-party core call sites — silenced via sentinel
- New `__suppressDeprecationWarning?: boolean` field on
`IWidgetOptions` (marked @internal, NOT part of public surface).
- Added to all first-party call sites that haven't yet migrated:
src/scripts/widgets.ts (valueControl, comboFilter),
src/extensions/core/uploadAudio.ts (4 sites),
src/extensions/core/load3d.ts (3 sites),
src/extensions/core/webcamCapture.ts (2 sites),
src/extensions/core/customWidgets.ts (1 site).
- `src/scripts/domWidget.ts addWidget()` helper (internal renderer
registration path) auto-injects the sentinel before delegating to
`addCustomWidget` — third-party callers of LGraphNode.addCustomWidget
still see the warning.
- Migration of these first-party sites tracked as wave-9 follow-up
#2 (preview/progress/audio widgets migration audit).
## Axiom-Excluded Test Annotation Policy — new, codified
- AXIOMS.md: new "Axiom-Excluded Test Annotation Policy" section after
A14, retiring the "compat-floor blast_radius ≥ N MUST pass" doctrine.
- AGENTS.md Rule 11: tests asserting on axiom-excluded surfaces MUST
use `axiomExcluded({...})` (vitest test.fails + task.meta.annotations)
rather than deletion. Deletion only when the *scenario* is no longer
meaningful.
- decisions/D-ban-runtime-addwidget.md: "Testing policy" section
documenting concrete application to bc-05 / bc-11 BC tests in tf
branch (deferred to tf cascade step).
## Decision propagation
- (a) commit on PR branches — this commit (foundation) + cascade
- (b) ADR — `decisions/D-ban-runtime-addwidget.md` ACCEPTED 2026-05-20
- (c) dashboard MDX — refresh via scripts/refresh-api-docs.sh after
cascade
## Validation
- scripts/check-axiom-compliance.sh: all 7 checks pass (no new strict
patterns added; A15 already strict-fails on v2 re-introduction per
wave-9, and the v1 deprecation is enforced at the call-site level
via the warnDeprecated mechanism)
- oxlint: 0 warnings/errors on all 13 touched files
- oxfmt: applied to all 13 touched files
- tsc: no new errors introduced (pre-existing TS2305/TS2353/TS2307 errors
from prior waves remain under AGENTS.md Rule 8 carve-out)
- Bundle size shrinks by ~30 lines (dead v2 shims removed)
## Compatibility (D6 parallel-paths)
- v1 path remains fully functional. Deprecation is a soft signal — no
throw, no exception, no behavior change beyond one console.warn per
session.
- Existing custom-node packs (R7 sweep: 5+ evidenced) continue to work;
authors see migration text on first addWidget call.
Refs: AXIOMS.md A15, A16; D-widget-serialization-simplification (wave-9);
ADR-0010 (node-level beforeSerialize deprecation pattern); D6
parallel-paths.
Codify A15 (Widget Declarativity) + A16 (Unified Serialization Target) by
collapsing widget-level serialization to its irreducible core.
Per D-widget-serialization-simplification (wave-9, 2026-05-20) — comment out
in src/extension-api/widget.ts (A14 pattern):
- WidgetHandle.setSerializeEnabled(enabled) / .isSerializeEnabled()
- WidgetBeforeSerializeEvent.context: 'workflow'|'prompt'|'clone'|'subgraph-promote'
- WidgetBeforeSerializeEvent.skip()
- WidgetPropertyChangeEvent (vacuous union after 'serialize' removed)
- WidgetHandle.on('propertyChange', handler) overload
- WidgetOptions.serialize?: boolean key
Per A16, the sole extension-author interface to serialization is
`widget.on('beforeSerialize', handler)`. The framework writes one payload
to every transport (workflow JSON, API prompt, clone, subgraph-promote);
authors do not branch on transport and cannot disable serialization. Per
A15, runtime widget addition was the underlying reason for the disable
matrix — declarativity removes the cause, A16 removes the escape hatch.
Removed framework-side adapters in src/services/extension-api-service.ts:
isSerializeEnabled / setSerializeEnabled blocks (lines 302-315) and the
propertyChange branch of the event dispatcher (line 362). Dropped
WidgetComponentSerialize import (now unused).
Removed WidgetPropertyChangeEvent from src/extension-api/index.ts barrel.
Updated JSDoc: stripped 4-context narrative + skip() examples from
WidgetBeforeSerializeEvent, dropped widget.options.serialize references
from the options accessor, dropped e.context === 'prompt' from the
serializeValue accessor example.
node.on('beforeSerialize') (separate surface) remains `@deprecated` +
runtime-warned per ADR-0010 — NOT banned by this commit (per user
direction 2026-05-20).
Blast radius: 0 v2 ext call sites for any removed surface (verified via
rg sweep across restack-ext-v2/src and foundation extensions/core).
v1 path untouched per D6 parallel-paths migration.
Refs:
- decisions/D-widget-serialization-simplification.md (ACCEPTED 2026-05-20)
- AXIOMS.md §A15 (Widget Declarativity), §A16 (Unified Serialization Target)
- AXIOMS.md §A14 (7 new rows in COMMENTED OUT table)
- D14-serialization-convergence.md (predecessor — promised this end-state)
- D-no-node-widget-access.md (wave-8, structural sibling)
- design-review-12142.md row #11
Verified: scripts/check-axiom-compliance.sh ✅ all checks pass
(A1, A2, A3, A4, A6, A15, A16 — strict-fail on re-introduction)
Comments out NodeHandle.getWidget(name) + NodeHandle.getWidgets() per
D-no-node-widget-access (ACCEPTED 2026-05-19, ADR landed). Closes the
node→widget direction so that the v2 public surface enforces A1 as
written: 'nodes cannot enumerate widgets' is now bilateral with
'nodes cannot reference widgets' — the widget→node direction
(widget.parentNode) remains the sole node↔widget channel.
Origin: a contradiction was surfaced during handoff-14 (wave-7
post-cascade). AXIOMS.md §A1 is NON-NEGOTIABLE and says 'Node hooks
cannot reference/modify widgets' + 'Widgets can know their parent
node, but nodes cannot enumerate widgets'. However design-review-12142
decision #13 (2026-05-12, 'getWidget seems good') had renamed
widget() → getWidget() without re-checking A1, and a codified
read-only carve-out in scripts/check-axiom-compliance.sh:22 papered
over the gap. The carve-out is removed; the axiom checker is now
strict-fail on any node→widget surface.
Changes:
- node.ts: getWidget(name) + getWidgets() commented out with A1+A2
rationale block (A2 pattern: 'comment out if not 100% sure')
- widget.ts: 2 JSDoc examples rewritten to use
defineWidget({mount}, ctx.widget) — the only legal v2 path to a
WidgetHandle
Migration cost (v2 surface):
- 0 call sites in the tf test suite
- 1 call site in ext-v2 (extensions/core/dynamicPrompts.v2.ts) —
stubbed pending follow-up 'defineWidgetAugmenter' API; v1 path
(Comfy.DynamicPrompts) continues to work
- TypeScript-only signature change; no runtime change
Restoration criteria: see AXIOMS.md §A14 entry — a documented use
case unexpressible via widget.parentNode + defineWidget({mount}) +
provide/inject, A1 re-audit pass, and bc-XX test triplet coverage
across promotion / app-mode / linked-instance scenarios.
Refs:
- ADR: decisions/D-no-node-widget-access.md (ACCEPTED 2026-05-19)
- AXIOMS.md §A1 + §A14
- scripts/check-axiom-compliance.sh (strict bilateral check)
Adopt per-surface defineX entries plus inline-imperative carve-out for
toast + notify, per D-shell-ui-entrypoints ADR (ACCEPTED 2026-05-18,
foundation impl handoff-13).
## What lands
New shell-UI registration entries (registrations.ts, NEW):
- defineSidebarTab / defineBottomPanelTab — wire to workspace stores
- defineCommand — wires to commandStore.registerCommand
- defineHotkey — parses key combo, wires to keybindingStore
- defineSetting — wires to settingStore.addSetting
- defineAboutBadge / defineToolbarButton — module-level registries
(consumed by aboutPanelStore / action-bar component via P5.E follow-up)
All defineX return DisposableHandle { dispose(): void }. Lazy-mount
queue (pendingEntries[]) flushed by startExtensionSystem() via the new
_flushShellRegistrations() hook so defineX is safe to call at
module-eval time (before Pinia is ready). Async store imports inside
each mount-fn keep the registration module itself dependency-free.
Inline imperatives (imperatives.ts, NEW):
- toast.show / toast.remove / toast.removeAll
- notify({ kind, message, detail, life }) — thin convenience wrapper
- Fire-and-forget; no DisposableHandle, no defineX wrapper
- 100% imperative across 166 ecosystem hits / 16 repos (R1+R2+R3)
Net-new public arg types (extensionTypes.ts):
- CommandDefinition (alias of v1 ComfyCommand)
- HotkeyExtension (keys + commandId + optional targetElementId)
- AboutBadgeExtension (label/url/icon/severity)
- SettingDefinition<TValue> (alias of SettingParams<TValue>)
- ToolbarButtonExtension (id/icon/label/tooltip/class/onClick)
Barrel reshape (shell.ts + index.ts):
- Re-export the 5 new arg types from shell.ts
- DROP ExtensionManager + CommandManager from public re-export per
W6.P5.B reconciliation — v2 uses per-surface disposables, not
umbrella handles. Internal callers still import from
@/types/extensionTypes directly.
- Export 7 new defineX + DisposableHandle + toast/notify/NotifyOptions
from index.ts
v1 deprecation (comfy.ts):
- ComfyExtension.{commands, keybindings, settings, bottomPanelTabs,
aboutPageBadges, actionBarButtons} gain @deprecated JSDoc pointing at
the v2 defineX equivalent. Slots remain functional for back-compat
during the deprecation window (v1 extensionService still loads them).
- menuCommands + topbarBadges marked @deprecated with scope-note that
they're not part of W6.P5 (follow-on ADRs).
Runtime wiring (extension-api-service.ts):
- startExtensionSystem() dynamic-imports registrations and calls
_flushShellRegistrations() so pending defineX calls land into stores
exactly once at bootstrap.
Verification:
- tsc --noEmit: zero new errors in modified files (pre-existing node.ts
/ widget.ts errors are uncommitted working-tree state from prior
agent, not from this work)
- oxfmt: clean
- oxlint: 0 warnings / 0 errors on touched files
- vitest/knip blocked by Node 20-vs-24 env requirement (env, not code)
ADR: decisions/D-shell-ui-entrypoints.md §Implementation plan Steps 1-5.
Steps 6 (codemod) lands in PKG; Step 7 (.d.ts regen) cascades via
restack-after-foundation.sh; Steps 8-13 land in EXT/TF/docs/dashboard.
Per AGENTS.md §Decision propagation: subject contains
'D-shell-ui-entrypoints' so check-decision-propagation.sh picks it up.
