Repository navigation
[Phase A · Foundation] ext-api/i-foundation — declarations + service rename + scope registry - #12102
christian-byrne wants to merge 10 commits into
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThis PR establishes a typed, publishable Extension API v2 (with barrel entry), a detailed handle/lifecycle/event service, stubs for ECS/world/entity integration, full shell/UI/option/event contract surfaces, upgrades core extensions to v2, wires app bootstrap through new services, brings a robust test harness, full backward-compat/migration test matrix, dedicated CI/docs tooling, and extensive cross-layer naming documentation. ChangesExtension API v2: Public Surface, Core, Compatibility/Migration Test System, ECS, CI, and Naming Docs
Sequence Diagram(s)sequenceDiagram
AppBootstrap->>ExtensionAPIService: startExtensionSystem(), invokeV2AppExtensions()
ExtensionAPIService->>ECSWorld: entitiesWith(NodeTypeKey)
ExtensionAPIService->>ExtensionCoreV2: mount extension scopes, run v2 hooks
ExtensionAPIService->>TestHarness: expose handles/APIs for contract tests
Estimated code review effort🎯 5 (Critical) | ⏱️ ~120 minutes Poem
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
|
🎨 Storybook: ✅ Built — View Storybook |
🎭 Playwright: ❌ -3 passed, 3 failed❌ Failed Tests📊 Browser Reports
|
📦 Bundle: 5.31 MB gzip 🔴 +4.2 kBDetailsSummary
Category Glance App Entry Points — 31.6 kB (baseline 31.6 kB) • ⚪ 0 BMain entry bundles and manifests
Status: 1 added / 1 removed Graph Workspace — 1.24 MB (baseline 1.24 MB) • 🔴 +1 BGraph editor runtime, canvas, workflow orchestration
Status: 1 added / 1 removed Views & Navigation — 82.4 kB (baseline 82.4 kB) • ⚪ 0 BTop-level views, pages, and routed surfaces
Status: 11 added / 11 removed Panels & Settings — 491 kB (baseline 491 kB) • ⚪ 0 BConfiguration panels, inspectors, and settings screens
Status: 10 added / 10 removed / 12 unchanged User & Accounts — 17.6 kB (baseline 17.6 kB) • ⚪ 0 BAuthentication, profile, and account management bundles
Status: 7 added / 7 removed Editors & Dialogs — 112 kB (baseline 112 kB) • ⚪ 0 BModals, dialogs, drawers, and in-app editors
Status: 4 added / 4 removed UI Components — 62.9 kB (baseline 62.9 kB) • ⚪ 0 BReusable component library chunks
Status: 14 added / 14 removed Data & Services — 3.15 MB (baseline 3.13 MB) • 🔴 +14 kBStores, services, APIs, and repositories
Status: 17 added / 17 removed Utilities & Hooks — 367 kB (baseline 367 kB) • ⚪ 0 BHelpers, composables, and utility bundles
Status: 20 added / 20 removed / 11 unchanged Vendor & Third-Party — 9.94 MB (baseline 9.94 MB) • 🔴 +36 BExternal libraries and shared vendor chunks
Status: 6 added / 6 removed / 10 unchanged Other — 8.98 MB (baseline 8.98 MB) • 🔴 +2.32 kBBundles that do not match a named category
Status: 92 added / 92 removed / 44 unchanged ⚡ Performance
|
Adds the v2 extension API public surface:
src/types/extensionV2.ts (169 lines) — branded entity IDs,
geometry primitives, slot/widget options, NodeHandle/WidgetHandle
contracts. Pure types. The stable public surface extensions depend on.
src/services/extensionV2Service.ts (413 lines) — surface-only impl.
Thin pass-throughs to existing LGraphNode/widget/canvas. No new
internal architecture; no patching guards yet (Phase A scope per D9).
Reactive mounting via Vue EffectScope; scope registry keyed by
extension:entityId.
src/extensions/core/{dynamicPrompts,imageCrop,previewAny}.v2.ts
Three smallest core extensions ported as proof-of-concept. Used
as the I-COORD.1 reference for Simon + Austin to push back on
the API shape with concrete code.
Phase A goals (per todo.md "Branch + phasing topology"):
- Stable v2 surface coworkers can branch off
- Internal methods are pass-throughs (no behavior change)
- I-PG.A: no interception/blocking; v1 path coexists unchanged
Stacks under this branch (will be opened as draft PRs):
- ext-v2/i-tf-test-framework
- ext-v2/i-sr-scope-registry
- ext-v2/i-ws-lazy-serialize
…-TF) Adds the isolated vitest config, CI workflow, and all 41×3 compat-floor stub triples so the blast_radius≥2.0 gate passes from day one. - vitest.extension-api.config.mts — targets src/extension-api-v2/__tests__/ - .github/workflows/ci-tests-extension-api.yaml — two jobs: vitest run + python3 scripts/check-compat-floor.py (exits 1 on missing stubs) - package.json — test:extension-api / :watch / :coverage scripts - src/extension-api/ — public declaration files (NodeHandle, WidgetHandle, defineNodeExtension, typed events, lifecycle hooks) - src/extension-api-v2/__tests__/v1|v2|migration — 123 stub files covering BC.01–BC.41 (all 34 compat-floor categories × 3 stub types) - packages/extension-api/ — typedoc wrapper package compat-floor gate: OK — 102 stub files present (34 categories × 3 types) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- src/extension-api/{index,lifecycle,node,widget}.ts polish (D5/D6/D7/D10)
- docs/architecture/extension-api-v2/names-appendix.md (DOC1.E6)
- AGENTS.md: cross-repo ownership note
Foundation step 1/3 of ext-api/i-foundation.
… (MIG1.E5) - src/services/extension-api-service.ts (canonical name; replaces extensionV2Service.ts) - src/scripts/app.ts: invoke v2 lifecycle alongside v1 at init+setup - src/services/extensionService.ts: invokeV2AppExtensions helper - src/types/extensionV2.ts: NodeEntityId/WidgetEntityId surface - src/extensions/core/index.ts: register v2 sample extensions - *.v2.ts samples: align to refreshed surface Foundation step 2/3 of ext-api/i-foundation.
- src/world/: ECS World skeleton (entities, components, NodeEntityId) - src/services/__tests__/scope-registry.test.ts: registry semantics per D10 (lifecycle context+ordering) and D12 (clone-on-copy) Foundation step 3/3 of ext-api/i-foundation. Coworker fork point: child PRs i-tf and i-ext stack on top of this branch.
b412aff to
96addd0
Compare
christian-byrne
left a comment
There was a problem hiding this comment.
Adversarial Architecture Review — Phase A Foundation
Role: Architect · Focus: layering violations, Phase B/C extensibility blockers
| # | Severity | Location | Finding |
|---|---|---|---|
| 1 | HIGH | src/extension-api/node.ts:30 vs src/world/entityIds.ts:6 |
NodeEntityId type split — public API is number-branded, internal world is string-branded |
| 2 | HIGH | src/world/worldInstance.ts:11 vs src/services/extension-api-service.ts:598 |
World.getComponent returns unknown; startExtensionSystem assumes a reactive World that doesn't exist |
| 3 | MED | src/extension-api/lifecycle.ts:322 vs src/services/extension-api-service.ts:57 |
Circular import: extension-api-service imports lifecycle.ts which re-exports from extension-api-service |
| 4 | MED | src/services/extensionV2Service.ts |
Dead file: imports from @/ecs/* (does not exist), never imported anywhere, not excluded from typecheck |
| 5 | MED | src/services/extension-api-service.ts:26-28 |
pauseTracking/resetTracking are deliberate no-ops; the D3.5 comment describes real Vue internals that do not apply |
| 6 | MED | src/services/extension-api-service.ts:403-411 |
node.on('executed'/'connected'/'disconnected'/'configured') dispatches to the stub returning undefined, breaking the Unsubscribe contract silently |
| 7 | LOW | src/scripts/app.ts:865 vs :960 |
startExtensionSystem() watcher is created before init() runs and has no owning scope — watch leak on teardown |
| 8 | LOW | src/services/extension-api-service.ts:247-253 |
node.on() falls through silently for unknown event names with no dev warning |
1 — NodeEntityId type split breaks Phase B rebase (HIGH)
src/extension-api/node.ts:30 declares:
export type NodeEntityId = number & { readonly __brand: 'NodeEntityId' }src/world/entityIds.ts:6 (the stub Phase B replaces with real ECS IDs) declares:
export type NodeEntityId = Brand<string, 'NodeEntityId'>extension-api-service.ts imports the world type (line 40) and passes it to createNodeHandle() which returns a NodeHandle typed with the public type. TypeScript accepts this now only because World.getComponent returns unknown everywhere, silencing the incompatibility.
When Phase B lands Alex's real ECS, extensions that have stored or compared NodeHandle.entityId will silently carry string values in a number-branded type. Two NodeEntityId declarations will exist with incompatible underlying primitives.
Fix: Remove NodeEntityId/WidgetEntityId/SlotEntityId from src/extension-api/node.ts and re-export from @/world/entityIds. The public barrel already re-exports types from elsewhere; entity IDs should follow the same pattern so Phase B changes one definition.
2 — startExtensionSystem assumes a reactive World that D8 says is still unresolved (HIGH)
extension-api-service.ts:598:
watch(
() => world.entitiesWith(NodeTypeKey), // returns unknown[] from stub
...
)The comment at line 589 says "world component buckets are reactive(Map)." But decisions/D8-world-vue-reactive-adapter.md marks World reactivity as "scoping / blocker" with three un-spiked options. The World stub returns a plain unknown[] with no Vue tracking — the watch never fires in Phase A (stub throws on getWorld()).
The deeper Phase B blocker: getWorld() is captured at startExtensionSystem() call time. ADR 0008 says World is per-workflow. After a workflow switch the watcher holds a stale World reference, so the mount/unmount diff never sees new-workflow entities. D8's Q5 (workflow swap semantics) is unresolved.
Fix: Add a TODO keyed to D8 (not only #11939) at line 589. The watcher should re-acquire the World reference inside its getter, or the system needs restart-on-workflow-change. The current comment ("reactive(Map)") will mislead the Phase B implementer — it describes a design decision that hasn't been made yet.
3 — Circular import between extension-api-service and lifecycle.ts (MED)
extension-api-service.ts:57 import type { … } from '@/extension-api/lifecycle'
lifecycle.ts:322 export { onNodeMounted, onNodeRemoved } from '@/services/extension-api-service'
lifecycle.ts re-exports onNodeMounted/onNodeRemoved from extension-api-service, and extension-api-service imports WidgetExtensionOptions from lifecycle.ts. Real circular dependency. ESM typically resolves this via hoisting, but any import-time side effect in either module breaks the cycle silently — and extension-api-service.ts has module-level globals (scopeRegistry, nodeExtensions arrays) that initialize on first import.
index.ts compounds this (imports from both at lines 52 and 64).
Fix: Move type declarations (WidgetExtensionOptions, NodeExtensionOptions, ExtensionOptions) to a dedicated src/extension-api/types.ts with no implementation imports. Both lifecycle.ts and extension-api-service.ts import from types.ts; neither imports from the other.
4 — extensionV2Service.ts is dead code that imports non-existent modules (MED)
src/services/extensionV2Service.ts imports:
import { useWorld } from '@/ecs/world' // does not exist
import { dispatch } from '@/ecs/commands' // does not exist
import { … } from '@/ecs/components' // does not existIt is imported from nowhere. The PR description flags deletion as landing in a child PR — but this file currently lives in the typecheck surface. pnpm typecheck will fail on it unless tsconfig.json explicitly excludes it.
The file also defines a divergent parallel implementation (entityId: number vs string, world.queryAll() vs world.entitiesWith()) that contradicts the design landed in this PR — its presence confuses the design record.
Fix: Delete the file in this PR. Simple deletion, zero downstream impact.
5 — pauseTracking/resetTracking no-ops contradict their stated purpose (MED)
extension-api-service.ts:26-28:
// They are Vue internals not publicly exported. Use no-op shims…
const pauseTracking = (): void => {}
const resetTracking = (): void => {}mountExtensionsForNode (line 542) documents step 3 as "pauseTracking() prevents accidental reactive deps on setup args." Without real pauseTracking, any reactive reads inside a nodeCreated() hook that touch a ref/reactive in the current rendering scope create unintended dependencies — extensions calling node.getPosition() during setup inside a component render will accidentally bind the component's re-render to node position changes.
extensionV2Service.ts imports the real Vue internals (import { pauseTracking, resetTracking } from 'vue'), confirming the original intent.
Fix: Import from @vue/reactivity (already a peer dep), or explicitly document that Phase A intentionally accepts the tracking leak with a TODO(#D3.5) to restore it in Phase B. The current shim presents a false invariant.
6 — node.on('executed'/'connected'/...) breaks the Unsubscribe contract silently in Phase A (MED)
// extension-api-service.ts:407-411
dispatch({ type: 'SubscribeNodeEvent', nodeId, event, handler: fn })
return () => dispatch({ type: 'UnsubscribeNodeEvent', nodeId, event, handler: fn })The dispatch stub returns undefined and does nothing. The subscription never registers; the returned Unsubscribe tries to cancel a subscription that never existed.
Both dynamicPrompts.v2.ts and previewAny.v2.ts use node.on('executed', ...) as their primary event. They silently do nothing in Phase A. Extensions Simon/Austin convert against this surface, pass their own tests, and fail at runtime.
Fix: Either exclude these events from Phase A's surface (mark @stability internal or omit from public barrel), or throw in dev when called:
if (import.meta.env.DEV) throw new Error('[extension-api] node.on("executed") is not wired in Phase A — lands in Phase B (#11939)')Silent no-ops in a stable-contract API are the worst outcome.
7 — startExtensionSystem watcher has no owning scope (LOW)
watch() called outside a Vue component or explicit EffectScope creates a detached watcher Vue cannot clean up automatically. _clearExtensionsForTesting() (line 491) clears the registries but doesn't stop the watcher. Calling startExtensionSystem() multiple times (possible in tests) accumulates N watchers.
D8 Q5 (workflow-swap teardown) will require stopping this watcher when the World is replaced — the current design has no handle for that.
Fix: startExtensionSystem() should create a EffectScope(true) (detached), run the watch inside it, and return a stop() function. Or guard against double-call with a module-level started flag.
8 — Silent fallthrough on unknown event names (LOW)
node.on('typo', fn) returns () => {} with no dev warning. The typed overload on NodeHandle.on catches misspellings at compile time, but the as NodeHandle['on'] cast at line 418 means runtime registration of unknown string events is silently accepted.
Fix: Add a DEV-only console.warn('[extension-api] Unknown event name: …') in the final fallthrough. Same pattern as the async-setup guard at line 554.
Phase B/C extensibility summary
Two findings are load-bearing Phase B blockers:
-
NodeEntityIdtype split (finding 1) — Alex's ECS uses string IDs; the public API promisesnumber. Fix before Phase A stabilizes the contract — changingNodeEntityIdafter extensions are converted is a breaking change. -
World reactivity assumption (finding 2) — The mount watcher presupposes a resolved D8 design. The current comment ("reactive(Map)") is a false claim that will mislead the Phase B implementer. Explicitly mark the watcher as provisional, keyed to D8 resolution.
Phase C (strangler over v1 hooks) is unaffected by this PR — correctly deferred per D9.
christian-byrne
left a comment
There was a problem hiding this comment.
Adversarial review — Minimalist (agent: codex)
| # | Severity | Location | Finding |
|---|---|---|---|
| 1 | High | src/services/extensionV2Service.ts (entire 413-line file) |
Dead duplicate of extension-api-service.ts. PR body acknowledges it "ended up in the i-tf child PR" — but in this branch it is still on disk and zero-referenced (rg extensionV2Service src/ → no hits). Delete it here; do not defer. |
| 2 | High | src/world/worldInstance.ts:11-13 + src/services/extension-api-service.ts:31-end |
getWorld() throws unconditionally ("Phase A stub"), yet ~340 lines of createNodeHandle / createWidgetHandle call getWorld() inside every accessor. The entire service is non-functional until #11939 lands. This is premature abstraction at scale: ship the stubs alone (or the real service after #11939) — not a fully-fleshed service hard-wired to throw. |
| 3 | High | src/extension-api-v2/__tests__/ |
246 test files, every assertion is it.todo. Worse, two parallel naming schemes coexist: bc-XX.{v1,v2,migration}.test.ts (123) and __tests__/{migration,v1,v2}/BC.XX.{v1,v2,migration}.test.ts (123) covering the same BC categories. Pick one layout; ~120 files of pure duplication can vanish. |
| 4 | Med | src/services/extension-api-service.ts:25-29 |
pauseTracking/resetTracking aliased to (): void => {} "so this service compiles … without a direct @vue/reactivity dep." The safety the comment claims (preventing accidental deps) does not exist — these are no-ops. Either import the real symbols (Vue re-exports them via @vue/reactivity) or delete the call sites and the comment. Right now the comment lies to readers. |
| 5 | Med | src/services/extension-api-service.ts:96-105 |
Module-level mutable _dispatchImpl plus exported _setDispatchImplForTesting. Production code reshaped for test injection. Pass the dispatcher in as a parameter to startExtensionSystem (DI), or postpone until the real dispatch exists; don't ship a back-door singleton. |
| 6 | Med | src/services/extension-api-service.ts:65-93 |
Eight inline *Data interfaces + matching defineComponentKey calls, each annotated TODO(#11939): replace with real imports. This block is scaffolding for code that hasn't landed and contributes nothing today (everything reads through a getWorld() that throws). Delete until #11939 supplies the real component module. |
| 7 | Med | src/services/extension-api-service.ts:312-318, 196-201 |
Widget identity is recovered by string-parsing the branded entity ID (raw.lastIndexOf(':'), id.endsWith(\:${name}`)). Comment admits this is wrong ("use a dedicated WidgetName component key instead of parsing ID"). Don't ship the wrong solution as a placeholder — gate widget(name)andget name()` behind the real component, or omit them from the v2 surface for now. |
| 8 | Med | src/world/{componentKey,entityIds,widgets/widgetComponents,worldInstance}.ts |
All four files are stubs (object/unknown payloads, defineComponentKey returns { name }). The directory exists only so this PR can compile. Either move it under src/services/__stubs__/ (making the temporary nature obvious) or vendor the bare minimum into extension-api-service.ts until the real @/world/* ships. Right now src/world/ looks like real architecture. |
| 9 | Low | packages/extension-api/scripts/build-docs.ts (470 lines) + tsconfig.docs.json + typedoc.json |
A full TypeDoc → Mintlify pipeline (PAGE_META map, watch mode, nav-snippet emitter, frontmatter munging, @example rewriting) for a public API whose runtime is currently throw new Error('… Phase A stub'). Defer the docgen pipeline to the PR that actually wires the service to the World. typedoc --plugin typedoc-plugin-markdown --readme none covers 90% of the value in zero custom code. |
| 10 | Low | .github/workflows/ci-tests-extension-api.yaml (88 lines) |
Dedicated CI workflow + vitest.extension-api.config.mts for a suite where every test is it.todo. There is nothing to fail. Fold these into the existing unit-test config until at least one bc-* test is real. |
Theme: the PR ships ~2.7 k lines of public API + service + scope registry + 246 stub tests + a docgen pipeline, all sitting on a getWorld() that throws. By Hickey/Carmack/Sussman standards this is the canonical "speculative scaffolding" anti-pattern: every layer is a placeholder for the layer beneath. Land #11939 first, then this becomes ~1/3 the size and actually runs.
christian-byrne
left a comment
There was a problem hiding this comment.
Adversarial Review — Skeptic Role
| Severity | File:Line | Issue | Suggested Fix |
|---|---|---|---|
| High | node.ts:30 vs extension-api-service.ts:76 | Type mismatch: NodeEntityId declared as number & {...} in public API but stubs use string format (node:graphId:nodeId). Phase B rebase will break callers or require migration. |
Align on single representation now; if string is final form, update declaration. |
| High | extension-api-service.ts:327-335 | dispatch() stub returns undefined; code casts result to WidgetEntityId and passes to createWidgetHandle(). Any call to addWidget() today creates handle with invalid ID. |
Guard: if (!widgetId) throw new Error('dispatch failed') or return sentinel handle. |
| Medium | extension-api-service.ts:252-253, 416-417 | Unknown event names silently return () => {}. Extension typos ('valuechange' vs 'valueChange') fail silently with no subscription. |
DEV-mode warning: console.warn('Unknown event:', event) before returning no-op. |
| Medium | extension-api-service.ts:544-556 | Async setup Promise is detected but not awaited. If the async code throws, it's an unhandled rejection. | result.catch(err => console.error(...)) to suppress unhandled rejection, or store promise for later await. |
| Medium | extension-api-service.ts:183-186, 313-318 | Widget name parsed via lastIndexOf(':'). Widget named 'foo:bar' would return 'bar' not 'foo:bar'. Same issue in widget() lookup using endsWith(). |
Use dedicated component for name, or document colon restriction, or use different delimiter. |
| Low | extension-api-service.ts:594-613 | startExtensionSystem() creates a watch() with no guard against multiple calls. Each call adds another watcher. |
Add let started = false guard or return cleanup function. |
| Low | extension-api-service.ts:290 | getProperties() returns shallow spread of properties. Nested objects share references with ECS data. |
structuredClone() or document mutability hazard. |
| Low | extension-api-service.ts:361-384 | Multiple as unknown as casts between SlotEntityId/WidgetEntityId brands indicate type misalignment. These casts will hide real bugs when real types land. |
Introduce proper SlotEntityId brand now; remove double-casts. |
Additional Concerns
-
Incomplete cleanup on partial mount failure: If
mountExtensionsForNodethrows mid-loop (line 524-567), earlier extensions remain mounted with no rollback. A corrupted extension could leave the system half-initialized. -
onNodeMountedraces with scope stop: Thewatch(() => null, fn, { flush: 'post', once: true })pattern schedules the callback for next tick. Ifscope.stop()is called synchronously after setup (e.g., rapid create-delete), Vue doesn't cancel scheduled post-flush watchers — the callback fires after the scope is dead. -
_setDispatchImplForTestingis public API: Exported without@internalJSDoc enforcement. Extensions could call this and hijack all command dispatch globally. -
No idempotency protection on
defineNodeExtension: CallingdefineNodeExtension({ name: 'foo', ... })twice pushes two entries tonodeExtensions. Both fire on every node. No warning, no dedup.
Review by skeptic agent — all concerns point to concrete failure modes, not style preferences.
christian-byrne
left a comment
There was a problem hiding this comment.
Adversarial Review — Skeptic Role
| Severity | File:Line | Issue | Suggested Fix |
|---|---|---|---|
| High | node.ts:30 vs extension-api-service.ts:76 | Type mismatch: NodeEntityId declared as number & {...} in public API but stubs use string format (node:graphId:nodeId). Phase B rebase will break callers or require migration. |
Align on single representation now; if string is final form, update declaration. |
| High | extension-api-service.ts:327-335 | dispatch() stub returns undefined; code casts result to WidgetEntityId and passes to createWidgetHandle(). Any call to addWidget() today creates handle with invalid ID. |
Guard: if (!widgetId) throw new Error('dispatch failed') or return sentinel handle. |
| Medium | extension-api-service.ts:252-253, 416-417 | Unknown event names silently return () => {}. Extension typos ('valuechange' vs 'valueChange') fail silently with no subscription. |
DEV-mode warning: console.warn('Unknown event:', event) before returning no-op. |
| Medium | extension-api-service.ts:544-556 | Async setup Promise is detected but not awaited. If the async code throws, it's an unhandled rejection. | result.catch(err => console.error(...)) to suppress unhandled rejection, or store promise for later await. |
| Medium | extension-api-service.ts:183-186, 313-318 | Widget name parsed via lastIndexOf(':'). Widget named 'foo:bar' would return 'bar' not 'foo:bar'. Same issue in widget() lookup using endsWith(). |
Use dedicated component for name, or document colon restriction, or use different delimiter. |
| Low | extension-api-service.ts:594-613 | startExtensionSystem() creates a watch() with no guard against multiple calls. Each call adds another watcher. |
Add let started = false guard or return cleanup function. |
| Low | extension-api-service.ts:290 | getProperties() returns shallow spread of properties. Nested objects share references with ECS data. |
structuredClone() or document mutability hazard. |
| Low | extension-api-service.ts:361-384 | Multiple as unknown as casts between SlotEntityId/WidgetEntityId brands indicate type misalignment. These casts will hide real bugs when real types land. |
Introduce proper SlotEntityId brand now; remove double-casts. |
Additional Concerns
-
Incomplete cleanup on partial mount failure: If
mountExtensionsForNodethrows mid-loop (line 524-567), earlier extensions remain mounted with no rollback. A corrupted extension could leave the system half-initialized. -
onNodeMountedraces with scope stop: Thewatch(() => null, fn, { flush: 'post', once: true })pattern schedules the callback for next tick. Ifscope.stop()is called synchronously after setup (e.g., rapid create-delete), Vue doesn't cancel scheduled post-flush watchers — the callback fires after the scope is dead. -
_setDispatchImplForTestingis public API: Exported without@internalJSDoc enforcement. Extensions could call this and hijack all command dispatch globally. -
No idempotency protection on
defineNodeExtension: CallingdefineNodeExtension({ name: 'foo', ... })twice pushes two entries tonodeExtensions. Both fire on every node. No warning, no dedup.
Review by skeptic agent — all concerns point to concrete failure modes, not style preferences.
christian-byrne
left a comment
There was a problem hiding this comment.
Regression-risk review (codex)
| Severity | File:Line | Issue | Suggested fix |
|---|---|---|---|
| none | — | No modifications touch lines previously introduced by bugfix commits. | n/a |
Method
Per .agents/checks/regression-risk.md:
- Base =
git merge-base origin/main HEAD(8f68be5699). - PR commits:
96addd0e,7200eb0d,e616a938,fe6d4399,6dd361bb. - Non-test, non-doc surface: 4 modified files (
src/extensions/core/index.ts,src/scripts/app.ts,src/services/extensionService.ts,AGENTS.md); the remaining ~270 are pure additions (newextension-apipackage,extension-api-v2tests,world/ECS scaffolding,*.v2.tsextensions, CI workflow, vitest config). - Diffs against base on the modified files contain only inserted lines (no deletions / no in-place edits). Insertion points were blamed in the base version:
src/extensions/core/index.ts(around new*.v2imports): blame =e179f7538format pass,be8916b4c(imageCrop add),fb14d2404(previewAny add),7e76665a2(rerouteNode),d8f074fea(electronAdapter),679288500(cloud nodeTemplates). None match bugfix patterns (fix/bug/patch/hotfix/revert/regression/CVE).src/scripts/app.ts:855-860, 945-955(startExtensionSystem()+ twoinvokeV2AppExtensions(...)calls): blame =a108c5257(blueprints feature),cce11bb63(refactor),acdaa6a59(format),37fab21da(YAGNI cleanup),e179f7538(format). None are bugfixes.src/services/extensionService.ts:200-220(DEP1 deprecation warn block): blame =4fc1d2ef5(No Explicit Any),b3da6cf1b(contextmenu migration feature),cce11bb63(refactor). None are bugfixes. Header import edits not modified.
- No PR-own SHA self-collisions; full clone (unshallowed) so blame depth is complete.
Notes (informational, not findings)
- The new lines in
extensionService.tsonly add a one-timeconsole.warninside the existing try-block; they do not alter the existingfn.call(ext, ...args, app)invocation guarded byb1050e3195(Fix session cookie creation race). That bugfix's wrapping behavior is preserved. - Insertions in
app.tsare sequenced afteruseExtensionService().invokeExtensionsAsync('init'|'setup'), preserving v1 ordering.
No blockers; no recommended changes from a regression-risk lens.
christian-byrne
left a comment
There was a problem hiding this comment.
dep-secrets-scan results
| Severity | File:Line | Issue | Suggested fix |
|---|---|---|---|
| info | — | gitleaks not installed on scanner host | Install gitleaks to enable automated secrets scan in future runs (per check file step 1). Manual diff sweep performed as fallback — see below. |
| info | — | pnpm audit ran; no new advisories introduced by this PR |
Lockfile (pnpm-lock.yaml) is unchanged in this diff and the two new devDeps in packages/extension-api/package.json (typedoc@0.28.19, typedoc-plugin-markdown@^4.6.3) are not yet resolved into the lockfile, so no new transitive vulns can be attributed to this PR. Pre-existing advisories on main (axios, vite, dompurify, minimatch, rollup, etc. — 1 critical / 37 high / 37 moderate / 1 low) are out of scope here and should be tracked separately. |
| info | — | Manual secrets sweep on the PR diff | No leaked secrets. Matches found were all benign: ${{ secrets.CODECOV_TOKEN }} (GHA reference, not a value), test description strings about extension auth-token plumbing, and useApiKeyAuthStore imports. |
Scope notes
- Only
package.json(3 addedtest:extension-api*scripts) and the newpackages/extension-api/package.json(devDeps:tsx,typedoc,typedoc-plugin-markdown,typescript) touch dependency surface. - New devDeps are scoped to the published-package workspace and do not appear in the audit findings paths.
Verdict: no blockers from dep-secrets-scan. Recommend installing gitleaks on the scanner host so the secrets half of this check can run automatically next time.
christian-byrne
left a comment
There was a problem hiding this comment.
ecosystem-compat review
| Severity | File:Line | Issue | Suggested fix |
|---|---|---|---|
| nit | src/services/extensionService.ts:215-225 | New console.warn fires once-per-extension for the deprecated beforeRegisterNodeDef hook. mcp__comfy_codesearch__search_code returned 5+ ecosystem consumers (result cap hit — likely many more). The hook still works (signature unchanged), so this is not a breaking change per the check criteria, but the deprecation message will be noisy across the ecosystem. |
Consider gating behind a setting (e.g. Comfy.ExtensionAPI.WarnDeprecated) defaulting on, or batching to a single end-of-load summary, so users with many third-party packs don't get a console flood. |
Verified non-breaking
Walked the diff against every criterion in .agents/checks/ecosystem-compat.md:
- Renamed/removed exports — none. New surface is additive:
src/extension-api/{events,identifiers,index,lifecycle,node,shell,widget}.ts,src/services/extension-api-service.ts,src/world/*,src/types/extensionV2.ts,packages/extension-api/*. Oldsrc/services/extensionV2Service.tsis intentionally retained here (PR description notes deletion lands in the i-tf child PR). - Changed function signatures / return types — none.
useExtensionService()keeps its existing shape; only an internalconsole.warnwas added insideinvokeExtensionsAsyncbefore the existingfn.call(...). - Renamed/removed CSS classes — none.
- Changed event names / payload shapes — none. New v2 events live under the new
src/extension-api/events.tssurface and don't collide with v1. - Changed global registrations / extension hooks —
app.tsaddsstartExtensionSystem()and twoinvokeV2AppExtensions('init'|'setup')calls alongside (not replacing) the existing v1 invocations. v1 lifecycle ordering is preserved. - Modified integration points — only additive (new
.v2core extension imports insrc/extensions/core/index.ts, newvitest.extension-api.config.mts, new CI workflow, newtest:extension-api*scripts inpackage.json).
No blockers; no request-changes warranted.
Method: diff vs merge-base origin/main (8f68be5), 279 files / +10597 / −1. Ecosystem usage probed via mcp__comfy_codesearch__search_code against custom-node repos.
christian-byrne
left a comment
There was a problem hiding this comment.
bug-hunter review (Phase A foundation, ext-api/i-foundation)
Walked the diff against the bug-hunter check-file criteria (off-by-one, null-deref, race, edge cases, type coercion, error handling, state mutation, boolean logic, plus repo-specific patterns). Findings below in severity order.
| Severity | File:Line | Issue | Suggested fix |
|---|---|---|---|
| blocker | src/extensions/core/index.ts:24, 28, 32 |
Imports ./noteNode.v2, ./rerouteNode.v2, ./slotDefaults.v2 — none of these files exist on this branch (only dynamicPrompts.v2.ts, imageCrop.v2.ts, previewAny.v2.ts were added). Module-resolution will throw at app boot before anything renders. |
Either add the three missing v2 extension files in this PR, or remove the three import lines until the corresponding files land. |
| blocker | src/scripts/app.ts:865 → src/services/extension-api-service.ts:595 → src/world/worldInstance.ts:13 |
startExtensionSystem() is called unconditionally during setup() and immediately calls getWorld(), which is a Phase A stub that always throws Error('[worldInstance] ECS world not yet initialized (Phase A stub)'). Combined with the missing v2 files above, the app cannot finish boot on this branch. |
Guard startExtensionSystem() behind a feature flag/dev-only check, or make getWorld() return a noop World until #11939 lands so the boot path doesn't throw. |
| blocker | src/services/extensionV2Service.ts:26-45 |
The "old" service file is still added by this PR (deletion deferred per PR description), but it imports @/ecs/world, @/ecs/commands, @/ecs/components, @/ecs/entityIds — modules that do not exist anywhere in src/. Even though no other file imports it, it lives under src/ and will be picked up by pnpm typecheck and the Vite build, producing unresolved-import / TS errors. |
Delete extensionV2Service.ts in this PR (don't defer to the i-tf child PR), or stub the missing imports so it at least typechecks. |
| blocker | src/services/extension-api-service.ts:451 (onNodeMounted) |
watch(() => null, fn, { flush: 'post', once: true }) — the source getter has zero reactive deps and returns a constant, so the watcher will never fire and the supplied fn is never invoked. Every extension that uses onNodeMounted(...) silently does nothing. |
Add immediate: true and rely on once: true to clean up after one invocation, or replace with nextTick(fn) inside the active scope. |
| blocker | src/services/extension-api-service.ts:274, 277 vs public Point/Size in src/extension-api/node.ts:39, 46 |
Public API declares Point = [x, y] and Size = [width, height] (tuples). The implementation returns object-shape fallbacks { x: 0, y: 0 } / { width: 0, height: 0 } when the World has no Position/Dimensions component. Callers like src/extensions/core/imageCrop.v2.ts:15 (const [w, h] = node.getSize()) destructure as an array and silently get [undefined, undefined], then Math.max(undefined, 300) returns NaN. |
Return tuple fallbacks: ?? [0, 0]. Same pattern for getPosition(). |
| recommended | src/services/extension-api-service.ts:594-613 (startExtensionSystem) |
watch(() => world.entitiesWith(NodeTypeKey), …, { flush: 'post' }) has no immediate: true. Any node entities that already exist in the World at the time startExtensionSystem() runs (e.g. workflow loaded before setup hooks fire) will not get extensions mounted — only entities added strictly after the first watcher tick are covered. |
Add immediate: true, or drive the initial mount imperatively before the watch is set up. |
| recommended | src/services/extension-api-service.ts:575-579 (unmountExtensionsForNode) |
Iterates nodeExtensions[] rather than the actual scope-registry entries for nodeEntityId. If an extension is registered after a node mounted, or if the registry contains stale keys, those scopes never get .stop()-ed and leak watchers/onScopeDispose callbacks. |
Iterate scopeRegistry for keys ending in :${nodeEntityId} (or maintain a per-entity index) to ensure full teardown. |
| recommended | src/services/extension-api-service.ts:29-30 |
pauseTracking/resetTracking are local no-op shims (const pauseTracking = (): void => {}). The doc comment promises "prevents accidental reactive deps during setup hooks" but the runtime behaviour is identical to not pausing at all — any world.getComponent(...) reads inside nodeCreated will create real reactive deps on the surrounding scope. |
Import the real pauseTracking / resetTracking from @vue/reactivity (still part of vue's exports via internal subpath) or remove the misleading comments. |
| recommended | src/services/extensionService.ts:19, 215-225 |
_warnedBeforeRegisterNodeDef is a module-scoped Set<string> keyed by ext.name. Two extensions with the same name (or HMR re-registration) will skip the warning after the first occurrence, even though they're different code. Minor, but the dedup key should include something stable like the file URL or be reset per extension reload. |
Either accept the dedup as best-effort (and add a comment) or key on ext.name + ':' + (ext as any).source if available. |
| nit | src/services/extension-api-service.ts:413-415 |
onScopeDispose(() => fn()) for the 'removed' event is registered, then return () => {} is returned as the unsubscribe. Calling the returned unsubscribe is a silent no-op, but extension authors will assume it actually unregisters the handler (other branches in this same on do). |
Either capture the handler in a local flag and check it inside the onScopeDispose callback, or document that 'removed' cannot be unsubscribed. |
| nit | src/extensions/core/previewAny.v2.ts:43 |
e.output['text'] is read without verifying e.output is a non-null object. Per NodeExecutedEvent.output: Record<string, unknown> the type rules out undefined, but real backend outputs occasionally arrive as null for muted/bypassed nodes — a defensive e.output?.['text'] would be safer until the typing settles. |
const text = (e.output?.['text'] as string | string[] | undefined) ?? '' |
Notes / out-of-scope
- The 250+ new
bc-*.test.tsfiles are scaffolding-only and were not walked line-by-line for behavioural bugs. - Documentation/typedoc additions (
packages/extension-api/**,names-appendix.md) and the new CI workflow are not in scope for bug-hunter. - The deferred deletion of
extensionV2Service.tsis called out in the PR description but, per finding #3 above, leaving it in the tree in a non-compiling state is itself a blocker.
Cited check-file criteria: §2 null/undefined dereferences (#5, #11), §3 race / async ordering (#4, #6), §4 edge cases (#5), §6 error handling gaps (#3, #4), §7 state mutation / leak (#7), repo-specific "watch without cleanup" + "destructuring without toRefs" guidance (#7, #4).
christian-byrne
left a comment
There was a problem hiding this comment.
vue-patterns review — no findings (out of scope)
| Severity | File:Line | Issue | Suggested fix |
|---|---|---|---|
| — | — | No in-scope files | — |
The vue-patterns check is scoped to .vue files and composable .ts files (e.g. useXyz.ts). Per the check rules: "Only review .vue and composable .ts files — skip stores, services, utils".
This PR's diff is entirely:
- Extension API declarations (
src/extension-api/{index,lifecycle,node,widget,events,identifiers,shell}.ts) - Services (
src/services/extension-api-service.ts,extensionV2Service.ts,extensionService.ts) - ECS world skeleton (
src/world/*.ts) - Types (
src/types/extensionV2.ts) - Tests (
src/extension-api-v2/__tests__/**,src/services/__tests__/scope-registry.test.ts) - Sample v2 extensions (
src/extensions/core/*.v2.ts) - Build/docs/CI infra (
packages/extension-api/**,vitest.extension-api.config.mts,.github/workflows/ci-tests-extension-api.yaml,docs/**)
No new .vue components, no new composables, no new primevue/* imports. Nothing to flag against criteria 1–10.
Reviewer: codex · check: .agents/checks/vue-patterns.md
- 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.
🌐 Website E2ETip All tests passed.
|
|
Pushed
Note: |
There was a problem hiding this comment.
Note
Due to the large number of review comments, Critical severity comments were prioritized as inline comments.
🟡 Minor comments (3)
packages/extension-api/README.md-4-5 (1)
4-5:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix workspace-relative doc paths.
From
packages/extension-api/README.md,../../../plans/...appears one level too high. These references should resolve frompackages/extension-apito repo-root using../../...to avoid broken path guidance.📌 Suggested path fix
-> `../../../plans/P2-extension-api-package.md` and -> `../../../plans/prompts/PKG3-npm-package.md` in the workspace root. +> `../../plans/P2-extension-api-package.md` and +> `../../plans/prompts/PKG3-npm-package.md` in the workspace root.Also applies to: 45-50
🤖 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 `@packages/extension-api/README.md` around lines 4 - 5, Update the workspace-relative paths in packages/extension-api/README.md: replace occurrences of "../../../plans/..." with "../../plans/..." (e.g., change `../../../plans/P2-extension-api-package.md` and `../../../plans/prompts/PKG3-npm-package.md` to `../../plans/P2-extension-api-package.md` and `../../plans/prompts/PKG3-npm-package.md`) and apply the same fix for the other occurrences around lines 45-50 so all references resolve from packages/extension-api to the repo root.src/extension-api/README.md-3-6 (1)
3-6:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix the status-link relative path depth
From
src/extension-api/README.md,../../../plans/...likely climbs one level too far.
Use repo-root-relative depth from this folder (typically../../plans/...) so the links resolve.🤖 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/README.md` around lines 3 - 6, The status links in src/extension-api/README.md use '../../../plans/...' which goes up one directory too many; update those relative paths to '../../plans/...' (or otherwise make them repo-root-relative) so the references like '../../../plans/P2-extension-api-package.md and ../../../plans/prompts/PKG2-author-declaration.md point correctly from the README in src/extension-api; modify the link targets in that README to the corrected '../../plans/...' paths.src/extension-api/README.md-16-27 (1)
16-27:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a language identifier to the fenced tree block
Line 16 uses an unlabeled fenced block, which triggers markdownlint MD040.
Suggested patch
-``` +```text extension-api/ ├── index.ts ← barrel — package entry point ├── node.ts ← NodeHandle + NodeEvents + payload types ├── widget.ts ← WidgetHandle + WidgetEvents + payload types ├── events.ts ← shared Handler<E>, cross-cutting event types ├── lifecycle.ts ← Setup ctx, defineExtension, lifecycle hooks ├── shell.ts ← sidebar, bottom panel, command, toast (moved │ from ../types/extensionTypes.ts) ├── identifiers.ts ← NodeLocatorId etc. (re-exports) └── README.md ← this file</details> <details> <summary>🤖 Prompt for AI Agents</summary>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/README.mdaround lines 16 - 27, The README.md contains an
unlabeled fenced code block (the directory tree under "extension-api/") which
triggers markdownlint MD040; edit the README.md and add a language identifier
(e.g., ```text) to the fenced block that contains the tree so the block is
labeled and MD040 is satisfied—update the opening fence for the block that lists
index.ts, node.ts, widget.ts, events.ts, lifecycle.ts, shell.ts, identifiers.ts,
and README.md.</details> </blockquote></details> </blockquote></details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `291f8b2f-1c97-4f27-a5ca-3a9f935a7a48` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 8f68be5699b99dcd046bde8c0b107fde87ab9a8c and 58d6d2a15774025b427d943b4937f214b9f08d7c. </details> <details> <summary>📒 Files selected for processing (279)</summary> * `.github/workflows/ci-tests-extension-api.yaml` * `AGENTS.md` * `docs/architecture/extension-api-v2/names-appendix.md` * `package.json` * `packages/extension-api/.gitignore` * `packages/extension-api/README.md` * `packages/extension-api/package.json` * `packages/extension-api/scripts/build-docs.ts` * `packages/extension-api/tsconfig.docs.json` * `packages/extension-api/typedoc.json` * `src/extension-api-v2/__tests__/bc-01.migration.test.ts` * `src/extension-api-v2/__tests__/bc-01.v1.test.ts` * `src/extension-api-v2/__tests__/bc-01.v2.test.ts` * `src/extension-api-v2/__tests__/bc-02.migration.test.ts` * `src/extension-api-v2/__tests__/bc-02.v1.test.ts` * `src/extension-api-v2/__tests__/bc-02.v2.test.ts` * `src/extension-api-v2/__tests__/bc-03.migration.test.ts` * `src/extension-api-v2/__tests__/bc-03.v1.test.ts` * `src/extension-api-v2/__tests__/bc-03.v2.test.ts` * `src/extension-api-v2/__tests__/bc-04.migration.test.ts` * `src/extension-api-v2/__tests__/bc-04.v1.test.ts` * `src/extension-api-v2/__tests__/bc-04.v2.test.ts` * `src/extension-api-v2/__tests__/bc-05.migration.test.ts` * `src/extension-api-v2/__tests__/bc-05.v1.test.ts` * `src/extension-api-v2/__tests__/bc-05.v2.test.ts` * `src/extension-api-v2/__tests__/bc-06.migration.test.ts` * `src/extension-api-v2/__tests__/bc-06.v1.test.ts` * `src/extension-api-v2/__tests__/bc-06.v2.test.ts` * `src/extension-api-v2/__tests__/bc-07.migration.test.ts` * `src/extension-api-v2/__tests__/bc-07.v1.test.ts` * `src/extension-api-v2/__tests__/bc-07.v2.test.ts` * `src/extension-api-v2/__tests__/bc-08.migration.test.ts` * `src/extension-api-v2/__tests__/bc-08.v1.test.ts` * `src/extension-api-v2/__tests__/bc-08.v2.test.ts` * `src/extension-api-v2/__tests__/bc-09.migration.test.ts` * `src/extension-api-v2/__tests__/bc-09.v1.test.ts` * `src/extension-api-v2/__tests__/bc-09.v2.test.ts` * `src/extension-api-v2/__tests__/bc-10.migration.test.ts` * `src/extension-api-v2/__tests__/bc-10.v1.test.ts` * `src/extension-api-v2/__tests__/bc-10.v2.test.ts` * `src/extension-api-v2/__tests__/bc-11.migration.test.ts` * `src/extension-api-v2/__tests__/bc-11.v1.test.ts` * `src/extension-api-v2/__tests__/bc-11.v2.test.ts` * `src/extension-api-v2/__tests__/bc-12.migration.test.ts` * `src/extension-api-v2/__tests__/bc-12.v1.test.ts` * `src/extension-api-v2/__tests__/bc-12.v2.test.ts` * `src/extension-api-v2/__tests__/bc-13.migration.test.ts` * `src/extension-api-v2/__tests__/bc-13.v1.test.ts` * `src/extension-api-v2/__tests__/bc-13.v2.test.ts` * `src/extension-api-v2/__tests__/bc-14.migration.test.ts` * `src/extension-api-v2/__tests__/bc-14.v1.test.ts` * `src/extension-api-v2/__tests__/bc-14.v2.test.ts` * `src/extension-api-v2/__tests__/bc-15.migration.test.ts` * `src/extension-api-v2/__tests__/bc-15.v1.test.ts` * `src/extension-api-v2/__tests__/bc-15.v2.test.ts` * `src/extension-api-v2/__tests__/bc-16.migration.test.ts` * `src/extension-api-v2/__tests__/bc-16.v1.test.ts` * `src/extension-api-v2/__tests__/bc-16.v2.test.ts` * `src/extension-api-v2/__tests__/bc-17.migration.test.ts` * `src/extension-api-v2/__tests__/bc-17.v1.test.ts` * `src/extension-api-v2/__tests__/bc-17.v2.test.ts` * `src/extension-api-v2/__tests__/bc-18.migration.test.ts` * `src/extension-api-v2/__tests__/bc-18.v1.test.ts` * `src/extension-api-v2/__tests__/bc-18.v2.test.ts` * `src/extension-api-v2/__tests__/bc-19.migration.test.ts` * `src/extension-api-v2/__tests__/bc-19.v1.test.ts` * `src/extension-api-v2/__tests__/bc-19.v2.test.ts` * `src/extension-api-v2/__tests__/bc-20.migration.test.ts` * `src/extension-api-v2/__tests__/bc-20.v1.test.ts` * `src/extension-api-v2/__tests__/bc-20.v2.test.ts` * `src/extension-api-v2/__tests__/bc-21.migration.test.ts` * `src/extension-api-v2/__tests__/bc-21.v1.test.ts` * `src/extension-api-v2/__tests__/bc-21.v2.test.ts` * `src/extension-api-v2/__tests__/bc-22.migration.test.ts` * `src/extension-api-v2/__tests__/bc-22.v1.test.ts` * `src/extension-api-v2/__tests__/bc-22.v2.test.ts` * `src/extension-api-v2/__tests__/bc-23.migration.test.ts` * `src/extension-api-v2/__tests__/bc-23.v1.test.ts` * `src/extension-api-v2/__tests__/bc-23.v2.test.ts` * `src/extension-api-v2/__tests__/bc-24.migration.test.ts` * `src/extension-api-v2/__tests__/bc-24.v1.test.ts` * `src/extension-api-v2/__tests__/bc-24.v2.test.ts` * `src/extension-api-v2/__tests__/bc-25.migration.test.ts` * `src/extension-api-v2/__tests__/bc-25.v1.test.ts` * `src/extension-api-v2/__tests__/bc-25.v2.test.ts` * `src/extension-api-v2/__tests__/bc-26.migration.test.ts` * `src/extension-api-v2/__tests__/bc-26.v1.test.ts` * `src/extension-api-v2/__tests__/bc-26.v2.test.ts` * `src/extension-api-v2/__tests__/bc-27.migration.test.ts` * `src/extension-api-v2/__tests__/bc-27.v1.test.ts` * `src/extension-api-v2/__tests__/bc-27.v2.test.ts` * `src/extension-api-v2/__tests__/bc-28.migration.test.ts` * `src/extension-api-v2/__tests__/bc-28.v1.test.ts` * `src/extension-api-v2/__tests__/bc-28.v2.test.ts` * `src/extension-api-v2/__tests__/bc-29.migration.test.ts` * `src/extension-api-v2/__tests__/bc-29.v1.test.ts` * `src/extension-api-v2/__tests__/bc-29.v2.test.ts` * `src/extension-api-v2/__tests__/bc-30.migration.test.ts` * `src/extension-api-v2/__tests__/bc-30.v1.test.ts` * `src/extension-api-v2/__tests__/bc-30.v2.test.ts` * `src/extension-api-v2/__tests__/bc-31.migration.test.ts` * `src/extension-api-v2/__tests__/bc-31.v1.test.ts` * `src/extension-api-v2/__tests__/bc-31.v2.test.ts` * `src/extension-api-v2/__tests__/bc-32.migration.test.ts` * `src/extension-api-v2/__tests__/bc-32.v1.test.ts` * `src/extension-api-v2/__tests__/bc-32.v2.test.ts` * `src/extension-api-v2/__tests__/bc-33.migration.test.ts` * `src/extension-api-v2/__tests__/bc-33.v1.test.ts` * `src/extension-api-v2/__tests__/bc-33.v2.test.ts` * `src/extension-api-v2/__tests__/bc-34.migration.test.ts` * `src/extension-api-v2/__tests__/bc-34.v1.test.ts` * `src/extension-api-v2/__tests__/bc-34.v2.test.ts` * `src/extension-api-v2/__tests__/bc-35.migration.test.ts` * `src/extension-api-v2/__tests__/bc-35.v1.test.ts` * `src/extension-api-v2/__tests__/bc-35.v2.test.ts` * `src/extension-api-v2/__tests__/bc-36.migration.test.ts` * `src/extension-api-v2/__tests__/bc-36.v1.test.ts` * `src/extension-api-v2/__tests__/bc-36.v2.test.ts` * `src/extension-api-v2/__tests__/bc-37.migration.test.ts` * `src/extension-api-v2/__tests__/bc-37.v1.test.ts` * `src/extension-api-v2/__tests__/bc-37.v2.test.ts` * `src/extension-api-v2/__tests__/bc-38.migration.test.ts` * `src/extension-api-v2/__tests__/bc-38.v1.test.ts` * `src/extension-api-v2/__tests__/bc-38.v2.test.ts` * `src/extension-api-v2/__tests__/bc-39.migration.test.ts` * `src/extension-api-v2/__tests__/bc-39.v1.test.ts` * `src/extension-api-v2/__tests__/bc-39.v2.test.ts` * `src/extension-api-v2/__tests__/bc-40.migration.test.ts` * `src/extension-api-v2/__tests__/bc-40.v1.test.ts` * `src/extension-api-v2/__tests__/bc-40.v2.test.ts` * `src/extension-api-v2/__tests__/bc-41.migration.test.ts` * `src/extension-api-v2/__tests__/bc-41.v1.test.ts` * `src/extension-api-v2/__tests__/bc-41.v2.test.ts` * `src/extension-api-v2/__tests__/migration/BC.01.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.02.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.03.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.04.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.05.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.06.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.07.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.08.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.09.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.10.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.11.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.12.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.13.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.14.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.15.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.16.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.17.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.18.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.19.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.20.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.21.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.22.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.23.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.24.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.25.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.26.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.27.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.28.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.29.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.30.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.31.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.32.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.33.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.34.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.35.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.36.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.37.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.38.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.39.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.40.migration.test.ts` * `src/extension-api-v2/__tests__/migration/BC.41.migration.test.ts` * `src/extension-api-v2/__tests__/v1/BC.01.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.02.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.03.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.04.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.05.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.06.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.07.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.08.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.09.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.10.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.11.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.12.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.13.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.14.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.15.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.16.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.17.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.18.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.19.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.20.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.21.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.22.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.23.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.24.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.25.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.26.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.27.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.28.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.29.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.30.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.31.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.32.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.33.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.34.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.35.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.36.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.37.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.38.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.39.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.40.v1.test.ts` * `src/extension-api-v2/__tests__/v1/BC.41.v1.test.ts` * `src/extension-api-v2/__tests__/v2/BC.01.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.02.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.03.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.04.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.05.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.06.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.07.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.08.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.09.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.10.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.11.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.12.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.13.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.14.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.15.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.16.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.17.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.18.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.19.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.20.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.21.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.22.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.23.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.24.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.25.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.26.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.27.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.28.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.29.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.30.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.31.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.32.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.33.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.34.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.35.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.36.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.37.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.38.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.39.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.40.v2.test.ts` * `src/extension-api-v2/__tests__/v2/BC.41.v2.test.ts` * `src/extension-api-v2/harness.ts` * `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/extensions/core/dynamicPrompts.v2.ts` * `src/extensions/core/imageCrop.v2.ts` * `src/extensions/core/index.ts` * `src/extensions/core/previewAny.v2.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` * `vitest.extension-api.config.mts` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
CI lint-and-format was failing with ERR_PNPM_OUTDATED_LOCKFILE because packages/extension-api/package.json (added in fe6d439) introduced 4 new deps (tsx, typedoc, typedoc-plugin-markdown, typescript) without a corresponding lockfile update. Regenerated to bring lock in sync.
Codecov Report❌ Patch coverage is
@@ Coverage Diff @@
## main #12102 +/- ##
===========================================
- Coverage 73.67% 58.71% -14.96%
===========================================
Files 1512 1411 -101
Lines 87575 71928 -15647
Branches 24339 19000 -5339
===========================================
- Hits 64521 42236 -22285
- Misses 22198 29215 +7017
+ Partials 856 477 -379
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 1004 files with indirect coverage changes 🚀 New features to boost your workflow:
|
…en World stub
Resolves ~40 pre-existing typecheck failures on the foundation branch
caused by divergent entity-ID brand definitions:
- src/world/entityIds.ts brands as string + brand
- src/extension-api/{node,widget}.ts brands as number + brand
Both are now unified by re-exporting the world-layer brand from the
public API surface (string is canonical because Phase A entity IDs are
formatted like 'node:<graphUuid>:<localId>').
Also:
- World.getComponent / setComponent / removeComponent / entitiesWith are
now properly generic over <TData, TEntity>, so call sites get typed
data back instead of unknown.
- WidgetComponentSchema/Display/Value/Serialize/Container in
src/world/widgets/widgetComponents.ts get real data shapes
(type/options/label/hidden/disabled/value/serialize/widgetIds)
instead of opaque 'object'.
- getMode() casts the int return to NodeMode union.
- Hook result is typed as unknown so the runtime defensive Promise +
setupReturn checks don't trip TS2358 / TS1345.
- dynamicPrompts.v2.ts: widget.getValue<string>() (method-generic does
not exist) → widget.getValue() as string.
Result: 'pnpm typecheck' is now clean on ext-api/i-foundation.
…sole.* - .github/workflows/ci-tests-extension-api.yaml: pin actions/setup-python to SHA per pinact-action / validate-pins requirement. - src/services/extension-api-service.ts: add // eslint-disable-next-line no-console on each intentional console.warn/error in the extension API service. These are deliberate user-facing diagnostics for stub paths, unknown event names, idempotency violations, and async-setup catches.
Foundation Review Rollup — triage & statusThanks all — consolidating ~12 review entries into one reply so threads don't fan out. Recent fix commits on this branch:
Status legend: ✅ addressed · 🟡 needs-fix (queued) · ⏭ out-of-scope (Phase B / #11939 / D8 / UWF Phase 3) · ❌ wontfix 🏛 Adversarial Architect (review 1)
🪶 Adversarial Minimalist — codex (review 2)
🤺 Adversarial Skeptic (reviews 3 & 4 — duplicates)
🐛 bug-hunter — codex (review 8)
🌐 ecosystem-compat — codex (review 7)
🧪 regression-risk — codex (review 5)No findings — full method/blame audit recorded; 🔒 dep-secrets-scan — codex (review 6)
🟦 vue-patterns — codex (review 9)Out-of-scope (no 🐰 CodeRabbit (reviews 10–12; 10 & 11 dismissed/empty)
Summary
Will land needs-fix items as a follow-up commit on this branch (or roll into the next PR in the stack if scope allows). Phase B blockers stay tracked under |
|
Closing in favor of #12142 (restratified — properly-scoped foundation 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 |
Stack root for Phase A child PRs. Coworkers converting core extensions should branch off this branch.
Stacks on: #12101 (Phase A base — research bundle + first-pass surface)
Three foundation commits (in order)
refactor(extension-api): polish public declaration files (D5/D6/D7/D10)—src/extension-api/{index,lifecycle,node,widget}.ts, names appendix (DOC1.E6), AGENTS.mdfeat(extension-api): rename to extension-api-service.ts + boot wiring (MIG1.E5)— canonicalextension-api-service.ts, app boot wiring, sample*.v2.tsextensions aligned to refreshed surfacefeat(extension-api): scope registry + ECS world skeleton (I-SR.2)—src/world/(entities/components/NodeEntityId),scope-registry.test.tsper D10 + D12What stacks on this
Known minor
The deletion of the old
src/services/extensionV2Service.tsended up in the i-tf child PR rather than alongside the rename here. Final merged state is correct; flagging for reviewer awareness.Refs
D5 events typing · D6 parallel paths · D7 widget shape · D10 lifecycle · D12 scope clone-on-copy · MIG1.E4/E5 boot wiring
Draft for review collaboration via inline comments.
┆Issue is synchronized with this Notion page by Unito