Skip to content

[ext-api 1/4] foundation: Extension API v2 surface + scope registry - #12142

Open
christian-byrne wants to merge 44 commits into
mainfrom
ext-api/i-foundation-v2
Open

christian-byrne wants to merge 44 commits into
mainfrom
ext-api/i-foundation-v2

Conversation

@christian-byrne

@christian-byrne christian-byrne commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

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 functions
  • NodeHandle, WidgetHandle — controlled access to node/widget state and events
  • onNodeMounted, onNodeRemoved — Vue-style implicit-context lifecycle hooks
  • Type exports: NodeEntityId, WidgetEntityId, SlotEntityId, Point, Size, etc.

Runtime (src/services/)

  • extension-api-service.ts — scope registry + handle factory
  • Unit tests for scope lifecycle

Phase A World Stubs (src/world/)

  • Branded entity ID types
  • Component key registry
  • Placeholder world instance (will connect to ECS in Phase B)

Stack

PR Description
#12142 Foundation (this PR)
#12143 @comfyorg/extension-api npm package + CI
#12144 Core extension v2 conversions
#12145 Test framework + behavior triplets

Test Plan

  • pnpm typecheck passes
  • Scope registry unit tests pass

…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.
@github-actions

github-actions Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 05/21/2026, 09:03:05 PM UTC

Links

@github-actions

github-actions Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

🎭 Playwright: 🕵🏻 0 passed, 0 failed

📊 Browser Reports
  • chromium: ❌ Deployment failed
  • chromium-2x: ❌ Deployment failed
  • chromium-0.5x: ❌ Deployment failed
  • mobile-chrome: ❌ Deployment failed

@coderabbitai

coderabbitai Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

Next included review available in 2 minutes.

Check out review usage here.

View limit details

Limit 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.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: f974d445-3b67-4141-9300-6bfd32619bf8

📥 Commits

Reviewing files that changed from the base of the PR and between 5b05f2b and 24d893d.

📒 Files selected for processing (46)
  • docs/adr/0010-deprecate-node-level-serialization-control.md
  • docs/adr/0011-immutability-via-fresh-copies.md
  • docs/adr/0012-pure-function-loader-pattern.md
  • docs/adr/README.md
  • docs/research/coordinate-systems.md
  • docs/research/dom-widget-convergence.md
  • docs/research/identity-encapsulation.md
  • docs/research/serialization-context.md
  • docs/research/widget-state-categories.md
  • knip.config.ts
  • package.json
  • research/touch-points/behavior-categories.yaml
  • research/touch-points/rollup.yaml
  • scripts/check-compat-floor.py
  • src/extension-api/README.md
  • src/extension-api/brand.ts
  • src/extension-api/events.ts
  • src/extension-api/identifiers.ts
  • src/extension-api/imperatives.ts
  • src/extension-api/index.ts
  • src/extension-api/lifecycle.ts
  • src/extension-api/node.ts
  • src/extension-api/registrations.ts
  • src/extension-api/shell.ts
  • src/extension-api/types.ts
  • src/extension-api/widget.ts
  • src/extensions/core/customWidgets.ts
  • src/extensions/core/load3d.ts
  • src/extensions/core/uploadAudio.ts
  • src/extensions/core/webcamCapture.ts
  • src/lib/litegraph/src/LGraphNode.ts
  • src/lib/litegraph/src/types/widgets.ts
  • src/scripts/app.ts
  • src/scripts/domWidget.ts
  • src/scripts/widgets.ts
  • src/services/__tests__/scope-registry.test.ts
  • src/services/extension-api-service.ts
  • src/services/extensionService.ts
  • src/services/registries/README.md
  • src/services/registries/appExtensionRegistry.ts
  • src/services/registries/nodeExtensionRegistry.ts
  • src/services/registries/widgetExtensionRegistry.ts
  • src/types/comfy.ts
  • src/types/extensionTypes.ts
  • src/types/extensionV2.ts
  • src/world/worldInstance.ts

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds 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.

Changes

Extension API v2 Foundation

Layer / File(s) Summary
Public API Documentation
src/extension-api/README.md
Establishes src/extension-api/ as the published source of truth, documents post-PKG2 layout, TSDoc/stability rules, naming/event typing constraints, and cross-references.
Event Handler Types
src/extension-api/events.ts
Exports Handler<E>, AsyncHandler<E>, and Unsubscribe types for event subscriptions.
Node Identity Types
src/extension-api/identifiers.ts
Re-exports NodeLocatorId/NodeExecutionId and their is/parse/create helpers for cross-boundary node referencing.
Public Option Types
src/extension-api/types.ts
Adds NodeExtensionOptions, ExtensionOptions, and WidgetExtensionOptions used in extension registration signatures.
Lifecycle Registration Declarations
src/extension-api/lifecycle.ts
Declares defineNodeExtension/defineExtension/defineWidgetExtension and re-exports onNodeMounted/onNodeRemoved.
NodeHandle & Node Events
src/extension-api/node.ts
Typed geometry/mode/slot types, node event payloads including async beforeSerialize with replace, DOMWidgetOptions, and the NodeHandle interface with widget/slot APIs and typed on(...).
WidgetHandle & Widget Events
src/extension-api/widget.ts
Defines WidgetEntityId, WidgetValue, widget event payloads (valueChange, optionChange, propertyChange, beforeSerialize, beforeQueue), WidgetHandle<T>, and WidgetOptions.
Shell UI Types
src/extension-api/shell.ts
Re-exports shell extension type definitions and manager types.
Public API Barrel
src/extension-api/index.ts
Aggregates and re-exports lifecycle, node, widget, events, shell, and identifier APIs as the package entry.
ECS Phase A Stubs
src/world/entityIds.ts, src/world/componentKey.ts, src/world/widgets/widgetComponents.ts, src/world/worldInstance.ts
Introduces branded entity IDs, ComponentKey factory, widget component keys/data shapes, and a World interface with a getWorld() stub.
Extension Service
src/services/extension-api-service.ts
Implements per-node EffectScope registry, dispatch stub/override, factories for NodeHandle/WidgetHandle, current-scope utilities, registration APIs, mount/unmount lifecycle, startExtensionSystem() watcher, and invokeV2AppExtensions().
App Integration
src/scripts/app.ts
Wires v2 extension bootstrap: imports startExtensionSystem/invokeV2AppExtensions, calls startExtensionSystem() after loading extensions, and routes app init/setup via invokeV2AppExtensions.
Scope Registry Tests
src/services/__tests__/scope-registry.test.ts
Vitest suite mocking world/componentKey to validate copy/paste semantics, current-scope behavior, lifecycle constraints, idempotency, promotion behavior, and LoadedFromWorkflow routing.
Knip Config & Deprecation
knip.config.ts, src/services/extensionService.ts, src/types/extensionV2.ts
Adds src/extension-api/index.ts workspace entry, updates ignore/tags, tracks per-extension deprecation warnings for beforeRegisterNodeDef, and provides a deprecated re-export shim for extensionV2.

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
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

"🐰
I stitched the scopes with care and light,
Hooks hum softly through the night,
IDs and widgets find their place,
A tiny v2 burrowed—brave and bright."

🚥 Pre-merge checks | ✅ 6 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 52.17% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (6 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The PR fully implements the three foundation commits outlined in issue #12102: public API declaration files, service rename with boot wiring, and scope registry with ECS world stubs.
Out of Scope Changes check ✅ Passed All changes directly support the foundation objectives: API surfaces, scope registry, ECS stubs, and boot wiring. The minor config/knip updates and extensionService warning tracking are proportional to the foundation scope.
End-To-End Regression Coverage For Fixes ✅ Passed PR title and commit subjects use only feature/refactoring language (refactor, feat), not bug-fix language. This is a foundational API surface PR, not a defect fix.
Adr Compliance For Entity/Litegraph Changes ✅ Passed PR does not modify src/lib/litegraph/, src/ecs/, or litegraph graph entity files. Check criteria do not apply.
Title check ✅ Passed The title accurately summarizes the main change: a foundation layer for Extension API v2 that includes both the public surface and the scope registry runtime.
Description check ✅ Passed The description is comprehensive and well-structured with sections covering Summary, What's Included, Stack, and Test Plan, exceeding the template requirements with clear organization and context.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch ext-api/i-foundation-v2

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle Size

⚠️ Size data collection failed. Check the CI workflow logs.

⚡ Performance

⚠️ Performance tests failed. Check the CI workflow logs.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🧹 Nitpick comments (1)
src/extension-api/index.ts (1)

59-64: ⚡ Quick win

Keep startExtensionSystem off the public package surface.

This is app bootstrap plumbing, not extension-author API, and src/scripts/app.ts already 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

📥 Commits

Reviewing files that changed from the base of the PR and between ced7c93 and 2de2e07.

📒 Files selected for processing (17)
  • src/extension-api/README.md
  • src/extension-api/events.ts
  • src/extension-api/identifiers.ts
  • src/extension-api/index.ts
  • src/extension-api/lifecycle.ts
  • src/extension-api/node.ts
  • src/extension-api/shell.ts
  • src/extension-api/widget.ts
  • src/scripts/app.ts
  • src/services/__tests__/scope-registry.test.ts
  • src/services/extension-api-service.ts
  • src/services/extensionService.ts
  • src/types/extensionV2.ts
  • src/world/componentKey.ts
  • src/world/entityIds.ts
  • src/world/widgets/widgetComponents.ts
  • src/world/worldInstance.ts

Comment thread src/extension-api/node.ts Resolved
Comment thread src/extension-api/README.md Resolved
Comment thread src/scripts/app.ts Outdated
Comment on lines +862 to +865
// 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()

@coderabbitai coderabbitai Bot May 11, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 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'`.

Comment thread src/services/extension-api-service.ts Resolved
Comment thread src/services/extension-api-service.ts Resolved
Comment thread src/services/extension-api-service.ts Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 2de2e07 and 9a6fff6.

📒 Files selected for processing (7)
  • src/extension-api/identifiers.ts
  • src/extension-api/lifecycle.ts
  • src/services/__tests__/scope-registry.test.ts
  • src/services/extension-api-service.ts
  • src/types/extensionV2.ts
  • src/world/widgets/widgetComponents.ts
  • src/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

Comment thread src/world/worldInstance.ts Resolved
@codecov

codecov Bot commented May 11, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 16.79507% with 540 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/services/extension-api-service.ts 22.53% 330 Missing ⚠️
src/extension-api/registrations.ts 0.00% 132 Missing ⚠️
src/extension-api/events.ts 0.00% 25 Missing ⚠️
src/extension-api/imperatives.ts 0.00% 17 Missing ⚠️
src/services/registries/appExtensionRegistry.ts 0.00% 7 Missing ⚠️
src/services/registries/nodeExtensionRegistry.ts 0.00% 7 Missing ⚠️
src/services/registries/widgetExtensionRegistry.ts 0.00% 7 Missing ⚠️
src/extension-api/brand.ts 40.00% 6 Missing ⚠️
src/services/extensionService.ts 16.66% 5 Missing ⚠️
src/scripts/app.ts 0.00% 2 Missing ⚠️
... and 1 more
@@             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     
Flag Coverage Δ
e2e ?
unit 59.49% <16.79%> (+0.42%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/world/componentKey.ts 100.00% <100.00%> (ø)
src/world/widgets/widgetComponents.ts 100.00% <100.00%> (ø)
src/scripts/app.ts 15.44% <0.00%> (-50.42%) ⬇️
src/world/worldInstance.ts 0.00% <0.00%> (ø)
src/services/extensionService.ts 34.04% <16.66%> (-27.76%) ⬇️
src/extension-api/brand.ts 40.00% <40.00%> (ø)
src/services/registries/appExtensionRegistry.ts 0.00% <0.00%> (ø)
src/services/registries/nodeExtensionRegistry.ts 0.00% <0.00%> (ø)
src/services/registries/widgetExtensionRegistry.ts 0.00% <0.00%> (ø)
src/extension-api/imperatives.ts 0.00% <0.00%> (ø)
... and 3 more

... and 1022 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Comment thread src/extension-api/index.ts Outdated
Comment on lines +54 to +58
// ── 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this build process and "re-expose at runtime" process be simplified if we use importmap and peer imports?

Comment thread src/extension-api/index.ts Outdated
* @packageDocumentation
*/

// ── Registration function types ───────────────────────────────────────────────

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can remove all the header comments from the api package files.

Comment thread src/extension-api/index.ts Outdated
Comment on lines +28 to +36
* ## 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`).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment on lines +38 to +42
* ## 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't need to go into package docs (external dev-facing)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment thread src/extension-api/events.ts Outdated
/**
* Shared event infrastructure for the ComfyUI extension API.
*
* @stability stable

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would the initial version actual be stable? What does this mean exactly?

Comment thread src/extension-api/widget.ts Outdated
Comment on lines +318 to +364
/**
* 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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced these need to be first-class. Can we go over pros/cons/tradeoffs again?

Comment thread src/extension-api/widget.ts Outdated
Comment on lines +366 to +380
// ── 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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/extension-api/widget.ts Outdated
Comment on lines +384 to +400
/**
* 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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment on lines +540 to +544
/**
* When `true`, the widget value is processed for dynamic prompt syntax
* at serialize time. (STRING widgets with `dynamicPrompts: true`.)
*/
dynamicPrompts?: boolean

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To consider: whether dynamicPrompts needs to be a first-class option concept and can't just use the APIs as an extension itself.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/scripts/app.ts Resolved
Connor Byrne and others added 13 commits May 11, 2026 17:43
…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)
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Wave-8 — D-no-node-widget-access + A14 enforcement landed

Two-commit cascade on foundation (then propagated through pkg / ext / tf):

  1. bd4d195230 — chore(ext-api): comment out NodeMode + Slot surfaces per AXIOMS.md A14 (pre-existing A14 enforcement work that was sitting uncommitted across the wave-6/7 reconciliations — NodeMode, SlotDirection, SlotInfo, SlotEntityId, NodeConnectedEvent, NodeDisconnectedEvent, getMode/setMode, inputs()/outputs(), position/size/title accessors, isSelected, isHidden/setHidden, isDisabled/setDisabled)
  2. 446d0a216e — feat(ext-api): bilateral A1 closure — D-no-node-widget-access (comments out NodeHandle.getWidget(name) + NodeHandle.getWidgets())

Why bilateral A1 closure

A 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 widget() → getWidget() without re-checking A1. A codified read-only carve-out in scripts/check-axiom-compliance.sh:22 papered over the gap.

Per A1 + A2, the bilateral closure removes the carve-out — the widget→node direction (widget.parentNode) remains the sole node↔widget channel. The axiom checker is now strict-fail on any node→widget surface (scripts/check-axiom-compliance.sh updated).

Migration impact (v2 surface only)

Surface Action
src/extension-api/node.ts:236,259 getWidget / getWidgets commented out with A1+A2 rationale block
src/extension-api/widget.ts (2 JSDoc cross-refs) Rewritten to use defineWidget({mount}, ctx.widget)
extensions/core/dynamicPrompts.v2.ts (1 call site) Stubbed pending follow-up defineWidgetAugmenter API; v1 (Comfy.DynamicPrompts) unaffected
tf test suite 0 call sites — clean

TypeScript signature change only — no runtime change. v1 ComfyExtension slot path is untouched (this is a v2-only constraint).

Cascade outcome

Branch Old HEAD New HEAD
ext-api/i-foundation-v2 ff314491da 446d0a216e
ext-api/i-pkg-v2 b87f7ea067 5e926d87ed
ext-api/i-ext-v2 85ecde3bbc bbb3c6ce02
ext-api/i-tf-v2 c69ca8dbe3 f4dfe0903a

Pkg/ext/tf rebased onto new foundation HEAD via git rebase; foundation commits skipped on pkg as "already applied" (the pre-existing uncommitted work in those worktrees was absorbed by the foundation commit). One trivial conflict on ext-v2's 7138e72bc2 idempotency-guard commit touching the now-stubbed dynamicPrompts.v2.ts — resolved by keeping the stub and dropping the moot guard for that file (imageCrop.v2.ts + previewAny.v2.ts parts of the same commit applied cleanly).

All 4 *-v2 ↔ *-restratify pairs reconciled to drift = 0.

Decision propagation (D-no-node-widget-access)

Leg Status
(a) commit on PR branches ✅ 446d0a216e on foundation; propagated through pkg/ext/tf
(b) ADR ✅ decisions/D-no-node-widget-access.md — ACCEPTED 2026-05-19
(c) dashboard JSON ✅ christian-byrne/ComfyUI_frontend-ecosystem ca1a14e — 68 MDX pages refreshed; nodehandle.mdx no longer mentions getWidget; pnpm test 178/178

Restoration criteria documented in AXIOMS.md §A14 — a defineWidgetAugmenter (or per-widget setup on defineWidget) follow-up will unblock the dynamicPrompts.v2 use case without loosening A1.

…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)
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Wave-9 cascade landed — D-widget-serialization-simplification + A15/A16 codified

Per design-review-12142.md row #11 reframed via user direction 2026-05-20: not banning node.on('beforeSerialize') (stays @deprecated + runtime-warned per ADR-0010). Instead, simplifying the widget surface to its irreducible core and codifying the two architectural premises that make the matrix moot.

New axioms (AXIOMS.md)

  • A15 — Widget Declarativity. Widgets are schema-declared. No runtime addWidget. No frontend-only widgets. UI-only state uses boxed widgets (BBOX-style), non-widget UI primitives, or schema inputs.
  • A16 — Unified Serialization Target. Workflow JSON ≡ API prompt payload. Authors cannot disable serialization at the widget level. The sole extension-author interface is widget.on('beforeSerialize', handler).

Surface removals (commented out per A14 pattern)

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 surface
  • pnpm test ✅ — 178/178 in ecosystem dashboard
  • tsc --noEmit against 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-addwidget skeleton — A15 enforcement on the v1 node.addWidget family (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.
@christian-byrne
christian-byrne requested a review from jtydhr88 as a code owner May 20, 2026 22:02
…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.
@christian-byrne

Copy link
Copy Markdown
Contributor Author

🧊 Phase A surface frozen — foundation ee0537fdb5 (wave-11)

The public API surface for this stack is now locked at foundation commit ee0537fdb5 per D-api-surface-finalization. All four PRs in the stack (#12142 / #12143 / #12144 / #12145) will be rebased onto the ECS branch (PR #11939) before merge — codecov, e2e, perf, and Playwright failures on this stack are intentionally divergent from current main and not a merge blocker until that rebase point.

What's frozen

  • 7 shell-UI defineX entry points (sidebar / bottom panel / command / hotkey / setting / about-badge / toolbar) + toast / notify inline carve-out
  • defineNode / defineWidget with reduced surfaces (NodeHandle.getWidget(s) removed per A1 bilateral; WidgetHandle.setSerializeEnabled removed per A16; runtime addWidget banned per A15)
  • Event surface: widget.on('valueChange' | 'beforeSerialize'), node.on(...) lifecycle
  • Bootstrap: defineExtension + setup / mount hooks

Re-open criteria

Either (1) a new ACCEPTED ADR with axiom-compliance verification, or (2) Phase B trigger (#11939 merges).

Next up — Phase B

Kickoff tracking: #12394.
First Phase B work: defineWidgetAugmenter (PROPOSED ADR D-define-widget-augmenter — unblocks dynamicPrompts.v2 stub + Pattern 3 cross-node sync).

Live frozen-surface dashboard

https://comfyui-frontend-ecosystem.vercel.app (marker commit cf0cf88 on the ecosystem repo surfaces this checkpoint in the Vercel deploy log).

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)
Connor Byrne added 2 commits May 20, 2026 20:07
- 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.
@christian-byrne

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor
⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@DrJKL DrJKL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

jaeone94 pushed a commit to jaeone94/ComfyUI_frontend that referenced this pull request Sep 16, 2026
…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)

![Clipboard failure with retry and manual
copy](https://ampcode.com/user-content/artifacts/365e2bfbb79ff7ee9d04297d6a8c434c24376bfe146f0251be3c0dd4e007b3f4-file.png)

<!-- authored-by:agent role-external-context-watcher -->

---------

Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Alexander Brown <drjkl@comfy.org>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants