Repository navigation
[ext-api 1/4] foundation: Extension API v2 surface + scope registry - #12142
christian-byrne wants to merge 44 commits into
Conversation
…A world stubs
Restratified foundation. Includes:
- Public API declaration files (src/extension-api/{events,identifiers,index,
lifecycle,node,shell,widget}.ts + README)
- Scope registry runtime (src/services/extension-api-service.ts) +
scope-registry tests
- Boot wiring (src/scripts/app.ts, src/services/extensionService.ts)
- Phase A ECS world stubs (src/world/{componentKey,entityIds,
widgets/widgetComponents,worldInstance}.ts)
- Public type re-exports (src/types/extensionV2.ts)
Test framework moved to ext-api/i-tf, npm package + docgen moved to
ext-api/i-pkg, core extension v2 conversions moved to ext-api/i-ext.
Original (pre-restratify) branch tip backed up at
refs/backup/restratify-20260511/ext-api-i-foundation
and tag backup/restratify/ext-api-i-foundation on fork.
🎨 Storybook: ✅ Built — View Storybook |
🎭 Playwright: 🕵🏻 0 passed, 0 failed📊 Browser Reports
|
|
Warning Review limit reachedNext included review available in 2 minutes. View limit detailsLimit details: You’ve used all 4 included reviews currently available. Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. Review configuration: ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Team Run ID: 📒 Files selected for processing (46)
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a Phase A v2 extension API scaffold: public API declarations (node/widget/events/lifecycle/shell/identifiers), a scope-managed extension lifecycle service using Vue EffectScopes, Phase‑A ECS stubs (entity IDs, component keys, world), app startup wiring for v2 extensions, scope-registry tests, and a deprecated compatibility shim. ChangesExtension API v2 Foundation
Sequence Diagram(s)sequenceDiagram
participant App as App (startup)
participant ExtensionService as extension-api-service
participant World as World (ECS)
participant Extension as Extension Hook
App->>ExtensionService: startExtensionSystem()
ExtensionService->>World: entitiesWith(NodeTypeKey)
Note right of World: detects new node entities
ExtensionService->>ExtensionService: mountExtensionsForNode(nodeId)
ExtensionService->>Extension: run nodeCreated/loadedGraphNode hook (sync)
Extension-->>ExtensionService: setup return (proxyRefs state)
ExtensionService->>ExtensionService: store NodeInstanceScope
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes
🚥 Pre-merge checks | ✅ 6 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (6 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
📦 Bundle Size
⚡ Performance
|
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (1)
src/extension-api/index.ts (1)
59-64: ⚡ Quick winKeep
startExtensionSystemoff the public package surface.This is app bootstrap plumbing, not extension-author API, and
src/scripts/app.tsalready imports the service directly. Re-exporting it here turns an internal startup hook into a public semver promise for no clear external consumer.As per coding guidelines, "Minimize the surface area (exported values) of each module and composable".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/extension-api/index.ts` around lines 59 - 64, Remove startExtensionSystem from the public re-exports in index.ts: update the export list that currently re-exports defineExtension, defineNodeExtension, defineWidgetExtension, startExtensionSystem from '@/services/extension-api-service' so it only re-exports defineExtension, defineNodeExtension, and defineWidgetExtension; ensure any internal usage (e.g., app bootstrap) imports startExtensionSystem directly from '@/services/extension-api-service' rather than from this index export.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/extension-api/node.ts`:
- Around line 93-98: The SlotEntityId branded type is incorrect for runtime
values; update SlotEntityId to match the actual string IDs returned by the
runtime (used by createNodeHandle().inputs() and createNodeHandle().outputs())
by replacing the current number brand with a string brand so the exported type
matches runtime values and consumers don't get a misleading numeric type.
In `@src/extension-api/README.md`:
- Around line 16-27: The fenced code block in README.md is missing a language
tag (MD040); update the opening triple-backtick to include a language (e.g.,
```text or ```text-tree) so the block is recognized by markdownlint — locate the
block containing the directory tree in README.md and change its opening fence to
include the chosen language tag.
In `@src/scripts/app.ts`:
- Around line 862-865: The boot currently calls startExtensionSystem() from
setup() while getWorld() in worldInstance.ts is still the Phase A throwing stub;
this causes an immediate crash. Fix by deferring startExtensionSystem() until a
real world exists (e.g., await or listen for the world initialization completion
event/initializeWorld() or canvas-ready hook) or by making
startExtensionSystem() tolerate the stub (wrap its initial call to getWorld() in
a safe check/try-catch and skip/reactively retry if it throws). Update
references to startExtensionSystem, getWorld, and setup so the starter only
executes after worldInstance transitions out of Phase A.
In `@src/services/extension-api-service.ts`:
- Around line 348-362: addDOMWidget currently places the raw HTMLElement into
the CreateWidget command via options.__domElement, making the command
non-serializable; instead, stop including opts.element in the dispatched payload
and store the DOM node in a scope-local side table keyed by the returned
widgetId (e.g., a WeakMap or Map from WidgetEntityId to HTMLElement) inside
addDOMWidget; dispatch CreateWidget with only stable metadata (name, widgetType
'DOM', __domHeight or computed height) and after receiving widgetId, set
sideTable.set(widgetId, opts.element) and wire cleanup via onScopeDispose to
remove the mapping—ensure the CreateWidget options no longer reference
__domElement so commands remain serializable and replayable.
- Around line 396-411: The event handlers in the on method are passing raw
values from watch into the listener instead of the expected event objects; wrap
the watched values into the proper event shapes (NodePositionChangedEvent with
.pos, NodeSizeChangedEvent with .size, and NodeModeChangedEvent with .mode)
before calling fn. Locate the on implementation and for the positionChanged,
sizeChanged, and modeChanged branches (they call watch(...) on
world.getComponent(nodeId, PositionKey|DimensionsKey|ExecutionKey)) construct
and pass an object like { pos: ... }, { size: ... }, or { mode: ... }
respectively so consumers can access e.pos / e.size / e.mode.
- Around line 493-503: The defineExtension, defineNodeExtension, and
defineWidgetExtension functions currently return void causing exported
expressions like export default defineExtension({...}) to yield undefined;
change each to return the registered options object (i.e., return the options
argument after pushing to appExtensions/nodeExtensions/widgetExtensions) so the
functions match the public contract and callers receive the registered
ExtensionOptions/NodeExtensionOptions/WidgetExtensionOptions instance.
---
Nitpick comments:
In `@src/extension-api/index.ts`:
- Around line 59-64: Remove startExtensionSystem from the public re-exports in
index.ts: update the export list that currently re-exports defineExtension,
defineNodeExtension, defineWidgetExtension, startExtensionSystem from
'@/services/extension-api-service' so it only re-exports defineExtension,
defineNodeExtension, and defineWidgetExtension; ensure any internal usage (e.g.,
app bootstrap) imports startExtensionSystem directly from
'@/services/extension-api-service' rather than from this index export.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: ace6bad9-32f5-4e75-8000-5538a1331e3a
📒 Files selected for processing (17)
src/extension-api/README.mdsrc/extension-api/events.tssrc/extension-api/identifiers.tssrc/extension-api/index.tssrc/extension-api/lifecycle.tssrc/extension-api/node.tssrc/extension-api/shell.tssrc/extension-api/widget.tssrc/scripts/app.tssrc/services/__tests__/scope-registry.test.tssrc/services/extension-api-service.tssrc/services/extensionService.tssrc/types/extensionV2.tssrc/world/componentKey.tssrc/world/entityIds.tssrc/world/widgets/widgetComponents.tssrc/world/worldInstance.ts
| // Start the v2 node-extension reactive mount watcher (I-SR.3 / MIG1.E5). | ||
| // Must run after loadExtensions() so all defineNodeExtension() calls have | ||
| // pushed into nodeExtensions[] before the first watcher tick. | ||
| startExtensionSystem() |
There was a problem hiding this comment.
This boot path will crash while getWorld() is still a throwing stub.
startExtensionSystem() calls getWorld() immediately, and src/world/worldInstance.ts currently always throws in Phase A. As soon as setup() reaches this line, the app aborts before the canvas initializes. Gate this until the real world exists, or make the starter tolerate the stub.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/scripts/app.ts` around lines 862 - 865, The boot currently calls
startExtensionSystem() from setup() while getWorld() in worldInstance.ts is
still the Phase A throwing stub; this causes an immediate crash. Fix by
deferring startExtensionSystem() until a real world exists (e.g., await or
listen for the world initialization completion event/initializeWorld() or
canvas-ready hook) or by making startExtensionSystem() tolerate the stub (wrap
its initial call to getWorld() in a safe check/try-catch and skip/reactively
retry if it throws). Update references to startExtensionSystem, getWorld, and
setup so the starter only executes after worldInstance transitions out of Phase
A.
There was a problem hiding this comment.
This is intentional Phase A behavior, not a bug. Per AGENTS.md Rule #8: PRs #12142–#12145 are intentionally divergent from main and will be rebased onto Alex's ECS branch (PR #11939) before merge. The getWorld() stub in src/world/worldInstance.ts is replaced by the real ECS world at that rebase point — at which time startExtensionSystem() runs normally.
Phase A CI failures on this stack do not block ready-for-review or forward motion. The only quality gates required during Phase A are pnpm lint && pnpm format:check && pnpm knip.
Leaving open for awareness; resolution will happen automatically at the ECS rebase merge gate.
There was a problem hiding this comment.
🧩 Analysis chain
@christian-byrne, understood — thanks for the thorough context. The getWorld() throwing stub is an intentional Phase A scaffold that gets replaced by the real ECS world when this stack rebases onto PR #11939. I'll record this pattern so it isn't flagged again on future reviews of this stack.
I'll go ahead and resolve this comment since the behavior is working as designed.
(◕ᴥ◕)ノ
🏁 Script executed:
#!/bin/bash
# Resolve the CodeRabbit review comment
gh api \
--method PUT \
-H "Accept: application/vnd.github+json" \
graphql \
-f query='mutation ResolveReviewThread($threadId: ID!) {
resolveReviewThread(input: {threadId: $threadId}) {
thread {
id
isResolved
}
}
}' \
-f threadId="PRRT_kwDOMnfCOc5mjA8p"
Length of output: 76
@christian-byrne, I wasn't able to resolve the comment automatically (the sandbox doesn't have GitHub CLI auth available). You can resolve it manually via the GitHub UI when convenient. The learning has been recorded so this pattern won't be flagged again on future reviews of this stack.
🧠 Learnings used
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 7169
File: src/platform/remote/comfyui/jobs/jobTypes.ts:1-107
Timestamp: 2025-12-09T03:39:54.501Z
Learning: In the ComfyUI_frontend project, Zod is on v3.x. Do not suggest Zod v4 standalone validators (z.uuid, z.ulid, z.cuid2, z.nanoid) until an upgrade to Zod 4 is performed. When reviewing TypeScript files (e.g., src/platform/remote/comfyui/jobs/jobTypes.ts) validate against Zod 3 capabilities and avoid introducing v4-specific features; flag any proposal to upgrade or incorporate v4-only validators and propose staying with compatible 3.x patterns.
Learnt from: christian-byrne
Repo: Comfy-Org/ComfyUI_frontend PR: 7358
File: src/components/dialog/content/signin/SignUpForm.vue:45-54
Timestamp: 2025-12-11T12:25:15.470Z
Learning: This repository uses CI automation to format code (pnpm format). Do not include manual formatting suggestions in code reviews for Comfy-Org/ComfyUI_frontend. If formatting issues are detected, rely on the CI formatter or re-run pnpm format. Focus reviews on correctness, readability, performance, accessibility, and maintainability rather than style formatting.
Learnt from: christian-byrne
Repo: Comfy-Org/ComfyUI_frontend PR: 7416
File: src/stores/imagePreviewStore.ts:5-7
Timestamp: 2025-12-13T11:03:11.264Z
Learning: In the ComfyUI_frontend repository, lint rules require keeping 'import type' statements separate from non-type imports, even if importing from the same module. Do not suggest consolidating them into a single import statement. Ensure type imports remain on their own line (import type { ... } from 'module') and regular imports stay on separate lines.
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 7537
File: src/components/ui/button/Button.stories.ts:45-55
Timestamp: 2025-12-17T00:40:09.635Z
Learning: Prefer pure function declarations over function expressions (e.g., use function foo() { ... } instead of const foo = () => { ... }) for pure functions in the repository. Function declarations are more functional-leaning, offer better hoisting clarity, and can improve readability and tooling consistency. Apply this guideline across TypeScript files in Comfy-Org/ComfyUI_frontend, including story and UI component code, except where a function expression is semantically required (e.g., callbacks, higher-order functions with closures).
Learnt from: kaili-yang
Repo: Comfy-Org/ComfyUI_frontend PR: 7805
File: src/composables/useCoreCommands.ts:439-439
Timestamp: 2025-12-30T22:22:33.836Z
Learning: When accessing reactive properties from Pinia stores in TypeScript files, avoid using .value on direct property access (e.g., useStore().isOverlayExpanded). Pinia auto-wraps refs when accessed directly, returning the primitive value. The .value accessor is only needed when destructuring store properties or when using storeToRefs().
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 7906
File: src/components/sidebar/tabs/AssetsSidebarTab.vue:545-552
Timestamp: 2026-01-12T17:39:27.738Z
Learning: In Vue/TypeScript files (src/**/*.{ts,tsx,vue}), prefer if/else statements over ternary operators when performing side effects or actions (e.g., mutating state, calling methods with side effects). Ternaries should be reserved for computing and returning values.
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 8248
File: src/platform/assets/schemas/assetSchema.ts:109-118
Timestamp: 2026-01-22T23:44:59.888Z
Learning: Do not export declarations (e.g., schemas, constants, types) unless they are actually used elsewhere in the codebase. Keep the public API surface minimal by exporting only items with concrete usage. This reduces coupling and keeps imports explicit. In src/platform/assets/schemas/assetSchema.ts, ensure only necessary exports are exposed; remove unused exports or switch to non-exported/internal where appropriate.
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 8722
File: src/composables/maskeditor/useBrushDrawing.ts:5-5
Timestamp: 2026-02-08T03:19:12.009Z
Learning: Treat unresolved import warnings caused by pnpm workspace catalog mappings (pnpm-workspace.yaml) and unplugin-typegpu in vite.config.mts as false positives. Do not flag these in PR reviews; they are expected in sandboxes without node_modules and are not indicative of actual missing dependencies in the TS codebase.
Learnt from: Myestery
Repo: Comfy-Org/ComfyUI_frontend PR: 8961
File: src/scripts/app.ts:1216-1220
Timestamp: 2026-02-18T20:58:43.671Z
Learning: In src/scripts/app.ts, using api.getFolderPaths() inside Promise.all is safe because the underlying API (src/scripts/api.ts) catches errors and resolves with a non-rejection value (null or {}) when the call fails. No additional per-call error handling is required for this Promise.all usage. Downstream code should handle possible empty object or null values returned by this API.
Learnt from: christian-byrne
Repo: Comfy-Org/ComfyUI_frontend PR: 8966
File: src/extensions/core/load3d.ts:427-430
Timestamp: 2026-02-19T02:06:23.468Z
Learning: In TypeScript, you can use typeof SomeClass in type annotation positions (e.g., param: typeof LGraphNode) even when SomeClass is imported with import type. This is a type query that only exists at compile time and is erased in runtime, so it is safe to combine with type-only imports. Apply this pattern to TS files broadly when you need a type that references the shape of a class or constructor function without importing the value at runtime.
Learnt from: christian-byrne
Repo: Comfy-Org/ComfyUI_frontend PR: 8966
File: src/extensions/core/uploadAudio.ts:91-94
Timestamp: 2026-02-19T02:06:38.395Z
Learning: In TypeScript files, you can use a type annotation like 'nodeType: typeof MyClass' even if MyClass is imported via 'import type'. Both the type-only import and 'typeof' operate at the type level and are erased at compile time. This pattern is commonly used for constructor types (e.g., 'nodeType: typeof LGraphNode'). Apply this pattern across TypeScript files in the repository (src/**/*.ts) as appropriate, ensuring the imported symbol is a type-only import when possible for clarity and to avoid runtime imports.
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 8992
File: src/lib/litegraph/src/widgets/GradientSliderWidget.ts:18-18
Timestamp: 2026-02-20T21:08:19.814Z
Learning: When drawing with CanvasRenderingContext2D in TypeScript/JavaScript, wrap the drawing logic with ctx.save() at the start and ctx.restore() at the end to preserve and restore the canvas state. Do not manually destructure and restore individual properties (e.g., fillStyle, strokeStyle); rely on save/restore to manage state changes in a scoped manner. This should be applied to all TS files that perform canvas drawing.
Learnt from: dante01yoon
Repo: Comfy-Org/ComfyUI_frontend PR: 9075
File: src/scripts/api.featureFlags.test.ts:237-268
Timestamp: 2026-02-22T04:27:33.379Z
Learning: In Vite/Vitest, import.meta.env.DEV is true for any mode that is not 'production' (i.e., DEV is the opposite of PROD, and can be true in 'test', 'development', etc.). Do not assume DEV implies only 'development' mode. When reviewing code and tests, treat DEV as a non-production flag and verify environment-specific logic accordingly. Reference: https://vite.dev/guide/env-and-mode#modes
Learnt from: christian-byrne
Repo: Comfy-Org/ComfyUI_frontend PR: 9427
File: src/renderer/extensions/vueNodes/widgets/components/form/dropdown/FormDropdownMenuFilter.vue:33-33
Timestamp: 2026-03-06T00:53:28.835Z
Learning: When reviewing code, note that the enforce-canonical-classes (better-tailwindcss) rule may auto-fix Tailwind v3 !class-name syntax by converting it to v4 class-name! syntax. Do not treat these auto-fixed class-name! instances as newly introduced issues; the perceived change is in syntax placement, not in usage or intent. This guidance applies across all .vue and .ts files in the repository.
Learnt from: sonnybox
Repo: Comfy-Org/ComfyUI_frontend PR: 9446
File: src/renderer/extensions/vueNodes/widgets/components/WidgetTextarea.vue:45-45
Timestamp: 2026-03-06T01:55:00.013Z
Learning: Treat wrap-break-word as a valid Tailwind CSS utility for overflow-wrap: break-word in Tailwind v4+ projects. Do not flag this class as invalid in any Vue (.vue) or TypeScript (.ts/.tsx) files within the repository (e.g., Comfy-Org/ComfyUI_frontend) or other Tailwind v4+ projects. When reviewing, verify that the class is used to enable word breaking in long text content and reference the Tailwind docs: https://tailwindcss.com/docs/overflow-wrap.
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 10810
File: src/stores/subgraphNavigationStore.ts:148-161
Timestamp: 2026-04-07T15:37:48.047Z
Learning: In Comfy-Org/ComfyUI_frontend, avoid duplicating the AABB node-visibility logic (e.g., computeVisibleArea and intersection/overlap checks against graph.nodes). If similar “visible area intersects nodes” code appears in stores or scripts, refactor it into a shared standalone helper in src/utils (e.g., src/utils/graphTraversalUtil.ts or src/utils/viewportUtil.ts) and call that utility from both locations. Do not implement this as a method on LGraphCanvas (per ADR 0008).
Learnt from: kaili-yang
Repo: Comfy-Org/ComfyUI_frontend PR: 11531
File: src/composables/maskeditor/brushDrawingUtils.ts:14-14
Timestamp: 2026-04-22T04:06:01.353Z
Learning: In the Comfy-Org/ComfyUI_frontend codebase, `knip` is used to detect unused exports. When reviewing TypeScript/TSX code, avoid recommending or introducing exported types/functions/constants that have no concrete external consumers (e.g., they’re only used within the same module). Only recommend exporting when there is an actual external usage outside the module. If something might be needed externally later, keep it non-exported for now and defer exporting until an external consumer is added.
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 12197
File: src/renderer/extensions/linearMode/AppInput.vue:23-23
Timestamp: 2026-05-14T21:10:45.382Z
Learning: In the ComfyUI_frontend repo, `WidgetEntityId` is a branded template-literal type (e.g., `${UUID}:${NodeId}:${string}`) and should be treated as structurally non-empty when valid—so an empty string is invalid and must be treated as “absent”. When handling optional `entityId?: WidgetEntityId` values (e.g., for Vue props or TS function parameters), guard missing/invalid IDs with a truthy check (e.g., `if (!entityId) return`) rather than `if (entityId === undefined)`. Rationale: `=== undefined` would allow empty-string values through into stores such as `appModeStore.selectedInputs`, creating rows that can’t resolve back to a widget.
Learnt from: DrJKL
Repo: Comfy-Org/ComfyUI_frontend PR: 12197
File: src/core/schemas/parseNodePropertyArray.ts:1-1
Timestamp: 2026-05-18T21:34:41.153Z
Learning: In TypeScript, it is correct to use `import type { z } from 'zod'` when the imported symbol `z` is used exclusively in type-annotation/type-only positions (e.g., `schema: z.ZodType<T[]>`, `z.infer<typeof schema>`, `type X = z.AnyZodObject`, etc.). Because `import type` is fully erased at compile time and requires no runtime value, code reviewers should not flag `import type { z }` as an error (e.g., as an unused value import or incorrect runtime import) in TypeScript/React projects when `z` is only referenced in type positions. If `z` is referenced in a value/runtime position, it should instead be imported with a normal `import { z } from 'zod'`.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/world/worldInstance.ts`:
- Line 7: The exported interface World is unused and causing knip/lint failures;
make it module-local by removing the export on the World declaration (i.e.,
change "export interface World" to "interface World") so it is no longer part of
the module public API, or alternatively add a real consumer that imports it;
ensure no other modules rely on World before removing export.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: f1bedc02-5284-4fd5-bcd2-fe36c9844e43
📒 Files selected for processing (7)
src/extension-api/identifiers.tssrc/extension-api/lifecycle.tssrc/services/__tests__/scope-registry.test.tssrc/services/extension-api-service.tssrc/types/extensionV2.tssrc/world/widgets/widgetComponents.tssrc/world/worldInstance.ts
✅ Files skipped from review due to trivial changes (3)
- src/world/widgets/widgetComponents.ts
- src/extension-api/identifiers.ts
- src/extension-api/lifecycle.ts
🚧 Files skipped from review as they are similar to previous changes (3)
- src/types/extensionV2.ts
- src/services/tests/scope-registry.test.ts
- src/services/extension-api-service.ts
Codecov Report❌ Patch coverage is @@ Coverage Diff @@
## main #12142 +/- ##
===========================================
- Coverage 73.63% 59.49% -14.14%
===========================================
Files 1516 1423 -93
Lines 85617 72910 -12707
Branches 22520 20210 -2310
===========================================
- Hits 63047 43381 -19666
- Misses 21752 29056 +7304
+ Partials 818 473 -345
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 1022 files with indirect coverage changes 🚀 New features to boost your workflow:
|
christian-byrne
left a comment
There was a problem hiding this comment.
Can we include a generated .d.ts file in the PR (even if just generating locally and pushing)? It might be more digestible for review/ideation phase?
| // ── Registration function implementations ──────────────────────────────────── | ||
| // Runtime implementations live in the service; the types above are the | ||
| // public contract. The barrel re-exports the concrete fns from the service | ||
| // so `import { defineNodeExtension } from '@comfyorg/extension-api'` works | ||
| // at both typecheck and runtime. |
There was a problem hiding this comment.
Can this build process and "re-expose at runtime" process be simplified if we use importmap and peer imports?
| * @packageDocumentation | ||
| */ | ||
|
|
||
| // ── Registration function types ─────────────────────────────────────────────── |
There was a problem hiding this comment.
I think we can remove all the header comments from the api package files.
| * ## API style (D3.3) | ||
| * | ||
| * The public API is **event + getter/setter**, not signals. Vue reactivity is | ||
| * the internal engine; extension authors never import from Vue or use | ||
| * `ref`/`computed`/`effect` directly. State is read via methods (`getValue()`, | ||
| * `getPosition()`), mutated via command-dispatch methods (`setValue()`, | ||
| * `setPosition()`), and observed via typed event subscriptions (`on('executed', fn)`). | ||
| * Read-only invariants (set at construction, never change) are exposed as | ||
| * accessors (`get entityId`, `get type`). |
There was a problem hiding this comment.
Internal decision logs do not need to be reflected in code comments (Across all PRs). They can be kept while the branches are being worked on but should eventually be removed (just note in todos or issues, don't action yet).
| * ## Barrel-file rule exception | ||
| * | ||
| * ComfyUI_frontend AGENTS.md rule #19 normally forbids barrel files in `/src`. | ||
| * This barrel is the **published package entry point** — not an internal | ||
| * re-export — and is the explicit exception documented in AGENTS.md. |
There was a problem hiding this comment.
This doesn't need to go into package docs (external dev-facing)
There was a problem hiding this comment.
Agreed — deferred to Phase B per D-api-surface-finalization (wave-12). The Phase A surface is frozen at foundation ee0537fdb5 and this is a docs-relocation change inside src/extension-api/**.
Tracked in #12395 (item 1) for the Phase B PR.
There was a problem hiding this comment.
Update (2026-05-21 — wave-16): tracking issue #12395 closed per direction "internal todo is the single source of truth". This refinement is now W16.R1 in the workspace todo (cross-repo-tasks/ecs-vue-hoisted-client-state-hook-api/todo.md). Phase A surface remains frozen at ee0537fdb5; bundled into the Phase B PR after the ECS rebase (PR #11939).
| /** | ||
| * Shared event infrastructure for the ComfyUI extension API. | ||
| * | ||
| * @stability stable |
There was a problem hiding this comment.
Would the initial version actual be stable? What does this mean exactly?
| /** | ||
| * Returns `true` if the widget is currently hidden from the node UI. | ||
| * | ||
| * @stability stable | ||
| */ | ||
| isHidden(): boolean | ||
|
|
||
| /** | ||
| * Show or hide the widget. Dispatches a `SetWidgetHidden` command. | ||
| * | ||
| * @stability stable | ||
| * @example | ||
| * ```ts | ||
| * toggle.on('valueChange', (e) => { | ||
| * detail.setHidden(!e.newValue) | ||
| * }) | ||
| * ``` | ||
| */ | ||
| setHidden(hidden: boolean): void | ||
|
|
||
| // ── DISABLED — first-class, every-widget ───────────────────────────────── | ||
|
|
||
| /** | ||
| * Returns `true` if the widget is disabled (read-only in the UI). | ||
| * | ||
| * @stability stable | ||
| */ | ||
| isDisabled(): boolean | ||
|
|
||
| /** | ||
| * Enable or disable the widget. | ||
| * | ||
| * @stability stable | ||
| */ | ||
| setDisabled(disabled: boolean): void | ||
|
|
||
| // ── LABEL — first-class, every-widget ──────────────────────────────────── | ||
|
|
||
| /** | ||
| * The widget's display label shown to the user. Defaults to the widget name. | ||
| * Read-only invariant per D6 Part 3 (set at creation, never changes after). | ||
| * | ||
| * To override at construction, pass `label` to `addWidget()` options. | ||
| * | ||
| * @stability stable | ||
| */ | ||
| readonly label: string |
There was a problem hiding this comment.
I'm not convinced these need to be first-class. Can we go over pros/cons/tradeoffs again?
| // ── HEIGHT — DOM widgets only ───────────────────────────────────────────── | ||
|
|
||
| /** | ||
| * Updates the reserved height for this DOM widget and triggers a node relayout. | ||
| * | ||
| * Only meaningful for widgets registered via `NodeHandle.addDOMWidget()`. | ||
| * For non-DOM widgets this is a no-op. | ||
| * | ||
| * Replaces the v1 pattern of re-assigning `node.computeSize` to return a new | ||
| * height whenever the embedded element resizes. | ||
| * | ||
| * @param px - New reserved height in pixels. | ||
| * @stability experimental | ||
| */ | ||
| setHeight(px: number): void |
There was a problem hiding this comment.
This being DOM-widget-only (and widgets being collapsed at this layer and not collapse at registration layer) feels off. We have freedom to change this now and should do so if a better end-state is possible. Consider.
| /** | ||
| * Returns `true` if this widget is included in workflow and prompt | ||
| * serialization. Defaults to `true` for all widget types. | ||
| * | ||
| * @stability stable | ||
| */ | ||
| isSerializeEnabled(): boolean | ||
|
|
||
| /** | ||
| * Enable or disable serialization for this widget. When disabled, the widget | ||
| * is excluded from both `widgets_values` in the workflow JSON and the API | ||
| * prompt payload. Equivalent to the v1 `widget.options.serialize = false` | ||
| * pattern. | ||
| * | ||
| * @stability stable | ||
| */ | ||
| setSerializeEnabled(enabled: boolean): void |
There was a problem hiding this comment.
Does this need to change at runtime... can't it all be set and readonly in a more declarative way (and entire API should be declarative or imperative not half and half).
| /** | ||
| * When `true`, the widget value is processed for dynamic prompt syntax | ||
| * at serialize time. (STRING widgets with `dynamicPrompts: true`.) | ||
| */ | ||
| dynamicPrompts?: boolean |
There was a problem hiding this comment.
To consider: whether dynamicPrompts needs to be a first-class option concept and can't just use the APIs as an extension itself.
There was a problem hiding this comment.
Good catch — agreed that dynamicPrompts doesn't obviously belong as a first-class WidgetOptions field if a built-in extension can express it using public APIs.
Deferred to Phase B per D-api-surface-finalization (wave-12). Requires evaluating whether removal is axiom-compatible (§A15 — widget declarativity may require the schema to declare this) before we drop it.
Tracked in #12395 (item 3).
There was a problem hiding this comment.
Update (2026-05-21 — wave-16): tracking issue #12395 closed per direction "internal todo is the single source of truth". This evaluation is now W16.R3 in the workspace todo and composes with W16.P0 (defineWidgetExtension widgetTypes/widgetNames filters — see decisions/D-define-widget-augmenter.md). Phase A surface remains frozen at ee0537fdb5.
…rt (review #12142.A3) Extract NodeExtensionOptions, ExtensionOptions, and WidgetExtensionOptions into a new src/extension-api/types.ts so both the runtime service and the public lifecycle barrel depend on the type contracts without forming a cycle. Before: - extension-api-service.ts imported the option types from @/extension-api/lifecycle. - lifecycle.ts re-exported onNodeMounted/onNodeRemoved from @/services/extension-api-service. -> service <-> lifecycle circular import (Architect review #3). After: - types.ts owns the three option-type interfaces (single source of truth). - lifecycle.ts re-exports them from ./types so the public path @/extension-api/lifecycle keeps working. - extension-api-service.ts imports the types from @/extension-api/types. - The barrel @/extension-api re-exports from ./types directly. No public API change - all named exports remain available from @comfyorg/extension-api and from @/extension-api/lifecycle.
… (review #12142.A5) The previous comment described what the Vue intrinsics do but called them no-op shims without explaining the contract gap. That read as if the service was relying on dep-tracking suppression that the shim was silently violating. Rewrite the comment to make the Phase A scope explicit: this is a no-op stub by design (the API surface is the contract being stabilized, not the dep-tracking guarantee), and the real @vue/reactivity import lands together with the reactive-World contract in #11939. Adds the TODO(#11939) marker so the swap-in is grep-able alongside the rest of the Phase B handoff points. No code change - comment-only. Per Architect review #5, we deliberately do NOT add @vue/reactivity as a direct dep in Phase A.
knip flagged the new src/extension-api/* files and exports as unused because nothing internal consumes them — by design. They are the public API surface published by PKG2 (#12143). Changes: - knip.config.ts: add src/extension-api/index.ts as entry point (per AGENTS.md, this barrel is the explicit exception to the no-barrel-files-in-src rule because it IS the package entry). - knip.config.ts: ignore src/types/extensionV2.ts (deprecated stub, removed once PKG2 ships). - knip.config.ts: register `-publicAPI` tag. - Tag externally-consumed exports with @publicapi: - lifecycle.ts: defineNodeExtension/Extension/WidgetExtension declares + back-compat type re-exports - extension-api-service.ts: _setDispatchImplForTesting, NodeInstanceScope - worldInstance.ts: World Verifies the full lint-format CI matrix locally: pnpm lint ✅ pnpm stylelint (unaffected, CSS-only) pnpm format:check ✅ pnpm knip ✅
Changes: - Strip internal decision refs (D3, D5, D6, D7, etc.) from JSDoc - Remove @stability stable tags (pre-v1.0, nothing is stable yet) - Remove apiVersion from ExtensionOptions (telemetry deferred) - Change NodeMode from number union to string union ('always'|'never'|'bypass'|'once'|'onTrigger') - Rename widget() to getWidget() for consistency Addresses review discussion items #1, #2, #3, #7, #8 from design-review-12142.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ptions Remove redundant "widget" prefix since we're already in widget context. Addresses review discussion item #5 from design-review-12142.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add clear documentation explaining why onNodeMounted/onNodeRemoved must be called synchronously in setup scope: - Implicit context pattern (Vue-style _currentScope slot) - Automatic cleanup via EffectScope disposal - Memory leak prevention through scope-tied garbage collection Also removes remaining decision refs (D6, D10a, etc.) and @stability stable tags. Addresses review discussion item #6 from design-review-12142.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…getExtension → defineWidget Shorter function names improve ergonomics while maintaining clarity: - defineNode() - register node-scoped extensions - defineWidget() - register widget type extensions Old names kept as deprecated aliases for backwards compatibility. Will be removed in v1.0. Updates all docs, examples, tests, and internal references. Addresses review discussion item #4 from design-review-12142.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Node-level `node.on('beforeSerialize')` is wrong-layered:
- Extension state should flow through widgets, not arbitrary node fields
- Widget-level `widget.on('beforeSerialize')` handles all legitimate use cases
- Node-level hooks encourage ad-hoc state storage that breaks clean separation
Decision: Deprecate now, remove in v1.0. Add migration guidance to ADR.
Addresses review discussion item #9 from design-review-12142.md (Topic 11)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Decision: All collection-returning methods (widgets(), inputs(), etc.) and object-returning methods (getProperties()) return fresh copies. Benefits: - True immutability: mutations never affect internal state - JavaScript-safe: works regardless of TypeScript types - Simple mental model: "this is your copy" Applied consistently across the extension API surface. Addresses review discussion item #10 from design-review-12142.md (Topic 14) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Documents the decision to use pure function registration (defineNode, defineWidget) with a centralized loader (startExtensionSystem) rather than side-effect registration at import time. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Analyzes when extensions need raw entity IDs and recommends keeping them exposed with clear documentation that they are opaque values. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Analyzes canvas vs screen coordinates in the extension API. Current approach is appropriate - node positions in canvas space, widget heights in pixels. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Analyzes the relationship between DOM widgets and base widgets. Recommends keeping the current partial convergence - unified at entity/interface/command level, separate at creation API level. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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)
Wave-8 — D-no-node-widget-access + A14 enforcement landedTwo-commit cascade on foundation (then propagated through pkg / ext / tf):
Why bilateral A1 closureA contradiction was surfaced during handoff-14: AXIOMS.md §A1 (NON-NEGOTIABLE) says "Node hooks cannot reference/modify widgets" + "Widgets can know their parent node, but nodes cannot enumerate widgets", but design-review-12142 decision #13 (2026-05-12, "getWidget seems good") had renamed Per A1 + A2, the bilateral closure removes the carve-out — the Migration impact (v2 surface only)
TypeScript signature change only — no runtime change. v1 Cascade outcome
Pkg/ext/tf rebased onto new foundation HEAD via All 4 Decision propagation (D-no-node-widget-access)
Restoration criteria documented in AXIOMS.md §A14 — a |
…ave-9)
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)
Wave-9 cascade landed —
|
| Symbol | File | Reason |
|---|---|---|
WidgetHandle.setSerializeEnabled(bool) |
widget.ts |
A16 — no widget-level disable |
WidgetHandle.isSerializeEnabled() |
widget.ts |
Reader of removed knob |
WidgetBeforeSerializeEvent.context: 'workflow'|'prompt'|'clone'|'subgraph-promote' |
widget.ts |
A16 — single target; framework owns transport |
WidgetBeforeSerializeEvent.skip(): void |
widget.ts |
A16 — skip() IS a per-call disable |
WidgetPropertyChangeEvent |
widget.ts |
Vacuous union after 'serialize' removed |
WidgetHandle.on('propertyChange', handler) overload |
widget.ts |
Subscriber for vacated event |
WidgetOptions.serialize?: boolean |
widget.ts |
Contradicted A16 at the read site |
isSerializeEnabled / setSerializeEnabled adapter blocks |
extension-api-service.ts |
Backed removed surface |
propertyChange branch in event dispatcher |
extension-api-service.ts |
Subscriber for vacated event |
What stays legal: widget.on('beforeSerialize', handler) (async-capable, sole interface), event.value: T, event.setSerializedValue(v). All other widget events untouched.
Migration impact
| Branch | Surface | v2 call sites | Action |
|---|---|---|---|
restack-foundation-v2 |
All removed surfaces | 0 | Comment-out + adapter removal landed |
restack-pkg-v2 |
.d.ts artifact |
n/a | Hand-patched .d.ts (Node 20 vs vite blocks pnpm build per AGENTS.md Rule 8) |
restack-ext-v2 |
v2 example extensions | 0 | Cascade clean (no edits required) |
restack-tf-v2 |
Behavior triplets | 0 | Cascade clean (no edits required) |
v1 path (Comfy.* extensions, widget.options.serialize, widget.serializeValue = fn) untouched per D6 parallel-paths migration. No user-visible regression.
Decision propagation matrix
| Leg | Status |
|---|---|
| (a) Commit on PR branches | ✅ foundation e56187adf3, pkg 166953175c, ext d532f43529, tf 0164d4dbf2 |
| (b) ADR file | ✅ decisions/D-widget-serialization-simplification.md — ACCEPTED 2026-05-20 |
| (c) Dashboard JSON | ✅ christian-byrne/ComfyUI_frontend-ecosystem commit a19632f — 68 MDX refreshed, widgetpropertychangeevent.mdx deleted, widgethandle.mdx no longer mentions setSerializeEnabled, widgetbeforeserializeevent.mdx reflects A16 |
Restratify mirror
All 4 pairs verified at drift = 0 on origin. Per AGENTS.md §Drift-prevention process, no marker files needed.
Quality gates
scripts/check-axiom-compliance.sh✅ — strict-fail on re-introduction of any A16-forbidden surfacepnpm test✅ — 178/178 in ecosystem dashboardtsc --noEmitagainst foundation: zero new errors from this change (pre-existing wave-8 union errors carried per AGENTS.md Rule 8 carve-out)
Open follow-ups
D-ban-runtime-addwidgetskeleton — A15 enforcement on the v1node.addWidgetfamily (tracked as wave-10)- Audit of existing preview/progress/audio widgets for migration to non-widget UI primitives (separate audit)
Reference
- ADR:
decisions/D-widget-serialization-simplification.md(workspace; D-no-node-widget-access from wave-8 followed the same workspace-only pattern) - Axioms:
AXIOMS.md§A15 + §A16 (new), §A14 (7 new rows in COMMENTED OUT table) - Predecessor:
decisions/D14-serialization-convergence.md— promised the end-state this ADR ships - Slack source: Proposal: A Single Serialization Target (WIP)
…-addwidget (wave-10) 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.
…ve-11) Closes the (a)+(b) propagation legs for five design-review-12142 rows: - Row #1 (Comments hygiene): strip 25 HR-style section dividers (`// ── XYZ ──`) across widget.ts/node.ts/registrations.ts/events.ts/ index.ts; strip ~30 sites of decision archaeology refs (D5, D20, D-immutability-enforcement (Hybrid C), D-bootstrap-hooks (W6.P6.C), D-shell-ui-entrypoints (W6.P5.C), etc.) from per-export JSDoc; preserve PHASE_A_EXCLUDED axiom-ref blocks (functional — tells axiom-checker + future readers WHY surfaces are absent); preserve AXIOMS.md §A1/A14/A15/A16/A12 cross-refs; delete shell.ts "What changed in W6.P5" wave-history banner. - Row #2 (@stability stable): already DONE in code (0 stable hits); this ADR closes leg (b). - Row #4 (apiVersion drop): already DONE in code (0 hits); this ADR closes leg (b). - Row #5 (defineNode/defineWidget short-form): D11 ACCEPTED 2026-05-12; one stale JSDoc @example in lifecycle.ts:113,115 fixed (defineWidgetExtension → defineWidget). - Row #6 (Widget-prefixed methods): already DONE via D-bootstrap-hooks (unprefixed onMounted/onUnmounted etc.); this ADR closes leg (b). Also drops two now-unused imports in node.ts (WidgetHandle, WidgetOptions were only referenced in commented-out A14-deferred surfaces). ADR: decisions/D-design-review-hygiene-cleanup.md Net diff: -62 lines, zero behavior change. Quality gates: lint + format:check + axiom-compliance all green.
|
🧊 Phase A surface frozen — foundation The public API surface for this stack is now locked at foundation commit What's frozen
Re-open criteriaEither (1) a new ACCEPTED ADR with axiom-compliance verification, or (2) Phase B trigger (#11939 merges). Next up — Phase BKickoff tracking: #12394. Live frozen-surface dashboardhttps://comfyui-frontend-ecosystem.vercel.app (marker commit |
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: #12142 (comment)
- 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 ee0537f (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.
…17.N.2) 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.
|
@coderabbitai review |
|
DrJKL
left a comment
There was a problem hiding this comment.
I recommend closing this PR as superseded rather than repairing the branch.
I reviewed the complete description and discussion; fully read the public API, scope registry, extension-api-service, src/world/**, and the architecture documents; and sampled the legacy integration, handle/event implementations, registry tests, and ecosystem touch-point data. I did not line-review every implementation line in this 8,393-line diff.
Current main took a different route. 87b8ff0 collapsed the central World into widgetValueStore; e994e4d deleted src/world/entityIds.ts and the remaining widget World layer; and be38f14 updated ADR 0008 to dedicated concern-specific stores. ADR 0016 now defines per-store collision contracts. ADR 0023 requires preserving extension widget object identity and prototypes behind a compatibility adapter, which conflicts with this branch's proposed ban on runtime addWidget, addCustomWidget, and addDOMWidget.
Earlier API-shape requests were partly addressed, but the remaining package-doc, naming, identity, immutability, widget-boundary, and dynamicPrompts requests were deferred and remain unresolved. I am not repeating those points inline.
Checks on the historical head: install passed; the focused scope-registry suite passed 13/13; changed-file format passed; changed-file ESLint had no errors, with seven legacy paths ignored by current config. Typecheck failed with 19 API/export mismatches, and Knip failed on an unused WidgetComponentSerialize export. The PR is also conflicting with current main.
…17773) ## Summary Repair full diagnostic-report copying, retain a manual-copy fallback, and default all three optional sources on in the internal CRDT panel. ## Changes - Normalize structured cloud logs to text at `api.getLogs()`; preserve local string output and environment-specific endpoints. - Keep clipboard failures actionable with a persistent message, readonly report, and retry. Collection failures show a distinct retry message. - Default logs/settings/workflow on; preserve off controls, credential redaction, sharing warnings, source timeouts, and size caps. - Add collection status for collected, turned off, failed, unavailable, and omitted workflow sources; retain workflow serialization errors. <details> <summary>Root cause, verification, and review focus</summary> `getLogs(): Promise<string>` returned Axios `.data` unchanged. Local `/internal/logs` returns a JSON string; cloud `/api/logs` returns `[{"level":"info","message":"System is running normally"}]`. The array passed `truncate` unchanged and reached `fence`, causing `body.matchAll is not a function or its return value is not iterable`. The regression exercises the real API method and collector with that cloud response, not a string-only API mock: - [Test-only commit](Comfy-Org@284900cf16): `pnpm test:unit src/scripts/api.logs.test.ts` — 2 failed / 1 passed; exact reported exception reproduced. - [API fix](Comfy-Org@d0d88a658c): same unchanged tests — 3 passed. - Final: `NODE_OPTIONS=--no-experimental-webstorage pnpm test:unit src/workbench/extensions/agent/crdt src/scripts/api. src/components/rightSidePanel/errors/useErrorReport.test.ts` — 647 passed / 47 files. - Hooks passed: typecheck, targeted ESLint/type-aware Oxlint/stylelint/format, unused i18n/frozen-directory checks, and push-time Knip. Node 25.9.0 used as requested; current main's Node 26 engine range produces a warning. - Chromium component preview: rejected clipboard write exposes the alert and readonly report; successful retry clears failure; Settings off removes its payload. Both screenshots inspected. Collection-rejection recovery also verified through rendered component DOM assertions. Review focus: full-report copying awaits native clipboard failure instead of VueUse's success-reporting legacy fallback. When the Clipboard API is unavailable/denied, manual copy remains available. Other copy controls are unchanged. Scope: internal CRDT diagnostics only; no Typeform/public-feedback changes or auto-upload. Existing redaction repairs Comfy-Org#16774 and Comfy-Org#16926 are separate work. No changes to held Comfy-Org#16385 or Comfy-Org#12142. Limitations: local red/green proof, not red CI (feature-branch pushes do not run the unit workflow before a PR exists). CI is pending on opening. Browser verification used isolated component rendering with controlled API/clipboard failures, not a live cloud session. Figma MCP was unavailable; existing panel styling retained. Cloud `/api/logs` is currently a static backend stub; real cloud-log collection is outside this frontend repair. </details> ## Screenshots [All sources enabled](https://ampcode.com/user-content/artifacts/f3cd34957f909f1dc09a9dce64eeab07895197336002ef26bc8052f6e24b9648-file.png)  <!-- authored-by:agent role-external-context-watcher --> --------- Co-authored-by: Amp <amp@ampcode.com> Co-authored-by: Alexander Brown <drjkl@comfy.org>
Summary
Foundation layer for the Extension API v2. Provides the public API surface that extension authors import, plus the runtime scope registry that manages node/widget lifecycle hooks.
What's Included
Public API (
src/extension-api/)defineNode,defineExtension,defineWidget— registration functionsNodeHandle,WidgetHandle— controlled access to node/widget state and eventsonNodeMounted,onNodeRemoved— Vue-style implicit-context lifecycle hooksNodeEntityId,WidgetEntityId,SlotEntityId,Point,Size, etc.Runtime (
src/services/)extension-api-service.ts— scope registry + handle factoryPhase A World Stubs (
src/world/)Stack
@comfyorg/extension-apinpm package + CITest Plan
pnpm typecheckpasses