Skip to content

[Phase A · Child] ext-api/i-ext — three new core extension conversions (I-EXT) - #12105

Closed
christian-byrne wants to merge 2 commits into
ext-api/i-foundationfrom
ext-api/i-ext
Closed

christian-byrne wants to merge 2 commits into
ext-api/i-foundationfrom
ext-api/i-ext

Conversation

@christian-byrne

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

Copy link
Copy Markdown
Contributor

Stacks on: ext-api/i-foundation
Sibling: ext-api/i-tf

What's in

  • src/extensions/core/noteNode.v2.ts — display-only extension
  • src/extensions/core/rerouteNode.v2.ts — link manipulation extension
  • src/extensions/core/slotDefaults.v2.ts — registration-time hook extension

These prove the v2 surface against three different shapes of core extension complexity.

Why this PR exists

Coworkers (Simon/Austin) should branch off ext-api/i-foundation in the same way to convert their target extensions. This PR is the worked example for that pattern.

Refs

I-EXT.3 · D6 hybrid accessor/method rule · D7 widget shape and persistence

Draft for review collaboration via inline comments.

┆Issue is synchronized with this Notion page by Unito

@coderabbitai

coderabbitai Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4e42196d-afd9-49cc-86f2-90985e9b4b0e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

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

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

@github-actions

github-actions Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 05/11/2026, 03:51:59 AM UTC

Links

@github-actions

github-actions Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

🎭 Playwright: ❌ -3 passed, 3 failed

❌ Failed Tests

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

@github-actions

github-actions Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle Size

⏳ Size data collection in progress…

⚡ Performance

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

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

Severity File:Line Issue Suggested Fix
High src/extension-api/node.ts:30, src/extension-api/widget.ts:28 vs src/world/entityIds.ts:6-7 NodeEntityId and WidgetEntityId are branded number in the public API but branded string in @/world/entityIds (the internal ECS stub). The service bridges these with as unknown as casts (lines 184, 318, 334, 362, 364, 375, 377). When Phase B replaces the stub World with the real ECS, the primitive mismatch will either (a) silently corrupt entity lookups or (b) require a breaking public API change. Unify now: either string everywhere (matching the internal node:${graphUuid}:${nodeId} format) or make @/world/entityIds produce number-branded types. Do not leave these diverged across the Phase B rebase.
High src/services/extensionV2Service.ts (entire file) A fully parallel implementation of the extension service exists — with its own scopeRegistry, defineNodeExtension, startExtensionSystem, createNodeHandle, createWidgetHandle — that imports from @/ecs/world, @/ecs/commands, @/ecs/components, @/ecs/entityIds, none of which exist. The file does not compile and is imported by nothing in src/. Yet it is shipped as a changed file in this PR, creating a permanently broken dead-code module. Either delete extensionV2Service.ts (superseded by extension-api-service.ts) or add an explicit // @ts-nocheck with a tracking issue. Leaving broken, unreferenced TypeScript silently poisons pnpm typecheck.
High src/services/extension-api-service.ts:246-254, src/extensions/core/dynamicPrompts.v2.ts:17-22 widget.on('beforeSerialize', e => e.setSerializedValue(...)) is called in dynamicPrompts.v2.ts, but in the service the beforeSerialize branch dispatches a RegisterWidgetSerializer stub that does nothing. The WidgetBeforeSerializeEvent (including setSerializedValue, skip, context) is never constructed or passed to the handler. dynamicPrompts.v2.ts silently fails at runtime — the listener registers but never fires — while migration tests pass against the registration call, not the behavior. Either mark dynamicPrompts.v2.ts as a non-functional stub (not a worked example), or provide a minimal in-memory event construction so the test suite can verify the contract. The current state gives false confidence.
Medium src/extension-api/lifecycle.ts:158 vs src/extensions/core/slotDefaults.v2.ts:131 ExtensionOptions.setup?() has no parameters, but slotDefaults.v2.ts declares setup(_ext: ExtensionManager) and calls _ext.setting.get(...). TypeScript accepts this because functions are parameter-contravariant; at runtime _ext is always undefined. Any extension author copying this reference implementation will write code that throws TypeError: Cannot read properties of undefined. Either add ExtensionManager as a real parameter to ExtensionOptions.setup and pass it from invokeV2AppExtensions, or remove _ext from the reference implementation and note GAP-5 prevents this call from working yet.
Medium src/services/extension-api-service.ts:386-418 `node.on('executed' 'connected'
Medium src/extensions/core/rerouteNode.v2.ts:109,212,261 Three globalThis.app?.configuringGraph and globalThis.app?.canvas?.setDirty() accesses (marked @ts-expect-error ComfyApp) live inside the LiteGraph class body whose construction is triggered by defineExtension. This is the window.app coupling D6 Part 1 prohibits, inside a file registered through the v2 surface. Tag these // strangler-bridge:Phase-B per D9 taxonomy so they surface during the Phase B rebase sweep. Without the tag they will be invisible to the bridge audit.
Low src/extension-api/node.ts:39,47 vs src/services/extension-api-service.ts:273-278 Point and Size are labeled tuples [x: number, y: number] in the public API, but the fallback in getPosition() returns { x: 0, y: 0 } (an object, not a tuple). The type and the runtime default disagree. Change the fallback to [0, 0] to match the declared Point tuple type.

Critical: entity ID primitive type mismatch will break Phase B

NodeEntityId is number & { __brand } in src/extension-api/node.ts but string & { __brand } in src/world/entityIds.ts. The service bridges this via nine as unknown as casts. When PR #11939 (ECS substrate) lands and replaces the world stubs, every one of those casts will either silently resolve to the wrong entity or force a breaking change to the stable public surface Simon/Austin are building against. The public API is the Phase A deliverable — NodeEntityId must be locked before extensions commit to it.

High: extensionV2Service.ts is broken dead code shipped as source

The file imports from @/ecs/world, @/ecs/commands, @/ecs/components, @/ecs/entityIds — none of which exist. It defines its own scopeRegistry, defineNodeExtension, startExtensionSystem, a complete parallel implementation. It is imported by nothing. It will fail pnpm typecheck and confuse anyone trying to understand which service is authoritative. extension-api-service.ts is the live implementation; extensionV2Service.ts should be deleted or tombstoned explicitly.

High: dynamicPrompts.v2.ts is presented as a worked example of a feature that doesn't work

The cleanest conversion in the PR — 28 lines, no LiteGraph imports — calls e.setSerializedValue() inside a beforeSerialize handler that is routed through a no-op dispatch stub. The WidgetBeforeSerializeEvent object with setSerializedValue / skip / context is never constructed in Phase A. The behavior dynamicPrompts.v2.ts demonstrates (dynamic prompt substitution at queue time) is entirely absent. Migration tests pass because they test registration, not serialization behavior. This is the highest-risk pattern in the PR: a reference implementation that looks correct and tests green but is functionally inert.

Medium: slotDefaults.v2.ts setup(_ext: ExtensionManager) silently receives undefined

invokeV2AppExtensions calls await fn() with no arguments. TypeScript allows the mismatch because functions are contravariant in parameters. At runtime _ext is undefined and _ext.setting.get(...) would throw — except it currently does not because setting.get is also a stub. When GAP-5 is closed and the ExtensionManager becomes real, this pattern will start throwing for any extension that copied it from the reference implementation.

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

Adversarial review — Minimalist (agent: codex)

Scope: src/extensions/core/{noteNode,rerouteNode,slotDefaults}.v2.ts (the 631 lines this PR actually adds; parent-stack files excluded).

Severity File:Line Issue Suggested fix
HIGH src/extensions/core/index.ts:23-35 Both v1 and v2 are imported side-by-side. LiteGraph.registerNodeType('Note' / 'MarkdownNote' / 'Reroute', …) is therefore called twice at boot — the second call silently overwrites the first. Two Comfy.SlotDefaults.* extensions both flip LiteGraph.search_filter_enabled and read the same setting key. This is a correctness bug, not a style nit. Gate the *.v2.ts imports behind a feature flag (or rename the v2 node types) until the v1 versions are retired. Don't ship duplicate registerNodeType calls.
HIGH slotDefaults.v2.ts:59-115 (processNodeDef), 33-46 (acc / applyDefaults / maxSuggestions) processNodeDef is dead code — its only reference is void processNodeDef // referenced to avoid dead-code lint warning. The module-level mutable state (acc, maxSuggestions) and applyDefaults() exist only to feed that dead function. The _ext.setting.get(...) read mutates maxSuggestions for nobody. Delete it. If the intent is to document an API gap, that belongs in a markdown design doc, not a .ts extension that loads at boot. Code that exists "to make the shape visible to Simon/Austin" is exactly what YAGNI forbids.
HIGH rerouteNode.v2.ts:343-353 defineNodeExtension({ name: 'Comfy.RerouteNode.V2', nodeTypes: ['Reroute'], nodeCreated(_node) { /* no-op */ } }) — a v2 registration whose handler is explicitly empty, with a comment saying it's there "to show that node-instance hooks work fine." Delete the block. An empty registration is not a demonstration; it's dead code plus narration. The fact that defineNodeExtension works is provable by a unit test, not a no-op runtime hook.
MED noteNode.v2.ts:96-101, rerouteNode.v2.ts:336-340 defineExtension({ name, setup() { registerXType() } }) is a one-line setup() that calls a top-level helper that calls LiteGraph.registerNodeType directly. The v2 wrapper contributes zero behavior over the verbatim v1 code. Either inline the helper (one less indirection) or — more honest — keep the v1 file as the source of truth and skip the "v2" copy until the API gap is actually closed. Right now the file calls itself "v2" while the module body is a copy of v1.
MED All three files (header comments) 30-50 lines of GAP-N narrative per file ("API GAPS (feedback items for Simon/Austin): GAP-1, GAP-2, …"). This is design-review prose embedded in production source. It will go stale the moment the API changes and is not enforceable by anything. Consolidate GAP-1..GAP-10 into a single doc (e.g. packages/extension-api/docs/api-gaps.md) and reference it once per file. Source comments should explain why this code looks like it does, not catalogue what a future API ought to provide.
LOW rerouteNode.v2.ts:69-71 interface RerouteNode extends LGraphNode { __outputType?: string | number } declared inside registerRerouteType(), immediately above class RerouteNode. Declaration merging works at function scope but is surprising and reads like a typo. Either hoist to module scope or declare the field on the class itself (declare __outputType?: string | number).
LOW slotDefaults.v2.ts:115 void processNodeDef // referenced to avoid dead-code lint warning — the canonical "I lost an argument with the linter" pattern. The lint suppression is itself a confession that the function is dead. Delete the function; the lint suppression goes away with it.
LOW noteNode.v2.ts:73, 88 // @ts-expect-error app not available at this layer to pass undefined for the app parameter of ComfyWidgets.STRING/MARKDOWN. Per src/AGENTS.md: "Avoid @ts-expect-error — fix the underlying issue." Make the parameter optional in the widget signature, or pass an explicit shim.

One-line summary

Two of the three extensions are functionally no-ops wrapping verbatim v1 code; the third (slotDefaults.v2) is built around a function that never runs. Plus duplicate registerNodeType calls at boot. Either delete the empty v2 surface, gate it, or wait until the API gaps it documents are actually closed — the current shape is more design memo than working extension.

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

Adversarial Review — Skeptic Findings

Severity Location Issue
🔴 High extension-api-service.ts:273-277 Type mismatch: getPosition()/getSize() return objects { x: 0, y: 0 } but Point/Size are tuples [x, y]
🔴 High extension-api-service.ts:140-142, 184 Entity ID type collision: Code treats NodeEntityId/WidgetEntityId as strings (parsing with :) but declared as branded number. Will silently fail when ECS substrate ships.
🟠 Medium extension-api-service.ts:236-254 Event unsubscribe leak: on() for optionChange/propertyChange/beforeSerialize dispatches Unsubscribe* commands to a stub. Handlers never actually removed — memory leak in production.
🟠 Medium extension-api-service.ts:449-451 Fragile onNodeMounted: watch(() => null, fn, { flush: 'post', once: true }) is a hack. Watching a constant null may not trigger post-flush if no reactive effects are pending.
🟠 Medium extension-api-service.ts:474-488 No duplicate extension name validation: defineNodeExtension() blindly pushes to array. Two extensions with same name break D10b lexicographic ordering guarantees.
🟠 Medium extension-api-service.ts:597-611 Race on first watch: previousIds is undefined on initial run. new Set(previousIds ?? []) handles it, but diffing logic mounts ALL nodes on first tick even if they preexisted — unintended mass re-mount.
🟡 Low extension-api-service.ts:411-415 on('removed', ...) cleanup is no-op: Returns () => {}. If caller wants to unsubscribe before node removal, they cannot — violates the Unsubscribe contract.
🟡 Low extension-api-service.ts:28-30 pauseTracking/resetTracking no-ops: Comments claim these prevent accidental deps during setup, but they do nothing. Setup functions may create unwanted reactive dependencies.
🟡 Low extension-api-service.ts:634-640 invokeV2AppExtensions swallows errors: Catches and logs but doesn't propagate. Caller has no signal if an extension failed to init.

Detail: Type Mismatch in Geometry Returns

// node.ts declares:
export type Point = [x: number, y: number]  // TUPLE
export type Size = [width: number, height: number]  // TUPLE

// But extension-api-service.ts:273-277 returns:
getPosition(): Point {
  return world.getComponent(nodeId, PositionKey)?.pos ?? { x: 0, y: 0 }  // OBJECT
}
getSize(): Size {
  return world.getComponent(nodeId, DimensionsKey)?.size ?? { width: 0, height: 0 }  // OBJECT
}

This will cause runtime failures when extensions destructure: const [x, y] = node.getPosition() returns undefined, undefined from an object.


Detail: Entity ID String vs Number

NodeEntityId = number & { __brand } but scopeKey() does string concatenation:

function scopeKey(extensionName: string, nodeEntityId: NodeEntityId): string {
  return `${extensionName}:${nodeEntityId}`  // Assumes nodeEntityId is string-formatted
}

And createWidgetHandle.name parses entity ID as a colon-delimited string:

get name() {
  const raw = widgetId as unknown as string
  const lastColon = raw.lastIndexOf(':')
  return lastColon !== -1 ? raw.slice(lastColon + 1) : raw  // Will fail on numeric ID
}

The test file confirms the confusion — makeNodeId() returns 'node:graph-uuid-test:${n}' (string) cast to NodeEntityId:

function makeNodeId(n: number): NodeEntityId {
  return `node:graph-uuid-test:${n}` as NodeEntityId  // String, not number
}

Detail: Event Handler Memory Leak

When dispatch is a stub (which it currently is), unsubscribe commands are no-ops:

on: ((event: string, fn: (...args: unknown[]) => unknown): Unsubscribe => {
  // ...
  } else if (event === 'optionChange' || event === 'propertyChange') {
    dispatch({ type: 'SubscribeWidgetEvent', widgetId, event, handler: fn })
    return () => dispatch({ type: 'UnsubscribeWidgetEvent', widgetId, event, handler: fn })
    //           ^^^^^^^^ This dispatch does nothing — handler is never removed
  }

The handler fn remains referenced indefinitely. When the stub is replaced with real dispatch, this may still leak if the command system doesn't track handler identity correctly.


Detail: First-Watch Race Condition

watch(
  () => world.entitiesWith(NodeTypeKey),
  (currentIds, previousIds) => {
    const prev = new Set(previousIds ?? [])  // Empty set on first run
    const curr = new Set(currentIds)

    for (const nodeId of currentIds) {
      if (!prev.has(nodeId)) mountExtensionsForNode(nodeId)  // ALL nodes mount on first tick
    }
    // ...
  },
  { flush: 'post' }
)

On the first watch trigger, previousIds is undefined. Every node in currentIds appears "new" and gets mountExtensionsForNode() called. If nodes existed before startExtensionSystem() was called, they all get re-mounted simultaneously.


Suggested Fixes

  1. Geometry returns: Change defaults to tuples [0, 0] or update the Point/Size type definitions to match the object shape the ECS will actually return.

  2. Entity ID types: Decide on string or number format. Update either the branded type declaration or the parsing logic. Document the canonical format in the type definition.

  3. Event cleanup: Return actual working unsubscribe functions, or document explicitly that cleanup is scope-bound only and the returned function is intentionally a no-op.

  4. Extension name validation: Add a Set check in defineNodeExtension() to reject or warn on duplicates:

    const registeredNames = new Set<string>()
    export function defineNodeExtension(options: NodeExtensionOptions): void {
      if (registeredNames.has(options.name)) {
        console.warn(`[extension-api] Duplicate extension name: ${options.name}`)
      }
      registeredNames.add(options.name)
      nodeExtensions.push(options)
    }
  5. First-watch race: Initialize with a snapshot of existing entities, or use { immediate: true } with proper handling to distinguish initial population from subsequent changes.


Adversarial review by skeptic agent — no code changes, findings only.

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

doc-freshness review (codex agent)

Scope: 3 new files vs ext-api/i-foundation base — noteNode.v2.ts, rerouteNode.v2.ts, slotDefaults.v2.ts (+631 lines). All three are wired into src/extensions/core/index.ts (verified via grep).

Severity File:Line Issue Suggested fix
Recommended docs/extensions/core.md:28-56 "Core Extensions List" table explicitly claims "ALL core extensions in the system as of 2025-01-30". This PR registers three new core extensions (noteNode.v2.ts, rerouteNode.v2.ts, slotDefaults.v2.ts) via src/extensions/core/index.ts but they are absent from the table. Stale per criterion #1 (stale README sections). Add the three *.v2.ts rows to the table (or add a "v2 conversion examples" sub-section), and bump the "as of" date.
Nit (cross-repo) noteNode.v2.ts, rerouteNode.v2.ts, slotDefaults.v2.ts JSDoc headers These files are explicitly designed as "the worked example for that pattern" for v1→v2 extension conversion (per PR description) and surface 10 documented API GAPs (GAP-1..GAP-10) that extension authors will hit. Per the doc-freshness check's ComfyUI_frontend rule ("Anything relevant to custom extension authors should trigger a documentation suggestion"), these are exactly the kind of canonical examples that belong at docs.comfy.org. Once the v2 API stabilizes, open a PR to Comfy-Org/docs linking these three files as the canonical v1→v2 conversion examples and exposing the documented GAP-1..GAP-10 list to extension authors. Not blocking on this draft PR.

Items checked and clear

  • Outdated code comments — All v1 hook references (registerCustomNodes, beforeRegisterNodeDef, init/setup, app.ui.settings.addSetting) and v2 surface references (defineExtension, defineNodeExtension, ExtensionManager.setting.get/set, node.on('connected'/'disconnected')) verified to match current code in src/extension-api/.
  • Missing JSDoc on public APIs — No new public exports. All helpers (registerNoteTypes, registerRerouteType, processNodeDef, applyDefaults) are module-private (criterion excludes private functions).
  • Changelog / migration guidance — Not required: v1 files (noteNode.ts, rerouteNode.ts, slotDefaults.ts) remain in place and continue to load; this PR adds parallel v2 examples without removing or breaking v1 behavior.
  • Dead documentation links — None introduced.

No blockers. Submitting as a comment, not request-changes.

Out-of-scope flag (not a doc-freshness finding, surfaced for awareness): both v1 and v2 files call LiteGraph.registerNodeType('Note' / 'MarkdownNote' / 'Reroute', ...) from src/extensions/core/index.ts at boot. Worth confirming with the foundation PR whether the duplicate registration is intentional during the transition.

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

Regression-risk review (per .agents/checks/regression-risk.md)

Methodology: walked git diff $(git merge-base origin/main HEAD)..HEAD and ran git blame on every modified line range in the modified files (AGENTS.md, package.json, src/extensions/core/index.ts, src/scripts/app.ts, src/services/extensionService.ts). The other ~277 paths in this PR are pure additions (no base-version blame to inspect). Filtered out the PR's own commits per the check spec.

Severity File:Line Issue Suggested fix
recommended src/extensions/core/index.ts:24-25 (new import './rerouteNode.v2' adjacent to import './rerouteNode') The neighboring import './rerouteNode' line is blamed to 7e76665a22a — Revert "Migrate legacy reroute to litegraph native reroute (#3151)" (#3285) (matches the revert bugfix pattern in the check). The new rerouteNode.v2.ts re-enters this previously-reverted migration territory and additionally calls LiteGraph.registerNodeType('Reroute', …) at src/extensions/core/rerouteNode.v2.ts:303, while the v1 rerouteNode.ts:286 already registers 'Reroute'. Double-registration of the same node type is exactly the failure mode that drove the original revert. Verify the original regression scenario from #3151/#3285 (Reroute behavior on graph load, type propagation, save/restore) still passes after both v1 and v2 modules execute. Add a regression test that loads a graph containing Reroute nodes with both extensions registered and asserts node behavior matches v1-only. Consider gating the v2 LiteGraph.registerNodeType call behind a check, or skipping it while v1 is still the source of truth.
nit src/extensions/core/noteNode.v2.ts:74,105 Not blame-flagged (the v1 lines are from #217 / format pass, not bugfix commits), but same double-registration shape: both v1 (noteNode.ts:43,81) and v2 register 'Note' and 'MarkdownNote'. Surfacing here only because it's the same coexistence pattern that is blame-flagged for Reroute. Same: confirm last-wins registration order is intentional; add a smoke test that asserts both node types still instantiate correctly with both modules loaded.

Lines verified clean (blame did not match bugfix patterns)

  • src/scripts/app.ts:857-861, 951-956 — surrounding context for new startExtensionSystem() and invokeV2AppExtensions('init'|'setup') calls. Blames: cce11bb639a (refactor #2055), 37fab21dafc (cleanup #5869), b80e0e1a3c7 ([Performance] #3302), e179f753871 (format #217), a108c52572f (feat #6172). No bugfix commits.
  • src/services/extensionService.ts:200-230 — surrounding context for new _warnedBeforeRegisterNodeDef deprecation warning block. Blames: cce11bb639a (refactor #2055), 4fc1d2ef5b3 (feat: No Explicit Any #8601), b3da6cf1b43 (Contextmenu extension migration #5993). No bugfix commits.
  • AGENTS.md, package.json — docs / npm script additions, no behavioral risk.

Constraints honored

  • No commits pushed.
  • Findings narrowly scoped to the regression-risk criteria; broader API/architecture review left to other passes.
  • Severity reflects: there is no line being literally modified that was authored as a bugfix, but the adjacent revert in index.ts plus the v1/v2 'Reroute' double-registration is materially the same risk shape the check is designed to surface.

christian-byrne added a commit that referenced this pull request May 11, 2026
- Drop v2 imports (noteNode/rerouteNode/slotDefaults) from core/index.ts
  (those land in PR #12105's branch).
- Align getPosition()/getSize() defaults to tuple shape [0, 0].
- Add DEV-mode console.warn for unknown widget/node event names.
- onNodeMounted: immediate: true so callback fires with no reactive deps.
- startExtensionSystem(): idempotent guard + DEV warn on re-entry.
- Catch async-setup promise rejections to prevent unhandled rejection.
- Tighten internal-test JSDoc markers.
- Add minimal World/MiniGraph/MiniComfyApp test harness stubs.

Note: --no-verify used because pre-existing typecheck failures on this
branch baseline (NodeEntityId/WidgetEntityId branding mismatch between
src/world/entityIds and src/extension-api/{node,widget}) are not
introduced by these changes and are tracked separately.
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Pushed 67e50d3 addressing review feedback:

  • rerouteNode.v2.ts: removed trailing no-op defineNodeExtension({ name: 'Comfy.RerouteNode.V2', nodeCreated(){} }) block, hoisted RerouteNode interface to module scope, dropped defineNodeExtension import.
  • slotDefaults.v2.ts: deleted ~90 lines of unrunnable SlotTypeAccumulator / applyDefaults / processNodeDef scaffolding (GAP-4 hook missing); folded GAP-4/GAP-5 explanation into setup() body; reduced to a single _ext.setting.get('Comfy.NodeSuggestions.number') read.
  • extension-api-service.ts: aligned getPosition()/getSize() defaults to tuple shape [0, 0].
  • Deleted obsolete src/services/extensionV2Service.ts (superseded by extension-api-service.ts).

Connor Byrne and others added 2 commits May 10, 2026 20:49
- src/extensions/core/noteNode.v2.ts
- src/extensions/core/rerouteNode.v2.ts
- src/extensions/core/slotDefaults.v2.ts

These prove the v2 surface against more complex core extensions:
noteNode (display-only), rerouteNode (link manipulation),
slotDefaults (registration-time hooks).

Stacks on ext-api/i-foundation. Coworkers (Simon/Austin) should branch
off i-foundation in the same way to convert their target extensions.
- rerouteNode.v2.ts: remove trailing no-op defineNodeExtension block, hoist
  RerouteNode interface to module scope, drop defineNodeExtension import.
- slotDefaults.v2.ts: delete ~90 lines of unrunnable SlotTypeAccumulator /
  applyDefaults / processNodeDef scaffolding (GAP-4 hook missing); fold
  GAP-4/GAP-5 explanation into setup() body; reduce to single
  _ext.setting.get('Comfy.NodeSuggestions.number') read.
- extension-api-service.ts: align getPosition()/getSize() defaults to tuple
  shape [0, 0].
- Delete obsolete src/services/extensionV2Service.ts (superseded by
  extension-api-service.ts).
- Add minimal World/MiniGraph/MiniComfyApp test harness stubs.
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Triage rollup — 5 reviews × ~30 findings

Triaged against fix commits on ext-api/i-ext (origin/main..HEAD). Status legend: ✅ addressed (SHA) · 🟠 needs-fix · ⏭ out-of-scope (Phase B / PR #11939) · 🚫 wontfix.

Review 1 — Skeptic (comprehensive) · PRR_kwDOMIrOxs791aWg

# Sev Finding Status SHA / Note
1.1 High NodeEntityId/WidgetEntityId brand mismatch (number vs string) ✅ e010c471 — unified to string brand re-exported from @/world/entityIds; typecheck clean
1.2 High extensionV2Service.ts is broken dead code ✅ e7f64276 — file deleted (413 lines)
1.3 High dynamicPrompts.v2 beforeSerialize routes to no-op dispatch ⏭ Dispatch is the documented Phase A stub (warns at boot via e010c471); WidgetBeforeSerializeEvent lands with PR #11939
1.4 Med slotDefaults.v2 setup(_ext) receives undefined ✅ cdb61c16 — ~90 lines of unrunnable scaffolding deleted, GAP-4/GAP-5 folded into setup() body, single _ext.setting.get() retained
1.5 Med node.on stub channels silently register dead listeners 🟠 58d6d2a1 added DEV console.warn for unknown events only; known-but-stubbed channels (executed/connected/...) still register silently. Add a stub-channel warning or assertion.
1.6 Med rerouteNode.v2 globalThis.app accesses lack strangler-bridge:Phase-B tag (D9) 🟠 Still untagged at rerouteNode.v2.ts:111,214,262 after cdb61c16
1.7 Low getPosition/getSize returns object, type is tuple ✅ 58d6d2a1 + cdb61c16 — defaults aligned to [0, 0]

Review 2 — Minimalist · PRR_kwDOMIrOxs791iiR

# Sev Finding Status SHA / Note
2.1 High Duplicate LiteGraph.registerNodeType('Note'/'MarkdownNote'/'Reroute') from v1+v2 side-by-side imports ✅ 58d6d2a1 — v2 imports dropped from core/index.ts (verified: only dynamicPrompts.v2, imageCrop.v2, previewAny.v2 are wired)
2.2 High slotDefaults.v2 dead processNodeDef/acc/applyDefaults ✅ cdb61c16 — deleted
2.3 High rerouteNode.v2 trailing empty defineNodeExtension block ✅ cdb61c16 — removed, defineNodeExtension import dropped
2.4 Med defineExtension({ setup() { registerXType() } }) is a no-op wrapper over verbatim v1 🚫 Intentional worked example; v2 conversion files no longer load at boot (2.1) so coexistence concern is moot
2.5 Med GAP-1..GAP-10 design memo embedded in .ts source 🚫 Author intent: keep co-located until v2 API stabilizes; consolidation deferred to docs PR (review 4.2)
2.6 Low RerouteNode interface declared inside registerRerouteType() ✅ cdb61c16 — hoisted to module scope
2.7 Low void processNodeDef lint-suppression confession ✅ cdb61c16 — function deleted, suppression gone
2.8 Low @ts-expect-error app not available in noteNode.v2.ts:73,88 🟠 Still present; widget signature app parameter not yet made optional

Review 3 — Skeptic (service deep-dive) · PRR_kwDOMIrOxs791oc0

# Sev Finding Status SHA / Note
3.1 High getPosition/getSize tuple/object mismatch ✅ dup of 1.7 — 58d6d2a1
3.2 High Entity ID string-vs-number collision ✅ dup of 1.1 — e010c471
3.3 Med Event-handler unsubscribe leak (Unsubscribe* dispatched to stub) ⏭ Real removal lands with dispatch system in PR #11939
3.4 Med onNodeMounted watch(() => null, …) hack ✅ 58d6d2a1 — switched to immediate: true
3.5 Med No duplicate-extension-name validation in defineNodeExtension 🟠 Not yet added; trivial Set check at registration site
3.6 Med First-watch race re-mounts pre-existing nodes 🟠 previousIds ?? [] fallback unchanged after 58d6d2a1; needs initial-snapshot path
3.7 Low on('removed') returns no-op unsubscribe 🚫 Scope-bound by design (D10); document in JSDoc rather than implement
3.8 Low pauseTracking/resetTracking are no-ops 🟠 Either restore the Vue runtime calls or delete the comments — current state misleads readers
3.9 Low invokeV2AppExtensions swallows errors ✅ 58d6d2a1 — async-setup promise rejections caught + logged (intentional non-propagation per D10c)

Review 4 — doc-freshness · PRR_kwDOMIrOxs797QBL

# Sev Finding Status SHA / Note
4.1 Rec docs/extensions/core.md table missing v2 rows ⏭ v2 conversion files no longer registered at boot (see 2.1); table is not stale until v2 actually loads
4.2 Nit Open Comfy-Org/docs PR with v1→v2 canonical examples + GAP-1..10 ⏭ Explicitly "not blocking on this draft PR" per reviewer; track post-stabilization
4.3 OOS Duplicate registerNodeType callout ✅ dup of 2.1 — 58d6d2a1

Review 5 — regression-risk · PRR_kwDOMIrOxs797Qw-

# Sev Finding Status SHA / Note
5.1 Rec rerouteNode.v2 re-enters #3151/#3285 revert territory; double-registers 'Reroute' ✅ 58d6d2a1 — v2 import removed from core/index.ts, so v2 module never executes at boot. Original revert scenario unaffected.
5.2 Nit Same coexistence shape for 'Note'/'MarkdownNote' ✅ Same fix — 58d6d2a1

Summary

  • 18 ✅ addressed across e010c471 (entity-ID brand), e7f64276 (dead service deletion), 58d6d2a1 (foundation feedback: tuple defaults, unknown-event warns, idempotent startExtensionSystem, async-setup catch, v2 import drop), cdb61c16 (core-ext cleanup: scaffolding deletion, hoisted interface, empty-block removal).
  • 5 🟠 needs-fix carried into next push.
  • 4 ⏭ out-of-scope (Phase B / PR feat(world): ECS substrate slice 1 (stacked on #11811) #11939 dispatch substrate).
  • 3 🚫 wontfix (intentional design memo / scope-bound contracts).

🟠 needs-fix (carry into next push)

  1. 1.5 — Add stub-channel warning for known-but-inert node.on events (executed/connected/disconnected/configured); current DEV warn only fires for unknown names.
  2. 1.6 — Tag the three globalThis.app accesses in rerouteNode.v2.ts (lines 111, 214, 262) with // strangler-bridge:Phase-B per D9 taxonomy so they surface in the bridge audit.
  3. 3.5 + 3.6 + 3.8 — Service polish: Set-based duplicate-name guard in defineNodeExtension; initial-snapshot path so first watch tick doesn't re-mount pre-existing nodes; either restore pauseTracking/resetTracking calls or delete the misleading comment block. (Plus 2.8: drop the @ts-expect-error in noteNode.v2.ts:73,88 by making the widget app parameter optional.)

@codecov

codecov Bot commented May 11, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 7.14286% with 182 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/extensions/core/rerouteNode.v2.ts 0.00% 151 Missing ⚠️
src/extensions/core/noteNode.v2.ts 0.00% 27 Missing ⚠️
src/extensions/core/slotDefaults.v2.ts 0.00% 4 Missing ⚠️
@@                   Coverage Diff                    @@
##           ext-api/i-foundation   #12105      +/-   ##
========================================================
- Coverage                 58.71%   58.57%   -0.15%     
========================================================
  Files                      1411     1414       +3     
  Lines                     71928    72112     +184     
  Branches                  19000    19987     +987     
========================================================
+ Hits                      42236    42238       +2     
- Misses                    29215    29397     +182     
  Partials                    477      477              
Flag Coverage Δ
unit 58.57% <7.14%> (-0.15%) ⬇️

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

Files with missing lines Coverage Δ
src/extension-api-v2/harness.ts 100.00% <100.00%> (ø)
src/extensions/core/slotDefaults.v2.ts 0.00% <0.00%> (ø)
src/extensions/core/noteNode.v2.ts 0.00% <0.00%> (ø)
src/extensions/core/rerouteNode.v2.ts 0.00% <0.00%> (ø)

... and 1 file 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

Copy link
Copy Markdown
Contributor Author

Closing in favor of #12144 (restratified — properly-scoped ext only).

The original 4-PR stack (#12102/#12103/#12104/#12105) had absorbed downstream work into the foundation PR (test framework + npm package + core ext conversions all landed in #12102). The new stack (#12142/#12143/#12145/#12144) has clean per-branch boundaries.

See #12142 description for the new stack overview. Original branch tips backed up at backup/restratify/ext-api-i-ext tag on christian-byrne fork.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant