diff --git a/.github/workflows/ci-tests-extension-api.yaml b/.github/workflows/ci-tests-extension-api.yaml
new file mode 100644
index 0000000000..9fd7c3d034
--- /dev/null
+++ b/.github/workflows/ci-tests-extension-api.yaml
@@ -0,0 +1,88 @@
+# Description: Extension API test suite (I-TF) + compat-floor gate (I-TF.7)
+#
+# Runs on any PR touching extension-api declaration files, extension-api-v2
+# implementation/tests, or the touch-point DB/rollup (blast-radius changes).
+#
+# Two jobs:
+#   test          — vitest run against src/extension-api-v2/__tests__/
+#   compat-floor  — python scripts/check-compat-floor.py (exits 1 if any
+#                   blast_radius ≥ 2.0 category is missing a stub triple)
+#
+# The compat-floor job is the CI enforcement of PLAN.md §Compat-floor:
+#   "Every blast_radius ≥ 2.0 pattern MUST pass v1 + v2 + migration before v2 ships."
+name: 'CI: Tests Extension API'
+
+on:
+  push:
+    branches: [main, master, dev*, core/*, extension-v2*]
+    paths:
+      - 'src/extension-api/**'
+      - 'src/extension-api-v2/**'
+      - 'packages/extension-api/**'
+      - 'vitest.extension-api.config.mts'
+      - 'research/touch-points/rollup.yaml'
+      - 'research/touch-points/behavior-categories.yaml'
+      - 'scripts/check-compat-floor.py'
+      - 'pnpm-lock.yaml'
+  pull_request:
+    branches-ignore: [wip/*, draft/*, temp/*]
+    paths:
+      - 'src/extension-api/**'
+      - 'src/extension-api-v2/**'
+      - 'packages/extension-api/**'
+      - 'vitest.extension-api.config.mts'
+      - 'research/touch-points/rollup.yaml'
+      - 'research/touch-points/behavior-categories.yaml'
+      - 'scripts/check-compat-floor.py'
+      - 'pnpm-lock.yaml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Extension API tests (vitest)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup frontend
+        uses: ./.github/actions/setup-frontend
+
+      - name: Run extension-api test suite
+        run: pnpm test:extension-api
+
+      - name: Run with coverage (push only)
+        if: github.event_name == 'push'
+        run: pnpm test:extension-api:coverage
+
+      - name: Upload coverage to Codecov
+        if: github.event_name == 'push'
+        uses: codecov/codecov-action@1af58845a975a7985b0beb0cbe6fbbb71a41dbad # v5.5.3
+        with:
+          files: coverage/lcov.info
+          flags: extension-api
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+  compat-floor:
+    name: Compat-floor gate (blast_radius ≥ 2.0)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install PyYAML
+        run: pip install pyyaml
+
+      - name: Check compat floor
+        run: python3 scripts/check-compat-floor.py
+        # Exits 1 if any blast_radius ≥ 2.0 behavior category is missing
+        # any of its three stub files (v1/v2/migration). Enforces PLAN.md §Compat-floor.
diff --git a/package.json b/package.json
index 275f3c49d5..6989a316c8 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,9 @@
     "test:browser:coverage": "cross-env COLLECT_COVERAGE=true pnpm test:browser",
     "test:browser:local": "cross-env PLAYWRIGHT_LOCAL=1 PLAYWRIGHT_TEST_URL=http://localhost:5173 pnpm test:browser",
     "test:coverage": "vitest run --coverage",
+    "test:extension-api": "vitest run --config vitest.extension-api.config.mts",
+    "test:extension-api:watch": "vitest --config vitest.extension-api.config.mts",
+    "test:extension-api:coverage": "vitest run --config vitest.extension-api.config.mts --coverage",
     "test:unit": "nx run test",
     "typecheck": "vue-tsc --noEmit",
     "typecheck:browser": "vue-tsc --project browser_tests/tsconfig.json",
diff --git a/packages/extension-api/.gitignore b/packages/extension-api/.gitignore
new file mode 100644
index 0000000000..43bb7e5561
--- /dev/null
+++ b/packages/extension-api/.gitignore
@@ -0,0 +1,3 @@
+docs-build/
+build/
+node_modules/
diff --git a/packages/extension-api/README.md b/packages/extension-api/README.md
new file mode 100644
index 0000000000..c56f9bf3a5
--- /dev/null
+++ b/packages/extension-api/README.md
@@ -0,0 +1,50 @@
+# @comfyorg/extension-api
+
+> **Status**: scaffolded. Package implementation pending PKG3 — see
+> `../../../plans/P2-extension-api-package.md` and
+> `../../../plans/prompts/PKG3-npm-package.md` in the workspace root.
+
+The official TypeScript declaration package for ComfyUI extensions. This
+package replaces the practice of vendoring `comfy.d.ts` files in custom
+node repos.
+
+## Install (post-publish)
+
+```bash
+pnpm add -D @comfyorg/extension-api
+```
+
+```ts
+import { defineExtension } from '@comfyorg/extension-api'
+
+export default defineExtension({
+  name: 'MyExtension',
+  setup(ctx) {
+    ctx.onNodeMounted((node) => {
+      // ...
+    })
+  }
+})
+```
+
+## Source
+
+This package is built from the source-of-truth folder
+`../../src/extension-api/`. Do not edit the package's `build/` output
+directly.
+
+## Versioning
+
+- `0.x.y` — experimental during parallel-paths transition (D6 Phase A).
+- `1.0.0` — first stable release once D5/D6/D7/D8 are accepted and the
+  surface has stabilized.
+- Breaking changes follow semver strictly from `1.0.0` onward.
+
+## Cross-references
+
+- `decisions/D6-parallel-paths-migration.md` — versioning rationale
+- `plans/P2-extension-api-package.md` — package structure plan
+- `plans/prompts/PKG3-npm-package.md` — implementation prompt
+- `plans/prompts/PKG4-ci-workflows.md` — publish workflow
+- `plans/prompts/PKG5-docgen-mdx.md` — docgen pipeline
+- `plans/prompts/PKG6-docs-comfy-org.md` — docs.comfy.org integration
diff --git a/packages/extension-api/package.json b/packages/extension-api/package.json
new file mode 100644
index 0000000000..75bc66ef52
--- /dev/null
+++ b/packages/extension-api/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@comfyorg/extension-api",
+  "version": "0.1.0",
+  "description": "Official TypeScript extension API for ComfyUI custom nodes",
+  "type": "module",
+  "exports": {
+    ".": "./build/index.js"
+  },
+  "types": "./build/index.d.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --emitDeclarationOnly --outDir build",
+    "docs:build": "tsx scripts/build-docs.ts",
+    "docs:watch": "tsx scripts/build-docs.ts --watch"
+  },
+  "devDependencies": {
+    "tsx": "catalog:",
+    "typedoc": "0.28.19",
+    "typedoc-plugin-markdown": "^4.6.3",
+    "typescript": "catalog:"
+  },
+  "nx": {
+    "tags": [
+      "scope:shared",
+      "type:api"
+    ]
+  }
+}
diff --git a/packages/extension-api/scripts/build-docs.ts b/packages/extension-api/scripts/build-docs.ts
new file mode 100644
index 0000000000..26e3f7741a
--- /dev/null
+++ b/packages/extension-api/scripts/build-docs.ts
@@ -0,0 +1,470 @@
+#!/usr/bin/env tsx
+/**
+ * PKG5 docgen pipeline: TypeDoc → Mintlify MDX
+ *
+ * Steps:
+ * 1. Run TypeDoc with typedoc-plugin-markdown to emit raw markdown into docs-build/raw/
+ * 2. Post-process each markdown file:
+ *    - Add Mintlify frontmatter (title, description, sidebarTitle, icon)
+ *    - Convert ``` fences without lang tag → ```ts
+ *    - Replace raw [TypeName] cross-refs with MDX relative links
+ *    - Wrap @example blocks in proper code fences
+ * 3. Write final .mdx files to docs-build/mintlify/
+ * 4. Emit docs-build/mintlify/nav-snippet.json — merges into docs.comfy.org mint.json
+ *
+ * Run: pnpm --filter @comfyorg/extension-api docs:build
+ */
+
+import { execSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const pkgRoot = path.resolve(__dirname, '..')
+const rawDir = path.join(pkgRoot, 'docs-build', 'raw')
+const mintlifyDir = path.join(pkgRoot, 'docs-build', 'mintlify')
+const watchMode = process.argv.includes('--watch')
+
+// ── Page metadata ────────────────────────────────────────────────────────────
+// Controls frontmatter for each generated page. Key = TypeDoc output filename
+// stem (lowercased). Unrecognised files get generic metadata.
+
+interface PageMeta {
+  title: string
+  sidebarTitle?: string
+  description: string
+  icon?: string
+  group: 'core' | 'handles' | 'events' | 'shell' | 'identity' | 'root'
+  order: number
+}
+
+const PAGE_META: Record<string, PageMeta> = {
+  // Top-level overview
+  index: {
+    title: 'Extension API Overview',
+    description: 'TypeScript API reference for ComfyUI custom node extensions.',
+    icon: 'puzzle-piece',
+    group: 'root',
+    order: 0
+  },
+  // Lifecycle / registration
+  defineextension: {
+    title: 'defineExtension',
+    description: 'Register an app-scoped extension for init, setup, and shell UI contributions.',
+    icon: 'code',
+    group: 'core',
+    order: 1
+  },
+  definenodeextension: {
+    title: 'defineNodeExtension',
+    description: 'Register a node-scoped extension reacting to node lifecycle events.',
+    icon: 'code',
+    group: 'core',
+    order: 2
+  },
+  definewidgetextension: {
+    title: 'defineWidgetExtension',
+    description: 'Register a custom widget type with its own DOM rendering.',
+    icon: 'code',
+    group: 'core',
+    order: 3
+  },
+  extensionoptions: {
+    title: 'ExtensionOptions',
+    description: 'Options object for defineExtension — app-wide lifecycle and shell UI.',
+    group: 'core',
+    order: 4
+  },
+  nodeextensionoptions: {
+    title: 'NodeExtensionOptions',
+    description: 'Options object for defineNodeExtension — node lifecycle hooks.',
+    group: 'core',
+    order: 5
+  },
+  widgetextensionoptions: {
+    title: 'WidgetExtensionOptions',
+    description: 'Options object for defineWidgetExtension — custom widget rendering.',
+    group: 'core',
+    order: 6
+  },
+  onnoderemoved: {
+    title: 'onNodeRemoved',
+    sidebarTitle: 'onNodeRemoved',
+    description: 'Implicit-context lifecycle hook: fires when a node is removed from the graph.',
+    group: 'core',
+    order: 7
+  },
+  onnodemounted: {
+    title: 'onNodeMounted',
+    sidebarTitle: 'onNodeMounted',
+    description: 'Implicit-context lifecycle hook: fires when a node is fully mounted.',
+    group: 'core',
+    order: 8
+  },
+  // Handles
+  nodehandle: {
+    title: 'NodeHandle',
+    description: 'Controlled access to node state, mutations, slots, and events.',
+    icon: 'circle-nodes',
+    group: 'handles',
+    order: 10
+  },
+  widgethandle: {
+    title: 'WidgetHandle',
+    description: 'Controlled access to widget state, mutations, and events.',
+    icon: 'sliders',
+    group: 'handles',
+    order: 11
+  },
+  slotinfo: {
+    title: 'SlotInfo',
+    description: 'Read-only snapshot of a node slot (input or output).',
+    group: 'handles',
+    order: 12
+  },
+  // Events
+  nodeexecutedevent: {
+    title: 'NodeExecutedEvent',
+    description: 'Payload fired when a node finishes execution.',
+    group: 'events',
+    order: 20
+  },
+  nodeconnectedevent: {
+    title: 'NodeConnectedEvent',
+    description: 'Payload fired when a slot connection is made.',
+    group: 'events',
+    order: 21
+  },
+  nodedisconnectedevent: {
+    title: 'NodeDisconnectedEvent',
+    description: 'Payload fired when a slot connection is removed.',
+    group: 'events',
+    order: 22
+  },
+  nodepositionchangedevent: {
+    title: 'NodePositionChangedEvent',
+    description: 'Payload fired when a node is moved on the canvas.',
+    group: 'events',
+    order: 23
+  },
+  nodesizechangedevent: {
+    title: 'NodeSizeChangedEvent',
+    description: 'Payload fired when a node is resized.',
+    group: 'events',
+    order: 24
+  },
+  nodemodechangedevent: {
+    title: 'NodeModeChangedEvent',
+    description: 'Payload fired when a node execution mode changes.',
+    group: 'events',
+    order: 25
+  },
+  nodebeforeserializeevent: {
+    title: 'NodeBeforeSerializeEvent',
+    description: 'Pre-serialization hook payload — override or skip node data.',
+    group: 'events',
+    order: 26
+  },
+  widgetvaluechangeevent: {
+    title: 'WidgetValueChangeEvent',
+    description: 'Payload fired when a widget value changes.',
+    group: 'events',
+    order: 27
+  },
+  widgetbeforeserializeevent: {
+    title: 'WidgetBeforeSerializeEvent',
+    description: 'Pre-serialization hook payload — override or skip widget value.',
+    group: 'events',
+    order: 28
+  },
+  widgetbeforequeueevent: {
+    title: 'WidgetBeforeQueueEvent',
+    description: 'Pre-queue validation payload — call reject() to cancel queue.',
+    group: 'events',
+    order: 29
+  },
+  // Shell UI
+  sidebartabextension: {
+    title: 'SidebarTabExtension',
+    description: 'Register a custom sidebar tab.',
+    group: 'shell',
+    order: 40
+  },
+  bottompanelextension: {
+    title: 'BottomPanelExtension',
+    description: 'Register a custom bottom panel tab.',
+    group: 'shell',
+    order: 41
+  },
+  toastmanager: {
+    title: 'ToastManager',
+    description: 'Show toast notifications to the user.',
+    group: 'shell',
+    order: 42
+  },
+  commandmanager: {
+    title: 'CommandManager',
+    description: 'Register keyboard shortcuts and command palette entries.',
+    group: 'shell',
+    order: 43
+  },
+  extensionmanager: {
+    title: 'ExtensionManager',
+    description: 'Access shell UI registration APIs.',
+    group: 'shell',
+    order: 44
+  },
+  // Identity
+  nodelocatorid: {
+    title: 'NodeLocatorId',
+    description: 'Branded string ID that uniquely locates a node across graph snapshots.',
+    group: 'identity',
+    order: 50
+  },
+  nodeexecutionid: {
+    title: 'NodeExecutionId',
+    description: 'Branded string ID for a specific node execution run.',
+    group: 'identity',
+    order: 51
+  }
+}
+
+const GROUP_LABELS: Record<PageMeta['group'], string> = {
+  root: 'Extensions API',
+  core: 'Registration',
+  handles: 'Handles',
+  events: 'Events',
+  shell: 'Shell UI',
+  identity: 'Identity'
+}
+
+// ── Utilities ────────────────────────────────────────────────────────────────
+
+function slug(stem: string): string {
+  return stem.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+}
+
+function metaFor(stem: string): PageMeta {
+  const key = stem.toLowerCase().replace(/[^a-z]/g, '')
+  return (
+    PAGE_META[key] ?? {
+      title: stem,
+      description: `API reference for ${stem}.`,
+      group: 'core',
+      order: 99
+    }
+  )
+}
+
+/** Convert TypeDoc raw markdown to Mintlify-compatible MDX. */
+function toMintlifyMdx(raw: string, stem: string): string {
+  const meta = metaFor(stem)
+
+  // Build frontmatter
+  const fm: string[] = [
+    `---`,
+    `title: "${meta.title}"`,
+    ...(meta.sidebarTitle ? [`sidebarTitle: "${meta.sidebarTitle}"`] : []),
+    `description: "${meta.description}"`,
+    ...(meta.icon ? [`icon: "${meta.icon}"`] : []),
+    `---`
+  ]
+
+  let body = raw
+
+  // Strip TypeDoc breadcrumb header lines (e.g. "[**@comfyorg/...**](../index.md)\n\n***\n\n[@comfyorg...]...")
+  body = body.replace(/^\[.*?\]\(\.\.\/index\.md\)\n+\*+\n+/gm, '')
+  body = body.replace(/^\[.*?\]\(\.\.\/index\.md\).*\n+/gm, '')
+
+  // Remove the TypeDoc-generated H1 (we use frontmatter title instead)
+  body = body.replace(/^# .+\n+/, '')
+
+  // Ensure opening code fences that have no lang tag get `ts`
+  // Only match a ``` that is immediately followed by a newline (opening fence),
+  // not a closing fence (which also has just ``` + newline but we can detect
+  // by context: opening fences follow non-fence lines; closing fences follow content).
+  // Simpler heuristic: replace ``` at start of line only when not already closing a block.
+  // We track state via a flag pass instead of a single regex.
+  let inBlock = false
+  body = body
+    .split('\n')
+    .map((line) => {
+      if (inBlock) {
+        if (line.trim() === '```') { inBlock = false; return line }
+        return line
+      }
+      if (line.startsWith('```')) {
+        if (line.trim() === '```') {
+          // bare opening fence → add ts
+          inBlock = true
+          return '```ts'
+        }
+        // has a lang tag already
+        inBlock = true
+        return line
+      }
+      return line
+    })
+    .join('\n')
+
+  // TypeDoc emits `typescript` lang tag; normalize to `ts`
+  body = body.replace(/^```typescript\b/gm, '```ts')
+
+  // Fix TypeDoc cross-ref links: [TypeName](../type-alias/TypeName.md) → relative MDX paths
+  // Pattern: [Label](../category/FileName.md) → [Label](./filename)
+  body = body.replace(
+    /\[([^\]]+)\]\(\.\.\/([\w-]+)\/([\w-]+)\.md\)/g,
+    (_match, label, _category, file) => `[${label}](./${slug(file)})`
+  )
+  // Same-dir links
+  body = body.replace(
+    /\[([^\]]+)\]\(([\w-]+)\.md\)/g,
+    (_match, label, file) => `[${label}](./${slug(file)})`
+  )
+
+  // TypeDoc wraps @example content in a "## Example" heading; Mintlify prefers
+  // code examples to be directly under prose without a sub-heading.
+  // Flatten "## Example\n\n```ts" → "```ts"
+  body = body.replace(/^## Example\s*\n+/gm, '')
+
+  // Stability tags: render as a <Tip> callout
+  body = body.replace(
+    /\*\*Stability\*\*: `(stable|experimental|deprecated)`/g,
+    (_match, level) => {
+      const label =
+        level === 'stable'
+          ? '<Tip>**Stability:** Stable — part of the public API contract.</Tip>'
+          : level === 'experimental'
+            ? '<Warning>**Stability:** Experimental — may change before 1.0.</Warning>'
+            : '<Warning>**Stability:** Deprecated — will be removed. See migration guide.</Warning>'
+      return label
+    }
+  )
+
+  // @stability TSDoc tag (appears as plain text after TypeDoc strips tags)
+  body = body.replace(
+    /^Stability: (stable|experimental|deprecated)\s*$/gm,
+    (_match, level) => {
+      if (level === 'stable') return '<Tip>**Stability:** Stable</Tip>'
+      if (level === 'experimental') return '<Warning>**Stability:** Experimental</Warning>'
+      return '<Warning>**Stability:** Deprecated</Warning>'
+    }
+  )
+
+  return [...fm, '', body.trim(), ''].join('\n')
+}
+
+// ── Nav snippet builder ───────────────────────────────────────────────────────
+
+interface NavPage {
+  group?: string
+  pages: (string | NavPage)[]
+}
+
+function buildNavSnippet(stems: string[]): NavPage {
+  const byGroup: Record<string, string[]> = {}
+
+  for (const stem of stems) {
+    const meta = metaFor(stem)
+    const group = meta.group
+    if (!byGroup[group]) byGroup[group] = []
+    byGroup[group].push(`extensions/api/${slug(stem)}`)
+  }
+
+  // Sort each group by order
+  const sortedStems = stems.slice().sort((a, b) => metaFor(a).order - metaFor(b).order)
+  const sortedByGroup: Record<string, string[]> = {}
+  for (const stem of sortedStems) {
+    const group = metaFor(stem).group
+    if (!sortedByGroup[group]) sortedByGroup[group] = []
+    sortedByGroup[group].push(`extensions/api/${slug(stem)}`)
+  }
+
+  const groupOrder: PageMeta['group'][] = ['root', 'core', 'handles', 'events', 'shell', 'identity']
+
+  const pages: (string | NavPage)[] = []
+
+  // Overview at top level
+  if (sortedByGroup['root']) {
+    for (const p of sortedByGroup['root']) pages.push(p)
+  }
+
+  for (const grp of groupOrder) {
+    if (grp === 'root') continue
+    const grpPages = sortedByGroup[grp]
+    if (!grpPages?.length) continue
+    pages.push({ group: GROUP_LABELS[grp], pages: grpPages })
+  }
+
+  return { group: 'Extensions API', pages }
+}
+
+// ── Main pipeline ────────────────────────────────────────────────────────────
+
+function runTypedoc(): void {
+  console.log('▶ Running TypeDoc...')
+  execSync(
+    `npx typedoc --options ${path.join(pkgRoot, 'typedoc.json')} --out ${rawDir}`,
+    { cwd: pkgRoot, stdio: 'inherit' }
+  )
+}
+
+function processFiles(): void {
+  if (!fs.existsSync(rawDir)) {
+    throw new Error(`TypeDoc output directory not found: ${rawDir}`)
+  }
+
+  fs.mkdirSync(mintlifyDir, { recursive: true })
+
+  const mdFiles = fs.readdirSync(rawDir, { recursive: true })
+    .filter((f): f is string => typeof f === 'string' && f.endsWith('.md'))
+
+  const stems: string[] = []
+
+  for (const relPath of mdFiles) {
+    const src = path.join(rawDir, relPath)
+    const stem = path.basename(relPath, '.md')
+    const raw = fs.readFileSync(src, 'utf8')
+    const mdx = toMintlifyMdx(raw, stem)
+
+    const destName = slug(stem) + '.mdx'
+    const dest = path.join(mintlifyDir, destName)
+    fs.writeFileSync(dest, mdx)
+    console.log(`  ✔ ${relPath} → mintlify/${destName}`)
+    stems.push(stem)
+  }
+
+  // Write nav snippet
+  const nav = buildNavSnippet(stems)
+  const navDest = path.join(mintlifyDir, 'nav-snippet.json')
+  fs.writeFileSync(navDest, JSON.stringify(nav, null, 2) + '\n')
+  console.log(`  ✔ nav-snippet.json`)
+
+  console.log(`\n✅ Mintlify MDX written to: ${mintlifyDir}`)
+  console.log(`   ${stems.length} pages + nav-snippet.json`)
+}
+
+function run(): void {
+  runTypedoc()
+  processFiles()
+}
+
+if (watchMode) {
+  // Simple watch: re-run on change to source files
+  console.log('👁  Watch mode — watching src/extension-api/**')
+  const srcDir = path.resolve(pkgRoot, '../../src/extension-api')
+  let debounce: ReturnType<typeof setTimeout> | null = null
+
+  run()
+
+  fs.watch(srcDir, { recursive: true }, () => {
+    if (debounce) clearTimeout(debounce)
+    debounce = setTimeout(() => {
+      console.log('\n🔄 Source changed — rebuilding...')
+      try { run() } catch (e) { console.error(e) }
+    }, 500)
+  })
+} else {
+  run()
+}
diff --git a/packages/extension-api/tsconfig.docs.json b/packages/extension-api/tsconfig.docs.json
new file mode 100644
index 0000000000..2699f818b4
--- /dev/null
+++ b/packages/extension-api/tsconfig.docs.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "paths": {
+      "@/*": ["../../src/*"]
+    }
+  },
+  "include": [
+    "../../src/extension-api/**/*.ts"
+  ],
+  "exclude": [
+    "../../src/**/*.test.ts",
+    "../../src/**/*.spec.ts",
+    "../../src/**/*.vue"
+  ]
+}
diff --git a/packages/extension-api/typedoc.json b/packages/extension-api/typedoc.json
new file mode 100644
index 0000000000..3338ea5425
--- /dev/null
+++ b/packages/extension-api/typedoc.json
@@ -0,0 +1,37 @@
+{
+  "entryPoints": ["../../src/extension-api/index.ts"],
+  "tsconfig": "./tsconfig.docs.json",
+  "out": "./docs-build/raw",
+  "plugin": ["typedoc-plugin-markdown"],
+  "excludeInternal": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "readme": "none",
+  "skipErrorChecking": true,
+  "githubPages": false,
+  "blockTags": ["@stability", "@packageDocumentation", "@example", "@typeParam", "@returns", "@deprecated", "@remarks"],
+  "hideGenerator": true,
+  "useCodeBlocks": true,
+  "flattenOutputFiles": false,
+  "entryFileName": "index",
+  "fileExtension": ".md",
+  "outputFileStrategy": "members",
+  "hidePageHeader": false,
+  "hideBreadcrumbs": false,
+  "useHTMLAnchors": false,
+  "sanitizeComments": true,
+  "expandObjects": false,
+  "parametersFormat": "table",
+  "propertiesFormat": "table",
+  "typeDeclarationFormat": "table",
+  "indexFormat": "table",
+  "tableColumnSettings": {
+    "hideDefaults": false,
+    "hideInherited": false,
+    "hideModifiers": false,
+    "hideOverrides": false,
+    "hideSources": true,
+    "hideValues": false,
+    "leftAlignHeaders": false
+  }
+}
diff --git a/src/extension-api-v2/__tests__/bc-01.migration.test.ts b/src/extension-api-v2/__tests__/bc-01.migration.test.ts
new file mode 100644
index 0000000000..aab3f658fd
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-01.migration.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.01 — Node lifecycle: creation
+// DB cross-ref: S2.N1, S2.N8
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/saveImageExtraOutput.ts#L31
+// compat-floor: blast_radius 4.48 ≥ 2.0 — MUST pass before v2 ships
+// Migration: v1 nodeCreated(node) + beforeRegisterNodeDef → v2 defineNodeExtension({ nodeCreated(handle) })
+
+import { describe, it } from 'vitest'
+
+describe('BC.01 migration — node lifecycle: creation', () => {
+  describe('nodeCreated parity (S2.N1)', () => {
+    it.todo(
+      'v1 nodeCreated and v2 nodeCreated are both invoked the same number of times when N nodes are created'
+    )
+    it.todo(
+      'side-effects applied to the node in v1 nodeCreated(node) are reproducible via NodeHandle methods in v2'
+    )
+    it.todo(
+      'v2 nodeCreated fires in the same relative order as v1 for extensions registered in the same order'
+    )
+  })
+
+  describe('beforeRegisterNodeDef → type-scoped defineNodeExtension (S2.N8)', () => {
+    it.todo(
+      'prototype mutation applied in v1 beforeRegisterNodeDef produces the same per-instance behavior as v2 type-scoped nodeCreated'
+    )
+    it.todo(
+      'v2 type-scoped extension does not affect node types that were excluded, matching v1 type-guard behavior'
+    )
+  })
+
+  describe('VueNode mount timing invariant', () => {
+    it.todo(
+      'both v1 and v2 nodeCreated fire before VueNode mounts — extensions relying on this ordering do not need changes'
+    )
+    it.todo(
+      'extensions that deferred DOM work to a callback in v1 can use onNodeMounted in v2 for the same guarantee'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-01.v1.test.ts b/src/extension-api-v2/__tests__/bc-01.v1.test.ts
new file mode 100644
index 0000000000..f7d273a13d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-01.v1.test.ts
@@ -0,0 +1,45 @@
+// Category: BC.01 — Node lifecycle: creation
+// DB cross-ref: S2.N1, S2.N8
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/saveImageExtraOutput.ts#L31
+// Surface: S2.N1 = nodeCreated hook, S2.N8 = beforeRegisterNodeDef
+// compat-floor: blast_radius 4.48 ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: app.registerExtension({ nodeCreated(node) { ... } })
+// Note: nodeCreated fires BEFORE the VueNode Vue component mounts; extensions needing
+//       VueNode-backed state must defer (see BC.37).
+
+import { describe, it } from 'vitest'
+
+describe('BC.01 v1 contract — node lifecycle: creation', () => {
+  describe('S2.N1 — nodeCreated hook', () => {
+    it.todo(
+      'nodeCreated is called once per node instance immediately after the node is constructed'
+    )
+    it.todo(
+      'nodeCreated receives the LGraphNode instance as its first argument'
+    )
+    it.todo(
+      'nodeCreated fires before the node is added to the graph (graph.nodes does not yet contain the node)'
+    )
+    it.todo(
+      'nodeCreated fires before the VueNode Vue component is mounted (vm.$el is null at call time)'
+    )
+    it.todo(
+      'properties set on node inside nodeCreated are accessible in subsequent lifecycle hooks'
+    )
+  })
+
+  describe('S2.N8 — beforeRegisterNodeDef hook', () => {
+    it.todo(
+      'beforeRegisterNodeDef is called once per node type before the type is registered in the node registry'
+    )
+    it.todo(
+      'beforeRegisterNodeDef receives the node constructor and the raw node definition object'
+    )
+    it.todo(
+      'prototype mutations made in beforeRegisterNodeDef affect all subsequently created instances of that type'
+    )
+    it.todo(
+      'beforeRegisterNodeDef is NOT called again on graph reload if the type is already registered'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-01.v2.test.ts b/src/extension-api-v2/__tests__/bc-01.v2.test.ts
new file mode 100644
index 0000000000..0f16ac27ca
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-01.v2.test.ts
@@ -0,0 +1,41 @@
+// Category: BC.01 — Node lifecycle: creation
+// DB cross-ref: S2.N1, S2.N8
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/saveImageExtraOutput.ts#L31
+// compat-floor: blast_radius 4.48 ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: defineNodeExtension({ nodeCreated(handle) { ... } })
+// Note: v2 nodeCreated receives a NodeHandle, not a raw LGraphNode. VueNode mount
+//       timing guarantee is unchanged — defer to onNodeMounted for Vue-backed state.
+
+import { describe, it } from 'vitest'
+
+describe('BC.01 v2 contract — node lifecycle: creation', () => {
+  describe('nodeCreated(handle) — per-instance setup', () => {
+    it.todo(
+      'nodeCreated is called once per node instance and receives a NodeHandle wrapping the created node'
+    )
+    it.todo(
+      'NodeHandle.id is stable and matches the underlying LGraphNode id at call time'
+    )
+    it.todo(
+      'NodeHandle.type returns the registered node type string'
+    )
+    it.todo(
+      'state stored via NodeHandle.setState() inside nodeCreated is retrievable in subsequent hooks for the same instance'
+    )
+    it.todo(
+      'nodeCreated fires before VueNode mounts; accessing NodeHandle.vueRef inside nodeCreated returns null'
+    )
+  })
+
+  describe('type-level registration (replacement for S2.N8)', () => {
+    it.todo(
+      'defineNodeExtension({ types: [\"MyNode\"] }) scopes nodeCreated to only instances of the listed types'
+    )
+    it.todo(
+      'omitting types: causes nodeCreated to fire for every node type (global registration)'
+    )
+    it.todo(
+      'type-scoped registration does not receive nodeCreated calls for unregistered node types'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-02.migration.test.ts b/src/extension-api-v2/__tests__/bc-02.migration.test.ts
new file mode 100644
index 0000000000..9d86599ed0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-02.migration.test.ts
@@ -0,0 +1,36 @@
+// Category: BC.02 — Node lifecycle: teardown
+// DB cross-ref: S2.N4
+// Exemplar: https://github.com/Lightricks/ComfyUI-LTXVideo/blob/main/web/js/sparse_track_editor.js#L137
+// compat-floor: blast_radius 5.20 ≥ 2.0 — MUST pass before v2 ships
+// Migration: v1 node.onRemoved assignment → v2 defineNodeExtension({ onRemoved(handle) })
+
+import { describe, it } from 'vitest'
+
+describe('BC.02 migration — node lifecycle: teardown', () => {
+  describe('invocation parity (S2.N4)', () => {
+    it.todo(
+      'v1 onRemoved and v2 onRemoved are both called the same number of times for the same sequence of node removals'
+    )
+    it.todo(
+      'v2 onRemoved fires at the same point in the removal lifecycle as v1 (after node is detached from graph)'
+    )
+  })
+
+  describe('resource cleanup equivalence', () => {
+    it.todo(
+      'intervals cleared in v1 onRemoved are equally suppressible via NodeHandle.onDispose() in v2 without manual tracking'
+    )
+    it.todo(
+      'DOM elements removed manually in v1 onRemoved are automatically removed by v2 auto-disposal when registered via addDOMWidget()'
+    )
+    it.todo(
+      'observer.disconnect() patterns in v1 can be replaced by NodeHandle.onDispose(() => observer.disconnect()) in v2'
+    )
+  })
+
+  describe('graph clear coverage', () => {
+    it.todo(
+      'both v1 and v2 teardown hooks are invoked for all nodes when graph.clear() is called'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-02.v1.test.ts b/src/extension-api-v2/__tests__/bc-02.v1.test.ts
new file mode 100644
index 0000000000..c65fdf6c91
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-02.v1.test.ts
@@ -0,0 +1,135 @@
+// Category: BC.02 — Node lifecycle: teardown
+// DB cross-ref: S2.N4
+// Exemplar: https://github.com/Lightricks/ComfyUI-LTXVideo/blob/main/web/js/sparse_track_editor.js#L137
+// Surface: S2.N4 = node.onRemoved
+// compat-floor: blast_radius 5.20 ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.onRemoved = function() { /* cleanup DOM, intervals, observers */ }
+//
+// I-TF.3.C3 — proof-of-concept harness wiring.
+// Phase A harness limitation: MiniGraph.remove() deletes the entity from the World
+// but does NOT automatically call onRemoved (that requires Phase B eval sandbox +
+// LiteGraph prototype wiring). The wired tests below call onRemoved explicitly after
+// graph.remove() to prove the harness mechanics and assertion patterns work.
+// The TODO stubs below them track what needs Phase B to become real assertions.
+
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  countEvidenceExcerpts,
+  createHarnessWorld,
+  createMiniComfyApp,
+  loadEvidenceSnippet
+} from '../harness'
+
+// ── Proof-of-concept wired tests (I-TF.3.C3) ────────────────────────────────
+// These pass today. They prove: (a) the harness can model the v1 teardown
+// pattern, (b) removal is reflected in the World, (c) the cleanup callback
+// fires when the extension calls it, (d) evidence excerpts load for S2.N4.
+
+describe('BC.02 v1 contract — node lifecycle: teardown [harness POC]', () => {
+  describe('S2.N4 — onRemoved harness mechanics', () => {
+    it('cleanup callback fires when extension calls it after graph.remove()', () => {
+      const world = createHarnessWorld()
+      const app = createMiniComfyApp(world)
+
+      // v1 pattern: extension patches onRemoved on the node during nodeCreated.
+      // We model this as a plain function stored on a node-shaped object.
+      const cleanupFn = vi.fn()
+      const node = {
+        type: 'LTXVideo',
+        entityId: app.graph.add({ type: 'LTXVideo' }),
+        onRemoved: cleanupFn
+      }
+
+      expect(world.findNode(node.entityId)).toBeDefined()
+
+      // Simulate the LiteGraph removal sequence (Phase A: explicit call).
+      app.graph.remove(node.entityId)
+      node.onRemoved()
+
+      expect(world.findNode(node.entityId)).toBeUndefined()
+      expect(cleanupFn).toHaveBeenCalledOnce()
+    })
+
+    it('cleanup callback does not fire if remove is never called', () => {
+      const world = createHarnessWorld()
+      const app = createMiniComfyApp(world)
+      const cleanupFn = vi.fn()
+      const entityId = app.graph.add({ type: 'KSampler' })
+
+      // Node exists; no removal; callback should not have been invoked.
+      void entityId
+      expect(cleanupFn).not.toHaveBeenCalled()
+      expect(world.allNodes()).toHaveLength(1)
+    })
+
+    it('multiple nodes — each removal triggers only its own callback', () => {
+      const world = createHarnessWorld()
+      const app = createMiniComfyApp(world)
+
+      const cbA = vi.fn()
+      const cbB = vi.fn()
+      const idA = app.graph.add({ type: 'NodeA' })
+      const idB = app.graph.add({ type: 'NodeB' })
+
+      // Remove only A.
+      app.graph.remove(idA)
+      cbA()  // simulate LiteGraph calling onRemoved on the removed node only
+
+      expect(cbA).toHaveBeenCalledOnce()
+      expect(cbB).not.toHaveBeenCalled()
+      expect(world.findNode(idA)).toBeUndefined()
+      expect(world.findNode(idB)).toBeDefined()
+    })
+
+    it('graph.clear() removes all nodes from the World', () => {
+      const world = createHarnessWorld()
+      const app = createMiniComfyApp(world)
+
+      app.graph.add({ type: 'NodeA' })
+      app.graph.add({ type: 'NodeB' })
+      app.graph.add({ type: 'NodeC' })
+      expect(world.allNodes()).toHaveLength(3)
+
+      world.clear()
+      expect(world.allNodes()).toHaveLength(0)
+    })
+  })
+
+  describe('S2.N4 — evidence excerpt (loadEvidenceSnippet)', () => {
+    it('S2.N4 has at least one evidence excerpt in the snapshot', () => {
+      expect(countEvidenceExcerpts('S2.N4')).toBeGreaterThan(0)
+    })
+
+    it('S2.N4 excerpt contains onRemoved fingerprint', () => {
+      const snippet = loadEvidenceSnippet('S2.N4', 0)
+      expect(snippet.length).toBeGreaterThan(0)
+      expect(snippet).toMatch(/onRemoved/i)
+    })
+  })
+})
+
+// ── Phase B stubs — need eval sandbox + LiteGraph prototype wiring ───────────
+
+describe('BC.02 v1 contract — node lifecycle: teardown [Phase B]', () => {
+  describe('S2.N4 — node.onRemoved', () => {
+    it.todo(
+      'onRemoved is called exactly once when a node is removed from the graph via graph.remove(node)'
+    )
+    it.todo(
+      'onRemoved is called when a node is deleted via the canvas context-menu delete action'
+    )
+    it.todo(
+      'onRemoved is called for every node when the graph is cleared (graph.clear())'
+    )
+    it.todo(
+      'DOM widgets appended by the extension are accessible for cleanup inside onRemoved (not yet garbage-collected)'
+    )
+    it.todo(
+      'setInterval / requestAnimationFrame handles stored on the node instance can be cancelled inside onRemoved'
+    )
+    it.todo(
+      'MutationObserver and ResizeObserver instances stored on the node can be disconnected inside onRemoved'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-02.v2.test.ts b/src/extension-api-v2/__tests__/bc-02.v2.test.ts
new file mode 100644
index 0000000000..cfd985699a
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-02.v2.test.ts
@@ -0,0 +1,38 @@
+// Category: BC.02 — Node lifecycle: teardown
+// DB cross-ref: S2.N4
+// Exemplar: https://github.com/Lightricks/ComfyUI-LTXVideo/blob/main/web/js/sparse_track_editor.js#L137
+// compat-floor: blast_radius 5.20 ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: defineNodeExtension({ onRemoved(handle) { ... } })
+// Note: v2 onRemoved runs inside the NodeHandle scope; extension-owned resources
+//       registered via handle APIs are auto-disposed before onRemoved fires.
+
+import { describe, it } from 'vitest'
+
+describe('BC.02 v2 contract — node lifecycle: teardown', () => {
+  describe('onRemoved(handle) — cleanup hook', () => {
+    it.todo(
+      'onRemoved is called exactly once per node instance when the node is removed from the graph'
+    )
+    it.todo(
+      'onRemoved receives the same NodeHandle that was passed to nodeCreated for the same instance'
+    )
+    it.todo(
+      'NodeHandle.getState() is still readable inside onRemoved (state not yet cleared)'
+    )
+    it.todo(
+      'onRemoved is called for every node when the graph is cleared, in no guaranteed order'
+    )
+  })
+
+  describe('auto-disposal of handle-registered resources', () => {
+    it.todo(
+      'DOM widgets registered via NodeHandle.addDOMWidget() are removed from the DOM before onRemoved fires'
+    )
+    it.todo(
+      'cleanup functions registered via NodeHandle.onDispose() are invoked before onRemoved fires'
+    )
+    it.todo(
+      'extension can still perform additional teardown in onRemoved after auto-disposal completes'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-03.migration.test.ts b/src/extension-api-v2/__tests__/bc-03.migration.test.ts
new file mode 100644
index 0000000000..4880df9c5b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-03.migration.test.ts
@@ -0,0 +1,36 @@
+// Category: BC.03 — Node lifecycle: hydration from saved workflows
+// DB cross-ref: S1.H1, S2.N7
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// compat-floor: blast_radius 4.91 ≥ 2.0 — MUST pass before v2 ships
+// Migration: v1 node.onConfigure / beforeRegisterNodeDef → v2 defineNodeExtension({ onConfigure(handle, data) })
+
+import { describe, it } from 'vitest'
+
+describe('BC.03 migration — node lifecycle: hydration from saved workflows', () => {
+  describe('onConfigure parity (S2.N7)', () => {
+    it.todo(
+      'v1 node.onConfigure and v2 onConfigure are both called exactly once per node during workflow load'
+    )
+    it.todo(
+      'the serialized data object received in v2 onConfigure contains the same fields as in v1'
+    )
+    it.todo(
+      'custom property restoration logic written for v1 onConfigure is portable to v2 with only handle substitution'
+    )
+  })
+
+  describe('beforeRegisterNodeDef hydration guard → type-scoped extension (S1.H1)', () => {
+    it.todo(
+      'prototype-level onConfigure injected via v1 beforeRegisterNodeDef produces the same hydration result as a v2 type-scoped onConfigure'
+    )
+    it.todo(
+      'v2 type-scoped onConfigure does not fire for node types not listed in types:, matching v1 guard behavior'
+    )
+  })
+
+  describe('fresh-creation exclusion invariant', () => {
+    it.todo(
+      'neither v1 nor v2 onConfigure fires when a node is created fresh (not from a saved workflow)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-03.v1.test.ts b/src/extension-api-v2/__tests__/bc-03.v1.test.ts
new file mode 100644
index 0000000000..ebe4844649
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-03.v1.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.03 — Node lifecycle: hydration from saved workflows
+// DB cross-ref: S1.H1, S2.N7
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// Surface: S1.H1 = beforeRegisterNodeDef (used for hydration guards), S2.N7 = node.onConfigure
+// compat-floor: blast_radius 4.91 ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: S1.H1 = beforeRegisterNodeDef guard; S2.N7 = node.onConfigure = function(data) { ... }
+// Note: loadedGraphNode hook exists in LiteGraph but is effectively unused in ComfyUI —
+//       onConfigure is the de-facto hydration surface.
+
+import { describe, it } from 'vitest'
+
+describe('BC.03 v1 contract — node lifecycle: hydration from saved workflows', () => {
+  describe('S2.N7 — node.onConfigure', () => {
+    it.todo(
+      'onConfigure is called when a saved workflow is loaded and the node is rehydrated from serialized data'
+    )
+    it.todo(
+      'onConfigure receives the raw serialized node object (data) as its first argument'
+    )
+    it.todo(
+      'onConfigure is NOT called on freshly created nodes (only on deserialization)'
+    )
+    it.todo(
+      'widget values written to data inside a prior session are accessible via data.widgets_values in onConfigure'
+    )
+    it.todo(
+      'extensions can restore custom properties stored in data.properties inside onConfigure'
+    )
+  })
+
+  describe('S1.H1 — beforeRegisterNodeDef hydration guard', () => {
+    it.todo(
+      'beforeRegisterNodeDef can inject a custom onConfigure override on the node prototype before any instance is created'
+    )
+    it.todo(
+      'prototype-level onConfigure injected in beforeRegisterNodeDef is invoked for all instances during workflow load'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-03.v2.test.ts b/src/extension-api-v2/__tests__/bc-03.v2.test.ts
new file mode 100644
index 0000000000..a207e3a14a
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-03.v2.test.ts
@@ -0,0 +1,36 @@
+// Category: BC.03 — Node lifecycle: hydration from saved workflows
+// DB cross-ref: S1.H1, S2.N7
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// compat-floor: blast_radius 4.91 ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: defineNodeExtension({ onConfigure(handle, data) { ... } })
+
+import { describe, it } from 'vitest'
+
+describe('BC.03 v2 contract — node lifecycle: hydration from saved workflows', () => {
+  describe('onConfigure(handle, data) — workflow hydration hook', () => {
+    it.todo(
+      'onConfigure is called when a node is rehydrated from a saved workflow and NOT on fresh node creation'
+    )
+    it.todo(
+      'onConfigure receives the NodeHandle as first argument and the raw serialized node object as second argument'
+    )
+    it.todo(
+      'data passed to onConfigure contains widgets_values from the saved workflow'
+    )
+    it.todo(
+      'data passed to onConfigure contains properties from the saved workflow'
+    )
+    it.todo(
+      'state written to NodeHandle inside onConfigure is readable in all subsequent hook calls for that instance'
+    )
+  })
+
+  describe('ordering and idempotency guarantees', () => {
+    it.todo(
+      'onConfigure fires after nodeCreated for the same instance during workflow load'
+    )
+    it.todo(
+      'onConfigure is not called a second time if the same node receives a re-configure (idempotent load)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-04.migration.test.ts b/src/extension-api-v2/__tests__/bc-04.migration.test.ts
new file mode 100644
index 0000000000..1b4ce440d2
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-04.migration.test.ts
@@ -0,0 +1,45 @@
+// Category: BC.04 — Node interaction: pointer, selection, resize
+// DB cross-ref: S2.N10, S2.N17, S2.N19
+// Exemplar: https://github.com/diodiogod/TTS-Audio-Suite/blob/main/web/chatterbox_voice_capture.js#L202
+// compat-floor: blast_radius 4.95 ≥ 2.0 — MUST pass before v2 ships
+// Migration: v1 node.onMouseDown/onSelected/onResize → v2 handle.on('mousedown'|'selected'|'resize', ...)
+
+import { describe, it } from 'vitest'
+
+describe('BC.04 migration — node interaction: pointer, selection, resize', () => {
+  describe('mousedown parity (S2.N10)', () => {
+    it.todo(
+      'v1 node.onMouseDown and v2 handle.on("mousedown") are both invoked for the same pointer-down events'
+    )
+    it.todo(
+      'propagation-stop by returning true in v1 is equivalent to event.stopPropagation() in v2 handler'
+    )
+    it.todo(
+      'local coordinates passed to v1 onMouseDown match the x/y in the v2 event object for the same input'
+    )
+  })
+
+  describe('selection parity (S2.N17)', () => {
+    it.todo(
+      'v1 node.onSelected and v2 handle.on("selected") are both invoked when the node is selected'
+    )
+    it.todo(
+      'v2 introduces an explicit deselected event absent in v1; migration must add deselected handler for cleanup that relied on onSelected re-fire'
+    )
+  })
+
+  describe('resize parity (S2.N19)', () => {
+    it.todo(
+      'v1 node.onResize([w,h]) and v2 handle.on("resize", { width, height }) convey the same dimensions for the same resize action'
+    )
+    it.todo(
+      'computeSize overrides that triggered onResize in v1 still trigger the resize event in v2'
+    )
+  })
+
+  describe('listener lifetime', () => {
+    it.todo(
+      'v1 listeners on removed nodes remain registered (leak); v2 handle.on() listeners are auto-removed on node removal'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-04.v1.test.ts b/src/extension-api-v2/__tests__/bc-04.v1.test.ts
new file mode 100644
index 0000000000..47143020c0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-04.v1.test.ts
@@ -0,0 +1,49 @@
+// Category: BC.04 — Node interaction: pointer, selection, resize
+// DB cross-ref: S2.N10, S2.N17, S2.N19
+// Exemplar: https://github.com/diodiogod/TTS-Audio-Suite/blob/main/web/chatterbox_voice_capture.js#L202
+// Surface: S2.N10 = node.onMouseDown, S2.N17 = node.onSelected, S2.N19 = node.onResize
+// compat-floor: blast_radius 4.95 ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.onMouseDown, node.onSelected, node.onResize prototype method assignments
+
+import { describe, it } from 'vitest'
+
+describe('BC.04 v1 contract — node interaction: pointer, selection, resize', () => {
+  describe('S2.N10 — node.onMouseDown', () => {
+    it.todo(
+      'onMouseDown is called when a pointer-down event occurs within the node bounding box on the canvas'
+    )
+    it.todo(
+      'onMouseDown receives the MouseEvent and the local [x, y] position within the node as arguments'
+    )
+    it.todo(
+      'returning true from onMouseDown stops propagation to LiteGraph default mouse handling'
+    )
+    it.todo(
+      'onMouseDown is NOT called when the pointer down is outside the node bounding box'
+    )
+  })
+
+  describe('S2.N17 — node.onSelected', () => {
+    it.todo(
+      'onSelected is called when the node transitions to selected state (single-click or box-select)'
+    )
+    it.todo(
+      'onSelected is called once per selection event even if the node was already selected'
+    )
+    it.todo(
+      'onSelected is not called when a different node is selected and this node is deselected'
+    )
+  })
+
+  describe('S2.N19 — node.onResize', () => {
+    it.todo(
+      'onResize is called after the node dimensions change (user drag-resize or programmatic setSize)'
+    )
+    it.todo(
+      'onResize receives the new [width, height] array as its argument'
+    )
+    it.todo(
+      'onResize is called after the node size is committed, not during the drag'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-04.v2.test.ts b/src/extension-api-v2/__tests__/bc-04.v2.test.ts
new file mode 100644
index 0000000000..b9ce7ed22c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-04.v2.test.ts
@@ -0,0 +1,48 @@
+// Category: BC.04 — Node interaction: pointer, selection, resize
+// DB cross-ref: S2.N10, S2.N17, S2.N19
+// Exemplar: https://github.com/diodiogod/TTS-Audio-Suite/blob/main/web/chatterbox_voice_capture.js#L202
+// compat-floor: blast_radius 4.95 ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: defineNodeExtension({ on('mousedown', ...), on('selected', ...), on('resize', ...) })
+
+import { describe, it } from 'vitest'
+
+describe('BC.04 v2 contract — node interaction: pointer, selection, resize', () => {
+  describe('on(\"mousedown\", handler) — pointer events (S2.N10)', () => {
+    it.todo(
+      'handle.on("mousedown", handler) registers a listener called when pointer-down occurs within the node bounding box'
+    )
+    it.todo(
+      'handler receives an event object with local x/y coordinates relative to the node origin'
+    )
+    it.todo(
+      'handler returning true stops propagation to LiteGraph default mouse handling'
+    )
+    it.todo(
+      'listener registered via handle.on() is automatically removed when the node is removed from the graph'
+    )
+  })
+
+  describe('on(\"selected\", handler) — selection focus (S2.N17)', () => {
+    it.todo(
+      'handle.on("selected", handler) is called when the node enters selected state'
+    )
+    it.todo(
+      'handle.on("deselected", handler) is called when the node exits selected state'
+    )
+    it.todo(
+      'selected and deselected events do not fire during programmatic selection with { silent: true } option'
+    )
+  })
+
+  describe('on(\"resize\", handler) — resize feedback (S2.N19)', () => {
+    it.todo(
+      'handle.on("resize", handler) is called after the node dimensions change'
+    )
+    it.todo(
+      'handler receives a { width, height } object matching the new node size'
+    )
+    it.todo(
+      'resize event fires for both user drag-resize and programmatic NodeHandle.setSize() calls'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-05.migration.test.ts b/src/extension-api-v2/__tests__/bc-05.migration.test.ts
new file mode 100644
index 0000000000..d1f38640c8
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-05.migration.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.05 — Custom DOM widgets and node sizing
+// DB cross-ref: S4.W2, S2.N11
+// Exemplar: https://github.com/Lightricks/ComfyUI-LTXVideo/blob/main/web/js/sparse_track_editor.js#L218
+// compat-floor: blast_radius 5.45 ≥ 2.0 — MUST pass before v2 ships
+// Migration: v1 node.addDOMWidget + node.computeSize → v2 NodeHandle.addDOMWidget + WidgetHandle.setHeight
+
+import { describe, it } from 'vitest'
+
+describe('BC.05 migration — custom DOM widgets and node sizing', () => {
+  describe('widget registration parity (S4.W2)', () => {
+    it.todo(
+      'v1 node.addDOMWidget and v2 NodeHandle.addDOMWidget both result in the element being visible inside the node widget area'
+    )
+    it.todo(
+      'the widget is accessible by name in both v1 node.widgets and v2 NodeHandle.widgets after registration'
+    )
+    it.todo(
+      'v1 opts.getHeight() returning N produces the same reserved height as v2 addDOMWidget({ height: N })'
+    )
+  })
+
+  describe('computeSize elimination (S2.N11)', () => {
+    it.todo(
+      'v1 manual computeSize override is unnecessary in v2; equivalent height reservation is achieved via WidgetHandle.setHeight()'
+    )
+    it.todo(
+      'node rendered with v2 auto-computeSize integration has the same final dimensions as v1 with an equivalent manual computeSize override'
+    )
+  })
+
+  describe('cleanup parity', () => {
+    it.todo(
+      'v1 requires manual DOM removal in onRemoved; v2 auto-removes the widget element — both result in the element being absent after node removal'
+    )
+    it.todo(
+      'v2 auto-cleanup does not remove DOM elements that were not registered via addDOMWidget, matching v1 scoping'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-05.v1.test.ts b/src/extension-api-v2/__tests__/bc-05.v1.test.ts
new file mode 100644
index 0000000000..c632156cd9
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-05.v1.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.05 — Custom DOM widgets and node sizing
+// DB cross-ref: S4.W2, S2.N11
+// Exemplar: https://github.com/Lightricks/ComfyUI-LTXVideo/blob/main/web/js/sparse_track_editor.js#L218
+// Surface: S4.W2 = node.addDOMWidget, S2.N11 = node.computeSize override
+// compat-floor: blast_radius 5.45 ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.addDOMWidget(name, type, element, opts) + node.computeSize = function(out) { ... }
+
+import { describe, it } from 'vitest'
+
+describe('BC.05 v1 contract — custom DOM widgets and node sizing', () => {
+  describe('S4.W2 — node.addDOMWidget', () => {
+    it.todo(
+      'addDOMWidget(name, type, element, opts) appends the provided DOM element inside the node widget area'
+    )
+    it.todo(
+      'widget registered via addDOMWidget is accessible via node.widgets array by the given name'
+    )
+    it.todo(
+      'addDOMWidget opts.getHeight() is called during layout to determine the widget reserved height'
+    )
+    it.todo(
+      'addDOMWidget opts.onDraw(ctx) callback is invoked during each canvas render pass'
+    )
+    it.todo(
+      'the DOM element is removed from the document when the node is removed via graph.remove()'
+    )
+  })
+
+  describe('S2.N11 — node.computeSize override', () => {
+    it.todo(
+      'assigning node.computeSize = function(out) { ... } overrides the default size calculation for the node'
+    )
+    it.todo(
+      'overridden computeSize is called by LiteGraph layout engine before rendering'
+    )
+    it.todo(
+      'computeSize can return a [width, height] pair that accounts for the DOM widget reserved height'
+    )
+    it.todo(
+      'computeSize override persists across graph load/reload if set in nodeCreated or beforeRegisterNodeDef'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-05.v2.test.ts b/src/extension-api-v2/__tests__/bc-05.v2.test.ts
new file mode 100644
index 0000000000..4c89cd939a
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-05.v2.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.05 — Custom DOM widgets and node sizing
+// DB cross-ref: S4.W2, S2.N11
+// Exemplar: https://github.com/Lightricks/ComfyUI-LTXVideo/blob/main/web/js/sparse_track_editor.js#L218
+// compat-floor: blast_radius 5.45 ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: NodeHandle.addDOMWidget(opts) — auto-hooks computeSize via WidgetHandle geometry
+
+import { describe, it } from 'vitest'
+
+describe('BC.05 v2 contract — custom DOM widgets and node sizing', () => {
+  describe('NodeHandle.addDOMWidget(opts) — widget registration', () => {
+    it.todo(
+      'NodeHandle.addDOMWidget({ name, element }) appends the element inside the node widget area'
+    )
+    it.todo(
+      'addDOMWidget returns a WidgetHandle that exposes the registered widget for further configuration'
+    )
+    it.todo(
+      'widget registered via addDOMWidget is included in NodeHandle.widgets list under opts.name'
+    )
+    it.todo(
+      'addDOMWidget({ name, element, height }) reserves the specified height without requiring a manual computeSize override'
+    )
+    it.todo(
+      'the DOM element is removed from the document automatically when the node is removed (no manual cleanup)'
+    )
+  })
+
+  describe('WidgetHandle geometry — auto-computeSize integration (S2.N11)', () => {
+    it.todo(
+      'WidgetHandle.setHeight(px) updates the reserved height and triggers a node relayout without a manual computeSize call'
+    )
+    it.todo(
+      'when multiple DOM widgets are registered, the total node height accounts for all widget heights'
+    )
+    it.todo(
+      'calling WidgetHandle.setHeight() after initial mount correctly re-lays out the node on next render frame'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-06.migration.test.ts b/src/extension-api-v2/__tests__/bc-06.migration.test.ts
new file mode 100644
index 0000000000..f6e122c067
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-06.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.06 — Custom canvas drawing (per-node and canvas-level)
+// DB cross-ref: S2.N9, S3.C1, S3.C2
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/setgetnodes.js#L1256
+// compat-floor: blast_radius 5.25 ≥ 2.0 — MUST pass before v2 ships
+// Migration: v1 node.onDrawForeground → v2 NodeHandle.onDraw (partial).
+//            S3.C1 / S3.C2 canvas-level overrides: no v2 migration path yet (D9 Phase C).
+
+import { describe, it } from 'vitest'
+
+describe('BC.06 migration — custom canvas drawing (per-node and canvas-level)', () => {
+  describe('per-node drawing migration (S2.N9)', () => {
+    it.todo(
+      'v1 node.onDrawForeground and v2 NodeHandle.onDraw both produce visually equivalent output on the canvas for the same drawing operations'
+    )
+    it.todo(
+      'draw callback in v2 fires the same number of times per second as v1 onDrawForeground for a static scene'
+    )
+    it.todo(
+      'v2 DrawContext.ctx is the same CanvasRenderingContext2D state as v1 receives (same transform, same clip)'
+    )
+  })
+
+  describe('auto-deregistration vs manual cleanup', () => {
+    it.todo(
+      'v1 onDrawForeground continues to fire after node removal if the reference is not cleared (leak); v2 onDraw is auto-removed'
+    )
+    it.todo(
+      'v2 auto-deregistration on node removal does not affect onDraw callbacks registered for other nodes'
+    )
+  })
+
+  describe('canvas-level override coexistence (S3.C1, S3.C2)', () => {
+    it.todo(
+      'extensions that replace LGraphCanvas.prototype methods in v1 continue to function alongside v2 NodeHandle.onDraw registrations without conflict'
+    )
+    it.todo(
+      'processContextMenu replacement in v1 is not disrupted by extensions migrated to v2 per-node APIs'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-06.v1.test.ts b/src/extension-api-v2/__tests__/bc-06.v1.test.ts
new file mode 100644
index 0000000000..5d19088376
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-06.v1.test.ts
@@ -0,0 +1,55 @@
+// Category: BC.06 — Custom canvas drawing (per-node and canvas-level)
+// DB cross-ref: S2.N9, S3.C1, S3.C2
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/setgetnodes.js#L1256
+// Surface: S2.N9 = node.onDrawForeground, S3.C1 = LGraphCanvas.prototype overrides, S3.C2 = ContextMenu replacement
+// compat-floor: blast_radius 5.25 ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.onDrawForeground(ctx, area), LGraphCanvas.prototype.processContextMenu = ...,
+//              LGraphCanvas.prototype.drawNodeShape = ... etc.
+// v1_scope_note: Simon Tranter (COM-3668) vetoed canvas drawing overrides as "too hacky/specific".
+//                S3.C* patterns tracked for blast-radius / strangler-fig planning only.
+
+import { describe, it } from 'vitest'
+
+describe('BC.06 v1 contract — custom canvas drawing (per-node and canvas-level)', () => {
+  describe('S2.N9 — node.onDrawForeground', () => {
+    it.todo(
+      'onDrawForeground(ctx, visibleArea) is called once per render frame for each visible node'
+    )
+    it.todo(
+      'ctx passed to onDrawForeground is the same CanvasRenderingContext2D used by LiteGraph for the node layer'
+    )
+    it.todo(
+      'drawing operations performed in onDrawForeground appear above the node body and below the selection highlight'
+    )
+    it.todo(
+      'onDrawForeground is NOT called for nodes outside the visible area (culled by LiteGraph)'
+    )
+    it.todo(
+      'canvas transform (scale, translate) is already applied when onDrawForeground fires — coordinates are in graph space'
+    )
+  })
+
+  describe('S3.C1 — LGraphCanvas.prototype method overrides', () => {
+    it.todo(
+      'assigning LGraphCanvas.prototype.drawNodeShape replaces the built-in node shape renderer for all nodes'
+    )
+    it.todo(
+      'prototype override affects all canvas instances sharing the same prototype (global side-effect)'
+    )
+    it.todo(
+      'two extensions both overriding the same LGraphCanvas.prototype method result in last-writer-wins behavior'
+    )
+  })
+
+  describe('S3.C2 — ContextMenu global replacement', () => {
+    it.todo(
+      'reassigning LGraphCanvas.prototype.processContextMenu replaces the context-menu handler for every right-click on the canvas'
+    )
+    it.todo(
+      'extensions replacing processContextMenu must call the original to preserve built-in menu items'
+    )
+    it.todo(
+      'replacing processContextMenu is the most destructive canvas-level override — absence of original call silently drops all built-in menu entries'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-06.v2.test.ts b/src/extension-api-v2/__tests__/bc-06.v2.test.ts
new file mode 100644
index 0000000000..6a4cf1272e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-06.v2.test.ts
@@ -0,0 +1,41 @@
+// Category: BC.06 — Custom canvas drawing (per-node and canvas-level)
+// DB cross-ref: S2.N9, S3.C1, S3.C2
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/setgetnodes.js#L1256
+// compat-floor: blast_radius 5.25 ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: NodeHandle.onDraw(callback) for per-node drawing (S2.N9).
+//                 Canvas-level overrides (S3.C1, S3.C2) are OUT OF v2 SCOPE — deferred to D9 Phase C.
+//                 S3.C* stubs present for blast-radius tracking and strangler-fig planning.
+
+import { describe, it } from 'vitest'
+
+describe('BC.06 v2 contract — custom canvas drawing (per-node and canvas-level)', () => {
+  describe('NodeHandle.onDraw(callback) — per-node foreground drawing (S2.N9)', () => {
+    it.todo(
+      'NodeHandle.onDraw(cb) registers cb to be called once per render frame while the node is visible'
+    )
+    it.todo(
+      'callback receives a DrawContext with ctx (CanvasRenderingContext2D) and area (bounding rect) arguments'
+    )
+    it.todo(
+      'drawing operations in the callback appear in the same layer as v1 onDrawForeground (above node body)'
+    )
+    it.todo(
+      'the canvas transform is pre-applied when the callback fires — coordinates are in graph space, matching v1 behavior'
+    )
+    it.todo(
+      'callback registered via NodeHandle.onDraw() is automatically deregistered when the node is removed'
+    )
+  })
+
+  describe('canvas-level overrides — deferred (S3.C1, S3.C2)', () => {
+    it.todo(
+      '[D9 Phase C] v2 exposes no stable API for replacing LGraphCanvas.prototype.drawNodeShape — extensions using this pattern must remain on v1 shim'
+    )
+    it.todo(
+      '[D9 Phase C] v2 exposes no stable API for replacing processContextMenu — context-menu customization is deferred to the ComfyUI menu extension point'
+    )
+    it.todo(
+      '[D9 Phase C] blast-radius tracking: S3.C1 and S3.C2 overrides coexist with v2 per-node drawing without mutual interference'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-07.migration.test.ts b/src/extension-api-v2/__tests__/bc-07.migration.test.ts
new file mode 100644
index 0000000000..09de5f7ee4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-07.migration.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.07 — Connection observation, intercept, and veto
+// DB cross-ref: S2.N3, S2.N12, S2.N13
+// Exemplar: https://github.com/rgthree/rgthree-comfy/blob/main/web/comfyui/node_mode_relay.js#L90
+// Migration: v1 prototype method assignment → v2 NodeHandle.on('connectInput'/'connectOutput'/'connectionChange')
+
+import { describe, it } from 'vitest'
+
+describe('BC.07 migration — connection observation, intercept, and veto', () => {
+  describe('onConnectionsChange → on(\'connectionChange\') (S2.N3)', () => {
+    it.todo(
+      'v1 onConnectionsChange and v2 on(\'connectionChange\') both fire for the same link connect event with equivalent payload data'
+    )
+    it.todo(
+      'v2 connectionChange event fires at the same point in the link-wiring sequence as v1 onConnectionsChange'
+    )
+  })
+
+  describe('onConnectInput → on(\'connectInput\') (S2.N12)', () => {
+    it.todo(
+      'v1 onConnectInput returning false and v2 on(\'connectInput\') returning false both result in an unwired graph with no link object created'
+    )
+    it.todo(
+      'type coercion performed inside v1 onConnectInput produces the same wired slot type as equivalent mutation inside v2 on(\'connectInput\')'
+    )
+  })
+
+  describe('onConnectOutput → on(\'connectOutput\') (S2.N13)', () => {
+    it.todo(
+      'v1 onConnectOutput veto and v2 on(\'connectOutput\') veto both prevent connectionChange from firing on either endpoint node'
+    )
+    it.todo(
+      'v2 on(\'connectOutput\') listener receives equivalent data to v1 onConnectOutput arguments for the same connection attempt'
+    )
+  })
+
+  describe('scope and cleanup', () => {
+    it.todo(
+      'v1 prototype method persists after extension unregisters (no cleanup); v2 on() listeners are removed on scope dispose'
+    )
+    it.todo(
+      'v2 cleanup does not affect connection listeners registered by other extensions on the same node'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-07.v1.test.ts b/src/extension-api-v2/__tests__/bc-07.v1.test.ts
new file mode 100644
index 0000000000..605d84616b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-07.v1.test.ts
@@ -0,0 +1,53 @@
+// Category: BC.07 — Connection observation, intercept, and veto
+// DB cross-ref: S2.N3, S2.N12, S2.N13
+// Exemplar: https://github.com/rgthree/rgthree-comfy/blob/main/web/comfyui/node_mode_relay.js#L90
+// blast_radius: 5.46 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.onConnectInput(slot, type, link, node, fromSlot)
+//              node.onConnectOutput(slot, type, link, node, toSlot)
+//              node.onConnectionsChange(type, slot, connected, link, ioSlot)
+
+import { describe, it } from 'vitest'
+
+describe('BC.07 v1 contract — connection observation, intercept, and veto', () => {
+  describe('S2.N3 — onConnectionsChange: passive observation', () => {
+    it.todo(
+      'onConnectionsChange is called on the node when any input or output link is connected or disconnected'
+    )
+    it.todo(
+      'onConnectionsChange receives type (INPUT=1/OUTPUT=2), slot index, connected boolean, link info, and ioSlot'
+    )
+    it.todo(
+      'onConnectionsChange fires after the link is already wired into the graph (link is present at call time)'
+    )
+    it.todo(
+      'onConnectionsChange fires for both the source node and the target node on a single link operation'
+    )
+  })
+
+  describe('S2.N12 — onConnectInput: intercept and veto incoming connections', () => {
+    it.todo(
+      'onConnectInput returning false vetoes the connection before it is wired'
+    )
+    it.todo(
+      'onConnectInput returning true (or undefined) allows the connection to proceed'
+    )
+    it.todo(
+      'onConnectInput receives slot index, incoming type, link object, source node, and source slot'
+    )
+    it.todo(
+      'onConnectInput can mutate the slot type to coerce an incompatible type before wiring'
+    )
+  })
+
+  describe('S2.N13 — onConnectOutput: intercept and veto outgoing connections', () => {
+    it.todo(
+      'onConnectOutput returning false vetoes the outgoing connection before it is wired'
+    )
+    it.todo(
+      'onConnectOutput receives slot index, outgoing type, link object, target node, and target slot'
+    )
+    it.todo(
+      'onConnectOutput veto does not trigger onConnectionsChange on either node'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-07.v2.test.ts b/src/extension-api-v2/__tests__/bc-07.v2.test.ts
new file mode 100644
index 0000000000..9187489d58
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-07.v2.test.ts
@@ -0,0 +1,51 @@
+// Category: BC.07 — Connection observation, intercept, and veto
+// DB cross-ref: S2.N3, S2.N12, S2.N13
+// Exemplar: https://github.com/rgthree/rgthree-comfy/blob/main/web/comfyui/node_mode_relay.js#L90
+// blast_radius: 5.46 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: NodeHandle.on('connectInput', ...), on('connectOutput', ...), on('connectionChange', ...)
+
+import { describe, it } from 'vitest'
+
+describe('BC.07 v2 contract — connection observation, intercept, and veto', () => {
+  describe('on(\'connectionChange\', fn) — passive observation', () => {
+    it.todo(
+      'NodeHandle.on(\'connectionChange\', fn) fires fn after any input or output link is connected or disconnected'
+    )
+    it.todo(
+      'connectionChange event payload includes type (\'input\'|\'output\'), slotIndex, connected boolean, and link info'
+    )
+    it.todo(
+      'multiple listeners registered via on(\'connectionChange\') are all invoked in registration order'
+    )
+    it.todo(
+      'listener registered with on() is removed when the extension scope is disposed'
+    )
+  })
+
+  describe('on(\'connectInput\', fn) — intercept and veto incoming connections', () => {
+    it.todo(
+      'fn returning false from on(\'connectInput\') vetoes the connection; graph remains unwired'
+    )
+    it.todo(
+      'fn returning true or undefined from on(\'connectInput\') allows the connection to proceed'
+    )
+    it.todo(
+      'connectInput event payload includes slotIndex, type, link, sourceHandle, and sourceSlot'
+    )
+    it.todo(
+      'fn can mutate event.type to coerce a type mismatch before the connection is wired'
+    )
+  })
+
+  describe('on(\'connectOutput\', fn) — intercept and veto outgoing connections', () => {
+    it.todo(
+      'fn returning false from on(\'connectOutput\') vetoes the outgoing connection; connectionChange does not fire'
+    )
+    it.todo(
+      'connectOutput event payload includes slotIndex, type, link, targetHandle, and targetSlot'
+    )
+    it.todo(
+      'veto from connectOutput does not affect other registered connectOutput listeners on the same node'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-08.migration.test.ts b/src/extension-api-v2/__tests__/bc-08.migration.test.ts
new file mode 100644
index 0000000000..fe43d93c35
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-08.migration.test.ts
@@ -0,0 +1,38 @@
+// Category: BC.08 — Programmatic linking
+// DB cross-ref: S10.D2
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts/blob/main/web/js/quickNodes.js#L138
+// Migration: v1 node.connect/disconnectInput → v2 NodeHandle.connect/disconnectInput (typed handles)
+
+import { describe, it } from 'vitest'
+
+describe('BC.08 migration — programmatic linking', () => {
+  describe('connect() equivalence', () => {
+    it.todo(
+      'v1 node.connect(srcSlot, targetNode, dstSlot) and v2 NodeHandle.connect(srcSlot, targetHandle, dstSlot) produce identical graph link state'
+    )
+    it.todo(
+      'link id returned by v2 connect() matches the id on the underlying LGraph link created by an equivalent v1 call'
+    )
+    it.todo(
+      'v2 connect() with a type-incompatible pair raises a typed error; v1 returns null — callers must handle both forms during migration'
+    )
+  })
+
+  describe('disconnectInput() equivalence', () => {
+    it.todo(
+      'v1 node.disconnectInput(slot) and v2 NodeHandle.disconnectInput(slotIndex) both leave the graph with no link on that slot'
+    )
+    it.todo(
+      'onConnectionsChange (v1) and on(\'connectionChange\') (v2) both fire for the same disconnect operation with equivalent payload data'
+    )
+  })
+
+  describe('handle vs. raw node reference', () => {
+    it.todo(
+      'v2 NodeHandle.connect() accepts a NodeHandle for targetHandle; passing a raw LGraphNode instance throws a deprecation error'
+    )
+    it.todo(
+      'NodeHandle obtained from v2 nodeCreated correctly wraps the same node that v1 connect() would operate on'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-08.v1.test.ts b/src/extension-api-v2/__tests__/bc-08.v1.test.ts
new file mode 100644
index 0000000000..da0b2d2bb6
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-08.v1.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.08 — Programmatic linking
+// DB cross-ref: S10.D2
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts/blob/main/web/js/quickNodes.js#L138
+// blast_radius: 5.99 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.connect(srcSlot, targetNode, dstSlot)
+//              node.disconnectInput(slot)
+
+import { describe, it } from 'vitest'
+
+describe('BC.08 v1 contract — programmatic linking', () => {
+  describe('S10.D2 — node.connect(srcSlot, targetNode, dstSlot)', () => {
+    it.todo(
+      'node.connect(srcSlot, targetNode, dstSlot) creates a link between the source output slot and the target input slot'
+    )
+    it.todo(
+      'connect() returns the newly created link object with a stable numeric id'
+    )
+    it.todo(
+      'connect() on an already-occupied input slot replaces the existing link without leaving a dangling reference'
+    )
+    it.todo(
+      'connect() with a type-incompatible slot pair is rejected and returns null without modifying the graph'
+    )
+    it.todo(
+      'onConnectionsChange fires on both the source and target node after a successful connect() call'
+    )
+  })
+
+  describe('S10.D2 — node.disconnectInput(slot)', () => {
+    it.todo(
+      'node.disconnectInput(slot) removes the link on the specified input slot and updates both endpoint nodes'
+    )
+    it.todo(
+      'disconnectInput() on an empty slot is a no-op and does not throw'
+    )
+    it.todo(
+      'onConnectionsChange fires on both the source and target node after disconnectInput() removes a link'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-08.v2.test.ts b/src/extension-api-v2/__tests__/bc-08.v2.test.ts
new file mode 100644
index 0000000000..ea3dc9ad43
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-08.v2.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.08 — Programmatic linking
+// DB cross-ref: S10.D2
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts/blob/main/web/js/quickNodes.js#L138
+// blast_radius: 5.99 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: NodeHandle.connect(slotIndex, targetHandle, dstSlot) — same semantics, typed handles
+
+import { describe, it } from 'vitest'
+
+describe('BC.08 v2 contract — programmatic linking', () => {
+  describe('NodeHandle.connect(slotIndex, targetHandle, dstSlot) — create links', () => {
+    it.todo(
+      'NodeHandle.connect(slotIndex, targetHandle, dstSlot) creates a link between the source output slot and the target input slot'
+    )
+    it.todo(
+      'connect() returns a LinkHandle with a stable id that matches the underlying graph link id'
+    )
+    it.todo(
+      'connect() on an already-occupied input slot replaces the existing link and the old LinkHandle becomes invalid'
+    )
+    it.todo(
+      'connect() with a type-incompatible slot pair throws a typed error and leaves the graph unchanged'
+    )
+    it.todo(
+      'on(\'connectionChange\') fires on both NodeHandles after a successful connect() call'
+    )
+  })
+
+  describe('NodeHandle.disconnectInput(slotIndex) — remove links', () => {
+    it.todo(
+      'NodeHandle.disconnectInput(slotIndex) removes the link on the specified input slot and the returned LinkHandle becomes invalid'
+    )
+    it.todo(
+      'disconnectInput() on an empty slot is a no-op and does not throw'
+    )
+    it.todo(
+      'on(\'connectionChange\') fires on both source and target NodeHandles after disconnectInput() removes a link'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-09.migration.test.ts b/src/extension-api-v2/__tests__/bc-09.migration.test.ts
new file mode 100644
index 0000000000..9ca79b1f21
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-09.migration.test.ts
@@ -0,0 +1,42 @@
+// Category: BC.09 — Dynamic slot and output mutation
+// DB cross-ref: S10.D1, S10.D3, S15.OS1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/lib/litegraph/src/canvas/LinkConnector.core.test.ts#L121
+// Migration: v1 positional addInput/removeInput/addOutput/removeOutput + manual setSize
+//            → v2 name-based NodeHandle.addInput/removeInput/addOutput/removeOutput with auto-reflow
+
+import { describe, it } from 'vitest'
+
+describe('BC.09 migration — dynamic slot and output mutation', () => {
+  describe('addInput / addOutput equivalence (S10.D1, S10.D3)', () => {
+    it.todo(
+      'v1 node.addInput(name, type) and v2 NodeHandle.addInput({ name, type }) both result in an equivalent slot appended to the node'
+    )
+    it.todo(
+      'v1 node.addOutput(name, type) and v2 NodeHandle.addOutput({ name, type }) both result in an equivalent output slot with a matching type'
+    )
+    it.todo(
+      'slot added via v2 addInput() is accessible at the same index position as an equivalent v1 addInput() call (append-only ordering preserved)'
+    )
+  })
+
+  describe('removeInput / removeOutput equivalence', () => {
+    it.todo(
+      'v1 node.removeInput(slotIndex) and v2 NodeHandle.removeInput(name) both remove the slot and detach active links; remaining slots have consistent indices'
+    )
+    it.todo(
+      'v2 removeInput(name) correctly identifies the slot when multiple slots exist, matching by name not by position'
+    )
+  })
+
+  describe('reflow: manual setSize vs. automatic (S15.OS1)', () => {
+    it.todo(
+      'v1 addInput() + setSize([...computeSize()]) and v2 addInput() auto-reflow both produce a node with equal or greater height to display the new slot'
+    )
+    it.todo(
+      'v2 auto-reflow after removeOutput() shrinks the node to the same height as a v1 removeOutput() + manual setSize() sequence'
+    )
+    it.todo(
+      'omitting setSize after a v1 addInput() call causes slot overlap; v2 auto-reflow never produces this condition'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-09.v1.test.ts b/src/extension-api-v2/__tests__/bc-09.v1.test.ts
new file mode 100644
index 0000000000..ff1ff32286
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-09.v1.test.ts
@@ -0,0 +1,50 @@
+// Category: BC.09 — Dynamic slot and output mutation
+// DB cross-ref: S10.D1, S10.D3, S15.OS1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/lib/litegraph/src/canvas/LinkConnector.core.test.ts#L121
+// blast_radius: 6.03 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.addInput(name, type), node.removeInput(slot)
+//              node.addOutput(name, type), node.removeOutput(slot)
+//              node.setSize([w, h])
+
+import { describe, it } from 'vitest'
+
+describe('BC.09 v1 contract — dynamic slot and output mutation', () => {
+  describe('S10.D1 — addInput / removeInput', () => {
+    it.todo(
+      'node.addInput(name, type) appends a new input slot to node.inputs and increments node.inputs.length'
+    )
+    it.todo(
+      'node.removeInput(slot) removes the slot at the given index and shifts subsequent slots down by one'
+    )
+    it.todo(
+      'removing an input slot that has an active link also removes the corresponding link from the graph'
+    )
+    it.todo(
+      'addInput with a duplicate name appends a second slot without error (v1 allows duplicates)'
+    )
+  })
+
+  describe('S10.D3 — addOutput / removeOutput', () => {
+    it.todo(
+      'node.addOutput(name, type) appends a new output slot to node.outputs and increments node.outputs.length'
+    )
+    it.todo(
+      'node.removeOutput(slot) removes the output slot and detaches all outgoing links on that slot'
+    )
+    it.todo(
+      'removing an output slot does not affect links on other output slots of the same node'
+    )
+  })
+
+  describe('S15.OS1 — computeSize / setSize reflow', () => {
+    it.todo(
+      'node.setSize([w, h]) updates node.size to the provided dimensions immediately'
+    )
+    it.todo(
+      'addInput/addOutput followed by node.setSize([...node.computeSize()]) produces a node tall enough to display all slots without overlap'
+    )
+    it.todo(
+      'setSize does not trigger a canvas redraw synchronously; redraw occurs on the next animation frame'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-09.v2.test.ts b/src/extension-api-v2/__tests__/bc-09.v2.test.ts
new file mode 100644
index 0000000000..6f9bd4c278
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-09.v2.test.ts
@@ -0,0 +1,50 @@
+// Category: BC.09 — Dynamic slot and output mutation
+// DB cross-ref: S10.D1, S10.D3, S15.OS1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/lib/litegraph/src/canvas/LinkConnector.core.test.ts#L121
+// blast_radius: 6.03 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: NodeHandle.addInput(opts), NodeHandle.removeInput(name)
+//                 NodeHandle.addOutput(opts), NodeHandle.removeOutput(name)
+//                 reflow handled automatically — no manual setSize required
+
+import { describe, it } from 'vitest'
+
+describe('BC.09 v2 contract — dynamic slot and output mutation', () => {
+  describe('NodeHandle.addInput / removeInput (S10.D1)', () => {
+    it.todo(
+      'NodeHandle.addInput({ name, type }) appends a new input slot and returns a SlotHandle with a stable name-based identity'
+    )
+    it.todo(
+      'NodeHandle.removeInput(name) removes the named input slot and detaches any active link on that slot'
+    )
+    it.todo(
+      'removeInput(name) on a non-existent slot name throws a typed SlotNotFoundError'
+    )
+    it.todo(
+      'addInput with a duplicate name throws a DuplicateSlotError (v2 enforces uniqueness unlike v1)'
+    )
+  })
+
+  describe('NodeHandle.addOutput / removeOutput (S10.D3)', () => {
+    it.todo(
+      'NodeHandle.addOutput({ name, type }) appends a new output slot and returns a SlotHandle'
+    )
+    it.todo(
+      'NodeHandle.removeOutput(name) removes the output slot and detaches all outgoing links on that slot'
+    )
+    it.todo(
+      'removeOutput does not affect slots or links on other output slots of the same node'
+    )
+  })
+
+  describe('automatic reflow (replaces S15.OS1 manual setSize)', () => {
+    it.todo(
+      'after addInput() or addOutput() the node size is automatically reflowed to fit all slots without a manual setSize call'
+    )
+    it.todo(
+      'after removeInput() or removeOutput() the node size is automatically shrunk to remove the vacated slot space'
+    )
+    it.todo(
+      'automatic reflow does not trigger a synchronous canvas redraw; redraw occurs on the next animation frame'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-10.migration.test.ts b/src/extension-api-v2/__tests__/bc-10.migration.test.ts
new file mode 100644
index 0000000000..c7db05b7bb
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-10.migration.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.10 — Widget value subscription
+// DB cross-ref: S4.W1, S2.N14
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/widgetInputs.ts#L317
+// Migration: v1 widget.callback chain-patching / node.onWidgetChanged
+//            → v2 WidgetHandle.on('change') / NodeHandle.on('widgetChanged')
+
+import { describe, it } from 'vitest'
+
+describe('BC.10 migration — widget value subscription', () => {
+  describe('widget.callback → WidgetHandle.on(\'change\') (S4.W1)', () => {
+    it.todo(
+      'v1 widget.callback and v2 WidgetHandle.on(\'change\') both fire with the new value for the same user interaction'
+    )
+    it.todo(
+      'v2 on(\'change\') fires at the same point in the event sequence as the last v1 callback in the chain'
+    )
+    it.todo(
+      'v1 chain-patching does not compose with v2 on(\'change\'): each operates independently; both fire for the same change event'
+    )
+  })
+
+  describe('node.onWidgetChanged → NodeHandle.on(\'widgetChanged\') (S2.N14)', () => {
+    it.todo(
+      'v1 node.onWidgetChanged and v2 NodeHandle.on(\'widgetChanged\') both receive equivalent widget name, value, and oldValue for the same change'
+    )
+    it.todo(
+      'v2 widgetChanged payload includes a WidgetHandle reference instead of a raw widget object; WidgetHandle.name matches the widget name'
+    )
+  })
+
+  describe('ordering and isolation', () => {
+    it.todo(
+      'v2 on(\'change\') listeners from different extensions on the same widget all fire without one suppressing another'
+    )
+    it.todo(
+      'disposing one extension scope removes only its own on(\'change\') listeners; other extensions\' listeners continue to fire'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-10.v1.test.ts b/src/extension-api-v2/__tests__/bc-10.v1.test.ts
new file mode 100644
index 0000000000..e502b43b31
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-10.v1.test.ts
@@ -0,0 +1,37 @@
+// Category: BC.10 — Widget value subscription
+// DB cross-ref: S4.W1, S2.N14
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/widgetInputs.ts#L317
+// blast_radius: 5.09 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: widget.callback = function(value, ...) { ... }  (chain-patching)
+//              node.onWidgetChanged = function(name, value, ...) { ... }
+
+import { describe, it } from 'vitest'
+
+describe('BC.10 v1 contract — widget value subscription', () => {
+  describe('S4.W1 — widget.callback chain-patching', () => {
+    it.todo(
+      'assigning widget.callback invokes the function with the new value whenever the widget is interacted with'
+    )
+    it.todo(
+      'chain-patching preserves the previous callback: saving the old reference and calling it at the end of the new function'
+    )
+    it.todo(
+      'widget.callback receives (value, app, node, pos, event) in that argument order'
+    )
+    it.todo(
+      'if multiple extensions chain-patch widget.callback, all callbacks are invoked in stack order (last-patched first)'
+    )
+  })
+
+  describe('S2.N14 — node.onWidgetChanged', () => {
+    it.todo(
+      'node.onWidgetChanged is called once per widget value change with the widget name, new value, old value, and widget reference'
+    )
+    it.todo(
+      'onWidgetChanged fires for every widget on the node, not only those with an explicit callback'
+    )
+    it.todo(
+      'onWidgetChanged fires after widget.callback has been invoked for the same change event'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-10.v2.test.ts b/src/extension-api-v2/__tests__/bc-10.v2.test.ts
new file mode 100644
index 0000000000..93b2568832
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-10.v2.test.ts
@@ -0,0 +1,36 @@
+// Category: BC.10 — Widget value subscription
+// DB cross-ref: S4.W1, S2.N14
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/widgetInputs.ts#L317
+// blast_radius: 5.09 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: WidgetHandle.on('change', fn), NodeHandle.on('widgetChanged', fn)
+
+import { describe, it } from 'vitest'
+
+describe('BC.10 v2 contract — widget value subscription', () => {
+  describe('WidgetHandle.on(\'change\', fn) — per-widget subscription (S4.W1)', () => {
+    it.todo(
+      'WidgetHandle.on(\'change\', fn) fires fn with (newValue, oldValue) whenever the widget value changes'
+    )
+    it.todo(
+      'multiple on(\'change\') listeners on the same WidgetHandle are all invoked in registration order'
+    )
+    it.todo(
+      'on(\'change\') listener is removed when the extension scope is disposed; subsequent changes do not invoke the stale listener'
+    )
+    it.todo(
+      'on(\'change\') listener can call event.preventDefault() to block the value write (unlike v1 callback which cannot veto)'
+    )
+  })
+
+  describe('NodeHandle.on(\'widgetChanged\', fn) — node-level subscription (S2.N14)', () => {
+    it.todo(
+      'NodeHandle.on(\'widgetChanged\', fn) fires fn for any widget value change on the node, with payload { name, value, oldValue, widget }'
+    )
+    it.todo(
+      'widgetChanged fires after all per-widget on(\'change\') listeners have been invoked for the same change event'
+    )
+    it.todo(
+      'widgetChanged fires for every widget on the node regardless of whether the widget has individual on(\'change\') listeners'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-11.migration.test.ts b/src/extension-api-v2/__tests__/bc-11.migration.test.ts
new file mode 100644
index 0000000000..6829039dad
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-11.migration.test.ts
@@ -0,0 +1,45 @@
+// Category: BC.11 — Widget imperative state writes
+// DB cross-ref: S4.W4, S4.W5, S2.N16
+// Exemplar: https://github.com/r-vage/ComfyUI_Eclipse/blob/main/js/eclipse-set-get.js#L9
+// Migration: v1 direct property mutation (widget.value, widget.options.values, node.widgets.push/splice)
+//            → v2 WidgetHandle.setValue / setOptions / NodeHandle.addWidget / removeWidget
+
+import { describe, it } from 'vitest'
+
+describe('BC.11 migration — widget imperative state writes', () => {
+  describe('widget.value → WidgetHandle.setValue() (S4.W4)', () => {
+    it.todo(
+      'v1 widget.value = v and v2 WidgetHandle.setValue(v) both result in the same displayed value on the canvas'
+    )
+    it.todo(
+      'v1 direct assignment does not fire on(\'change\') listeners; v2 setValue() does — callers must not assume silence'
+    )
+    it.todo(
+      'v2 setValue() raises InvalidValueError for out-of-range COMBO values; v1 assignment silently accepts them'
+    )
+  })
+
+  describe('widget.options.values → WidgetHandle.setOptions() (S4.W5)', () => {
+    it.todo(
+      'v1 widget.options.values = [...] and v2 WidgetHandle.setOptions({ values: [...] }) both replace the COMBO option list'
+    )
+    it.todo(
+      'v1 does not auto-reset stale current value; v2 setOptions() does — migration callers must handle the resulting on(\'change\') event'
+    )
+  })
+
+  describe('node.widgets.push/splice → NodeHandle.addWidget/removeWidget (S2.N16)', () => {
+    it.todo(
+      'v1 node.widgets.push(w) and v2 NodeHandle.addWidget(opts) both result in the widget being present in the node\'s widget list after the call'
+    )
+    it.todo(
+      'v1 splice causes widgets_values positional drift; v2 addWidget uses named-map and produces no drift even when inserted mid-list'
+    )
+    it.todo(
+      'v1 push requires a manual setSize reflow; v2 addWidget performs it automatically — do not double-reflow when migrating'
+    )
+    it.todo(
+      'v2 removeWidget(name) correctly finds the widget by name regardless of its position in the list; v1 splice requires the caller to track the index'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-11.v1.test.ts b/src/extension-api-v2/__tests__/bc-11.v1.test.ts
new file mode 100644
index 0000000000..2af4991687
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-11.v1.test.ts
@@ -0,0 +1,51 @@
+// Category: BC.11 — Widget imperative state writes
+// DB cross-ref: S4.W4, S4.W5, S2.N16
+// Exemplar: https://github.com/r-vage/ComfyUI_Eclipse/blob/main/js/eclipse-set-get.js#L9
+// blast_radius: 5.81 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: widget.value = newVal
+//              widget.options.values = [...]
+//              node.widgets.splice(i, 0, w)
+//              node.widgets.push(w)
+
+import { describe, it } from 'vitest'
+
+describe('BC.11 v1 contract — widget imperative state writes', () => {
+  describe('S4.W4 — widget.value direct assignment', () => {
+    it.todo(
+      'assigning widget.value = newVal updates the displayed value on the next canvas redraw without triggering widget.callback'
+    )
+    it.todo(
+      'widget.value assignment to a value outside the COMBO options list does not throw but may display an invalid state'
+    )
+    it.todo(
+      'reading widget.value immediately after assignment returns the assigned value'
+    )
+  })
+
+  describe('S4.W5 — widget.options.values mutation (COMBO options)', () => {
+    it.todo(
+      'assigning widget.options.values = [...] replaces the COMBO dropdown options on the next canvas redraw'
+    )
+    it.todo(
+      'if the current widget.value is absent from the new options list, the widget continues to display the stale value (no auto-reset in v1)'
+    )
+    it.todo(
+      'widget.options.values mutation does not fire widget.callback'
+    )
+  })
+
+  describe('S2.N16 — node.widgets array mutation (insert / push)', () => {
+    it.todo(
+      'node.widgets.push(widget) appends the widget to the node\'s widget list and it renders on the next canvas redraw'
+    )
+    it.todo(
+      'node.widgets.splice(i, 0, widget) inserts a widget at position i and shifts subsequent widgets\' positional indices'
+    )
+    it.todo(
+      'inserting a widget via splice causes widgets_values positional drift if not followed by a node size reflow'
+    )
+    it.todo(
+      'node.widgets.push does not update node.size; calling setSize([...computeSize()]) is required to avoid slot overlap'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-11.v2.test.ts b/src/extension-api-v2/__tests__/bc-11.v2.test.ts
new file mode 100644
index 0000000000..8390bc9164
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-11.v2.test.ts
@@ -0,0 +1,52 @@
+// Category: BC.11 — Widget imperative state writes
+// DB cross-ref: S4.W4, S4.W5, S2.N16
+// Exemplar: https://github.com/r-vage/ComfyUI_Eclipse/blob/main/js/eclipse-set-get.js#L9
+// blast_radius: 5.81 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: WidgetHandle.setValue(v), WidgetHandle.setOptions({ values: [...] })
+//                 NodeHandle.addWidget(opts), NodeHandle.removeWidget(name)
+
+import { describe, it } from 'vitest'
+
+describe('BC.11 v2 contract — widget imperative state writes', () => {
+  describe('WidgetHandle.setValue(v) — controlled value write (S4.W4)', () => {
+    it.todo(
+      'WidgetHandle.setValue(v) updates the widget\'s current value and triggers a reactive update visible on the next canvas frame'
+    )
+    it.todo(
+      'setValue() fires the on(\'change\') listeners with (newValue, oldValue) in the same tick'
+    )
+    it.todo(
+      'setValue() with a value outside the COMBO options list throws a typed InvalidValueError'
+    )
+    it.todo(
+      'reading WidgetHandle.value immediately after setValue() returns the new value'
+    )
+  })
+
+  describe('WidgetHandle.setOptions({ values }) — COMBO option replacement (S4.W5)', () => {
+    it.todo(
+      'WidgetHandle.setOptions({ values: [...] }) replaces the COMBO options and triggers a reactive update'
+    )
+    it.todo(
+      'if the current value is absent from the new options list, setOptions() resets the value to options[0] automatically'
+    )
+    it.todo(
+      'setOptions() fires on(\'change\') only if the current value was reset due to option list change'
+    )
+  })
+
+  describe('NodeHandle.addWidget / removeWidget — managed widget list mutation (S2.N16)', () => {
+    it.todo(
+      'NodeHandle.addWidget(opts) appends a widget, auto-reflowing node size and updating the named widgets_values map'
+    )
+    it.todo(
+      'NodeHandle.removeWidget(name) removes the named widget, auto-reflowing node size and removing the entry from widgets_values'
+    )
+    it.todo(
+      'addWidget does not cause widgets_values positional drift because v2 uses a named map rather than a positional array'
+    )
+    it.todo(
+      'removeWidget(name) on a non-existent widget name throws a typed WidgetNotFoundError'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-12.migration.test.ts b/src/extension-api-v2/__tests__/bc-12.migration.test.ts
new file mode 100644
index 0000000000..4e943c90ae
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-12.migration.test.ts
@@ -0,0 +1,41 @@
+// Category: BC.12 — Per-widget serialization transform
+// DB cross-ref: S4.W3
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/browser_tests/helpers/painter.ts#L70
+// Migration: v1 widget.serializeValue positional index → v2 WidgetHandle.on('serialize') / setSerializeValue name-based
+
+import { describe, it } from 'vitest'
+
+describe('BC.12 migration — per-widget serialization transform', () => {
+  describe('serializeValue → on(\'serialize\') round-trip equivalence', () => {
+    it.todo(
+      'a v1 widget.serializeValue that returns a transformed value and a v2 on(\'serialize\') returning the same transformation produce identical output in the serialized workflow JSON'
+    )
+    it.todo(
+      'v1 serializeValue receives a positional index; v2 on(\'serialize\') does not — callers relying on the index for slot lookup must migrate to name-based lookup'
+    )
+    it.todo(
+      'async transforms: both v1 serializeValue and v2 on(\'serialize\') are awaited by graphToPrompt() before the workflow is finalized'
+    )
+  })
+
+  describe('serialize===false widget compat', () => {
+    it.todo(
+      'v1 positional index for a widget after control_after_generate is offset by 1 relative to the backend prompt; v2 named-map has no such offset'
+    )
+    it.todo(
+      'migrate: v1 code that hard-codes an index offset for serialize===false slots must be rewritten to use WidgetHandle identity by name in v2'
+    )
+    it.todo(
+      'widgets_values_named round-trip: a workflow serialized under v2 with an on(\'serialize\') transform deserializes to the same widget values as the equivalent v1 serializeValue workflow'
+    )
+  })
+
+  describe('identity stability', () => {
+    it.todo(
+      'v2 WidgetHandle identity is stable after node.widgets reordering; v1 serializeValue index changes if widgets are reordered — this is the primary reason to migrate'
+    )
+    it.todo(
+      'setSerializeValue(fn) called twice replaces the first registration; widget.serializeValue overwrites also replace — both v1 and v2 are last-write-wins'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-12.v1.test.ts b/src/extension-api-v2/__tests__/bc-12.v1.test.ts
new file mode 100644
index 0000000000..b677d9caaf
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-12.v1.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.12 — Per-widget serialization transform
+// DB cross-ref: S4.W3
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/browser_tests/helpers/painter.ts#L70
+// blast_radius: 5.58 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: widget.serializeValue = async function(node, index) { return transformedValue }
+// Notes: widget.options.serialize===false widgets (e.g. control_after_generate) still occupy a
+//        widgets_values slot and still fire serializeValue — excluded only from backend prompt by
+//        graphToPrompt(). See research/architecture/widget-serialization-historical-analysis.md.
+
+import { describe, it } from 'vitest'
+
+describe('BC.12 v1 contract — per-widget serialization transform', () => {
+  describe('S4.W3 — widget.serializeValue assignment', () => {
+    it.todo(
+      'assigning widget.serializeValue = async fn(node, index) causes graphToPrompt() to await fn and use its return value in widgets_values'
+    )
+    it.todo(
+      'serializeValue receives the owning node as first argument and the widget\'s positional index in node.widgets as second argument'
+    )
+    it.todo(
+      'if serializeValue is not assigned, graphToPrompt() uses widget.value directly as the serialized value'
+    )
+    it.todo(
+      'serializeValue may return a value of a different type than widget.value (e.g. string expansion of a seed integer)'
+    )
+  })
+
+  describe('serialize===false widgets (control_after_generate)', () => {
+    it.todo(
+      'a widget with options.serialize===false still occupies a slot in the widgets_values positional array during serialization'
+    )
+    it.todo(
+      'serializeValue fires for a serialize===false widget and its return value appears in widgets_values even though graphToPrompt() excludes it from the backend prompt'
+    )
+    it.todo(
+      'the positional index passed to serializeValue for widgets after a serialize===false widget is offset by one relative to the backend prompt widgets_values array'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-12.v2.test.ts b/src/extension-api-v2/__tests__/bc-12.v2.test.ts
new file mode 100644
index 0000000000..4b863184e9
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-12.v2.test.ts
@@ -0,0 +1,47 @@
+// Category: BC.12 — Per-widget serialization transform
+// DB cross-ref: S4.W3
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/browser_tests/helpers/painter.ts#L70
+// blast_radius: 5.58 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: WidgetHandle.on('serialize', fn) or WidgetHandle.setSerializeValue(fn)
+// Notes: WidgetHandle identity is by name not position (PR #10392 widgets_values_named migration path).
+//        serialize===false widgets still fire the serialize event and still appear in the named map.
+
+import { describe, it } from 'vitest'
+
+describe('BC.12 v2 contract — per-widget serialization transform', () => {
+  describe('WidgetHandle.on(\'serialize\', fn) — event-based transform', () => {
+    it.todo(
+      'WidgetHandle.on(\'serialize\', fn) fires fn during graphToPrompt(); fn may return a transformed value which replaces the default in the named map'
+    )
+    it.todo(
+      'fn receives a SerializeEvent with { node: NodeHandle, widget: WidgetHandle, value } and can set event.serializedValue to override'
+    )
+    it.todo(
+      'if no on(\'serialize\') listener is registered, graphToPrompt() uses WidgetHandle.value directly'
+    )
+    it.todo(
+      'on(\'serialize\') listener is removed when the extension scope is disposed; subsequent serializations use the raw value'
+    )
+  })
+
+  describe('WidgetHandle.setSerializeValue(fn) — imperative transform assignment', () => {
+    it.todo(
+      'WidgetHandle.setSerializeValue(async fn) registers fn as the sole serialize transform, superseding any prior assignment'
+    )
+    it.todo(
+      'fn passed to setSerializeValue receives (widgetHandle) and its return value is placed in widgets_values_named under the widget name'
+    )
+  })
+
+  describe('serialize===false widgets (control_after_generate)', () => {
+    it.todo(
+      'a widget with serialize===false still appears as a named entry in widgets_values_named during serialization'
+    )
+    it.todo(
+      'on(\'serialize\') fires for a serialize===false WidgetHandle; the returned value is stored in the named map but omitted from the backend prompt'
+    )
+    it.todo(
+      'WidgetHandle identity for serialize===false widgets is stable across slot reordering because it is name-based not position-based'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-13.migration.test.ts b/src/extension-api-v2/__tests__/bc-13.migration.test.ts
new file mode 100644
index 0000000000..6dc31ecaae
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-13.migration.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.13 — Per-node serialization interception
+// DB cross-ref: S2.N6, S2.N15
+// Exemplar: https://github.com/Azornes/Comfyui-LayerForge/blob/main/js/CanvasView.js#L1438
+// Migration: v1 prototype.serialize patching / node.onSerialize → v2 NodeHandle.on('serialize') named-map
+
+import { describe, it } from 'vitest'
+
+describe('BC.13 migration — per-node serialization interception', () => {
+  describe('(a) positional v1 compat: prototype.serialize / onSerialize parity', () => {
+    it.todo(
+      'custom field injected via v1 prototype.serialize patch and the same field injected via v2 on(\'serialize\') both appear in the serialized workflow JSON under identical keys'
+    )
+    it.todo(
+      'v1 onSerialize and v2 on(\'serialize\') both fire once per graphToPrompt() call with the same node\'s serialization data'
+    )
+    it.todo(
+      'v1 chain of two prototype.serialize patchers produces the same custom-field set as two v2 on(\'serialize\') listeners registered by separate extensions'
+    )
+  })
+
+  describe('(b) named-map v2 round-trip parity', () => {
+    it.todo(
+      'a workflow serialized under v2 with widgets_values_named and deserialized produces the same widget values as the equivalent v1 workflow with a positional widgets_values array'
+    )
+    it.todo(
+      'adding a new widget between two existing widgets does not shift the named-map entries for subsequent widgets (v2); it does shift positional indices in v1 — migration callers must stop relying on hardcoded indices'
+    )
+    it.todo(
+      'serialize===false widget (control_after_generate) occupies a named-map entry in v2 with no positional offset; v1 callers that computed offsets must remove that logic'
+    )
+  })
+
+  describe('(c) null-in-numeric-widget: warning + default substitution', () => {
+    it.todo(
+      'v1 NaN widget value silently becomes null in the workflow JSON; v2 substitutes the declared default and emits a console.warn — the logged message includes the node id and widget name'
+    )
+    it.todo(
+      'a workflow with a null widgets_values entry for a numeric widget loaded under v2 emits a console.warn and restores the declared default rather than loading null'
+    )
+    it.todo(
+      'the NaN guard does not trigger for non-numeric widgets whose value is legitimately null (e.g. unset optional inputs)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-13.v1.test.ts b/src/extension-api-v2/__tests__/bc-13.v1.test.ts
new file mode 100644
index 0000000000..72a62a789f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-13.v1.test.ts
@@ -0,0 +1,53 @@
+// Category: BC.13 — Per-node serialization interception
+// DB cross-ref: S2.N6, S2.N15
+// Exemplar: https://github.com/Azornes/Comfyui-LayerForge/blob/main/js/CanvasView.js#L1438
+// blast_radius: 6.36 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v1 contract: node.prototype.serialize = function() { const r = origSerialize.call(this); r.myData = ...; return r }
+//              node.onSerialize = function(data) { data.myData = ... }
+// Notes: widgets_values is positional. Three index-drift sources: control_after_generate slot occupancy,
+//        extension-injected widgets, V3 IO.MultiType topology-dependent widget count. NaN→null pipeline
+//        produces silent corruption. Test (a) positional v1 compat, (b) named-map v2 round-trip parity,
+//        (c) null-in-numeric-widget logs warning + substitutes default.
+
+import { describe, it } from 'vitest'
+
+describe('BC.13 v1 contract — per-node serialization interception', () => {
+  describe('S2.N6 — prototype.serialize patching', () => {
+    it.todo(
+      'patching node.constructor.prototype.serialize and calling origSerialize.call(this) produces the base serialization object which can be extended with custom fields'
+    )
+    it.todo(
+      'custom fields added to the object returned by the patched serialize are present in the workflow JSON written to disk'
+    )
+    it.todo(
+      'multiple extensions each patching prototype.serialize via origSerialize chaining all contribute their custom fields to the final serialized object'
+    )
+    it.todo(
+      'positional widgets_values in the patched serialize output drifts when a serialize===false widget occupies a slot before the target widget'
+    )
+  })
+
+  describe('S2.N15 — node.onSerialize callback', () => {
+    it.todo(
+      'assigning node.onSerialize = fn causes fn to be called with the serialization data object after the base serialize completes'
+    )
+    it.todo(
+      'onSerialize may mutate data.myData in place; the mutation is reflected in the workflow JSON'
+    )
+    it.todo(
+      'NaN values written to widgets_values inside onSerialize are silently coerced to null by JSON.stringify, producing silent corruption'
+    )
+    it.todo(
+      'onSerialize fires once per serialization pass; calling graphToPrompt() twice calls onSerialize twice'
+    )
+  })
+
+  describe('NaN→null silent corruption', () => {
+    it.todo(
+      'a numeric widget whose serializeValue returns NaN causes a null entry in widgets_values after JSON round-trip'
+    )
+    it.todo(
+      'the null entry in widgets_values is loaded back as null on graph restore, not as 0 or the widget default'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-13.v2.test.ts b/src/extension-api-v2/__tests__/bc-13.v2.test.ts
new file mode 100644
index 0000000000..34e6d75079
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-13.v2.test.ts
@@ -0,0 +1,50 @@
+// Category: BC.13 — Per-node serialization interception
+// DB cross-ref: S2.N6, S2.N15
+// Exemplar: https://github.com/Azornes/Comfyui-LayerForge/blob/main/js/CanvasView.js#L1438
+// blast_radius: 6.36 — compat-floor: blast_radius ≥ 2.0 — MUST pass before v2 ships
+// v2 replacement: NodeHandle.on('serialize', (data) => { data.myData = ... }) — named map round-trip
+// Notes: v2 uses widgets_values_named keyed by widget name, eliminating positional drift.
+//        NaN→null pipeline: v2 serializer logs a warning and substitutes the widget's declared default.
+
+import { describe, it } from 'vitest'
+
+describe('BC.13 v2 contract — per-node serialization interception', () => {
+  describe('NodeHandle.on(\'serialize\', fn) — node-level serialization hook (S2.N6, S2.N15)', () => {
+    it.todo(
+      'NodeHandle.on(\'serialize\', fn) fires fn with the serialization data object during graphToPrompt(); fn may add custom fields'
+    )
+    it.todo(
+      'custom fields added to data inside on(\'serialize\') are present in the workflow JSON under the node\'s entry'
+    )
+    it.todo(
+      'multiple on(\'serialize\') listeners from different extensions all fire and their custom fields coexist without overwriting each other (assuming distinct keys)'
+    )
+    it.todo(
+      'on(\'serialize\') listener is removed when the extension scope is disposed; subsequent serializations omit the custom fields'
+    )
+  })
+
+  describe('named-map round-trip (widgets_values_named)', () => {
+    it.todo(
+      'v2 serialization stores widget values in a named map (widgets_values_named) keyed by widget name; the map survives a JSON round-trip with no null drift'
+    )
+    it.todo(
+      'a workflow serialized with three widgets including one serialize===false widget deserializes with correct values for all three regardless of insertion order'
+    )
+    it.todo(
+      'widgets added or removed between two serialization passes do not corrupt the named-map entries for unaffected widgets'
+    )
+  })
+
+  describe('NaN→null guard (numeric widget safety)', () => {
+    it.todo(
+      'when a numeric widget value resolves to NaN at serialization time, v2 logs a console warning and substitutes the widget\'s declared default value'
+    )
+    it.todo(
+      'the substituted default value round-trips through JSON correctly; the deserialized node shows the default, not null'
+    )
+    it.todo(
+      'NaN guard fires per-widget and does not abort the serialization of the remaining widgets on the same node'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-14.migration.test.ts b/src/extension-api-v2/__tests__/bc-14.migration.test.ts
new file mode 100644
index 0000000000..ab78c9ea8f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-14.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.14 — Workflow → API serialization interception (graphToPrompt)
+// DB cross-ref: S6.A1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/components-manager.js#L781
+// blast_radius: 7.02 (HIGHEST in dataset)
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 app.graphToPrompt monkey-patch → v2 app.on('beforeGraphToPrompt', handler)
+
+import { describe, it } from 'vitest'
+
+describe('BC.14 migration — graphToPrompt interception', () => {
+  describe('payload equivalence', () => {
+    it.todo(
+      'v1 monkey-patch and v2 beforeGraphToPrompt handler both receive equivalent { output, workflow } structures'
+    )
+    it.todo(
+      'custom metadata injected in v1 via return-value mutation is equally injectable via v2 payload mutation'
+    )
+    it.todo(
+      'v1 virtual-node removal logic produces the same serialized output as v2 automatic isVirtual resolution'
+    )
+  })
+
+  describe('execution ordering', () => {
+    it.todo(
+      'v2 handler fires at the same logical point in the queue pipeline as v1 wrapper (before HTTP dispatch)'
+    )
+    it.todo(
+      'v2 cancellation via payload.cancel() has equivalent effect to v1 throwing an error inside the wrapper'
+    )
+  })
+
+  describe('coexistence during migration window', () => {
+    it.todo(
+      'a v1 monkey-patch and a v2 beforeGraphToPrompt handler active simultaneously do not double-mutate the payload'
+    )
+    it.todo(
+      'removing the v1 monkey-patch while keeping the v2 handler produces identical final API payloads'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-14.v1.test.ts b/src/extension-api-v2/__tests__/bc-14.v1.test.ts
new file mode 100644
index 0000000000..7045d44d46
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-14.v1.test.ts
@@ -0,0 +1,32 @@
+// Category: BC.14 — Workflow → API serialization interception (graphToPrompt)
+// DB cross-ref: S6.A1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/components-manager.js#L781
+// blast_radius: 7.02 (HIGHEST in dataset)
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: monkey-patch app.graphToPrompt — const orig = app.graphToPrompt.bind(app); app.graphToPrompt = async function(...args) { const r = await orig(...args); /* mutate r */ return r }
+// v2 replacement: app.on('beforeGraphToPrompt', (payload) => { /* mutate payload */ }) event with cancellable/mutable payload
+
+import { describe, it } from 'vitest'
+
+describe('BC.14 v1 contract — graphToPrompt monkey-patch', () => {
+  describe('S6.A1 — app.graphToPrompt interception', () => {
+    it.todo(
+      'extension can replace app.graphToPrompt with a wrapper that calls the original and returns the result'
+    )
+    it.todo(
+      'wrapper receives the same positional arguments that the caller passed to app.graphToPrompt'
+    )
+    it.todo(
+      'mutations to the resolved prompt object (output, workflow) are reflected in the final API payload'
+    )
+    it.todo(
+      'virtual nodes resolved by the extension wrapper are absent from the serialized output sent to the backend'
+    )
+    it.todo(
+      'custom metadata injected into prompt.output is preserved through the full queuePrompt call'
+    )
+    it.todo(
+      'multiple extensions wrapping graphToPrompt in sequence each receive and pass through prior mutations'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-14.v2.test.ts b/src/extension-api-v2/__tests__/bc-14.v2.test.ts
new file mode 100644
index 0000000000..9f6a3129be
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-14.v2.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.14 — Workflow → API serialization interception (graphToPrompt)
+// DB cross-ref: S6.A1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/components-manager.js#L781
+// blast_radius: 7.02 (HIGHEST in dataset)
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: app.on('beforeGraphToPrompt', (payload) => { /* mutate payload */ }) event with cancellable/mutable payload
+
+import { describe, it } from 'vitest'
+
+describe('BC.14 v2 contract — beforeGraphToPrompt event', () => {
+  describe('event registration and dispatch', () => {
+    it.todo(
+      'app.on("beforeGraphToPrompt", handler) registers a handler that fires before every prompt serialization'
+    )
+    it.todo(
+      'handler receives a mutable payload object containing { output, workflow } matching the v1 return shape'
+    )
+    it.todo(
+      'mutations to payload.output inside the handler are present in the API body sent to the backend'
+    )
+    it.todo(
+      'handler can cancel serialization by calling payload.cancel(), preventing the queue call from proceeding'
+    )
+  })
+
+  describe('virtual node resolution', () => {
+    it.todo(
+      'virtual nodes declared via defineNodeExtension({ isVirtual: true }) are resolved before beforeGraphToPrompt fires'
+    )
+    it.todo(
+      'handler does not need to manually remove virtual nodes; they are absent from payload.output by default'
+    )
+  })
+
+  describe('multiple handlers and ordering', () => {
+    it.todo(
+      'multiple handlers registered with app.on("beforeGraphToPrompt") are called in registration order'
+    )
+    it.todo(
+      'each handler sees mutations made by prior handlers in the same event cycle'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-15.migration.test.ts b/src/extension-api-v2/__tests__/bc-15.migration.test.ts
new file mode 100644
index 0000000000..ff45c3b12d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-15.migration.test.ts
@@ -0,0 +1,37 @@
+// Category: BC.15 — Workflow loading into the editor
+// DB cross-ref: S6.A2
+// Exemplar: https://github.com/BennyKok/comfyui-deploy/blob/main/web-plugin/workflow-list.js#L456
+// blast_radius: 5.05 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 app.loadGraphData(json) → v2 app.loadWorkflow(json) with lifecycle hooks
+
+import { describe, it } from 'vitest'
+
+describe('BC.15 migration — workflow loading', () => {
+  describe('graph state equivalence', () => {
+    it.todo(
+      'v1 app.loadGraphData(json) and v2 app.loadWorkflow(json) produce identical node/link graphs for the same input'
+    )
+    it.todo(
+      'node widget values are preserved identically between v1 and v2 load paths'
+    )
+    it.todo(
+      'custom node types registered by extensions are correctly hydrated by both v1 and v2 load paths'
+    )
+  })
+
+  describe('interception migration', () => {
+    it.todo(
+      'v1 monkey-patching app.loadGraphData to mutate json can be replaced by a v2 beforeLoadWorkflow handler with equivalent effect'
+    )
+    it.todo(
+      'v1 post-load logic run synchronously after app.loadGraphData can be moved to a v2 afterLoadWorkflow handler'
+    )
+  })
+
+  describe('coexistence', () => {
+    it.todo(
+      'calling v2 app.loadWorkflow does not break extensions that still listen on the legacy nodeCreated hook'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-15.v1.test.ts b/src/extension-api-v2/__tests__/bc-15.v1.test.ts
new file mode 100644
index 0000000000..0428220f7d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-15.v1.test.ts
@@ -0,0 +1,28 @@
+// Category: BC.15 — Workflow loading into the editor
+// DB cross-ref: S6.A2
+// Exemplar: https://github.com/BennyKok/comfyui-deploy/blob/main/web-plugin/workflow-list.js#L456
+// blast_radius: 5.05 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: app.loadGraphData(workflowJson) — direct call, no lifecycle events
+
+import { describe, it } from 'vitest'
+
+describe('BC.15 v1 contract — app.loadGraphData', () => {
+  describe('S6.A2 — direct workflow load', () => {
+    it.todo(
+      'app.loadGraphData(json) replaces the current graph with the nodes and links from json'
+    )
+    it.todo(
+      'calling app.loadGraphData clears all existing nodes before deserializing the new workflow'
+    )
+    it.todo(
+      'node IDs in the loaded workflow are preserved as-is in the editor graph'
+    )
+    it.todo(
+      'app.loadGraphData accepts a plain JSON object (not a string) as its argument'
+    )
+    it.todo(
+      'extensions registered with nodeCreated receive each deserialized node after loadGraphData completes'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-15.v2.test.ts b/src/extension-api-v2/__tests__/bc-15.v2.test.ts
new file mode 100644
index 0000000000..be2d395efc
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-15.v2.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.15 — Workflow loading into the editor
+// DB cross-ref: S6.A2
+// Exemplar: https://github.com/BennyKok/comfyui-deploy/blob/main/web-plugin/workflow-list.js#L456
+// blast_radius: 5.05 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: app.loadWorkflow(json) — stable public API with beforeLoad/afterLoad hooks for intercepting extensions
+
+import { describe, it } from 'vitest'
+
+describe('BC.15 v2 contract — app.loadWorkflow', () => {
+  describe('core load API', () => {
+    it.todo(
+      'app.loadWorkflow(json) loads workflow nodes and links into the editor, equivalent to v1 loadGraphData'
+    )
+    it.todo(
+      'app.loadWorkflow returns a Promise that resolves once all nodes are deserialized and rendered'
+    )
+    it.todo(
+      'app.loadWorkflow accepts both plain objects and JSON strings'
+    )
+  })
+
+  describe('beforeLoad hook', () => {
+    it.todo(
+      'app.on("beforeLoadWorkflow", handler) fires before the graph is cleared, allowing cancellation via event.cancel()'
+    )
+    it.todo(
+      'handler can mutate event.workflow to transform the incoming JSON before deserialization'
+    )
+  })
+
+  describe('afterLoad hook', () => {
+    it.todo(
+      'app.on("afterLoadWorkflow", handler) fires after all nodes are created, with the fully hydrated graph accessible'
+    )
+    it.todo(
+      'afterLoad handler receives the original workflow JSON alongside the live graph for cross-referencing'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-16.migration.test.ts b/src/extension-api-v2/__tests__/bc-16.migration.test.ts
new file mode 100644
index 0000000000..88cf2ae4a2
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-16.migration.test.ts
@@ -0,0 +1,37 @@
+// Category: BC.16 — Execution output consumption (per-node)
+// DB cross-ref: S2.N2
+// Exemplar: https://github.com/andreszs/ComfyUI-Ultralytics-Studio/blob/main/js/show_string.js#L9
+// blast_radius: 4.67 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 node.onExecuted = fn → v2 NodeHandle.on('executed', fn)
+
+import { describe, it } from 'vitest'
+
+describe('BC.16 migration — per-node execution output', () => {
+  describe('data equivalence', () => {
+    it.todo(
+      'v1 onExecuted data argument and v2 executed event data contain identical fields for the same backend response'
+    )
+    it.todo(
+      'data.text and data.images accessed in v2 handler match the same properties read in v1 onExecuted for the same execution'
+    )
+  })
+
+  describe('timing equivalence', () => {
+    it.todo(
+      'v2 NodeHandle.on("executed") fires at the same point in the WebSocket message processing pipeline as v1 onExecuted'
+    )
+    it.todo(
+      'DOM/widget updates performed in the v2 handler are applied within the same animation frame as equivalent v1 updates'
+    )
+  })
+
+  describe('cleanup behaviour', () => {
+    it.todo(
+      'v1 onExecuted persists after node removal (no automatic cleanup); v2 handler is removed automatically'
+    )
+    it.todo(
+      'explicitly calling the v2 unsubscribe function produces equivalent silence to never assigning v1 onExecuted'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-16.v1.test.ts b/src/extension-api-v2/__tests__/bc-16.v1.test.ts
new file mode 100644
index 0000000000..cfa6978a5c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-16.v1.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.16 — Execution output consumption (per-node)
+// DB cross-ref: S2.N2
+// Exemplar: https://github.com/andreszs/ComfyUI-Ultralytics-Studio/blob/main/js/show_string.js#L9
+// blast_radius: 4.67 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: node.onExecuted = function(data) { /* data.text, data.images etc */ }
+
+import { describe, it } from 'vitest'
+
+describe('BC.16 v1 contract — node.onExecuted callback', () => {
+  describe('S2.N2 — per-node execution output', () => {
+    it.todo(
+      'node.onExecuted is called by the runtime when the backend reports output for that node\'s ID'
+    )
+    it.todo(
+      'data.text is an array of strings when the node outputs text-type results'
+    )
+    it.todo(
+      'data.images is an array of image descriptor objects when the node outputs image-type results'
+    )
+    it.todo(
+      'data passed to onExecuted matches the raw output object from the backend executed event for that node'
+    )
+    it.todo(
+      'assigning node.onExecuted after graph load is sufficient; the handler receives subsequent execution outputs'
+    )
+    it.todo(
+      'onExecuted is not called for nodes whose IDs are absent from the execution output'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-16.v2.test.ts b/src/extension-api-v2/__tests__/bc-16.v2.test.ts
new file mode 100644
index 0000000000..a518a53c88
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-16.v2.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.16 — Execution output consumption (per-node)
+// DB cross-ref: S2.N2
+// Exemplar: https://github.com/andreszs/ComfyUI-Ultralytics-Studio/blob/main/js/show_string.js#L9
+// blast_radius: 4.67 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: NodeHandle.on('executed', (data) => { ... })
+
+import { describe, it } from 'vitest'
+
+describe('BC.16 v2 contract — NodeHandle executed event', () => {
+  describe('event subscription', () => {
+    it.todo(
+      'nodeHandle.on("executed", handler) registers a handler that fires when backend output arrives for that node'
+    )
+    it.todo(
+      'handler receives a typed data object with text, images, and any other output slots defined by the node\'s schema'
+    )
+    it.todo(
+      'nodeHandle.on("executed", ...) returns an unsubscribe function; calling it stops future invocations'
+    )
+  })
+
+  describe('data shape and typing', () => {
+    it.todo(
+      'data.text is typed as string[] for text-output nodes; accessing it does not require a cast'
+    )
+    it.todo(
+      'data.images is typed as ImageOutput[] for image-output nodes, including filename, subfolder, and type fields'
+    )
+  })
+
+  describe('handler lifecycle', () => {
+    it.todo(
+      'handlers registered via nodeHandle.on("executed") are automatically removed when the node is removed from the graph'
+    )
+    it.todo(
+      'multiple handlers on the same node each fire independently and in registration order'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-17.migration.test.ts b/src/extension-api-v2/__tests__/bc-17.migration.test.ts
new file mode 100644
index 0000000000..046ec9c76f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-17.migration.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.17 — Backend execution lifecycle and progress events
+// DB cross-ref: S5.A1, S5.A2, S5.A3
+// Exemplar: https://github.com/AIGODLIKE/AIGODLIKE-ComfyUI-Studio/blob/main/loader/components/public/iconRenderer.js#L39
+// blast_radius: 5.00 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 app.api.addEventListener → v2 comfyApp.on with typed payloads
+
+import { describe, it } from 'vitest'
+
+describe('BC.17 migration — execution lifecycle events', () => {
+  describe('event payload equivalence (S5.A1 — executed / execution_error)', () => {
+    it.todo(
+      'v1 "executed" CustomEvent.detail and v2 "executed" payload carry the same node ID and output fields'
+    )
+    it.todo(
+      'v1 "execution_error" detail and v2 "executionError" payload both identify the failing node and provide error text'
+    )
+  })
+
+  describe('progress payload equivalence (S5.A2)', () => {
+    it.todo(
+      'v1 progress detail { value, max } and v2 progress payload { step, totalSteps } encode the same completion fraction'
+    )
+  })
+
+  describe('status and reconnect equivalence (S5.A3)', () => {
+    it.todo(
+      'v1 "status" event and v2 "status" event fire at the same points in the WebSocket message lifecycle'
+    )
+    it.todo(
+      'v1 "reconnecting" event and v2 "reconnecting" event both fire before the first reconnect attempt'
+    )
+  })
+
+  describe('handler removal equivalence', () => {
+    it.todo(
+      'v1 app.api.removeEventListener(name, fn) and v2 unsubscribe() both stop the handler from firing on subsequent events'
+    )
+    it.todo(
+      'removing a v1 listener does not affect a concurrently registered v2 listener for the same logical event'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-17.v1.test.ts b/src/extension-api-v2/__tests__/bc-17.v1.test.ts
new file mode 100644
index 0000000000..36368833f0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-17.v1.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.17 — Backend execution lifecycle and progress events
+// DB cross-ref: S5.A1, S5.A2, S5.A3
+// Exemplar: https://github.com/AIGODLIKE/AIGODLIKE-ComfyUI-Studio/blob/main/loader/components/public/iconRenderer.js#L39
+// blast_radius: 5.00 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: app.api.addEventListener('executed'|'progress'|'status'|'execution_error'|'reconnecting', fn)
+
+import { describe, it } from 'vitest'
+
+describe('BC.17 v1 contract — app.api.addEventListener', () => {
+  describe('S5.A1 — execution lifecycle events (executed, execution_error)', () => {
+    it.todo(
+      'app.api.addEventListener("executed", fn) fires fn when a node execution completes with output data'
+    )
+    it.todo(
+      'app.api.addEventListener("execution_error", fn) fires fn with error detail when the backend reports a failure'
+    )
+    it.todo(
+      'the executed event detail includes { node, output } matching the backend WebSocket message structure'
+    )
+  })
+
+  describe('S5.A2 — progress events', () => {
+    it.todo(
+      'app.api.addEventListener("progress", fn) fires fn on each step tick during a running execution'
+    )
+    it.todo(
+      'the progress event detail includes { value, max } allowing accurate percentage calculation'
+    )
+  })
+
+  describe('S5.A3 — status and reconnect events', () => {
+    it.todo(
+      'app.api.addEventListener("status", fn) fires fn when the backend queue status changes'
+    )
+    it.todo(
+      'app.api.addEventListener("reconnecting", fn) fires fn when the WebSocket connection is lost and retrying'
+    )
+    it.todo(
+      'app.api.removeEventListener with the same event name and function reference removes the handler'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-17.v2.test.ts b/src/extension-api-v2/__tests__/bc-17.v2.test.ts
new file mode 100644
index 0000000000..7527e48ce3
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-17.v2.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.17 — Backend execution lifecycle and progress events
+// DB cross-ref: S5.A1, S5.A2, S5.A3
+// Exemplar: https://github.com/AIGODLIKE/AIGODLIKE-ComfyUI-Studio/blob/main/loader/components/public/iconRenderer.js#L39
+// blast_radius: 5.00 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: comfyApp.on('executed', fn), comfyApp.on('progress', fn) — typed event payloads
+
+import { describe, it } from 'vitest'
+
+describe('BC.17 v2 contract — comfyApp event subscriptions', () => {
+  describe('S5.A1 — execution lifecycle events', () => {
+    it.todo(
+      'comfyApp.on("executed", fn) fires fn when a node reports completion, with a typed { nodeId, output } payload'
+    )
+    it.todo(
+      'comfyApp.on("executionError", fn) fires fn with a typed error payload including nodeId and exception detail'
+    )
+    it.todo(
+      'comfyApp.on("executionStart", fn) fires fn when the backend begins processing a new prompt'
+    )
+  })
+
+  describe('S5.A2 — progress events', () => {
+    it.todo(
+      'comfyApp.on("progress", fn) fires fn on each step tick with typed { step, totalSteps, nodeId } fields'
+    )
+    it.todo(
+      'progress percentage derived from v2 payload (step / totalSteps) equals percentage from v1 (value / max)'
+    )
+  })
+
+  describe('S5.A3 — status and connectivity events', () => {
+    it.todo(
+      'comfyApp.on("status", fn) fires fn when queue depth or running state changes, with a typed status payload'
+    )
+    it.todo(
+      'comfyApp.on("reconnecting", fn) fires fn when the WebSocket drops and a reconnect attempt begins'
+    )
+    it.todo(
+      'calling the unsubscribe handle returned by comfyApp.on() removes the handler without affecting other subscribers'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-18.migration.test.ts b/src/extension-api-v2/__tests__/bc-18.migration.test.ts
new file mode 100644
index 0000000000..b38cf13455
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-18.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.18 — Backend HTTP calls
+// DB cross-ref: S6.A3
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/components/common/BackgroundImageUpload.vue#L61
+// blast_radius: 5.77 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 app.api.fetchApi → v2 comfyAPI.fetchApi (same signature, stable import)
+
+import { describe, it } from 'vitest'
+
+describe('BC.18 migration — backend HTTP calls', () => {
+  describe('request equivalence', () => {
+    it.todo(
+      'v1 app.api.fetchApi(path, init) and v2 comfyAPI.fetchApi(path, init) send identical HTTP requests to the backend'
+    )
+    it.todo(
+      'authentication headers attached by v1 and v2 are equivalent; the backend accepts both without reconfiguration'
+    )
+    it.todo(
+      'FormData uploads via v1 and v2 produce the same multipart body on the wire'
+    )
+  })
+
+  describe('response handling equivalence', () => {
+    it.todo(
+      'v1 and v2 both return a native Response object; callers can use .json(), .text(), and .ok identically'
+    )
+    it.todo(
+      '4xx/5xx responses resolve (not reject) in both v1 and v2, so existing error-check patterns remain valid'
+    )
+  })
+
+  describe('import path migration', () => {
+    it.todo(
+      'replacing "app.api.fetchApi" with an import of comfyAPI.fetchApi requires no call-site argument changes'
+    )
+    it.todo(
+      'comfyAPI.fetchApi is available at extension init time without waiting for app.setup() to complete'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-18.v1.test.ts b/src/extension-api-v2/__tests__/bc-18.v1.test.ts
new file mode 100644
index 0000000000..df00f5eb44
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-18.v1.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.18 — Backend HTTP calls
+// DB cross-ref: S6.A3
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/components/common/BackgroundImageUpload.vue#L61
+// blast_radius: 5.77 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: app.api.fetchApi('/endpoint', { method: 'POST', body: ... })
+
+import { describe, it } from 'vitest'
+
+describe('BC.18 v1 contract — app.api.fetchApi', () => {
+  describe('S6.A3 — authenticated HTTP calls via fetchApi', () => {
+    it.todo(
+      'app.api.fetchApi(path, init) returns a Promise<Response> from the ComfyUI backend origin'
+    )
+    it.todo(
+      'fetchApi prepends the configured base URL so callers use relative paths like "/upload/image"'
+    )
+    it.todo(
+      'fetchApi includes authentication headers (e.g. session cookie or Authorization) automatically'
+    )
+    it.todo(
+      'a POST call with a FormData body is forwarded without Content-Type override, allowing multipart to work'
+    )
+    it.todo(
+      'a non-2xx response from the backend is returned as a resolved Promise (not rejected); callers must check response.ok'
+    )
+    it.todo(
+      'concurrent fetchApi calls from different extensions do not share or corrupt each other\'s request state'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-18.v2.test.ts b/src/extension-api-v2/__tests__/bc-18.v2.test.ts
new file mode 100644
index 0000000000..c281282fc3
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-18.v2.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.18 — Backend HTTP calls
+// DB cross-ref: S6.A3
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/components/common/BackgroundImageUpload.vue#L61
+// blast_radius: 5.77 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: comfyAPI.fetchApi(path, opts) — same signature, same authentication, stable import path
+
+import { describe, it } from 'vitest'
+
+describe('BC.18 v2 contract — comfyAPI.fetchApi', () => {
+  describe('API surface stability', () => {
+    it.todo(
+      'comfyAPI.fetchApi(path, init) is importable from the stable extension-api-v2 package without accessing app.api'
+    )
+    it.todo(
+      'comfyAPI.fetchApi signature is identical to v1 app.api.fetchApi: (path: string, init?: RequestInit) => Promise<Response>'
+    )
+    it.todo(
+      'comfyAPI.fetchApi uses the same base URL and authentication mechanism as v1 fetchApi'
+    )
+  })
+
+  describe('request handling', () => {
+    it.todo(
+      'POST with FormData body is forwarded correctly, preserving multipart boundary'
+    )
+    it.todo(
+      'JSON body with explicit Content-Type: application/json is sent without modification'
+    )
+    it.todo(
+      'non-2xx responses resolve (not reject) the returned Promise, consistent with v1 behaviour'
+    )
+  })
+
+  describe('extension isolation', () => {
+    it.todo(
+      'comfyAPI.fetchApi does not expose session credentials in a way that allows cross-extension credential theft'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-19.migration.test.ts b/src/extension-api-v2/__tests__/bc-19.migration.test.ts
new file mode 100644
index 0000000000..8607841410
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-19.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.19 — Workflow execution trigger
+// DB cross-ref: S6.A4
+// Exemplar: https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager/blob/main/js/features/viewer/workflowSidebar/sidebarRunButton.js#L317
+// blast_radius: 6.09 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 app.queuePrompt monkey-patch → v2 comfyApp.on('beforeQueuePrompt') + comfyApp.queuePrompt(opts)
+
+import { describe, it } from 'vitest'
+
+describe('BC.19 migration — workflow execution trigger', () => {
+  describe('payload mutation equivalence', () => {
+    it.todo(
+      'v1 wrapper mutation of the serialized prompt body and v2 event.payload mutation produce identical HTTP request bodies'
+    )
+    it.todo(
+      'auth tokens injected via v1 wrapper extra_data and v2 event.payload.extra_data reach the backend identically'
+    )
+  })
+
+  describe('cancellation equivalence', () => {
+    it.todo(
+      'v1 wrapper that does not call orig() and v2 handler that calls event.cancel() both result in zero HTTP calls to /prompt'
+    )
+  })
+
+  describe('programmatic trigger equivalence', () => {
+    it.todo(
+      'v1 app.queuePrompt(0, 1) and v2 comfyApp.queuePrompt({ batchCount: 1 }) both enqueue the same graph payload'
+    )
+    it.todo(
+      'v2 comfyApp.queuePrompt() fires beforeQueuePrompt handlers; v1 programmatic call also triggers any active v1 wrappers'
+    )
+  })
+
+  describe('coexistence', () => {
+    it.todo(
+      'a v1 monkey-patch and a v2 beforeQueuePrompt handler active simultaneously do not double-submit the prompt'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-19.v1.test.ts b/src/extension-api-v2/__tests__/bc-19.v1.test.ts
new file mode 100644
index 0000000000..d27a07bef0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-19.v1.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.19 — Workflow execution trigger
+// DB cross-ref: S6.A4
+// Exemplar: https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager/blob/main/js/features/viewer/workflowSidebar/sidebarRunButton.js#L317
+// blast_radius: 6.09 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: monkey-patch app.queuePrompt — const orig = app.queuePrompt.bind(app); app.queuePrompt = async function(num, batchCount) { /* mutate */ return orig(num, batchCount) }
+
+import { describe, it } from 'vitest'
+
+describe('BC.19 v1 contract — app.queuePrompt monkey-patch', () => {
+  describe('S6.A4 — queuePrompt interception', () => {
+    it.todo(
+      'extension can replace app.queuePrompt with a wrapper that calls the original and returns its result'
+    )
+    it.todo(
+      'wrapper receives (number, batchCount) arguments matching the internal call signature'
+    )
+    it.todo(
+      'extension can inject an auth token or extra field into the prompt payload before delegating to orig()'
+    )
+    it.todo(
+      'extension can prevent execution by not calling orig() inside the wrapper'
+    )
+    it.todo(
+      'multiple extensions wrapping queuePrompt in sequence each execute in wrapping order'
+    )
+    it.todo(
+      'programmatic call to app.queuePrompt(0, 1) from an extension correctly enqueues the current graph'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-19.v2.test.ts b/src/extension-api-v2/__tests__/bc-19.v2.test.ts
new file mode 100644
index 0000000000..da063077cc
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-19.v2.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.19 — Workflow execution trigger
+// DB cross-ref: S6.A4
+// Exemplar: https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager/blob/main/js/features/viewer/workflowSidebar/sidebarRunButton.js#L317
+// blast_radius: 6.09 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: comfyApp.on('beforeQueuePrompt', handler) with event.payload mutation; comfyApp.queuePrompt(opts) for programmatic trigger
+
+import { describe, it } from 'vitest'
+
+describe('BC.19 v2 contract — beforeQueuePrompt event and comfyApp.queuePrompt', () => {
+  describe('beforeQueuePrompt event', () => {
+    it.todo(
+      'comfyApp.on("beforeQueuePrompt", handler) fires before every prompt is enqueued, including UI-triggered runs'
+    )
+    it.todo(
+      'handler receives a mutable event.payload containing the prompt body and extra_data fields'
+    )
+    it.todo(
+      'mutating event.payload.extra_data.extra_pnginfo in the handler persists into the queued request'
+    )
+    it.todo(
+      'calling event.cancel() inside the handler prevents the prompt from being submitted to the backend'
+    )
+  })
+
+  describe('programmatic trigger', () => {
+    it.todo(
+      'comfyApp.queuePrompt(opts) programmatically enqueues the current workflow, firing beforeQueuePrompt first'
+    )
+    it.todo(
+      'opts.batchCount defaults to 1 when omitted; the backend receives a single prompt'
+    )
+  })
+
+  describe('multiple handlers', () => {
+    it.todo(
+      'multiple beforeQueuePrompt handlers are called in registration order; each sees prior mutations'
+    )
+    it.todo(
+      'cancellation by any handler short-circuits remaining handlers and suppresses the HTTP call'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-20.migration.test.ts b/src/extension-api-v2/__tests__/bc-20.migration.test.ts
new file mode 100644
index 0000000000..57bd59898c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-20.migration.test.ts
@@ -0,0 +1,46 @@
+// Category: BC.20 — Custom node-type registration (frontend-only / virtual)
+// DB cross-ref: S1.H5, S1.H6, S8.P1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/rerouteNode.ts
+// blast_radius: 5.49 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 LiteGraph.registerNodeType + isVirtualNode → v2 defineNodeExtension({ isVirtual: true, setup })
+
+import { describe, it } from 'vitest'
+
+describe('BC.20 migration — custom and virtual node registration', () => {
+  describe('registration equivalence (S1.H5)', () => {
+    it.todo(
+      'v1 LiteGraph.registerNodeType("MyType", MyClass) and v2 defineNodeExtension({ nodeType: "MyType" }) both make the type droppable from the node picker'
+    )
+    it.todo(
+      'v1 MyClass.prototype.isVirtualNode = true and v2 isVirtual: true both exclude the node from the graphToPrompt output'
+    )
+    it.todo(
+      'canvas rendering behaviour of a virtual node is identical between v1 and v2 registration paths'
+    )
+  })
+
+  describe('augmentation equivalence (S1.H6)', () => {
+    it.todo(
+      'v1 beforeRegisterNodeDef prototype mutation and v2 defineNodeExtension setup() widget addition produce equivalent UI on existing backend node types'
+    )
+    it.todo(
+      'widget values set via v2 setup(handle) are serialized identically to those set via v1 prototype augmentation'
+    )
+  })
+
+  describe('serialization equivalence (S8.P1)', () => {
+    it.todo(
+      'a graph with virtual nodes serialized via v1 graphToPrompt and the same graph using v2 produce bit-equivalent backend payloads'
+    )
+    it.todo(
+      'link re-routing through virtual nodes produces the same source→target pairs in both v1 and v2 serialized outputs'
+    )
+  })
+
+  describe('cleanup on unregister', () => {
+    it.todo(
+      'v1 registered types persist in LiteGraph after extension unregisters; v2 types registered via defineNodeExtension are removed'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-20.v1.test.ts b/src/extension-api-v2/__tests__/bc-20.v1.test.ts
new file mode 100644
index 0000000000..14c1da7712
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-20.v1.test.ts
@@ -0,0 +1,47 @@
+// Category: BC.20 — Custom node-type registration (frontend-only / virtual)
+// DB cross-ref: S1.H5, S1.H6, S8.P1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/rerouteNode.ts
+// blast_radius: 5.49 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: app.registerExtension({ registerCustomNodes(app) { LiteGraph.registerNodeType('MyType', MyClass); MyClass.prototype.isVirtualNode = true } })
+//              app.registerExtension({ beforeRegisterNodeDef(nodeType, nodeData) { ... } })
+
+import { describe, it } from 'vitest'
+
+describe('BC.20 v1 contract — LiteGraph.registerNodeType and isVirtualNode', () => {
+  describe('S1.H5 — registerCustomNodes hook', () => {
+    it.todo(
+      'registerExtension({ registerCustomNodes(app) }) is called during setup before any graph is loaded'
+    )
+    it.todo(
+      'LiteGraph.registerNodeType("MyType", MyClass) inside registerCustomNodes makes the type instantiable in the graph'
+    )
+    it.todo(
+      'setting MyClass.prototype.isVirtualNode = true causes the serializer to omit the node from the backend API payload'
+    )
+    it.todo(
+      'virtual node is still visible and interactive in the LiteGraph canvas'
+    )
+  })
+
+  describe('S1.H6 — beforeRegisterNodeDef hook', () => {
+    it.todo(
+      'registerExtension({ beforeRegisterNodeDef(nodeType, nodeData) }) fires for every backend-defined node type before it is registered'
+    )
+    it.todo(
+      'extension can augment nodeType prototype inside beforeRegisterNodeDef and the change affects all future instances'
+    )
+    it.todo(
+      'mutations to nodeData inside beforeRegisterNodeDef alter the node\'s widget/input schema visible to the graph'
+    )
+  })
+
+  describe('S8.P1 — virtual node payload suppression', () => {
+    it.todo(
+      'graphToPrompt excludes nodes with isVirtualNode === true from the output object sent to the backend'
+    )
+    it.todo(
+      'links connected to a virtual node are re-routed in the serialized output to preserve logical connectivity'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-20.v2.test.ts b/src/extension-api-v2/__tests__/bc-20.v2.test.ts
new file mode 100644
index 0000000000..0866ceead5
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-20.v2.test.ts
@@ -0,0 +1,46 @@
+// Category: BC.20 — Custom node-type registration (frontend-only / virtual)
+// DB cross-ref: S1.H5, S1.H6, S8.P1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/rerouteNode.ts
+// blast_radius: 5.49 (compat-floor)
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: defineNodeExtension({ nodeType: 'MyType', isVirtual: true, setup(handle) { ... } })
+
+import { describe, it } from 'vitest'
+
+describe('BC.20 v2 contract — defineNodeExtension', () => {
+  describe('S1.H5 — virtual node registration', () => {
+    it.todo(
+      'defineNodeExtension({ nodeType: "MyType", isVirtual: true, setup }) registers a pure-frontend node type'
+    )
+    it.todo(
+      'nodes registered with isVirtual: true do not appear in the serialized API payload from graphToPrompt'
+    )
+    it.todo(
+      'the virtual node is rendered on the canvas and accepts user interaction normally'
+    )
+    it.todo(
+      'setup(handle) receives a NodeHandle bound to every instance created at graph-load or user-drop time'
+    )
+  })
+
+  describe('S1.H6 — backend node-def augmentation', () => {
+    it.todo(
+      'defineNodeExtension({ nodeType: "ExistingBackendType", setup }) fires setup for every instance of a backend-defined type'
+    )
+    it.todo(
+      'extension can add widgets to the handle inside setup() and they appear on all matching nodes'
+    )
+    it.todo(
+      'schema-level augmentation (adding an input slot) declared via defineNodeExtension takes effect before the node is first rendered'
+    )
+  })
+
+  describe('S8.P1 — serialization of virtual links', () => {
+    it.todo(
+      'links through a virtual node are transparently resolved in the serialized output so backend sees direct source→target connections'
+    )
+    it.todo(
+      'removing the virtual node from the canvas also removes any dangling link stubs from the serialized payload'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-21.migration.test.ts b/src/extension-api-v2/__tests__/bc-21.migration.test.ts
new file mode 100644
index 0000000000..d14c39e115
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-21.migration.test.ts
@@ -0,0 +1,34 @@
+// Category: BC.21 — Custom widget-type registration
+// DB cross-ref: S1.H2
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// blast_radius: 4.32
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 getCustomWidgets factory → v2 defineWidgetExtension
+
+import { describe, it } from 'vitest'
+
+describe('BC.21 migration — Custom widget-type registration', () => {
+  describe('factory invocation parity (S1.H2)', () => {
+    it.todo(
+      'v1 factory (node, inputData, app) and v2 create(handle, inputData) both receive equivalent inputData for the same node def'
+    )
+    it.todo(
+      'widget produced by v1 factory and v2 create have identical serialized value in node.widgets after creation'
+    )
+  })
+
+  describe('registration timing', () => {
+    it.todo(
+      'v1 getCustomWidgets fires during extension setup; v2 defineWidgetExtension registers before setup completes — both resolve before nodeCreated'
+    )
+  })
+
+  describe('scope cleanup on dispose', () => {
+    it.todo(
+      'v1 custom widget type persists after extension unregisters; v2 type is unregistered and nodes fall back to default rendering'
+    )
+    it.todo(
+      'v2 cleanup on dispose does not affect widget types registered by other extensions'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-21.v1.test.ts b/src/extension-api-v2/__tests__/bc-21.v1.test.ts
new file mode 100644
index 0000000000..ab0229c74e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-21.v1.test.ts
@@ -0,0 +1,29 @@
+// Category: BC.21 — Custom widget-type registration
+// DB cross-ref: S1.H2
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// blast_radius: 4.32
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: app.registerExtension({ getCustomWidgets(app) { return { MYWIDGET: (node, inputData, app) => { ... } } } })
+// Notes: small family — 2 evidence rows + 1 minor variant (acceptance carve-out)
+
+import { describe, it } from 'vitest'
+
+describe('BC.21 v1 contract — Custom widget-type registration', () => {
+  describe('S1.H2 — getCustomWidgets hook', () => {
+    it.todo(
+      'extension returning a widget factory from getCustomWidgets registers the type globally'
+    )
+    it.todo(
+      'registered widget factory is invoked with (node, inputData, app) when a node with that input type is created'
+    )
+    it.todo(
+      'widget returned by factory is attached to node.widgets array'
+    )
+    it.todo(
+      'two extensions registering distinct widget types do not collide'
+    )
+    it.todo(
+      'registering the same widget type key twice: second registration wins (last-write semantics)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-21.v2.test.ts b/src/extension-api-v2/__tests__/bc-21.v2.test.ts
new file mode 100644
index 0000000000..1dae0ee917
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-21.v2.test.ts
@@ -0,0 +1,28 @@
+// Category: BC.21 — Custom widget-type registration
+// DB cross-ref: S1.H2
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// blast_radius: 4.32
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: defineWidgetExtension({ widgetType: 'MYWIDGET', create(handle, inputData) { ... } })
+
+import { describe, it } from 'vitest'
+
+describe('BC.21 v2 contract — Custom widget-type registration', () => {
+  describe('defineWidgetExtension() — declarative widget registration', () => {
+    it.todo(
+      'defineWidgetExtension({ widgetType, create }) registers the type before any nodeCreated fires'
+    )
+    it.todo(
+      'create(handle, inputData) is called with a typed WidgetHandle and the input spec tuple'
+    )
+    it.todo(
+      'widget registered via defineWidgetExtension appears in NodeHandle.widgets after node creation'
+    )
+    it.todo(
+      'widget is removed from all nodes when the extension scope is disposed'
+    )
+    it.todo(
+      'defineWidgetExtension throws if widgetType is an empty string or conflicts with a built-in type'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-22.migration.test.ts b/src/extension-api-v2/__tests__/bc-22.migration.test.ts
new file mode 100644
index 0000000000..1ffd4b89f4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-22.migration.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.22 — Context menu contributions (node and canvas)
+// DB cross-ref: S2.N5, S1.H3, S1.H4
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// blast_radius: 5.10
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 getNodeMenuItems / prototype.getExtraMenuOptions / getCanvasMenuItems
+//         → v2 NodeHandle.addContextMenuItem / app.addCanvasMenuItem
+
+import { describe, it } from 'vitest'
+
+describe('BC.22 migration — Context menu contributions (node and canvas)', () => {
+  describe('node menu item parity (S1.H3 → NodeHandle.addContextMenuItem)', () => {
+    it.todo(
+      'v1 getNodeMenuItems item and v2 addContextMenuItem item both appear in the node context menu with equal label text'
+    )
+    it.todo(
+      'action/callback invoked by clicking the item receives equivalent node context in both v1 and v2'
+    )
+  })
+
+  describe('prototype patch migration (S2.N5 → NodeHandle.addContextMenuItem)', () => {
+    it.todo(
+      'v1 prototype.getExtraMenuOptions items and v2 addContextMenuItem items both render in the same menu section'
+    )
+    it.todo(
+      'migrating from prototype patch removes the need to manually chain prior implementations'
+    )
+  })
+
+  describe('canvas menu parity (S1.H4 → app.addCanvasMenuItem)', () => {
+    it.todo(
+      'v1 getCanvasMenuItems item and v2 addCanvasMenuItem item both appear when right-clicking empty canvas'
+    )
+  })
+
+  describe('scope cleanup on dispose', () => {
+    it.todo(
+      'v1 menu items persist after extension unregisters; v2 items are removed on dispose'
+    )
+    it.todo(
+      'v2 item removal on dispose does not affect items contributed by other extensions'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-22.v1.test.ts b/src/extension-api-v2/__tests__/bc-22.v1.test.ts
new file mode 100644
index 0000000000..033c7a3c1d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-22.v1.test.ts
@@ -0,0 +1,48 @@
+// Category: BC.22 — Context menu contributions (node and canvas)
+// DB cross-ref: S2.N5, S1.H3, S1.H4
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// blast_radius: 5.10
+// compat-floor: blast_radius ≥ 2.0
+// v1 node: app.registerExtension({ getNodeMenuItems(value, options) { return [{ content: 'My Item', callback: fn }] } })
+//          or node.prototype.getExtraMenuOptions = function(...) { return [...] }
+// v1 canvas: app.registerExtension({ getCanvasMenuItems() { return [{ content: 'Canvas Option', callback: fn }] } })
+
+import { describe, it } from 'vitest'
+
+describe('BC.22 v1 contract — Context menu contributions (node and canvas)', () => {
+  describe('S1.H3 — getNodeMenuItems hook', () => {
+    it.todo(
+      'extension returning items from getNodeMenuItems appends them to the node right-click menu'
+    )
+    it.todo(
+      'getNodeMenuItems receives (value, options) where options.node is the right-clicked LGraph node'
+    )
+    it.todo(
+      'returning null or undefined from getNodeMenuItems does not break the menu'
+    )
+    it.todo(
+      'multiple extensions contributing node menu items all appear in the same context menu'
+    )
+  })
+
+  describe('S2.N5 — prototype patch getExtraMenuOptions', () => {
+    it.todo(
+      'assigning node.prototype.getExtraMenuOptions appends extra items to the node context menu'
+    )
+    it.todo(
+      'prototype-patched getExtraMenuOptions receives (app, options) and its items are merged after built-ins'
+    )
+    it.todo(
+      'multiple prototype patches chain correctly without overwriting each other'
+    )
+  })
+
+  describe('S1.H4 — getCanvasMenuItems hook', () => {
+    it.todo(
+      'extension returning items from getCanvasMenuItems appends them to the canvas right-click menu'
+    )
+    it.todo(
+      'getCanvasMenuItems items appear only when no node is right-clicked'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-22.v2.test.ts b/src/extension-api-v2/__tests__/bc-22.v2.test.ts
new file mode 100644
index 0000000000..b5a0d3e28c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-22.v2.test.ts
@@ -0,0 +1,38 @@
+// Category: BC.22 — Context menu contributions (node and canvas)
+// DB cross-ref: S2.N5, S1.H3, S1.H4
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/
+// blast_radius: 5.10
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: NodeHandle.addContextMenuItem(opts), app.addCanvasMenuItem(opts)
+//                 registered items removed on extension dispose
+
+import { describe, it } from 'vitest'
+
+describe('BC.22 v2 contract — Context menu contributions (node and canvas)', () => {
+  describe('NodeHandle.addContextMenuItem() — node-scoped menu items', () => {
+    it.todo(
+      'NodeHandle.addContextMenuItem({ label, action }) appends the item to that node\'s right-click menu'
+    )
+    it.todo(
+      'action callback receives a MenuItemContext with the target NodeHandle'
+    )
+    it.todo(
+      'addContextMenuItem returns a disposable; calling it removes only that item'
+    )
+    it.todo(
+      'item added via addContextMenuItem is removed automatically when the extension scope is disposed'
+    )
+  })
+
+  describe('app.addCanvasMenuItem() — canvas-scoped menu items', () => {
+    it.todo(
+      'app.addCanvasMenuItem({ label, action }) appends the item to the canvas right-click menu'
+    )
+    it.todo(
+      'canvas menu item is visible only when right-clicking empty canvas (no node hit)'
+    )
+    it.todo(
+      'canvas menu item is removed when the extension scope is disposed'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-23.migration.test.ts b/src/extension-api-v2/__tests__/bc-23.migration.test.ts
new file mode 100644
index 0000000000..92741fb297
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-23.migration.test.ts
@@ -0,0 +1,38 @@
+// Category: BC.23 — Node property bag mutations
+// DB cross-ref: S2.N18
+// Exemplar: https://github.com/rgthree/rgthree-comfy/blob/main/src_web/comfyui/seed.ts#L78
+// blast_radius: 5.82
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 onPropertyChanged prototype patch / node.properties direct write
+//         → v2 NodeHandle.on('propertyChanged') / NodeHandle.setProperty
+
+import { describe, it } from 'vitest'
+
+describe('BC.23 migration — Node property bag mutations', () => {
+  describe('observer parity (S2.N18)', () => {
+    it.todo(
+      'v1 onPropertyChanged and v2 propertyChanged listener both receive identical (name, value, prevValue) for the same mutation'
+    )
+    it.todo(
+      'v2 listener fires for writes made via NodeHandle.setProperty; v1 hook fires for the same via native property set path'
+    )
+  })
+
+  describe('persistence parity', () => {
+    it.todo(
+      'property written via v1 node.properties.myKey and v2 NodeHandle.setProperty both round-trip through JSON serialization identically'
+    )
+    it.todo(
+      'property survives node.clone() in both v1 and v2 paths'
+    )
+  })
+
+  describe('scope cleanup on dispose', () => {
+    it.todo(
+      'v1 prototype.onPropertyChanged persists after extension unregisters; v2 listener is removed on dispose'
+    )
+    it.todo(
+      'v2 listener removal on dispose does not silence listeners registered by other extensions on the same node'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-23.v1.test.ts b/src/extension-api-v2/__tests__/bc-23.v1.test.ts
new file mode 100644
index 0000000000..0e920c3109
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-23.v1.test.ts
@@ -0,0 +1,38 @@
+// Category: BC.23 — Node property bag mutations
+// DB cross-ref: S2.N18
+// Exemplar: https://github.com/rgthree/rgthree-comfy/blob/main/src_web/comfyui/seed.ts#L78
+// blast_radius: 5.82
+// compat-floor: blast_radius ≥ 2.0
+// v1: node.prototype.onPropertyChanged = function(name, value, prevValue) { ... }
+//     or node.properties.myKey = value
+
+import { describe, it } from 'vitest'
+
+describe('BC.23 v1 contract — Node property bag mutations', () => {
+  describe('S2.N18 — onPropertyChanged lifecycle hook', () => {
+    it.todo(
+      'assigning node.prototype.onPropertyChanged wires a callback invoked when any property value changes'
+    )
+    it.todo(
+      'onPropertyChanged receives (name, value, prevValue) with correct types for each argument'
+    )
+    it.todo(
+      'onPropertyChanged is NOT called for properties set before the node is created'
+    )
+    it.todo(
+      'multiple prototype patches to onPropertyChanged: later patch overwrites earlier unless manually chained'
+    )
+  })
+
+  describe('S2.N18 — direct node.properties mutation', () => {
+    it.todo(
+      'setting node.properties.myKey = value persists the value through graph serialization and deserialization'
+    )
+    it.todo(
+      'direct property mutation does not automatically trigger onPropertyChanged'
+    )
+    it.todo(
+      'properties bag survives node clone (node.clone() copies node.properties by value)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-23.v2.test.ts b/src/extension-api-v2/__tests__/bc-23.v2.test.ts
new file mode 100644
index 0000000000..818eebdf9d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-23.v2.test.ts
@@ -0,0 +1,38 @@
+// Category: BC.23 — Node property bag mutations
+// DB cross-ref: S2.N18
+// Exemplar: https://github.com/rgthree/rgthree-comfy/blob/main/src_web/comfyui/seed.ts#L78
+// blast_radius: 5.82
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: NodeHandle.on('propertyChanged', (name, value, prevValue) => { ... })
+//                 NodeHandle.setProperty(name, value)
+
+import { describe, it } from 'vitest'
+
+describe('BC.23 v2 contract — Node property bag mutations', () => {
+  describe('NodeHandle.on(\'propertyChanged\') — reactive property observation', () => {
+    it.todo(
+      'NodeHandle.on(\'propertyChanged\', cb) fires cb with (name, value, prevValue) on every property write'
+    )
+    it.todo(
+      'propertyChanged event fires for mutations made via both NodeHandle.setProperty and direct node.properties writes'
+    )
+    it.todo(
+      'multiple listeners on the same node all receive the event independently'
+    )
+    it.todo(
+      'listener registered via NodeHandle.on is removed when the extension scope is disposed'
+    )
+  })
+
+  describe('NodeHandle.setProperty() — managed property mutation', () => {
+    it.todo(
+      'NodeHandle.setProperty(name, value) updates node.properties[name] and triggers propertyChanged listeners'
+    )
+    it.todo(
+      'value set via setProperty survives graph serialization and deserialization'
+    )
+    it.todo(
+      'setProperty with the same value as current does not fire propertyChanged (no-op guard)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-24.migration.test.ts b/src/extension-api-v2/__tests__/bc-24.migration.test.ts
new file mode 100644
index 0000000000..cacc8208ec
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-24.migration.test.ts
@@ -0,0 +1,37 @@
+// Category: BC.24 — Node-def schema inspection
+// DB cross-ref: S13.SC1
+// Exemplar: https://github.com/BennyKok/comfyui-deploy/blob/main/web-plugin/index.js#L1
+// blast_radius: 5.00
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 raw nodeData property access → v2 NodeHandle.def / NodeHandle.inputDefs / NodeHandle.outputDefs
+
+import { describe, it } from 'vitest'
+
+describe('BC.24 migration — Node-def schema inspection', () => {
+  describe('input schema parity (S13.SC1)', () => {
+    it.todo(
+      'v1 nodeData.input.required and v2 NodeHandle.def.input.required contain identical keys for the same node type'
+    )
+    it.todo(
+      'v1 InputSpec tuple first element and v2 InputDef.type are equal strings for every slot'
+    )
+    it.todo(
+      'v1 nodeData.input.optional and v2 NodeHandle.def.input.optional both reflect server-provided optional inputs'
+    )
+  })
+
+  describe('output schema parity', () => {
+    it.todo(
+      'v1 nodeData.output array and v2 NodeHandle.def.output have the same length and type strings in slot order'
+    )
+    it.todo(
+      'v1 nodeData.output_node and v2 NodeHandle.def.output_node are the same boolean value'
+    )
+  })
+
+  describe('category parity', () => {
+    it.todo(
+      'v1 nodeData.category and v2 NodeHandle.def.category are identical strings for the same node type'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-24.v1.test.ts b/src/extension-api-v2/__tests__/bc-24.v1.test.ts
new file mode 100644
index 0000000000..93a12c1d90
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-24.v1.test.ts
@@ -0,0 +1,41 @@
+// Category: BC.24 — Node-def schema inspection
+// DB cross-ref: S13.SC1
+// Exemplar: https://github.com/BennyKok/comfyui-deploy/blob/main/web-plugin/index.js#L1
+// blast_radius: 5.00
+// compat-floor: blast_radius ≥ 2.0
+// v1: direct inspection of nodeData.input.required, nodeData.input.optional, nodeData.output,
+//     nodeData.output_node, nodeData.category, InputSpec sentinel tuples
+
+import { describe, it } from 'vitest'
+
+describe('BC.24 v1 contract — Node-def schema inspection', () => {
+  describe('S13.SC1 — input slot inspection', () => {
+    it.todo(
+      'nodeData.input.required is an object mapping slot names to InputSpec tuples [type, opts?]'
+    )
+    it.todo(
+      'nodeData.input.optional is an object mapping slot names to InputSpec tuples and may be undefined'
+    )
+    it.todo(
+      'nodeData.input.hidden is an object or undefined; hidden inputs do not appear in the node UI'
+    )
+    it.todo(
+      'InputSpec tuple first element is a string type name or array of enum values'
+    )
+  })
+
+  describe('S13.SC1 — output slot inspection', () => {
+    it.todo(
+      'nodeData.output is an array of output type name strings in slot order'
+    )
+    it.todo(
+      'nodeData.output_node is a boolean indicating whether this node routes data to the server output'
+    )
+  })
+
+  describe('S13.SC1 — category inspection', () => {
+    it.todo(
+      'nodeData.category is a slash-delimited string used to place the node in the Add Node menu hierarchy'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-24.v2.test.ts b/src/extension-api-v2/__tests__/bc-24.v2.test.ts
new file mode 100644
index 0000000000..ae5e506864
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-24.v2.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.24 — Node-def schema inspection
+// DB cross-ref: S13.SC1
+// Exemplar: https://github.com/BennyKok/comfyui-deploy/blob/main/web-plugin/index.js#L1
+// blast_radius: 5.00
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: NodeHandle.def — typed ComfyNodeDef shape with same fields but typed accessors
+//                 NodeHandle.inputDefs, NodeHandle.outputDefs
+
+import { describe, it } from 'vitest'
+
+describe('BC.24 v2 contract — Node-def schema inspection', () => {
+  describe('NodeHandle.def — typed ComfyNodeDef accessor', () => {
+    it.todo(
+      'NodeHandle.def.input.required is a typed Record<string, InputDef> mirroring the v1 shape'
+    )
+    it.todo(
+      'NodeHandle.def.input.optional is a typed Record<string, InputDef> or undefined'
+    )
+    it.todo(
+      'NodeHandle.def.output is a typed readonly array of OutputDef in slot order'
+    )
+    it.todo(
+      'NodeHandle.def.output_node is a boolean identical to the server-provided value'
+    )
+    it.todo(
+      'NodeHandle.def.category is the slash-delimited category string'
+    )
+  })
+
+  describe('NodeHandle.inputDefs — convenience accessor', () => {
+    it.todo(
+      'NodeHandle.inputDefs returns a flat array merging required and optional inputs with a slot-order index'
+    )
+    it.todo(
+      'each InputDef entry exposes .name, .type, .required, and .options fields'
+    )
+  })
+
+  describe('NodeHandle.outputDefs — convenience accessor', () => {
+    it.todo(
+      'NodeHandle.outputDefs returns an array of OutputDef with .name, .type, and .index fields'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-25.migration.test.ts b/src/extension-api-v2/__tests__/bc-25.migration.test.ts
new file mode 100644
index 0000000000..4fe7194fd2
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-25.migration.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.25 — Shell UI registration (commands, sidebars, toasts)
+// DB cross-ref: S12.UI1
+// Exemplar: https://github.com/robertvoy/ComfyUI-Distributed/blob/main/web/main.js#L269
+// blast_radius: 4.02
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 extensionManager / commandManager / toastManager imports
+//         → v2 comfyApp.registerSidebarTab / registerCommand / showToast (stable import path)
+
+import { describe, it } from 'vitest'
+
+describe('BC.25 migration — Shell UI registration (commands, sidebars, toasts)', () => {
+  describe('sidebar tab parity (S12.UI1)', () => {
+    it.todo(
+      'v1 extensionManager.registerSidebarTab and v2 comfyApp.registerSidebarTab both result in a visible tab with equivalent id and title'
+    )
+    it.todo(
+      'v2 tab render context provides the same root element accessible in v1 raw render callback'
+    )
+  })
+
+  describe('command parity', () => {
+    it.todo(
+      'command registered via v1 commandManager.registerCommand and v2 comfyApp.registerCommand are both invocable by the same id'
+    )
+    it.todo(
+      'execute/function callback receives equivalent context objects in v1 and v2'
+    )
+  })
+
+  describe('toast parity', () => {
+    it.todo(
+      'v1 toastManager.add and v2 comfyApp.showToast both display a notification with the same severity and summary text'
+    )
+    it.todo(
+      'auto-dismiss timing is equivalent between v1 life and v2 life options'
+    )
+  })
+
+  describe('scope cleanup on dispose', () => {
+    it.todo(
+      'v1 sidebar tabs and commands persist after extension unregisters; v2 contributions are removed on dispose'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-25.v1.test.ts b/src/extension-api-v2/__tests__/bc-25.v1.test.ts
new file mode 100644
index 0000000000..ca3c76987f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-25.v1.test.ts
@@ -0,0 +1,52 @@
+// Category: BC.25 — Shell UI registration (commands, sidebars, toasts)
+// DB cross-ref: S12.UI1
+// Exemplar: https://github.com/robertvoy/ComfyUI-Distributed/blob/main/web/main.js#L269
+// blast_radius: 4.02
+// compat-floor: blast_radius ≥ 2.0
+// v1: app.registerExtension({ settings: [...] })
+//     extensionManager.registerSidebarTab(opts)
+//     commandManager.registerCommand(opts)
+//     toastManager.add(opts)
+
+import { describe, it } from 'vitest'
+
+describe('BC.25 v1 contract — Shell UI registration (commands, sidebars, toasts)', () => {
+  describe('S12.UI1 — settings registration', () => {
+    it.todo(
+      'extension passing a settings array to registerExtension adds each setting to the ComfyUI settings panel'
+    )
+    it.todo(
+      'registered setting value is readable via app.ui.settings.getSettingValue(id) after registration'
+    )
+    it.todo(
+      'setting onChange callback fires when the user changes the value in the settings panel'
+    )
+  })
+
+  describe('S12.UI1 — sidebar tab registration', () => {
+    it.todo(
+      'extensionManager.registerSidebarTab({ id, icon, title, render }) adds a tab to the sidebar'
+    )
+    it.todo(
+      'render function is called with the tab container element when the tab is first activated'
+    )
+  })
+
+  describe('S12.UI1 — command registration', () => {
+    it.todo(
+      'commandManager.registerCommand({ id, label, function }) makes the command invocable by id'
+    )
+    it.todo(
+      'registered command appears in the command palette UI'
+    )
+  })
+
+  describe('S12.UI1 — toast notifications', () => {
+    it.todo(
+      'toastManager.add({ severity, summary, detail }) displays a toast notification in the UI'
+    )
+    it.todo(
+      'toast with a specified life value auto-dismisses after the given number of milliseconds'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-25.v2.test.ts b/src/extension-api-v2/__tests__/bc-25.v2.test.ts
new file mode 100644
index 0000000000..5472ee0c82
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-25.v2.test.ts
@@ -0,0 +1,48 @@
+// Category: BC.25 — Shell UI registration (commands, sidebars, toasts)
+// DB cross-ref: S12.UI1
+// Exemplar: https://github.com/robertvoy/ComfyUI-Distributed/blob/main/web/main.js#L269
+// blast_radius: 4.02
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: same APIs stabilized — comfyApp.registerSidebarTab(opts),
+//                 comfyApp.registerCommand(opts), comfyApp.showToast(opts)
+//                 consistent import path from @comfyorg/extension-api
+
+import { describe, it } from 'vitest'
+
+describe('BC.25 v2 contract — Shell UI registration (commands, sidebars, toasts)', () => {
+  describe('comfyApp.registerSidebarTab() — stabilized sidebar API', () => {
+    it.todo(
+      'comfyApp.registerSidebarTab({ id, icon, title, render }) adds a tab accessible in the sidebar'
+    )
+    it.todo(
+      'sidebar tab registered via comfyApp is removed when the extension scope is disposed'
+    )
+    it.todo(
+      'render receives a typed SidebarTabContext instead of a raw DOM element'
+    )
+  })
+
+  describe('comfyApp.registerCommand() — stabilized command API', () => {
+    it.todo(
+      'comfyApp.registerCommand({ id, label, execute }) makes the command invocable by id'
+    )
+    it.todo(
+      'command appears in the command palette with the provided label'
+    )
+    it.todo(
+      'command is unregistered when the extension scope is disposed'
+    )
+  })
+
+  describe('comfyApp.showToast() — stabilized toast API', () => {
+    it.todo(
+      'comfyApp.showToast({ severity, summary, detail }) displays a toast notification'
+    )
+    it.todo(
+      'showToast with life option auto-dismisses after the specified duration'
+    )
+    it.todo(
+      'showToast returns a handle with a dismiss() method for programmatic removal'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-26.migration.test.ts b/src/extension-api-v2/__tests__/bc-26.migration.test.ts
new file mode 100644
index 0000000000..5b3f49a71b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-26.migration.test.ts
@@ -0,0 +1,41 @@
+// Category: BC.26 — Globals as ABI (window.LiteGraph, window.comfyAPI)
+// DB cross-ref: S7.G1
+// Exemplar: https://github.com/ryanontheinside/ComfyUI_RyanOnTheInside/blob/main/web/js/index.js#L1
+// blast_radius: 4.55
+// compat-floor: blast_radius ≥ 2.0
+// Migration: v1 window.LiteGraph / window.comfyAPI / window.app access
+//         → v2 explicit named imports from @comfyorg/extension-api
+
+import { describe, it } from 'vitest'
+
+describe('BC.26 migration — Globals as ABI (window.LiteGraph, window.comfyAPI)', () => {
+  describe('LiteGraph reference parity (S7.G1)', () => {
+    it.todo(
+      'window.LiteGraph.LGraphNode and the named import LGraphNode from @comfyorg/extension-api are the same constructor reference'
+    )
+    it.todo(
+      'a node registered via window.LiteGraph.registerNodeType is identical to one registered via the v2 import path'
+    )
+    it.todo(
+      'LiteGraph enum values accessed via window and via import are strictly equal (===)'
+    )
+  })
+
+  describe('comfyAPI / comfyApp reference parity', () => {
+    it.todo(
+      'window.app and the imported comfyApp share the same graph state — mutations via one are visible on the other'
+    )
+    it.todo(
+      'window.comfyAPI.modules.extensionService and imported extensionManager refer to the same instance'
+    )
+  })
+
+  describe('deprecation signal migration', () => {
+    it.todo(
+      'replacing window.LiteGraph access with named imports removes all deprecation console warnings'
+    )
+    it.todo(
+      'replacing window.comfyAPI access with named imports removes all deprecation console warnings'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-26.v1.test.ts b/src/extension-api-v2/__tests__/bc-26.v1.test.ts
new file mode 100644
index 0000000000..583775ce75
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-26.v1.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.26 — Globals as ABI (window.LiteGraph, window.comfyAPI)
+// DB cross-ref: S7.G1
+// Exemplar: https://github.com/ryanontheinside/ComfyUI_RyanOnTheInside/blob/main/web/js/index.js#L1
+// blast_radius: 4.55
+// compat-floor: blast_radius ≥ 2.0
+// v1: window.LiteGraph.registerNodeType(...), window.comfyAPI.modules.extensionService, window.app
+
+import { describe, it } from 'vitest'
+
+describe('BC.26 v1 contract — Globals as ABI (window.LiteGraph, window.comfyAPI)', () => {
+  describe('S7.G1 — window.LiteGraph global usage', () => {
+    it.todo(
+      'window.LiteGraph is defined and exposes registerNodeType, LGraph, LGraphNode, and LLink constructors'
+    )
+    it.todo(
+      'window.LiteGraph.registerNodeType(type, ctor) registers a custom node type visible in the Add Node menu'
+    )
+    it.todo(
+      'LiteGraph enum constants (e.g. LiteGraph.INPUT, LiteGraph.OUTPUT) are accessible via window.LiteGraph'
+    )
+  })
+
+  describe('S7.G1 — window.comfyAPI global registry', () => {
+    it.todo(
+      'window.comfyAPI is defined after the app boots and exposes a modules sub-object'
+    )
+    it.todo(
+      'window.comfyAPI.modules.extensionService references the active extensionManager instance'
+    )
+    it.todo(
+      'services accessed via window.comfyAPI.modules are the same objects as those available via ES module import'
+    )
+  })
+
+  describe('S7.G1 — window.app global', () => {
+    it.todo(
+      'window.app is defined and is the same object as the app instance passed to extension hooks'
+    )
+    it.todo(
+      'mutations made to the graph via window.app are reflected in the live canvas immediately'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-26.v2.test.ts b/src/extension-api-v2/__tests__/bc-26.v2.test.ts
new file mode 100644
index 0000000000..501461f063
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-26.v2.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.26 — Globals as ABI (window.LiteGraph, window.comfyAPI)
+// DB cross-ref: S7.G1
+// Exemplar: https://github.com/ryanontheinside/ComfyUI_RyanOnTheInside/blob/main/web/js/index.js#L1
+// blast_radius: 4.55
+// compat-floor: blast_radius ≥ 2.0
+// v2 replacement: explicit imports from @comfyorg/extension-api
+//                 globals still exported for compat shim but deprecated
+
+import { describe, it } from 'vitest'
+
+describe('BC.26 v2 contract — Globals as ABI (window.LiteGraph, window.comfyAPI)', () => {
+  describe('explicit LiteGraph imports from @comfyorg/extension-api', () => {
+    it.todo(
+      'LGraph, LGraphNode, LLink are importable by name from @comfyorg/extension-api'
+    )
+    it.todo(
+      'LiteGraph enum constants (INPUT, OUTPUT, etc.) are importable as named exports'
+    )
+    it.todo(
+      'imported constructors are the same references as window.LiteGraph equivalents during the compat shim window'
+    )
+  })
+
+  describe('explicit comfyApp / service imports', () => {
+    it.todo(
+      'comfyApp is importable from @comfyorg/extension-api and is the same instance as window.app'
+    )
+    it.todo(
+      'extensionManager is importable from @comfyorg/extension-api and is the same instance as window.comfyAPI.modules.extensionService'
+    )
+  })
+
+  describe('compat shim deprecation', () => {
+    it.todo(
+      'accessing window.LiteGraph in v2 mode emits a deprecation warning to the console'
+    )
+    it.todo(
+      'accessing window.comfyAPI in v2 mode emits a deprecation warning to the console'
+    )
+    it.todo(
+      'compat shim globals are still functional (not removed) so v1 extensions continue working during migration window'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-27.migration.test.ts b/src/extension-api-v2/__tests__/bc-27.migration.test.ts
new file mode 100644
index 0000000000..e76cfba318
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-27.migration.test.ts
@@ -0,0 +1,46 @@
+// Category: BC.27 — LiteGraph entity direct manipulation (reroute, group, link, slot)
+// DB cross-ref: S9.R1, S9.G1, S9.L1, S9.S1
+// Exemplar: https://github.com/nodetool-ai/nodetool/blob/main/subgraphs.md#L1
+// blast_radius: 5.62
+// compat-floor: blast_radius ≥ 2.0
+// migration: direct raw object mutations → read-only v2 accessors (mutations deferred to D9 Phase C)
+
+import { describe, it } from 'vitest'
+
+describe('BC.27 migration — LiteGraph entity direct manipulation', () => {
+  describe('reroute migration', () => {
+    it.todo(
+      'v1 graph.reroutes raw access is replaced by comfyApp.graph.reroutes iterable'
+    )
+    it.todo(
+      'v1 direct position mutation (graph.reroutes[id].pos = [...]) has no v2 equivalent until D9 Phase C'
+    )
+  })
+
+  describe('group migration', () => {
+    it.todo(
+      'v1 graph.groups[i].title mutation is replaced by a future GroupHandle.setTitle() (D9 Phase C)'
+    )
+    it.todo(
+      'v1 graph.groups iteration is replaced by comfyApp.graph.groups read-only iterable'
+    )
+  })
+
+  describe('link migration', () => {
+    it.todo(
+      'v1 link.color direct assignment is replaced by a future LinkHandle.setColor() (D9 Phase C)'
+    )
+    it.todo(
+      'v2 compat shim logs a deprecation warning when graph.links is accessed directly'
+    )
+  })
+
+  describe('slot migration', () => {
+    it.todo(
+      'v1 node.inputs[i].shape mutation has no v2 equivalent until D9 Phase C'
+    )
+    it.todo(
+      'v2 compat shim throws a TypeError when slot mutation is attempted via legacy path'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-27.v1.test.ts b/src/extension-api-v2/__tests__/bc-27.v1.test.ts
new file mode 100644
index 0000000000..b767c82cc0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-27.v1.test.ts
@@ -0,0 +1,52 @@
+// Category: BC.27 — LiteGraph entity direct manipulation (reroute, group, link, slot)
+// DB cross-ref: S9.R1, S9.G1, S9.L1, S9.S1
+// Exemplar: https://github.com/nodetool-ai/nodetool/blob/main/subgraphs.md#L1
+// blast_radius: 5.62
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: direct graph.reroutes, graph.groups, link.color, slot.shape mutations — no API, raw object access
+
+import { describe, it } from 'vitest'
+
+describe('BC.27 v1 contract — LiteGraph entity direct manipulation', () => {
+  describe('S9.R1 — reroute direct access', () => {
+    it.todo(
+      'extension can read graph.reroutes and iterate all reroute nodes in the graph'
+    )
+    it.todo(
+      'extension can mutate reroute position directly via graph.reroutes[id].pos'
+    )
+    it.todo(
+      'reroute additions via graph.reroutes[id] = { ... } are reflected in the rendered canvas'
+    )
+  })
+
+  describe('S9.G1 — group direct access', () => {
+    it.todo(
+      'extension can read graph.groups and iterate all groups'
+    )
+    it.todo(
+      'extension can mutate group title via graph.groups[i].title = string'
+    )
+    it.todo(
+      'extension can mutate group bounding box via graph.groups[i].bounding'
+    )
+  })
+
+  describe('S9.L1 — link direct access', () => {
+    it.todo(
+      'extension can read link.color and link.type directly from graph.links[id]'
+    )
+    it.todo(
+      'setting link.color mutates the rendered link color without requiring graph refresh'
+    )
+  })
+
+  describe('S9.S1 — slot direct access', () => {
+    it.todo(
+      'extension can read node.inputs[i].shape and node.outputs[i].shape directly'
+    )
+    it.todo(
+      'extension can mutate slot.shape to change rendered connector shape'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-27.v2.test.ts b/src/extension-api-v2/__tests__/bc-27.v2.test.ts
new file mode 100644
index 0000000000..786a4efe53
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-27.v2.test.ts
@@ -0,0 +1,50 @@
+// Category: BC.27 — LiteGraph entity direct manipulation (reroute, group, link, slot)
+// DB cross-ref: S9.R1, S9.G1, S9.L1, S9.S1
+// Exemplar: https://github.com/nodetool-ai/nodetool/blob/main/subgraphs.md#L1
+// blast_radius: 5.62
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: partial — reroute/group/link read APIs planned; mutations deferred to D9 Phase C.
+//              For now: read-only accessors
+
+import { describe, it } from 'vitest'
+
+describe('BC.27 v2 contract — LiteGraph entity direct manipulation', () => {
+  describe('S9.R1 — reroute read-only accessors', () => {
+    it.todo(
+      'comfyApp.graph.reroutes returns an iterable of read-only RerouteHandle objects'
+    )
+    it.todo(
+      'RerouteHandle exposes id, pos, and linked link IDs as read-only properties'
+    )
+    it.todo(
+      'attempting to mutate RerouteHandle.pos in v2 throws or is silently ignored (write-protect)'
+    )
+  })
+
+  describe('S9.G1 — group read-only accessors', () => {
+    it.todo(
+      'comfyApp.graph.groups returns an iterable of read-only GroupHandle objects'
+    )
+    it.todo(
+      'GroupHandle exposes title and bounding as read-only (mutations deferred to D9 Phase C)'
+    )
+  })
+
+  describe('S9.L1 — link read-only accessors', () => {
+    it.todo(
+      'comfyApp.graph.links returns a Map<id, LinkHandle> with read-only color and type'
+    )
+    it.todo(
+      'link mutation API is not available in v2 Phase A (deferred to D9 Phase C)'
+    )
+  })
+
+  describe('S9.S1 — slot read-only accessors', () => {
+    it.todo(
+      'NodeHandle.inputs and NodeHandle.outputs expose read-only SlotHandle with shape'
+    )
+    it.todo(
+      'slot shape mutation is not available in v2 Phase A (deferred to D9 Phase C)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-28.migration.test.ts b/src/extension-api-v2/__tests__/bc-28.migration.test.ts
new file mode 100644
index 0000000000..bbf851d8af
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-28.migration.test.ts
@@ -0,0 +1,39 @@
+// Category: BC.28 — Subgraph fan-out via set/get virtual nodes
+// DB cross-ref: S9.SG1
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/setgetnodes.js#L1406
+// blast_radius: 4.97
+// compat-floor: blast_radius ≥ 2.0
+// migration: isVirtualNode=true + graphToPrompt monkey-patch → defineNodeExtension({ virtual: true, resolveConnections })
+// Decision: I-UWF.5 (2026-05-08) — S8.P1 → virtual: true (mechanical rename); S9.SG1 → add resolveConnections.
+// Classified uwf-resolved per I-PG.B2 — UWF Phase 3 is the migration path.
+
+import { describe, it } from 'vitest'
+
+describe('BC.28 migration — subgraph fan-out via set/get virtual nodes', () => {
+  describe('S8.P1 — isVirtualNode flag migration', () => {
+    it.todo(
+      'v1 class-level isVirtualNode=true is replaced by defineNodeExtension({ virtual: true, resolveConnections })'
+    )
+    it.todo(
+      'v2 compat shim recognizes isVirtualNode=true on a registered class and emits a migration warning'
+    )
+    it.todo(
+      'migration is mechanical: rename isVirtualNode=true to virtual: true and add resolveConnections stub'
+    )
+  })
+
+  describe('S9.SG1 — graphToPrompt monkey-patch migration', () => {
+    it.todo(
+      'v1 graphToPrompt patch that rewrites link.target_id is replaced by resolveConnections returning ResolvedEdges'
+    )
+    it.todo(
+      'v2 resolveConnections receives the same graph state that v1 graphToPrompt received, as a read-only view'
+    )
+    it.todo(
+      'v2 compat shim logs a deprecation warning when graphToPrompt is monkey-patched for virtual node resolution'
+    )
+    it.todo(
+      'for cg-use-everywhere topology inference (graph-wide, not per-type): ctx.on("beforePrompt") is the bridge until UWF Phase 3'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-28.v1.test.ts b/src/extension-api-v2/__tests__/bc-28.v1.test.ts
new file mode 100644
index 0000000000..b1dc2c9b4e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-28.v1.test.ts
@@ -0,0 +1,35 @@
+// Category: BC.28 — Subgraph fan-out via set/get virtual nodes
+// DB cross-ref: S9.SG1
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/setgetnodes.js#L1406
+// blast_radius: 4.97
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: custom virtual node classes with isVirtualNode=true + graphToPrompt rewriting
+//              to resolve set/get references
+
+import { describe, it } from 'vitest'
+
+describe('BC.28 v1 contract — subgraph fan-out via set/get virtual nodes', () => {
+  describe('S9.SG1 — virtual node registration and isVirtualNode flag', () => {
+    it.todo(
+      'registering a node class with isVirtualNode=true excludes it from prompt serialization'
+    )
+    it.todo(
+      'virtual Set node stores a named value in a global registry keyed by node title'
+    )
+    it.todo(
+      'virtual Get node reads from the same named registry and wires its output as if linked'
+    )
+  })
+
+  describe('S9.SG1 — graphToPrompt rewriting', () => {
+    it.todo(
+      'graphToPrompt resolves all Get references to the corresponding Set node output before serialization'
+    )
+    it.todo(
+      'multiple Get nodes referencing the same Set name all resolve to the same upstream value'
+    )
+    it.todo(
+      'a Get node with no matching Set name is flagged as an error during graphToPrompt'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-28.v2.test.ts b/src/extension-api-v2/__tests__/bc-28.v2.test.ts
new file mode 100644
index 0000000000..398e243feb
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-28.v2.test.ts
@@ -0,0 +1,42 @@
+// Category: BC.28 — Subgraph fan-out via set/get virtual nodes
+// DB cross-ref: S9.SG1
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/setgetnodes.js#L1406
+// blast_radius: 4.97
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: defineNodeExtension({ virtual: true, resolveConnections(node, graph) → ResolvedEdges })
+// Decision: I-UWF.5 (2026-05-08) — Option (b) accepted. Phase B only.
+// resolveConnections is pure; runtime materializes edges at save time (UWF Phase 3).
+
+import { describe, it } from 'vitest'
+
+describe('BC.28 v2 contract — subgraph fan-out via set/get virtual nodes', () => {
+  describe('S9.SG1 — virtual: true declaration', () => {
+    it.todo(
+      'defineNodeExtension({ virtual: true }) excludes the node from spec.edges in the serialized prompt'
+    )
+    it.todo(
+      'virtual nodes do not appear in the serialized workflow output keyed by node id'
+    )
+    it.todo(
+      'virtual: true without resolveConnections is a type error at registration time'
+    )
+  })
+
+  describe('S9.SG1 — resolveConnections(node, graph) → ResolvedEdges', () => {
+    it.todo(
+      'resolveConnections receives a read-only view of the virtual node and the full graph'
+    )
+    it.todo(
+      'resolveConnections returns an array of { from: NodeSlotRef, to: NodeSlotRef } real edges'
+    )
+    it.todo(
+      'runtime calls resolveConnections for every virtual node during spec materialization at save time'
+    )
+    it.todo(
+      'resolveConnections returning an empty array removes this virtual node from the spec entirely'
+    )
+    it.todo(
+      'resolveConnections must be pure — mutations to node or graph throw in development mode'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-29.migration.test.ts b/src/extension-api-v2/__tests__/bc-29.migration.test.ts
new file mode 100644
index 0000000000..dcece24c2f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-29.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.29 — Graph enumeration, mutation, and cross-scope identity
+// DB cross-ref: S11.G2, S14.ID1
+// Exemplar: https://github.com/yolain/ComfyUI-Easy-Use/blob/main/web_version/v1/js/easy/easyExtraMenu.js#L439
+// blast_radius: 5.13
+// compat-floor: blast_radius ≥ 2.0
+// migration: app.graph raw methods → comfyApp.graph typed API; parseNodeLocatorId → NodeLocatorId.parse
+
+import { describe, it } from 'vitest'
+
+describe('BC.29 migration — graph enumeration, mutation, and cross-scope identity', () => {
+  describe('graph enumeration migration', () => {
+    it.todo(
+      'app.graph.findNodesByType(type) is replaced by comfyApp.graph.findByType(type) returning NodeHandle[]'
+    )
+    it.todo(
+      'v2 compat shim forwards app.graph.findNodesByType calls to comfyApp.graph.findByType with a deprecation warning'
+    )
+  })
+
+  describe('graph mutation migration', () => {
+    it.todo(
+      'app.graph.add(node) accepting a raw LiteGraph node is replaced by comfyApp.graph.addNode(opts)'
+    )
+    it.todo(
+      'app.graph.remove(node) accepting a raw reference is replaced by comfyApp.graph.removeNode(handle)'
+    )
+    it.todo(
+      'v2 compat shim wraps a raw LiteGraph node passed to add() as a NodeHandle automatically'
+    )
+  })
+
+  describe('cross-scope identity migration', () => {
+    it.todo(
+      'parseNodeLocatorId(id) free function is replaced by NodeLocatorId.parse(id) static method'
+    )
+    it.todo(
+      'createNodeLocatorId(scope, id) is replaced by NodeLocatorId.create(scope, id)'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-29.v1.test.ts b/src/extension-api-v2/__tests__/bc-29.v1.test.ts
new file mode 100644
index 0000000000..15aeefe6a4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-29.v1.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.29 — Graph enumeration, mutation, and cross-scope identity
+// DB cross-ref: S11.G2, S14.ID1
+// Exemplar: https://github.com/yolain/ComfyUI-Easy-Use/blob/main/web_version/v1/js/easy/easyExtraMenu.js#L439
+// blast_radius: 5.13
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: app.graph.findNodesByType, app.graph.add/remove, parseNodeLocatorId, createNodeLocatorId
+
+import { describe, it } from 'vitest'
+
+describe('BC.29 v1 contract — graph enumeration, mutation, and cross-scope identity', () => {
+  describe('S11.G2 — graph enumeration and mutation', () => {
+    it.todo(
+      'app.graph.findNodesByType("NodeType") returns an array of all matching LiteGraph nodes'
+    )
+    it.todo(
+      'app.graph.add(node) inserts a pre-constructed LiteGraph node into the live graph'
+    )
+    it.todo(
+      'app.graph.remove(node) removes a node from the live graph by reference'
+    )
+    it.todo(
+      'app.graph.serialize() produces a JSON-serializable object representing the full graph state'
+    )
+    it.todo(
+      'app.graph.configure(json) restores graph state from a previously serialized object'
+    )
+  })
+
+  describe('S14.ID1 — cross-subgraph identity helpers', () => {
+    it.todo(
+      'parseNodeLocatorId(id) splits a locator string into { scope, localId } parts'
+    )
+    it.todo(
+      'createNodeLocatorId(scope, localId) produces a stable colon-delimited locator string'
+    )
+    it.todo(
+      'round-tripping createNodeLocatorId → parseNodeLocatorId recovers the original scope and localId'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-29.v2.test.ts b/src/extension-api-v2/__tests__/bc-29.v2.test.ts
new file mode 100644
index 0000000000..dceb14a624
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-29.v2.test.ts
@@ -0,0 +1,37 @@
+// Category: BC.29 — Graph enumeration, mutation, and cross-scope identity
+// DB cross-ref: S11.G2, S14.ID1
+// Exemplar: https://github.com/yolain/ComfyUI-Easy-Use/blob/main/web_version/v1/js/easy/easyExtraMenu.js#L439
+// blast_radius: 5.13
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: comfyApp.graph.findByType, addNode, removeNode; NodeLocatorId helpers stable
+
+import { describe, it } from 'vitest'
+
+describe('BC.29 v2 contract — graph enumeration, mutation, and cross-scope identity', () => {
+  describe('S11.G2 — graph enumeration and mutation', () => {
+    it.todo(
+      'comfyApp.graph.findByType(type) returns an array of NodeHandle objects for matching nodes'
+    )
+    it.todo(
+      'comfyApp.graph.addNode(opts) creates and inserts a new node, returning its NodeHandle'
+    )
+    it.todo(
+      'comfyApp.graph.removeNode(handle) removes the node identified by the given NodeHandle'
+    )
+    it.todo(
+      'comfyApp.graph.serialize() returns the same JSON-compatible format as v1 for round-trip compatibility'
+    )
+  })
+
+  describe('S14.ID1 — cross-subgraph identity helpers', () => {
+    it.todo(
+      'NodeLocatorId.parse(id) returns a typed { scope, localId } object'
+    )
+    it.todo(
+      'NodeLocatorId.create(scope, localId) returns a stable string compatible with v1 parseNodeLocatorId output'
+    )
+    it.todo(
+      'NodeExecutionId is distinct from NodeLocatorId and reflects runtime execution scope, not graph scope'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-30.migration.test.ts b/src/extension-api-v2/__tests__/bc-30.migration.test.ts
new file mode 100644
index 0000000000..bf44d62cdb
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-30.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.30 — Graph change tracking, batching, and reactivity flush
+// DB cross-ref: S11.G1, S11.G3, S11.G4
+// Exemplar: https://github.com/nodetool-ai/nodetool/blob/main/subgraphs.md#L1
+// blast_radius: 5.48
+// compat-floor: blast_radius ≥ 2.0
+// migration: graph._version / beforeChange / afterChange / setDirtyCanvas → Vue reactivity + batchUpdate
+
+import { describe, it } from 'vitest'
+
+describe('BC.30 migration — graph change tracking, batching, and reactivity flush', () => {
+  describe('_version counter migration', () => {
+    it.todo(
+      'extensions that increment graph._version to signal changes should switch to comfyApp.graph.batchUpdate()'
+    )
+    it.todo(
+      'v2 compat shim intercepts graph._version++ and logs a deprecation warning'
+    )
+  })
+
+  describe('beforeChange / afterChange migration', () => {
+    it.todo(
+      'graph.beforeChange() + graph.afterChange() pairs are replaced by comfyApp.graph.batchUpdate(fn)'
+    )
+    it.todo(
+      'v2 compat shim stubs beforeChange/afterChange as no-ops and logs deprecation warnings'
+    )
+    it.todo(
+      'code relying on nested beforeChange ref-counting must be refactored to nested batchUpdate calls'
+    )
+  })
+
+  describe('setDirtyCanvas migration', () => {
+    it.todo(
+      'node.setDirtyCanvas(true, true) calls are safe to remove in v2 — reactivity handles repaints'
+    )
+    it.todo(
+      'v2 compat shim stubs setDirtyCanvas as a no-op with a deprecation warning rather than throwing'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-30.v1.test.ts b/src/extension-api-v2/__tests__/bc-30.v1.test.ts
new file mode 100644
index 0000000000..98a0ff6943
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-30.v1.test.ts
@@ -0,0 +1,43 @@
+// Category: BC.30 — Graph change tracking, batching, and reactivity flush
+// DB cross-ref: S11.G1, S11.G3, S11.G4
+// Exemplar: https://github.com/nodetool-ai/nodetool/blob/main/subgraphs.md#L1
+// blast_radius: 5.48
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: graph._version++, graph.beforeChange(), graph.afterChange(), node.setDirtyCanvas(true, true)
+
+import { describe, it } from 'vitest'
+
+describe('BC.30 v1 contract — graph change tracking, batching, and reactivity flush', () => {
+  describe('S11.G1 — _version monotonic counter', () => {
+    it.todo(
+      'graph._version is a numeric property that increments with each structural change'
+    )
+    it.todo(
+      'extension can increment graph._version to signal a change and trigger downstream listeners'
+    )
+    it.todo(
+      'reading graph._version before and after a node add/remove shows the value increased'
+    )
+  })
+
+  describe('S11.G3 — beforeChange / afterChange batching', () => {
+    it.todo(
+      'calling graph.beforeChange() suspends incremental canvas redraws'
+    )
+    it.todo(
+      'calling graph.afterChange() after a batch of mutations triggers a single consolidated redraw'
+    )
+    it.todo(
+      'nested beforeChange/afterChange calls are ref-counted and only flush on the outermost afterChange'
+    )
+  })
+
+  describe('S11.G4 — setDirtyCanvas imperative flush', () => {
+    it.todo(
+      'node.setDirtyCanvas(true, false) marks the foreground canvas dirty and schedules a repaint'
+    )
+    it.todo(
+      'node.setDirtyCanvas(true, true) marks both foreground and background canvases dirty'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-30.v2.test.ts b/src/extension-api-v2/__tests__/bc-30.v2.test.ts
new file mode 100644
index 0000000000..e0318ba598
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-30.v2.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.30 — Graph change tracking, batching, and reactivity flush
+// DB cross-ref: S11.G1, S11.G3, S11.G4
+// Exemplar: https://github.com/nodetool-ai/nodetool/blob/main/subgraphs.md#L1
+// blast_radius: 5.48
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: Vue reactivity replaces graph._version; comfyApp.graph.batchUpdate(fn) replaces
+//              beforeChange/afterChange; setDirtyCanvas is implicit
+
+import { describe, it } from 'vitest'
+
+describe('BC.30 v2 contract — graph change tracking, batching, and reactivity flush', () => {
+  describe('S11.G1 — reactive graph state replaces _version', () => {
+    it.todo(
+      'graph state is Vue-reactive; watchers on graph node count or structure auto-trigger without _version polling'
+    )
+    it.todo(
+      'graph._version does not exist on the v2 GraphHandle; accessing it returns undefined'
+    )
+    it.todo(
+      'comfyApp.graph exposes a reactive nodeCount property that updates when nodes are added or removed'
+    )
+  })
+
+  describe('S11.G3 — batchUpdate replaces beforeChange/afterChange', () => {
+    it.todo(
+      'comfyApp.graph.batchUpdate(fn) defers all reactive updates until fn completes'
+    )
+    it.todo(
+      'mutations inside batchUpdate are committed atomically; watchers see only the post-batch state'
+    )
+    it.todo(
+      'exceptions thrown inside batchUpdate cause the batch to be rolled back with no partial state visible'
+    )
+  })
+
+  describe('S11.G4 — implicit canvas flush', () => {
+    it.todo(
+      'setDirtyCanvas is not needed in v2 — Vue reactivity and the render loop coordinate repaints automatically'
+    )
+    it.todo(
+      'calling node.setDirtyCanvas in v2 is a no-op shim that logs a deprecation warning'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-31.migration.test.ts b/src/extension-api-v2/__tests__/bc-31.migration.test.ts
new file mode 100644
index 0000000000..6560d7e348
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-31.migration.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.31 — DOM injection and style management
+// DB cross-ref: S16.DOM1, S16.DOM2, S16.DOM3, S16.DOM4
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/help_popup.js
+// Migration: v1 raw DOM injection → v2 injectStyles / addPanel / addToolbarItem
+
+import { describe, it } from 'vitest'
+
+describe('BC.31 migration — DOM injection and style management', () => {
+  describe('style injection migration (S16.DOM1)', () => {
+    it.todo(
+      'v1 document.head.appendChild(styleEl) and v2 injectStyles(css) both result in equivalent CSS applied to document'
+    )
+    it.todo(
+      'v2 injectStyles() produces styles with equal or narrower specificity than v1 raw injection'
+    )
+  })
+
+  describe('panel injection migration (S16.DOM2)', () => {
+    it.todo(
+      'v1 document.body.appendChild(el) and v2 addPanel() both result in a panel element present in the DOM'
+    )
+    it.todo(
+      'v2 panel is visible in same position as v1 body-appended element for equivalent opts'
+    )
+  })
+
+  describe('HTML content migration (S16.DOM3)', () => {
+    it.todo(
+      'content rendered via v1 innerHTML and v2 safe rendering API produces equivalent visible output for trusted HTML'
+    )
+    it.todo(
+      'v2 safe rendering API blocks XSS payloads that v1 innerHTML would have executed'
+    )
+  })
+
+  describe('scope cleanup on unregister', () => {
+    it.todo(
+      'v1 style/panel injections persist after extension unregisters (no cleanup); v2 injections are removed'
+    )
+    it.todo(
+      'v2 cleanup on unregister does not affect styles/panels from other extensions'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-31.v1.test.ts b/src/extension-api-v2/__tests__/bc-31.v1.test.ts
new file mode 100644
index 0000000000..8beb91a21f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-31.v1.test.ts
@@ -0,0 +1,48 @@
+// Category: BC.31 — DOM injection and style management
+// DB cross-ref: S16.DOM1, S16.DOM2, S16.DOM3, S16.DOM4
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/help_popup.js
+// Surface: S16 — DOM injection (new surface family, not previously tracked)
+// Occurrence signal: DOM1=354, DOM2=364, DOM3=443, DOM4=232 packages (Notion API research 2026-05-08)
+
+import { describe, it } from 'vitest'
+
+describe('BC.31 v1 contract — DOM injection and style management', () => {
+  describe('S16.DOM1 — style tag injection into document.head', () => {
+    it.todo(
+      'extension can append a <style> element to document.head and styles take effect'
+    )
+    it.todo(
+      'multiple extensions injecting styles do not collide (last-write-wins for same selector)'
+    )
+    it.todo(
+      'styles injected during setup() are present before nodeCreated fires'
+    )
+  })
+
+  describe('S16.DOM2 — arbitrary element injection into document.body', () => {
+    it.todo(
+      'extension can appendChild an arbitrary element to document.body'
+    )
+    it.todo(
+      'injected panel element is accessible via document.getElementById after setup'
+    )
+  })
+
+  describe('S16.DOM3 — innerHTML rendering (unsanitized HTML strings)', () => {
+    it.todo(
+      'extension can set innerHTML on a container element it owns'
+    )
+    it.todo(
+      'innerHTML content is rendered immediately without requiring a Vue tick'
+    )
+  })
+
+  describe('S16.DOM4 — external script/asset loading via DOM', () => {
+    it.todo(
+      'extension can dynamically create and append a <script> element to load external code'
+    )
+    it.todo(
+      'extension can create a <link rel="stylesheet"> element for external CSS'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-31.v2.test.ts b/src/extension-api-v2/__tests__/bc-31.v2.test.ts
new file mode 100644
index 0000000000..89bbf24b90
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-31.v2.test.ts
@@ -0,0 +1,56 @@
+// Category: BC.31 — DOM injection and style management
+// DB cross-ref: S16.DOM1, S16.DOM2, S16.DOM3, S16.DOM4
+// Exemplar: https://github.com/kijai/ComfyUI-KJNodes/blob/main/web/js/help_popup.js
+// v2 replacement: extensionManager.injectStyles(css), extension.addPanel(opts), extension.addToolbarItem(opts)
+
+import { describe, it } from 'vitest'
+
+describe('BC.31 v2 contract — DOM injection and style management', () => {
+  describe('injectStyles(css) — scoped style injection', () => {
+    it.todo(
+      'extensionManager.injectStyles(css) appends a scoped <style> element to document.head'
+    )
+    it.todo(
+      'styles injected via injectStyles() are automatically removed when the extension is unregistered'
+    )
+    it.todo(
+      'multiple calls to injectStyles() do not create duplicate <style> tags for the same content'
+    )
+    it.todo(
+      'injectStyles() returns a cleanup handle; calling it removes the style tag'
+    )
+  })
+
+  describe('addPanel(opts) — managed panel injection', () => {
+    it.todo(
+      'extension.addPanel({ id, render }) mounts a panel into the host-managed panel container'
+    )
+    it.todo(
+      'panel mounted via addPanel() is accessible via document.getElementById(opts.id)'
+    )
+    it.todo(
+      'panel is unmounted when the extension scope is disposed'
+    )
+  })
+
+  describe('addToolbarItem(opts) — toolbar registration', () => {
+    it.todo(
+      'extension.addToolbarItem({ id, icon, tooltip, action }) appends an item to the ComfyUI toolbar'
+    )
+    it.todo(
+      'clicking the toolbar item invokes opts.action with the correct context'
+    )
+    it.todo(
+      'toolbar item is removed when the extension scope is disposed'
+    )
+  })
+
+  describe('safe HTML rendering', () => {
+    it.todo(
+      'v2 HTML rendering API sanitizes content before insertion (no raw innerHTML path)'
+    )
+    it.todo(
+      'safe rendering API accepts a Vue component as an alternative to raw HTML'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-32.migration.test.ts b/src/extension-api-v2/__tests__/bc-32.migration.test.ts
new file mode 100644
index 0000000000..81a102b623
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-32.migration.test.ts
@@ -0,0 +1,44 @@
+// Category: BC.32 — Embedded framework runtimes and Vue widget bundling
+// DB cross-ref: S16.VUE1
+// Exemplar: ComfyUI-NKD-Sigmas-Curve (aggregate — Notion API research §2.9)
+// Migration: v1 standalone createApp(Component).mount(el) → v2 registerVueWidget(nodeType, name, Component)
+
+import { describe, it } from 'vitest'
+
+describe('BC.32 migration — embedded framework runtimes and Vue widget bundling', () => {
+  describe('rendering equivalence', () => {
+    it.todo(
+      'Component renders equivalent visible output whether mounted via v1 createApp().mount() or v2 registerVueWidget()'
+    )
+    it.todo(
+      'Component props passed via v2 registerVueWidget() are accessible in the same way as v1 createApp() props'
+    )
+  })
+
+  describe('shared host access (v2 gain)', () => {
+    it.todo(
+      'v2 registered Component can read host i18n locale; v1 standalone app cannot without importing its own i18n instance'
+    )
+    it.todo(
+      'v2 registered Component can read Pinia store state; v1 standalone app sees an isolated Pinia instance'
+    )
+  })
+
+  describe('no double-Vue', () => {
+    it.todo(
+      'migrating one extension from createApp().mount() to registerVueWidget() does not load two Vue runtimes simultaneously'
+    )
+    it.todo(
+      'registerVueWidget() reuses the host Vue runtime (same version as host); no version mismatch warnings'
+    )
+  })
+
+  describe('cleanup regression', () => {
+    it.todo(
+      'v1 standalone createApp() is not unmounted on node removal unless extension explicitly handles onRemoved; v2 registerVueWidget() always unmounts on node removal'
+    )
+    it.todo(
+      'migrating to v2 eliminates the memory leak present in v1 when nodes are removed without explicit unmount'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-32.v1.test.ts b/src/extension-api-v2/__tests__/bc-32.v1.test.ts
new file mode 100644
index 0000000000..c5bf424943
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-32.v1.test.ts
@@ -0,0 +1,35 @@
+// Category: BC.32 — Embedded framework runtimes and Vue widget bundling
+// DB cross-ref: S16.VUE1
+// Exemplar: ComfyUI-NKD-Sigmas-Curve (aggregate — Notion API research §2.9)
+// Occurrence signal: 9 packages confirmed bundling their own Vue instance (Notion 2026-05-08)
+
+import { describe, it } from 'vitest'
+
+describe('BC.32 v1 contract — embedded framework runtimes and Vue widget bundling', () => {
+  describe('S16.VUE1 — extension bundles its own Vue createApp instance', () => {
+    it.todo(
+      'extension can call createApp(Component).mount(el) inside a DOM widget element'
+    )
+    it.todo(
+      'the mounted Vue app is isolated from the host app (no shared provide/inject)'
+    )
+    it.todo(
+      "extension's bundled Vue instance does not have access to host app's i18n plugin"
+    )
+    it.todo(
+      "extension's bundled Vue instance does not have access to host app's Pinia stores"
+    )
+    it.todo(
+      "extension's bundled Vue instance does not receive host app's theme/CSS variables by default"
+    )
+  })
+
+  describe('isolation hazards', () => {
+    it.todo(
+      'two extensions each bundling Vue do not conflict with each other at runtime'
+    )
+    it.todo(
+      "extension's bundled Vue app survives node removal without explicit unmount call (memory leak baseline)"
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-32.v2.test.ts b/src/extension-api-v2/__tests__/bc-32.v2.test.ts
new file mode 100644
index 0000000000..b2f0ff0ebf
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-32.v2.test.ts
@@ -0,0 +1,47 @@
+// Category: BC.32 — Embedded framework runtimes and Vue widget bundling
+// DB cross-ref: S16.VUE1
+// Exemplar: ComfyUI-NKD-Sigmas-Curve (aggregate — Notion API research §2.9)
+// v2 replacement: extension.registerVueWidget(nodeType, name, Component) — shares host Vue instance
+
+import { describe, it } from 'vitest'
+
+describe('BC.32 v2 contract — embedded framework runtimes and Vue widget bundling', () => {
+  describe('registerVueWidget(nodeType, name, Component) — shared host Vue instance', () => {
+    it.todo(
+      'extension.registerVueWidget(nodeType, name, Component) mounts Component inside the host Vue app instance'
+    )
+    it.todo(
+      'Component mounted via registerVueWidget has access to host i18n plugin'
+    )
+    it.todo(
+      'Component mounted via registerVueWidget has access to Pinia stores via useStore()'
+    )
+    it.todo(
+      'Component mounted via registerVueWidget receives host CSS custom properties (theme variables)'
+    )
+    it.todo(
+      'two extensions registering different widgets both mount under the same host app instance'
+    )
+  })
+
+  describe('lifecycle management', () => {
+    it.todo(
+      'widget Component is unmounted when the associated node is removed'
+    )
+    it.todo(
+      'widget Component is unmounted when the extension scope is disposed'
+    )
+    it.todo(
+      'unmounting the widget does not trigger host app teardown'
+    )
+  })
+
+  describe('composable access within registered widget', () => {
+    it.todo(
+      'useNodeSize() composable is accessible inside a Component registered via registerVueWidget'
+    )
+    it.todo(
+      'useWidgetValue() composable is accessible inside a Component registered via registerVueWidget'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-33.migration.test.ts b/src/extension-api-v2/__tests__/bc-33.migration.test.ts
new file mode 100644
index 0000000000..cc70c545fd
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-33.migration.test.ts
@@ -0,0 +1,34 @@
+// Category: BC.33 — Cross-extension DOM widget creation observation
+// DB cross-ref: S4.W6
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — migration is from workaround to new first-class event)
+// migration: MutationObserver / polling workaround → comfyApp.on('domWidgetCreated', handler)
+
+import { describe, it } from 'vitest'
+
+describe('BC.33 migration — cross-extension DOM widget creation observation', () => {
+  describe('MutationObserver workaround replacement', () => {
+    it.todo(
+      "MutationObserver on document.body for widget detection is replaced by comfyApp.on('domWidgetCreated', ...)"
+    )
+    it.todo(
+      "the v2 domWidgetCreated handler fires synchronously after widget construction, before the DOM is mutated"
+    )
+  })
+
+  describe('polling workaround replacement', () => {
+    it.todo(
+      'setInterval polling on node.widgets can be removed when migrating to the domWidgetCreated event'
+    )
+    it.todo(
+      'v2 event fires once per widget creation; no deduplication logic needed in the handler'
+    )
+  })
+
+  describe('no compat shim required', () => {
+    it.todo(
+      'there is no v1 hook to shim — extensions must opt-in to domWidgetCreated explicitly in v2'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-33.v1.test.ts b/src/extension-api-v2/__tests__/bc-33.v1.test.ts
new file mode 100644
index 0000000000..186a5b8049
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-33.v1.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.33 — Cross-extension DOM widget creation observation
+// DB cross-ref: S4.W6
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — no stable v1 hook exists)
+// v1 contract: no stable hook — workaround is MutationObserver on document or polling node.widgets
+
+import { describe, it } from 'vitest'
+
+describe('BC.33 v1 contract — cross-extension DOM widget creation observation', () => {
+  describe('S4.W6 — MutationObserver workaround', () => {
+    it.todo(
+      'extension can observe document.body with MutationObserver to detect newly added DOM widget elements'
+    )
+    it.todo(
+      'extension can poll node.widgets on an interval to detect DOM widgets added by another extension'
+    )
+    it.todo(
+      'MutationObserver approach fires for DOM changes regardless of whether they are ComfyUI widgets'
+    )
+  })
+
+  describe('S4.W6 — absence of stable hook', () => {
+    it.todo(
+      'no app.on or app.registerExtension hook reliably fires when a DOM widget is created by a third-party extension'
+    )
+    it.todo(
+      'nodeCreated fires before DOM widgets are appended, so widget list is empty at that point'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-33.v2.test.ts b/src/extension-api-v2/__tests__/bc-33.v2.test.ts
new file mode 100644
index 0000000000..1475d20c64
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-33.v2.test.ts
@@ -0,0 +1,32 @@
+// Category: BC.33 — Cross-extension DOM widget creation observation
+// DB cross-ref: S4.W6
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — this is a new v2 API surface)
+// v2 contract: comfyApp.on('domWidgetCreated', (widgetHandle) => { ... })
+//              fires for every DOM widget created by any extension
+
+import { describe, it } from 'vitest'
+
+describe('BC.33 v2 contract — cross-extension DOM widget creation observation', () => {
+  describe('S4.W6 — domWidgetCreated event', () => {
+    it.todo(
+      "comfyApp.on('domWidgetCreated', handler) registers a listener that fires for every DOM widget created"
+    )
+    it.todo(
+      'handler receives a WidgetHandle with type, name, and owning NodeHandle accessible'
+    )
+    it.todo(
+      'domWidgetCreated fires for widgets created by other extensions, not just the registering extension'
+    )
+    it.todo(
+      'listener registered before any node is created receives events for all subsequently created DOM widgets'
+    )
+  })
+
+  describe('S4.W6 — handler cleanup', () => {
+    it.todo(
+      "comfyApp.off('domWidgetCreated', handler) unregisters the listener without affecting other listeners"
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-34.migration.test.ts b/src/extension-api-v2/__tests__/bc-34.migration.test.ts
new file mode 100644
index 0000000000..23da72cf26
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-34.migration.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.34 — Settings-panel custom dialog integration
+// DB cross-ref: S12.UI3
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — migration from DOM workaround to first-class dialog API)
+// migration: innerHTML injection into #comfy-settings-dialog → comfyApp.settings.registerDialog()
+
+import { describe, it } from 'vitest'
+
+describe('BC.34 migration — settings-panel custom dialog integration', () => {
+  describe('innerHTML injection replacement', () => {
+    it.todo(
+      "document.getElementById('comfy-settings-dialog').innerHTML += is replaced by comfyApp.settings.registerDialog()"
+    )
+    it.todo(
+      'raw HTML string dialog content must be converted to a Vue single-file component before migration'
+    )
+    it.todo(
+      'event listeners attached via onclick= in injected HTML must be converted to Vue component methods'
+    )
+  })
+
+  describe('lifecycle correctness', () => {
+    it.todo(
+      'v2 registerDialog is called once during extension setup(), not on each settings-panel open'
+    )
+    it.todo(
+      'v2 dialog component is stable across settings panel re-renders; no re-injection needed'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-34.v1.test.ts b/src/extension-api-v2/__tests__/bc-34.v1.test.ts
new file mode 100644
index 0000000000..3cc7c2c815
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-34.v1.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.34 — Settings-panel custom dialog integration
+// DB cross-ref: S12.UI3
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — no v1 hook; workaround is raw DOM injection)
+// v1 contract: no hook — workaround is document.getElementById('comfy-settings-dialog').innerHTML += ...
+
+import { describe, it } from 'vitest'
+
+describe('BC.34 v1 contract — settings-panel custom dialog integration', () => {
+  describe('S12.UI3 — innerHTML injection workaround', () => {
+    it.todo(
+      "extension can locate the settings dialog via document.getElementById('comfy-settings-dialog')"
+    )
+    it.todo(
+      'extension can inject a button via innerHTML += that opens a custom modal when clicked'
+    )
+    it.todo(
+      'innerHTML injection persists across settings panel open/close cycles only if the element is not re-rendered'
+    )
+  })
+
+  describe('S12.UI3 — absence of stable hook', () => {
+    it.todo(
+      'no registerExtension lifecycle hook fires when the settings panel is opened'
+    )
+    it.todo(
+      'innerHTML injection breaks when ComfyUI re-renders the settings panel, removing the injected content'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-34.v2.test.ts b/src/extension-api-v2/__tests__/bc-34.v2.test.ts
new file mode 100644
index 0000000000..1843c185c0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-34.v2.test.ts
@@ -0,0 +1,34 @@
+// Category: BC.34 — Settings-panel custom dialog integration
+// DB cross-ref: S12.UI3
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — new v2 API surface)
+// v2 contract: comfyApp.settings.registerDialog({ id, label, component: MyVueComponent })
+
+import { describe, it } from 'vitest'
+
+describe('BC.34 v2 contract — settings-panel custom dialog integration', () => {
+  describe('S12.UI3 — registerDialog API', () => {
+    it.todo(
+      'comfyApp.settings.registerDialog({ id, label, component }) adds a trigger entry to the settings panel'
+    )
+    it.todo(
+      'clicking the settings entry opens the Vue component as a modal dialog managed by ComfyUI'
+    )
+    it.todo(
+      'dialog component receives a close() callback prop it can call to dismiss the modal'
+    )
+    it.todo(
+      'multiple extensions registering dialogs each get independent entries in the settings panel'
+    )
+  })
+
+  describe('S12.UI3 — settings entry type "dialog-trigger" alternative', () => {
+    it.todo(
+      "settings entry with type: 'dialog-trigger' and component property renders a button that opens the component"
+    )
+    it.todo(
+      'the dialog component is lazily mounted only when the trigger is clicked, not at registration time'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-35.migration.test.ts b/src/extension-api-v2/__tests__/bc-35.migration.test.ts
new file mode 100644
index 0000000000..2485fee0b0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-35.migration.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.35 — Pre-queue widget validation
+// DB cross-ref: S6.A5
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 3.10
+// compat-floor: blast_radius ≥ 2.0
+// migration: app.queuePrompt monkey-patch → comfyApp.on('beforeQueue', event => event.reject(...))
+
+import { describe, it } from 'vitest'
+
+describe('BC.35 migration — pre-queue widget validation', () => {
+  describe('queuePrompt monkey-patch replacement', () => {
+    it.todo(
+      "app.queuePrompt wrapper that throws is replaced by comfyApp.on('beforeQueue', (event) => event.reject(msg))"
+    )
+    it.todo(
+      "v2 compat shim detects monkey-patched app.queuePrompt and wraps the patch logic as a beforeQueue handler"
+    )
+    it.todo(
+      'extensions that previously chain-called the original queuePrompt can remove that pattern entirely in v2'
+    )
+  })
+
+  describe('error surfacing improvement', () => {
+    it.todo(
+      'v1 console-only errors are replaced by v2 UI-visible rejection messages via event.reject()'
+    )
+    it.todo(
+      'multiple v1 patchers that silently overwrote each other are now independently stackable via beforeQueue'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-35.v1.test.ts b/src/extension-api-v2/__tests__/bc-35.v1.test.ts
new file mode 100644
index 0000000000..d41cd40724
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-35.v1.test.ts
@@ -0,0 +1,35 @@
+// Category: BC.35 — Pre-queue widget validation
+// DB cross-ref: S6.A5
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 3.10
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: monkey-patch app.queuePrompt and throw or return early if validation fails
+//              (breaks other queuePrompt patchers — silent_breakage=true)
+
+import { describe, it } from 'vitest'
+
+describe('BC.35 v1 contract — pre-queue widget validation', () => {
+  describe('S6.A5 — queuePrompt monkey-patching', () => {
+    it.todo(
+      'extension can replace app.queuePrompt with a wrapper that inspects widget values before delegating'
+    )
+    it.todo(
+      'throwing inside the monkey-patched queuePrompt prevents the workflow from being submitted'
+    )
+    it.todo(
+      'returning early (undefined) inside the monkey-patched queuePrompt also cancels submission'
+    )
+    it.todo(
+      'two extensions both monkey-patching app.queuePrompt result in only the last patcher running (silent breakage)'
+    )
+  })
+
+  describe('S6.A5 — error surfacing limitations', () => {
+    it.todo(
+      'a thrown error in the monkey-patched queuePrompt is not displayed in the ComfyUI UI — it lands in the console only'
+    )
+    it.todo(
+      'there is no standard mechanism in v1 to surface a validation error message to the user from queuePrompt'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-35.v2.test.ts b/src/extension-api-v2/__tests__/bc-35.v2.test.ts
new file mode 100644
index 0000000000..ced91f86d7
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-35.v2.test.ts
@@ -0,0 +1,35 @@
+// Category: BC.35 — Pre-queue widget validation
+// DB cross-ref: S6.A5
+// Exemplar: https://github.com/goodtab/ComfyUI-Custom-Scripts
+// blast_radius: 3.10
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: comfyApp.on('beforeQueue', (event) => { if (!valid) event.reject('Error message') })
+//              stackable; rejection surfaced in UI
+
+import { describe, it } from 'vitest'
+
+describe('BC.35 v2 contract — pre-queue widget validation', () => {
+  describe('S6.A5 — beforeQueue event', () => {
+    it.todo(
+      "comfyApp.on('beforeQueue', handler) registers a validation listener that fires before each queue submission"
+    )
+    it.todo(
+      "calling event.reject('message') cancels queue submission and displays the message in the ComfyUI UI"
+    )
+    it.todo(
+      'multiple extensions registering beforeQueue handlers are all called; any rejection cancels the queue'
+    )
+    it.todo(
+      'event.reject() called with no arguments cancels the queue without displaying a message'
+    )
+  })
+
+  describe('S6.A5 — event payload', () => {
+    it.todo(
+      'beforeQueue event payload includes the serialized prompt so validators can inspect all node values'
+    )
+    it.todo(
+      'event.reject() called asynchronously (from an async handler) still cancels submission correctly'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-36.migration.test.ts b/src/extension-api-v2/__tests__/bc-36.migration.test.ts
new file mode 100644
index 0000000000..4e19a4712b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-36.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.36 — PrimeVue widget component API surface
+// DB cross-ref: S4.W1, S4.W4, S4.W5
+// Exemplar: none (new API surface)
+// blast_radius: 3.80
+// compat-floor: blast_radius ≥ 2.0
+// migration: widget.options.* direct mutation → WidgetHandle.setOptions<T>() typed per-component subsets
+
+import { describe, it } from 'vitest'
+
+describe('BC.36 migration — PrimeVue widget component API surface', () => {
+  describe('options bag to setOptions migration', () => {
+    it.todo(
+      'widget.options.values = [...] is replaced by WidgetHandle.setOptions<SelectOptions>({ values: [...] })'
+    )
+    it.todo(
+      'widget.options.min / .max / .step are replaced by WidgetHandle.setOptions<SliderOptions>({ min, max, step })'
+    )
+    it.todo(
+      'v2 compat shim intercepts widget.options writes and forwards them to setOptions with a deprecation warning'
+    )
+  })
+
+  describe('disabled/readonly migration', () => {
+    it.todo(
+      'widget.options.disabled = true is replaced by WidgetHandle.setDisabled(true)'
+    )
+    it.todo(
+      'widget.options.readonly = true is replaced by WidgetHandle.setReadOnly(true)'
+    )
+  })
+
+  describe('exclusion rule enforcement', () => {
+    it.todo(
+      'v1 style/class/pt options written via widget.options are silently dropped by the v2 compat shim'
+    )
+    it.todo(
+      'v2 setOptions<T>() TypeScript overloads prevent style/class/pt from being passed at compile time'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-36.v1.test.ts b/src/extension-api-v2/__tests__/bc-36.v1.test.ts
new file mode 100644
index 0000000000..6f456c5dc2
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-36.v1.test.ts
@@ -0,0 +1,41 @@
+// Category: BC.36 — PrimeVue widget component API surface
+// DB cross-ref: S4.W1, S4.W4, S4.W5
+// Exemplar: none (new API surface)
+// blast_radius: 3.80
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: widget.options.values = [...], widget.options.min = 0, widget.options.max = 100
+//              (direct mutation of options bag)
+
+import { describe, it } from 'vitest'
+
+describe('BC.36 v1 contract — PrimeVue widget component API surface', () => {
+  describe('S4.W1 — options bag direct mutation (select/combo)', () => {
+    it.todo(
+      'widget.options.values = [...] replaces the dropdown choices on a COMBO widget at runtime'
+    )
+    it.todo(
+      'widget.options.values mutation takes effect immediately on the next render without triggering a callback'
+    )
+    it.todo(
+      'setting widget.options.values to an empty array renders an empty dropdown without error'
+    )
+  })
+
+  describe('S4.W4 — options bag direct mutation (number/slider)', () => {
+    it.todo(
+      'widget.options.min and widget.options.max constrain the slider range when set directly'
+    )
+    it.todo(
+      'widget.options.step controls the increment of a number widget when set on options directly'
+    )
+  })
+
+  describe('S4.W5 — disabled / readonly via options bag', () => {
+    it.todo(
+      'widget.options.disabled = true disables the widget control in v1 options-bag approach'
+    )
+    it.todo(
+      'widget.options.readonly = true makes the widget read-only without affecting its value'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-36.v2.test.ts b/src/extension-api-v2/__tests__/bc-36.v2.test.ts
new file mode 100644
index 0000000000..0e392452e3
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-36.v2.test.ts
@@ -0,0 +1,48 @@
+// Category: BC.36 — PrimeVue widget component API surface
+// DB cross-ref: S4.W1, S4.W4, S4.W5
+// Exemplar: none (new API surface)
+// blast_radius: 3.80
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: typed WidgetHandle.setOptions<SliderOptions>({ min, max, step })
+//              15 PrimeVue components: Button, InputText, Select, ColorPicker, MultiSelect,
+//              SelectButton, Slider, Textarea, ToggleSwitch, Chart, Image, ImageCompare,
+//              Galleria, FileUpload, TreeSelect
+//              Exclusion rule: strip style/class/dt/pt/*Class/*Style
+//              disabled/readonly map to D7 first-class fields, not options bag
+
+import { describe, it } from 'vitest'
+
+describe('BC.36 v2 contract — PrimeVue widget component API surface', () => {
+  describe('S4.W1 — Select/MultiSelect/SelectButton options', () => {
+    it.todo(
+      'WidgetHandle.setOptions<SelectOptions>({ values: [...] }) replaces the dropdown choices'
+    )
+    it.todo(
+      'setOptions on a Select widget accepts only the Pick<> subset defined for that component (no style/class/pt)'
+    )
+    it.todo(
+      'passing an unknown option key to setOptions throws a TypeScript compile-time error'
+    )
+  })
+
+  describe('S4.W4 — Slider options', () => {
+    it.todo(
+      'WidgetHandle.setOptions<SliderOptions>({ min, max, step }) updates slider bounds reactively'
+    )
+    it.todo(
+      'setOptions on a Slider widget rejects style/class/pt keys per the exclusion rule'
+    )
+  })
+
+  describe('S4.W5 — disabled / readonly as D7 first-class fields', () => {
+    it.todo(
+      'WidgetHandle.setDisabled(true) is the v2 replacement for widget.options.disabled = true'
+    )
+    it.todo(
+      'WidgetHandle.setReadOnly(true) is the v2 replacement for widget.options.readonly = true'
+    )
+    it.todo(
+      'disabled and readonly are NOT accepted as keys inside setOptions<T>() — they are separate methods'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-37.migration.test.ts b/src/extension-api-v2/__tests__/bc-37.migration.test.ts
new file mode 100644
index 0000000000..c25f0af672
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-37.migration.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.37 — VueNode bridge timing — deferred mount access
+// DB cross-ref: S4.W5
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/load3d.ts
+// blast_radius: 3.20
+// compat-floor: blast_radius ≥ 2.0
+// migration: waitForLoad3d polling pattern → NodeHandle.on('mounted', callback)
+
+import { describe, it } from 'vitest'
+
+describe('BC.37 migration — VueNode bridge timing (deferred mount access)', () => {
+  describe('waitForLoad3d replacement', () => {
+    it.todo(
+      "waitForLoad3d(node, callback) is replaced by NodeHandle.on('mounted', callback) in v2"
+    )
+    it.todo(
+      "v2 'mounted' fires via event system rather than polling; no setTimeout or setInterval needed"
+    )
+    it.todo(
+      'v2 compat shim provides waitForLoad3d as a thin wrapper around NodeHandle.on(mounted) with a deprecation warning'
+    )
+  })
+
+  describe('timing contract at nodeCreated', () => {
+    it.todo(
+      "code that previously ran in nodeCreated and expected DOM to be ready must move into the 'mounted' handler"
+    )
+    it.todo(
+      'LiteGraph-side widget properties (value, callback, name) remain safe to read in nodeCreated without waiting'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-37.v1.test.ts b/src/extension-api-v2/__tests__/bc-37.v1.test.ts
new file mode 100644
index 0000000000..759cacb746
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-37.v1.test.ts
@@ -0,0 +1,36 @@
+// Category: BC.37 — VueNode bridge timing — deferred mount access
+// DB cross-ref: S4.W5
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/load3d.ts
+// blast_radius: 3.20
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: waitForLoad3d(node, callback) — deferred init pattern
+//              nodeCreated fires before Vue component mounts; DOM widget value/callback/name are
+//              LiteGraph-side only at nodeCreated time
+
+import { describe, it } from 'vitest'
+
+describe('BC.37 v1 contract — VueNode bridge timing (deferred mount access)', () => {
+  describe('S4.W5 — nodeCreated timing vs Vue mount', () => {
+    it.todo(
+      'nodeCreated fires synchronously when the LiteGraph node is constructed, before any Vue component mounts'
+    )
+    it.todo(
+      'accessing a Three.js renderer or DOM widget DOM element inside nodeCreated returns null'
+    )
+    it.todo(
+      'ComponentWidgetImpl value and callback are available at nodeCreated, but Vue props/emits are not'
+    )
+  })
+
+  describe('S4.W5 — waitForLoad3d deferred init pattern', () => {
+    it.todo(
+      'waitForLoad3d(node, callback) polls until the VueNode component is mounted, then calls callback'
+    )
+    it.todo(
+      'callback receives a stable reference to the mounted Vue component instance'
+    )
+    it.todo(
+      'if the node is removed before mount completes, waitForLoad3d does not invoke the callback'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-37.v2.test.ts b/src/extension-api-v2/__tests__/bc-37.v2.test.ts
new file mode 100644
index 0000000000..6ac122ea74
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-37.v2.test.ts
@@ -0,0 +1,34 @@
+// Category: BC.37 — VueNode bridge timing — deferred mount access
+// DB cross-ref: S4.W5
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/extensions/core/load3d.ts
+// blast_radius: 3.20
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: NodeHandle.on('mounted', () => { /* safe to access VueNode state */ })
+
+import { describe, it } from 'vitest'
+
+describe('BC.37 v2 contract — VueNode bridge timing (deferred mount access)', () => {
+  describe("S4.W5 — NodeHandle.on('mounted') hook", () => {
+    it.todo(
+      "NodeHandle.on('mounted', callback) fires after the Vue component backing the node has mounted"
+    )
+    it.todo(
+      "accessing VueNode state inside the 'mounted' callback returns initialized values, not null"
+    )
+    it.todo(
+      "'mounted' fires exactly once per node creation, even if the canvas re-renders"
+    )
+    it.todo(
+      "if the node is destroyed before mounting, the 'mounted' callback is never called"
+    )
+  })
+
+  describe('S4.W5 — ComponentWidgetImpl dual-identity in v2', () => {
+    it.todo(
+      'WidgetHandle exposes LiteGraph-side properties (value, name) before mounted fires'
+    )
+    it.todo(
+      "Vue-side props and component ref are only safe to access after the 'mounted' event"
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-38.migration.test.ts b/src/extension-api-v2/__tests__/bc-38.migration.test.ts
new file mode 100644
index 0000000000..d0bc43fe9f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-38.migration.test.ts
@@ -0,0 +1,34 @@
+// Category: BC.38 — Canvas mode observation
+// DB cross-ref: S17.AM1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — migration from broken workarounds to proposed v2 event)
+// migration: polling / heuristics → comfyApp.on('canvasModeChanged', handler)
+
+import { describe, it } from 'vitest'
+
+describe('BC.38 migration — canvas mode observation', () => {
+  describe('polling replacement', () => {
+    it.todo(
+      "setInterval polling on app.canvas.mode is replaced by comfyApp.on('canvasModeChanged', ...)"
+    )
+    it.todo(
+      'v2 event-based approach removes the need to track previous mode to detect transitions'
+    )
+  })
+
+  describe('heuristic replacement', () => {
+    it.todo(
+      "DOM-class heuristics used to infer canvas mode should be deleted in favor of comfyApp.on('canvasModeChanged')"
+    )
+    it.todo(
+      'extensions that imported appModeStore directly must switch to the event API to remain JS-extension-compatible'
+    )
+  })
+
+  describe('no compat shim available', () => {
+    it.todo(
+      'there is no v1 hook to shim — extensions must explicitly opt in to canvasModeChanged when v2 ships'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-38.v1.test.ts b/src/extension-api-v2/__tests__/bc-38.v1.test.ts
new file mode 100644
index 0000000000..be20a45830
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-38.v1.test.ts
@@ -0,0 +1,36 @@
+// Category: BC.38 — Canvas mode observation
+// DB cross-ref: S17.AM1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — no stable v1 API exists)
+// v1 contract: no API — must poll app.canvas.mode or use heuristics (broken)
+// Note: appModeStore is a Pinia composable; JS extensions cannot use Vue composables directly.
+//       DISTINCT from NodeModeChangedEvent (execution mode: muted/bypass/always/once/trigger).
+
+import { describe, it } from 'vitest'
+
+describe('BC.38 v1 contract — canvas mode observation', () => {
+  describe('S17.AM1 — polling workaround', () => {
+    it.todo(
+      'extension can read app.canvas.mode synchronously to determine the current canvas mode'
+    )
+    it.todo(
+      'polling app.canvas.mode on an interval detects transitions between graph/app/builder modes'
+    )
+    it.todo(
+      'heuristic-based mode detection (checking DOM classes or element visibility) is fragile and breaks on UI changes'
+    )
+  })
+
+  describe('S17.AM1 — absence of stable hook', () => {
+    it.todo(
+      'no app.on or registerExtension hook fires when canvas mode changes'
+    )
+    it.todo(
+      'NodeModeChangedEvent is distinct from canvas mode change and must not be used as a proxy'
+    )
+    it.todo(
+      'JS extensions cannot import appModeStore from Vue composable layer — import throws at runtime'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-38.v2.test.ts b/src/extension-api-v2/__tests__/bc-38.v2.test.ts
new file mode 100644
index 0000000000..c5224f5b36
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-38.v2.test.ts
@@ -0,0 +1,35 @@
+// Category: BC.38 — Canvas mode observation
+// DB cross-ref: S17.AM1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — proposed new v2 API, not yet implemented)
+// v2 contract: comfyApp.on('canvasModeChanged', (mode) => { ... }) — proposed, not yet implemented
+// Flagged: Terry DX walkthrough A.1
+
+import { describe, it } from 'vitest'
+
+describe('BC.38 v2 contract — canvas mode observation', () => {
+  describe('S17.AM1 — canvasModeChanged event', () => {
+    it.todo(
+      "comfyApp.on('canvasModeChanged', handler) registers a listener for mode transitions"
+    )
+    it.todo(
+      "handler receives a mode string typed as 'graph' | 'app' | 'builder:inputs' | 'builder:outputs' | 'builder:arrange'"
+    )
+    it.todo(
+      'canvasModeChanged fires synchronously when the mode store transitions, before the UI re-renders'
+    )
+    it.todo(
+      "comfyApp.off('canvasModeChanged', handler) correctly unregisters the listener"
+    )
+  })
+
+  describe('S17.AM1 — current mode access', () => {
+    it.todo(
+      'comfyApp.canvas.mode returns the current canvas mode string without needing to subscribe'
+    )
+    it.todo(
+      'canvasModeChanged event is DISTINCT from NodeModeChangedEvent — node execution mode changes do not fire it'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-39.migration.test.ts b/src/extension-api-v2/__tests__/bc-39.migration.test.ts
new file mode 100644
index 0000000000..5e3bceb812
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-39.migration.test.ts
@@ -0,0 +1,31 @@
+// Category: BC.39 — Subgraph boundary event propagation
+// DB cross-ref: S17.SB1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API, blocked on D9 Phase B / I-PG.B1)
+// migration: no v1 fix available — subgraphCompatible: true opts extensions into v2 propagation
+
+import { describe, it } from 'vitest'
+
+describe('BC.39 migration — subgraph boundary event propagation', () => {
+  describe('opt-in migration path', () => {
+    it.todo(
+      'extensions add subgraphCompatible: true to their defineNodeExtension call to enable boundary propagation'
+    )
+    it.todo(
+      'extensions without subgraphCompatible: true continue to exhibit v1 broken behavior — no silent upgrade'
+    )
+    it.todo(
+      'the migration guide documents all four failure modes and the subgraphCompatible fix for each'
+    )
+  })
+
+  describe('blocked status', () => {
+    it.todo(
+      'subgraphCompatible: true has no effect until D9 Phase B is merged (blocked on I-PG.B1 Alex rebase)'
+    )
+    it.todo(
+      'test suite for BC.39 is expected to remain all-todo until I-PG.B1 unblocks'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-39.v1.test.ts b/src/extension-api-v2/__tests__/bc-39.v1.test.ts
new file mode 100644
index 0000000000..bae72eaec6
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-39.v1.test.ts
@@ -0,0 +1,47 @@
+// Category: BC.39 — Subgraph boundary event propagation
+// DB cross-ref: S17.SB1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API, blocked — requires D9 Phase B post-Alex rebase on #11939)
+// v1 contract: broken — callbacks fire on internal node, not visible to external observers
+// Blocked: I-PG.B1
+
+import { describe, it } from 'vitest'
+
+describe('BC.39 v1 contract — subgraph boundary event propagation', () => {
+  describe('failure mode 1 — onExecuted not re-emitted by SubgraphNode', () => {
+    it.todo(
+      'onExecuted fires on the internal custom node when execution completes inside a subgraph'
+    )
+    it.todo(
+      'onExecuted does NOT fire on the outer SubgraphNode; external observers cannot detect inner execution'
+    )
+  })
+
+  describe('failure mode 2 — MatchType freezes type at boundary', () => {
+    it.todo(
+      'MatchType on an internal node resolves the type correctly for intra-subgraph connections'
+    )
+    it.todo(
+      'MatchType at the subgraph boundary uses the promoted slot type, ignoring internal MatchType resolution'
+    )
+  })
+
+  describe('failure mode 3 — autogrow not mirrored to SubgraphNode slots', () => {
+    it.todo(
+      'onConnectionsChange autogrow adds slots to the internal node correctly'
+    )
+    it.todo(
+      'autogrow-added slots are NOT mirrored to the SubgraphNode boundary, so external wiring is impossible'
+    )
+  })
+
+  describe('failure mode 4 — widget promotion callbacks fire on internal node only', () => {
+    it.todo(
+      'a promoted widget callback fires on the internal node instance, not the SubgraphNode'
+    )
+    it.todo(
+      'external code subscribing to the SubgraphNode widget value never receives promoted widget callbacks'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-39.v2.test.ts b/src/extension-api-v2/__tests__/bc-39.v2.test.ts
new file mode 100644
index 0000000000..8d981c49b5
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-39.v2.test.ts
@@ -0,0 +1,56 @@
+// Category: BC.39 — Subgraph boundary event propagation
+// DB cross-ref: S17.SB1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API, blocked — requires D9 Phase B post-Alex rebase on #11939)
+// v2 contract: proposed subgraphCompatible: true flag in NodeExtensionOptions;
+//              SubgraphNode must forward execution events
+
+import { describe, it } from 'vitest'
+
+describe('BC.39 v2 contract — subgraph boundary event propagation', () => {
+  describe('subgraphCompatible flag', () => {
+    it.todo(
+      'defineNodeExtension({ subgraphCompatible: true }) opts the node into boundary propagation'
+    )
+    it.todo(
+      'nodes without subgraphCompatible: true retain v1 behavior (fire on internal node only)'
+    )
+  })
+
+  describe('failure mode 1 — onExecuted forwarding', () => {
+    it.todo(
+      'when subgraphCompatible: true, SubgraphNode re-emits onExecuted after the internal node fires'
+    )
+    it.todo(
+      'external observers subscribing to SubgraphNode onExecuted receive the forwarded event payload'
+    )
+  })
+
+  describe('failure mode 2 — MatchType at boundary', () => {
+    it.todo(
+      'when subgraphCompatible: true, MatchType resolution propagates through the subgraph boundary'
+    )
+    it.todo(
+      'the SubgraphNode slot type reflects the resolved inner MatchType, not the promoted static type'
+    )
+  })
+
+  describe('failure mode 3 — autogrow mirroring', () => {
+    it.todo(
+      'when subgraphCompatible: true, slots added via onConnectionsChange autogrow are mirrored to the SubgraphNode boundary'
+    )
+    it.todo(
+      'externally wired connections to mirrored autogrow slots are valid and serialize correctly'
+    )
+  })
+
+  describe('failure mode 4 — promoted widget callback forwarding', () => {
+    it.todo(
+      'when subgraphCompatible: true, promoted widget callbacks are forwarded to the SubgraphNode widget'
+    )
+    it.todo(
+      'external code subscribing to the SubgraphNode widget receives callbacks that originated in the internal node'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-40.migration.test.ts b/src/extension-api-v2/__tests__/bc-40.migration.test.ts
new file mode 100644
index 0000000000..a8b80a2b11
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-40.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.40 — File upload and asset URL construction
+// DB cross-ref: S17.FA1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — migration from manual FormData pattern to comfyAPI helpers)
+// migration: manual api.fetchApi('/upload/image') + URL string construction → comfyAPI.uploadFile + getFileUrl
+
+import { describe, it } from 'vitest'
+
+describe('BC.40 migration — file upload and asset URL construction', () => {
+  describe('upload migration', () => {
+    it.todo(
+      "manual FormData construction + api.fetchApi('/upload/image') is replaced by comfyAPI.uploadFile(file, opts)"
+    )
+    it.todo(
+      'extensions with hardcoded 120s timeout should pass an explicit timeout option to comfyAPI.uploadFile'
+    )
+    it.todo(
+      'video upload variants (9 packages) can use the same comfyAPI.uploadFile with type: "video" option'
+    )
+  })
+
+  describe('URL construction migration', () => {
+    it.todo(
+      "manual '/view?filename=...' string assembly is replaced by comfyAPI.getFileUrl(filename, type, subfolder)"
+    )
+    it.todo(
+      'extensions that spread UploadResult directly into getFileUrl reduce URL construction to a single call'
+    )
+  })
+
+  describe('package boundary', () => {
+    it.todo(
+      'comfyAPI.uploadFile and getFileUrl are imported from @comfyorg/comfy-api, not @comfyorg/extension-api'
+    )
+    it.todo(
+      'migration is blocked until @comfyorg/comfy-api package ships; extensions must retain v1 pattern until then'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-40.v1.test.ts b/src/extension-api-v2/__tests__/bc-40.v1.test.ts
new file mode 100644
index 0000000000..19f6e2837e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-40.v1.test.ts
@@ -0,0 +1,38 @@
+// Category: BC.40 — File upload and asset URL construction
+// DB cross-ref: S17.FA1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — out of scope for @comfyorg/extension-api;
+//               belongs in future @comfyorg/comfy-api package)
+// v1 contract: each extension manually builds FormData, calls api.fetchApi('/upload/image', ...),
+//              constructs /view?filename=... URL
+// Note: 32+ packages affected; 9 implement video upload variants.
+//       Upload timeout hardcoded 120s; large 3D/video fail silently. No temp file lifecycle.
+
+import { describe, it } from 'vitest'
+
+describe('BC.40 v1 contract — file upload and asset URL construction', () => {
+  describe('S17.FA1 — manual FormData and fetchApi upload', () => {
+    it.todo(
+      'extension constructs a FormData with file, filename, subfolder, and type fields manually'
+    )
+    it.todo(
+      "extension calls api.fetchApi('/upload/image', { method: 'POST', body: formData }) to upload"
+    )
+    it.todo(
+      'upload response JSON contains filename, subfolder, and type fields for URL construction'
+    )
+    it.todo(
+      'upload timeout is hardcoded to 120s; uploads of large 3D or video files silently fail at that limit'
+    )
+  })
+
+  describe('S17.FA1 — manual /view URL construction', () => {
+    it.todo(
+      "extension constructs the retrieval URL as '/view?filename=...&type=...&subfolder=...' from upload response fields"
+    )
+    it.todo(
+      '32+ packages each duplicate this URL construction pattern with slight variations, causing inconsistencies'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-40.v2.test.ts b/src/extension-api-v2/__tests__/bc-40.v2.test.ts
new file mode 100644
index 0000000000..57369e7f78
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-40.v2.test.ts
@@ -0,0 +1,37 @@
+// Category: BC.40 — File upload and asset URL construction
+// DB cross-ref: S17.FA1
+// Exemplar: https://www.notion.so/comfy-org/Develop-a-custom-node-from-scratch-pain-point-assessment-33c6d73d365080f49126c0b5affa7559
+// blast_radius: 0.0
+// compat-floor: NO (absent API gap — future @comfyorg/comfy-api package, not @comfyorg/extension-api)
+// v2 contract: comfyAPI.uploadFile(file, { subfolder, type }) + comfyAPI.getFileUrl(filename, type, subfolder)
+
+import { describe, it } from 'vitest'
+
+describe('BC.40 v2 contract — file upload and asset URL construction', () => {
+  describe('S17.FA1 — comfyAPI.uploadFile', () => {
+    it.todo(
+      'comfyAPI.uploadFile(file, { subfolder, type }) returns a promise resolving to UploadResult'
+    )
+    it.todo(
+      'UploadResult contains filename, subfolder, and type fields matching the server response'
+    )
+    it.todo(
+      'comfyAPI.uploadFile accepts an optional timeout option, overriding the hardcoded 120s default'
+    )
+    it.todo(
+      'upload failure (network error or server error) rejects the promise with a typed UploadError'
+    )
+  })
+
+  describe('S17.FA1 — comfyAPI.getFileUrl', () => {
+    it.todo(
+      'comfyAPI.getFileUrl(filename, type, subfolder) returns the canonical /view?... URL string'
+    )
+    it.todo(
+      'getFileUrl with an UploadResult spread produces the same URL as calling it with individual fields'
+    )
+    it.todo(
+      'comfyAPI.getFileUrl is scoped to @comfyorg/comfy-api, not @comfyorg/extension-api'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-41.migration.test.ts b/src/extension-api-v2/__tests__/bc-41.migration.test.ts
new file mode 100644
index 0000000000..35a6132769
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-41.migration.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.41 — Widget values positional serialization fragility
+// DB cross-ref: S17.WV1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/utils/nodeDefOrderingUtil.ts
+// blast_radius: 3.45
+// compat-floor: blast_radius ≥ 2.0
+// migration: node.widgets_values positional array → widgets_values_named opt-in + migrateWidgetValues callback
+
+import { describe, it } from 'vitest'
+
+describe('BC.41 migration — widget values positional serialization fragility', () => {
+  describe('positional to named migration', () => {
+    it.todo(
+      'extension opts in to named dict by setting widgets_values_named: true in node definition'
+    )
+    it.todo(
+      'existing workflow JSONs with positional arrays are handled by the migrateWidgetValues callback during load'
+    )
+    it.todo(
+      'workflows saved after opt-in use named dict format and are not loadable by v1 ComfyUI without migration'
+    )
+  })
+
+  describe('migrateWidgetValues implementation', () => {
+    it.todo(
+      'migrateWidgetValues must convert the positional array to a { widgetName: value } dict using historical input_order'
+    )
+    it.todo(
+      'null guard (PR #11884) prevents migrateWidgetValues from being called with undefined values'
+    )
+  })
+
+  describe('blocked long-term fix', () => {
+    it.todo(
+      'full named dict serialization as the default requires a breaking workflow JSON schema change with versioning'
+    )
+    it.todo(
+      'migration to named dict as default is blocked on workflow-schema-migration work, out of v2 surface scope'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-41.v1.test.ts b/src/extension-api-v2/__tests__/bc-41.v1.test.ts
new file mode 100644
index 0000000000..47f88f6069
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-41.v1.test.ts
@@ -0,0 +1,40 @@
+// Category: BC.41 — Widget values positional serialization fragility
+// DB cross-ref: S17.WV1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/utils/nodeDefOrderingUtil.ts
+// blast_radius: 3.45
+// compat-floor: blast_radius ≥ 2.0
+// v1 contract: node.widgets_values = [v1, v2, v3] positional array;
+//              deserialization uses input_order alignment (only works when input_order defined)
+// Note: Blocked on workflow-schema-migration. PR #10392 added widgets_values_named opt-in;
+//       PR #11884 null guard.
+
+import { describe, it } from 'vitest'
+
+describe('BC.41 v1 contract — widget values positional serialization fragility', () => {
+  describe('S17.WV1 — positional array serialization', () => {
+    it.todo(
+      'node.widgets_values serializes as a positional array [v1, v2, v3] in the workflow JSON'
+    )
+    it.todo(
+      'deserialization assigns values by position using input_order alignment when input_order is defined'
+    )
+    it.todo(
+      'deserialization silently misaligns values when a new input is added before an existing input'
+    )
+    it.todo(
+      'deserialization silently misaligns values when an input is reordered or renamed in the node definition'
+    )
+  })
+
+  describe('S17.WV1 — silent failure modes', () => {
+    it.todo(
+      'adding a new required input at position 0 shifts all subsequent widget values by one with no error'
+    )
+    it.todo(
+      'removing an input from the middle of the definition causes trailing widget values to map to wrong inputs'
+    )
+    it.todo(
+      'changing a required input to optional (or vice versa) changes effective index alignment silently'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/bc-41.v2.test.ts b/src/extension-api-v2/__tests__/bc-41.v2.test.ts
new file mode 100644
index 0000000000..aba201ff74
--- /dev/null
+++ b/src/extension-api-v2/__tests__/bc-41.v2.test.ts
@@ -0,0 +1,46 @@
+// Category: BC.41 — Widget values positional serialization fragility
+// DB cross-ref: S17.WV1
+// Exemplar: https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/utils/nodeDefOrderingUtil.ts
+// blast_radius: 3.45
+// compat-floor: blast_radius ≥ 2.0
+// v2 contract: WidgetHandle identity by name not position; widgets_values_named: { seed: 12345, steps: 30 }
+//              opt-in; migrateWidgetValues(oldVersion, values) callback proposed.
+//              D7 Part 4 (4→2 serialization collapse) + beforeSerialize as partial mitigation.
+// Note: Long-term fix blocked on workflow-schema-migration (breaking JSON schema change requiring versioning).
+
+import { describe, it } from 'vitest'
+
+describe('BC.41 v2 contract — widget values positional serialization fragility', () => {
+  describe('S17.WV1 — named dict opt-in', () => {
+    it.todo(
+      'opting in to widgets_values_named serializes widget values as { widgetName: value } instead of positional array'
+    )
+    it.todo(
+      'named dict deserialization matches values by widget name, surviving input add/remove/reorder'
+    )
+    it.todo(
+      'WidgetHandle identity in v2 is by name, so setOptions and getValue APIs are stable across definition changes'
+    )
+  })
+
+  describe('S17.WV1 — migrateWidgetValues callback', () => {
+    it.todo(
+      'defineNodeExtension({ migrateWidgetValues(oldVersion, values) { ... } }) transforms legacy positional arrays'
+    )
+    it.todo(
+      'migrateWidgetValues receives the raw positional array from old workflow JSON and must return a named dict'
+    )
+    it.todo(
+      'if migrateWidgetValues is not defined, the runtime falls back to positional alignment for backwards compat'
+    )
+  })
+
+  describe('S17.WV1 — D7 partial mitigation', () => {
+    it.todo(
+      'beforeSerialize hook can rewrite widget values before they are serialized, providing a transform layer'
+    )
+    it.todo(
+      'D7 Part 4 (4→2 serialization collapse) reduces the number of widget value positions that can misalign'
+    )
+  })
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.01.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.01.migration.test.ts
new file mode 100644
index 0000000000..a03afc50dd
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.01.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.01 — S2.N1,S2.N8
+// blast_radius: 37.56  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.01 migration — Node lifecycle: creation', () => {
+  it.todo('v1 nodeType.prototype.onNodeCreated fires at the same point in node construction as v2 defineNodeExtension nodeCreated callback')
+  it.todo('v1 extension.nodeCreated receives the same node instance properties as v2 nodeCreated event argument')
+  it.todo('v2 nodeCreated fires once per node instantiation, matching v1 hook invocation count')
+  it.todo('v1 nodeType.prototype.onAdded fires at same graph-attach timing as v2 nodeAdded event')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.02.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.02.migration.test.ts
new file mode 100644
index 0000000000..08ee061e35
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.02.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.02 — S2.N4
+// blast_radius: 29.35  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.02 migration — Node lifecycle: teardown', () => {
+  it.todo('v1 nodeType.prototype.onRemoved fires at the same graph-removal point as v2 defineNodeExtension nodeRemoved callback')
+  it.todo('cleanup registered in v1 onRemoved (removing DOM widgets, clearing intervals) is equivalent to cleanup in v2 nodeRemoved')
+  it.todo('v2 nodeRemoved callback receives the same node reference as v1 onRemoved this-context')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.03.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.03.migration.test.ts
new file mode 100644
index 0000000000..128b8709be
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.03.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.03 — S1.H1,S2.N7
+// blast_radius: 15.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.03 migration — Node lifecycle: hydration from saved workflows', () => {
+  it.todo('v1 ComfyExtension.loadedGraphNode is called with the same node instance as v2 defineNodeExtension nodeConfigured')
+  it.todo('v1 nodeType.prototype.onConfigure receives the same serialized data object as v2 nodeConfigured event.data')
+  it.todo('v2 nodeConfigured fires after all widget values are restored, matching v1 onConfigure timing')
+  it.todo('state mutations applied in v1 loadedGraphNode produce the same visible node state as equivalent v2 nodeConfigured mutations')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.04.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.04.migration.test.ts
new file mode 100644
index 0000000000..6cd4e411f5
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.04.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.04 — S2.N10,S2.N17,S2.N19
+// blast_radius: 38.07  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.04 migration — Node interaction: pointer, selection, resize', () => {
+  it.todo('v1 nodeType.prototype.onMouseDown receives the same event coordinates as v2 pointerDown event argument')
+  it.todo('v1 nodeType.prototype.onSelected / onDeselected fire in the same order as v2 nodeSelected / nodeDeselected events')
+  it.todo('v1 nodeType.prototype.onResize provides the same new-size value as v2 nodeResized event.size')
+  it.todo('returning false in v1 onMouseDown to suppress default behavior is equivalent to v2 event.preventDefault()')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.05.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.05.migration.test.ts
new file mode 100644
index 0000000000..88accdde76
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.05.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.05 — S4.W2,S2.N11
+// blast_radius: 33.35  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.05 migration — Custom DOM widgets and node sizing', () => {
+  it.todo('v1 node.addDOMWidget(name, type, element, options) produces a widget with the same DOM element reference accessible via v2 widget.element')
+  it.todo('v1 nodeType.prototype.computeSize override returns the same [width, height] as v2 computeSize hook for the same node content')
+  it.todo('DOM widget created via v1 addDOMWidget is visible and positioned identically to a v2 addDOMWidget call with equivalent options')
+  it.todo('node auto-resizes to fit DOM widget in both v1 and v2 paths when options.hideOnZoom is false')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.06.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.06.migration.test.ts
new file mode 100644
index 0000000000..9d5099c4d1
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.06.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.06 — S2.N9,S3.C1,S3.C2
+// blast_radius: 58.97  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.06 migration — Custom canvas drawing (per-node and canvas-level)', () => {
+  it.todo('v1 nodeType.prototype.onDrawForeground(ctx) receives the same CanvasRenderingContext2D as v2 drawForeground event.ctx')
+  it.todo('draw calls made in v1 onDrawForeground appear at the same z-order as equivalent v2 drawForeground hook calls')
+  it.todo('v1 LGraphCanvas.prototype.* monkey-patch override produces the same canvas-level rendering as the v2 canvas draw extension hook')
+  it.todo('v2 canvas draw hook is invoked on every frame where v1 monkey-patch would have been called, with no missed frames')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.07.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.07.migration.test.ts
new file mode 100644
index 0000000000..7965383131
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.07.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.07 — S2.N3,S2.N12,S2.N13
+// blast_radius: 51.08  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.07 migration — Connection observation, intercept, and veto', () => {
+  it.todo('v1 nodeType.prototype.onConnectionsChange fires with the same (type, index, connected, linkInfo) args as v2 connectionChanged event')
+  it.todo('v1 nodeType.prototype.onConnectInput returning false vetoes the connection identically to v2 connectInput returning false')
+  it.todo('v1 nodeType.prototype.onConnectOutput returning false vetoes the connection identically to v2 connectOutput returning false')
+  it.todo('v2 connectionChanged event fires once per connect and once per disconnect, matching v1 onConnectionsChange invocation parity')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.08.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.08.migration.test.ts
new file mode 100644
index 0000000000..9d0274b4b7
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.08.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.08 — S10.D2
+// blast_radius: 11.81  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.08 migration — Programmatic linking', () => {
+  it.todo('v1 node.connect(slot, targetNode, targetSlot) produces a link with the same source/target slot indices as v2 graph.createLink()')
+  it.todo('v1 node.disconnectInput(slot) removes the link and fires connectionChanged with connected=false, matching v2 disconnectInput behavior')
+  it.todo('link created via v1 node.connect is serialized identically to a link created via v2 programmatic linking API')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.09.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.09.migration.test.ts
new file mode 100644
index 0000000000..360b20cd6b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.09.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.09 — S10.D1,S10.D3,S15.OS1
+// blast_radius: 38.63  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.09 migration — Dynamic slot and output mutation', () => {
+  it.todo('v1 node.addInput(name, type) adds a slot at the same index as v2 addInput, preserving existing link indices')
+  it.todo('v1 node.removeInput(slot) shifts remaining slot indices identically to v2 removeInput and updates serialized links')
+  it.todo('v1 node.setSize(node.computeSize()) produces the same node dimensions as v2 automatic reflow after slot mutation')
+  it.todo('dynamic outputs added via v1 node.addOutput appear in serialized workflow identically to schema-declared outputs in v2')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.10.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.10.migration.test.ts
new file mode 100644
index 0000000000..9194c82b03
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.10.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.10 — S4.W1,S2.N14
+// blast_radius: 32.22  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.10 migration — Widget value subscription', () => {
+  it.todo('v1 widget.callback chain fires with the same (value, widget, node) arguments as v2 on("widgetChanged") event payload')
+  it.todo('v1 nodeType.prototype.onWidgetChanged receives (name, value, oldValue, widget) matching v2 widgetChanged event fields')
+  it.todo('both v1 widget.callback and v2 widgetChanged fire on every programmatic widget.value assignment, not just UI interactions')
+  it.todo('multiple v1 chained callbacks and multiple v2 widgetChanged listeners are all invoked in registration order')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.11.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.11.migration.test.ts
new file mode 100644
index 0000000000..e0a39a26c9
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.11.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.11 — S4.W4,S4.W5,S2.N16
+// blast_radius: 28.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.11 migration — Widget imperative state writes', () => {
+  it.todo('v1 widget.options.values = [...] COMBO update is reflected in the rendered dropdown identically to v2 widget.updateOptions()')
+  it.todo('v1 direct widget.value write triggers the same reactive update path as v2 widget.setValue() for downstream subscribers')
+  it.todo('iterating v1 node.widgets array produces the same widget set in the same order as v2 node.widgets readonly accessor')
+  it.todo('removing a widget via v1 node.widgets.splice() leaves the node in the same state as v2 node.removeWidget()')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.12.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.12.migration.test.ts
new file mode 100644
index 0000000000..061a3ef7bb
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.12.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.12 — S4.W3
+// blast_radius: 27.94  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.12 migration — Per-widget serialization transform', () => {
+  it.todo('v1 widget.serializeValue() return value appears at the same widgets_values position as v2 on("beforeSerialize") event.setSerializedValue() output')
+  it.todo('v1 widget.serializeValue returning a transformed string produces the same serialized workflow JSON field as the v2 serializeValue hook')
+  it.todo('v2 beforeSerialize event is called exactly once per widget per graphToPrompt, matching v1 serializeValue invocation frequency')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.13.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.13.migration.test.ts
new file mode 100644
index 0000000000..77721ba0c4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.13.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.13 — S2.N6,S2.N15
+// blast_radius: 47.07  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.13 migration — Per-node serialization interception', () => {
+  it.todo('v1 nodeType.prototype.onSerialize(data) mutation of data object injects the same extra fields as v2 nodeSerialize event.data mutation')
+  it.todo('custom fields injected via v1 onSerialize are round-tripped through onConfigure with the same values as v2 nodeSerialize → nodeConfigured')
+  it.todo('v2 nodeSerialize event fires at the same serialization point as v1 onSerialize, before the node data is merged into the graph JSON')
+  it.todo('v1 node.serialize() return value structure matches the v2 serialized node object shape field-for-field')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.14.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.14.migration.test.ts
new file mode 100644
index 0000000000..5e8ef72a5d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.14.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.14 — S6.A1
+// blast_radius: 46.66  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.14 migration — Workflow → API serialization interception (graphToPrompt)', () => {
+  it.todo('v1 app.graphToPrompt monkey-patch that mutates output.workflow produces the same modified workflow as v2 beforeGraphToPrompt event mutation')
+  it.todo('v1 app.graphToPrompt monkey-patch that mutates output.output (API payload) produces the same API JSON as v2 beforeQueuePrompt event mutation')
+  it.todo('v2 beforeGraphToPrompt fires exactly once per queue action, matching v1 monkey-patch interception frequency')
+  it.todo('virtual nodes resolved in v1 graphToPrompt override are absent from the final API payload identically to v2 virtual node resolution hook')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.15.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.15.migration.test.ts
new file mode 100644
index 0000000000..e608190102
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.15.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.15 — S6.A2
+// blast_radius: 20.31  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.15 migration — Workflow loading into the editor', () => {
+  it.todo('v1 app.loadGraphData(workflowJson) populates the graph with the same nodes and links as v2 useWorkflowStore().loadWorkflow()')
+  it.todo('loadedGraphNode hook fires after v1 app.loadGraphData completes, matching v2 post-load nodeConfigured event order')
+  it.todo('v2 loadWorkflow API accepts the same workflow JSON shape as v1 app.loadGraphData without requiring format conversion')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.16.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.16.migration.test.ts
new file mode 100644
index 0000000000..11d1cdab3d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.16.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.16 — S2.N2
+// blast_radius: 5.74  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.16 migration — Execution output consumption (per-node)', () => {
+  it.todo('v1 nodeType.prototype.onExecuted(data) receives the same backend output payload as v2 nodeExecuted event.output')
+  it.todo('v2 nodeExecuted fires once per node execution completion, matching v1 onExecuted invocation count per prompt run')
+  it.todo('image/text output consumed in v1 onExecuted produces the same widget display state as equivalent v2 nodeExecuted handler')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.17.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.17.migration.test.ts
new file mode 100644
index 0000000000..cce8988e10
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.17.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.17 — S5.A1,S5.A2,S5.A3
+// blast_radius: 51.25  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.17 migration — Backend execution lifecycle and progress events', () => {
+  it.todo('v1 api.addEventListener("execution_start", handler) fires at the same execution phase as v2 useExecutionStore onExecutionStart hook')
+  it.todo('v1 api.addEventListener("progress", handler) receives the same {value, max, node} payload as v2 executionProgress event')
+  it.todo('v1 api.addEventListener("execution_success", handler) fires at the same time as v2 onExecutionComplete and with equivalent prompt_id')
+  it.todo('v2 execution lifecycle events cover all v1 event names (execution_start, execution_success, execution_error, progress) with no gaps')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.18.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.18.migration.test.ts
new file mode 100644
index 0000000000..41bffc873c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.18.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.18 — S6.A3
+// blast_radius: 22.74  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.18 migration — Backend HTTP calls', () => {
+  it.todo('v1 api.fetchApi("/custom/endpoint", options) sends the same HTTP request as v2 useApiStore().fetch("/custom/endpoint", options)')
+  it.todo('v1 api.fetchApi response object has the same shape (status, json(), text()) as the v2 fetch response')
+  it.todo('authentication headers applied by v1 api.fetchApi are also applied by the v2 fetch API call')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.19.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.19.migration.test.ts
new file mode 100644
index 0000000000..d668e0db2a
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.19.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.19 — S6.A4
+// blast_radius: 12.65  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.19 migration — Workflow execution trigger', () => {
+  it.todo('v1 app.queuePrompt() submits the same serialized workflow to the backend as v2 useQueueStore().queueWorkflow()')
+  it.todo('v1 app.api.queuePrompt monkey-patch intercepting the payload produces the same modified API body as v2 beforeQueuePrompt event mutation')
+  it.todo('v2 queueWorkflow triggers the same execution_start event sequence as a v1 app.queuePrompt call')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.20.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.20.migration.test.ts
new file mode 100644
index 0000000000..2a587d90cc
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.20.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.20 — S1.H5,S1.H6,S8.P1
+// blast_radius: 27.49  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.20 migration — Custom node-type registration (frontend-only / virtual)', () => {
+  it.todo('v1 ComfyExtension.addCustomNodeDefs registers node types visible to getNodeDefs() identically to v2 registerNodeType()')
+  it.todo('v1 ComfyExtension.registerCustomNodes callback runs at the same registration phase as v2 app.registerExtension nodeRegistered hook')
+  it.todo('v1 nodeType.prototype.isVirtualNode = true causes the node to be stripped from API payload identically to v2 isVirtualNode declaration')
+  it.todo('frontend-only node registered in v1 addCustomNodeDefs can be instantiated, serialized, and rehydrated identically to a v2 virtual node')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.21.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.21.migration.test.ts
new file mode 100644
index 0000000000..c909f1566d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.21.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.21 — S1.H2
+// blast_radius: 7.17  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.21 migration — Custom widget-type registration', () => {
+  it.todo('v1 ComfyExtension.getCustomWidgets() return value registers widget types accessible via nodeType inputs identically to v2 registerWidgetType()')
+  it.todo('custom widget registered via v1 getCustomWidgets is instantiated on a node with the same widget.name and widget.type as v2 registration')
+  it.todo('v1 custom widget factory function receives the same (node, inputName, inputData, app) arguments as v2 widgetFactory callback')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.22.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.22.migration.test.ts
new file mode 100644
index 0000000000..afb63b77e1
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.22.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.22 — S2.N5,S1.H3,S1.H4
+// blast_radius: 19.53  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.22 migration — Context menu contributions (node and canvas)', () => {
+  it.todo('v1 nodeType.prototype.getExtraMenuOptions returns items that appear in the right-click menu identically to v2 nodeContextMenu contributions')
+  it.todo('v1 ComfyExtension.getCanvasMenuItems array is rendered in the canvas context menu in the same position as v2 canvasContextMenu hook items')
+  it.todo('v1 ComfyExtension.getNodeMenuItems contributions appear in node menus identically to v2 nodeContextMenu registered items')
+  it.todo('menu item click handler receives the same node/canvas reference in v1 getExtraMenuOptions as in v2 nodeContextMenu event context')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.23.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.23.migration.test.ts
new file mode 100644
index 0000000000..b75e3a1680
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.23.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.23 — S2.N18
+// blast_radius: 14.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.23 migration — Node property bag mutations', () => {
+  it.todo('v1 nodeType.prototype.onPropertyChanged(name, value) fires with same args as v2 propertyChanged event when node.properties[name] is assigned')
+  it.todo('property change observer registered in v1 onPropertyChanged produces the same side-effects as v2 on("propertyChanged") handler')
+  it.todo('node.properties mutations survive serialization/deserialization identically in both v1 and v2 paths')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.24.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.24.migration.test.ts
new file mode 100644
index 0000000000..d8f44f8d3e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.24.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.24 — S13.SC1
+// blast_radius: 22.43  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.24 migration — Node-def schema inspection', () => {
+  it.todo('v1 ComfyNodeDef.input.required shape accessed in beforeRegisterNodeDef matches the v2 NodeDef.inputs schema shape')
+  it.todo('v1 nodeDef.output_node boolean accessed in beforeRegisterNodeDef is present at the same path in the v2 NodeDef')
+  it.todo('branching logic based on v1 input.required/optional/hidden field presence produces the same node customization as equivalent v2 schema inspection')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.25.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.25.migration.test.ts
new file mode 100644
index 0000000000..20cad5648c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.25.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.25 — S12.UI1
+// blast_radius: 10.98  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.25 migration — Shell UI registration (commands, sidebars, toasts)', () => {
+  it.todo('v1 app.extensionManager.commands.addCommand({id, label, callback}) registers a command visible in the command palette identically to v2 registerCommand()')
+  it.todo('v1 app.extensionManager.sidebar.addTab() produces a sidebar tab rendered at the same position as a v2 registerSidebarTab() call')
+  it.todo('v1 app.extensionManager.toast.add({severity, summary, detail}) produces the same toast notification as v2 useToastStore().add()')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.26.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.26.migration.test.ts
new file mode 100644
index 0000000000..c653c08ea1
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.26.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.26 — S7.G1
+// blast_radius: 27.0  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.26 migration — Globals as ABI (window.LiteGraph, window.comfyAPI)', () => {
+  it.todo('window.LiteGraph enum values (LiteGraph.INPUT, LiteGraph.OUTPUT, etc.) match the values exported from the v2 litegraph module import')
+  it.todo('window.comfyAPI.* module references resolve to the same objects as the corresponding v2 named imports from the extension API')
+  it.todo('extensions reading window.LiteGraph.registered_node_types see the same node registry as v2 useNodeDefStore().nodeTypes')
+  it.todo('v2 API module exports cover all window.comfyAPI surface area accessed by v1 extensions so globals can be dropped without behavior change')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.27.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.27.migration.test.ts
new file mode 100644
index 0000000000..7381729f1f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.27.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.27 — S9.R1,S9.G1,S9.L1,S9.S1
+// blast_radius: 39.37  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.27 migration — LiteGraph entity direct manipulation (reroute, group, link, slot)', () => {
+  it.todo('v1 LiteGraph.createRerouteOnLink() produces a reroute node with the same position and link connectivity as v2 graph.createReroute()')
+  it.todo('v1 direct link.color mutation is reflected on the canvas identically to v2 link style API call')
+  it.todo('v1 graph.groups array mutation (add/remove LGraphGroup) produces the same serialized group list as v2 group management API')
+  it.todo('v1 slot type string read from node.inputs[i].type matches v2 node.getInputInfo(i).type for all built-in and custom types')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.28.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.28.migration.test.ts
new file mode 100644
index 0000000000..9a859cc4d4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.28.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.28 — S9.SG1
+// blast_radius: 16.89  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.28 migration — Subgraph fan-out via set/get virtual nodes', () => {
+  it.todo('v1 Set virtual node stores a named value that a matching Get virtual node retrieves identically in v2 when both use the same slot name')
+  it.todo('v1 Set/Get pair serialized to workflow JSON round-trips to the same node graph state when loaded via v2 loadWorkflow()')
+  it.todo('multiple Get nodes referencing the same Set name in v1 all receive the same value as the v2 equivalent virtual slot binding')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.29.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.29.migration.test.ts
new file mode 100644
index 0000000000..4f5a0c685e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.29.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.29 — S11.G2,S14.ID1
+// blast_radius: 23.56  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.29 migration — Graph enumeration, mutation, and cross-scope identity', () => {
+  it.todo('v1 graph.findNodesByType("NodeClass") returns the same node instances as v2 useGraphStore().getNodesByType("NodeClass")')
+  it.todo('v1 graph.add(node) followed by graph.remove(node) leaves the graph in the same state as v2 addNode/removeNode API pair')
+  it.todo('v1 NodeLocatorId string format parsed manually matches the structured object returned by v2 parseNodeLocatorId()')
+  it.todo('node identity across subgraph scopes is consistent: v1 node.id resolves to the same node via v2 graph.getNodeById(id)')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.30.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.30.migration.test.ts
new file mode 100644
index 0000000000..bd6e506acf
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.30.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.30 — S11.G1,S11.G3,S11.G4
+// blast_radius: 34.38  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.30 migration — Graph change tracking, batching, and reactivity flush', () => {
+  it.todo('v1 graph._version increments after each mutation identically to the v2 graph change counter accessible via graphStore.changeId')
+  it.todo('v1 graph.beforeChange() / graph.afterChange() batching suppresses intermediate redraws identically to v2 graph.batchChanges() callback')
+  it.todo('v1 graph.setDirtyCanvas(true, true) triggers a synchronous canvas repaint equivalent to v2 canvas.requestFrame()')
+  it.todo('mutations batched via v1 beforeChange/afterChange produce the same final canvas state as equivalent v2 batchChanges() mutations')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.31.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.31.migration.test.ts
new file mode 100644
index 0000000000..f8fdc8e9c0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.31.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.31 — S16.DOM1,S16.DOM2,S16.DOM3,S16.DOM4
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.31 migration — DOM injection and style management', () => {
+  it.todo('v1 document.createElement("style") + head.appendChild CSS injection is replaced by v2 registerStylesheet() with identical visual effect')
+  it.todo('v1 document.body.appendChild arbitrary DOM panel is replaced by v2 sidebar or panel API with same rendered content')
+  it.todo('v1 innerHTML-based HTML injection produces the same DOM structure as v2 template-safe API with no XSS regression')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.32.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.32.migration.test.ts
new file mode 100644
index 0000000000..96c41a3b8d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.32.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.32 — S16.VUE1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.32 migration — Embedded framework runtimes and Vue widget bundling', () => {
+  it.todo('v1 DOM widget with bundled Vue app mounted via createApp() renders the same UI as a v2 VueNode widget using the host Vue instance')
+  it.todo('v2 VueNode component receives the same initial props as a v1 bundled-Vue widget receives through its DOM element dataset')
+  it.todo('reactive state updates inside a v2 VueNode widget are reflected in the DOM with the same latency as a v1 bundled Vue component')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.33.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.33.migration.test.ts
new file mode 100644
index 0000000000..629b0ea960
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.33.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.33 — S4.W6
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.33 migration — Cross-extension DOM widget creation observation', () => {
+  it.todo('v1 DOM widget creation observer callback receives the same widget instance as v2 on("domWidgetCreated") event argument')
+  it.todo('v2 domWidgetCreated event fires for widgets created by other extensions, matching v1 cross-extension observation behavior')
+  it.todo('logic attached to a foreign widget in v1 observation hook produces the same effect when migrated to v2 domWidgetCreated handler')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.34.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.34.migration.test.ts
new file mode 100644
index 0000000000..49d82507f5
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.34.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.34 — S12.UI3
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.34 migration — Settings-panel custom dialog integration', () => {
+  it.todo('v1 settings-triggered modal opened via direct DOM creation renders the same content as v2 useDialogStore().open() with equivalent component')
+  it.todo('v2 dialog opened from a settings panel action is dismissed with the same result value as a v1 custom dialog callback pattern')
+  it.todo('settings entry that opens a dialog in v1 produces the same settings JSON mutation as the v2 dialog-backed settings entry')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.35.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.35.migration.test.ts
new file mode 100644
index 0000000000..a0e1808f6b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.35.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.35 — S6.A5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.35 migration — Pre-queue widget validation', () => {
+  it.todo('v1 validation hook returning an error string prevents queue submission identically to v2 beforeQueuePrompt event.preventDefault()')
+  it.todo('v2 validation hook receives the same widget value and node reference as v1 for the same workflow state')
+  it.todo('error surfaced to user from v1 pre-queue validation is displayed with the same severity/message as v2 validation error toast')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.36.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.36.migration.test.ts
new file mode 100644
index 0000000000..9efc7978b1
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.36.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.36 — S4.W1,S4.W4,S4.W5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.36 migration — PrimeVue widget component API surface', () => {
+  it.todo('v1 widget.callback chain pattern produces the same change notification as v2 PrimeVue widget onChange prop')
+  it.todo('v1 widget.options.values COMBO mutation is reflected in the PrimeVue Dropdown options prop identically after v2 migration')
+  it.todo('v1 direct widget.value write is reflected in the PrimeVue component model value identically to v2 reactive binding update')
+  it.todo('PrimeVue widget emits the same serializable value as its v1 LiteGraph widget counterpart for the same user interaction')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.37.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.37.migration.test.ts
new file mode 100644
index 0000000000..95eb7386a8
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.37.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.37 — S4.W5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.37 migration — VueNode bridge timing — deferred mount access', () => {
+  it.todo('v1 widget.value write inside nodeCreated completes before the component renders; v2 equivalent using onMounted deferred write produces the same initial state')
+  it.todo('v2 VueNode component instance is accessible to external code after the nextTick following nodeCreated, matching v1 synchronous widget access timing')
+  it.todo('v1 Three.js renderer reference stored on widget survives the nodeCreated → first-draw cycle identically to v2 VueNode expose() ref access')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.38.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.38.migration.test.ts
new file mode 100644
index 0000000000..6656916331
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.38.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.38 — S17.AM1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.38 migration — Canvas mode observation', () => {
+  it.todo('v1 appModeStore.currentMode read produces the same string as v2 useCanvasModeStore().mode for each canvas mode transition')
+  it.todo('v1 watch on appModeStore.currentMode fires at the same lifecycle point as v2 on("canvasModeChanged") event for each transition')
+  it.todo('UI visibility logic branching on v1 appModeStore produces the same rendered state as equivalent v2 canvasModeChanged handler')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.39.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.39.migration.test.ts
new file mode 100644
index 0000000000..0c8c1f81bd
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.39.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.39 — S17.SB1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.39 migration — Subgraph boundary event propagation', () => {
+  it.todo('v1 onExecuted callback fires for nodes inside a subgraph identically to v2 nodeExecuted event propagated across the subgraph boundary')
+  it.todo('v1 onConnectionsChange fires for promoted subgraph boundary slots identically to v2 connectionChanged event at the parent graph level')
+  it.todo('promoted widget callback in v1 subgraph reflects the same value change as v2 widgetChanged event on the exposed parent slot')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.40.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.40.migration.test.ts
new file mode 100644
index 0000000000..850e9efa18
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.40.migration.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.40 — S17.FA1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.40 migration — File upload and asset URL construction', () => {
+  it.todo('v1 api.fetchApi("/upload/image", {method:"POST", body: formData}) uploads a file to the same backend path as v2 useFileStore().uploadFile()')
+  it.todo('asset URL constructed manually as "/view?filename=...&type=input" in v1 matches the URL returned by v2 useFileStore().getAssetUrl()')
+  it.todo('v2 uploadFile() resolves with the same {name, subfolder, type} shape as the v1 manual upload JSON response parse')
+})
diff --git a/src/extension-api-v2/__tests__/migration/BC.41.migration.test.ts b/src/extension-api-v2/__tests__/migration/BC.41.migration.test.ts
new file mode 100644
index 0000000000..84ea062313
--- /dev/null
+++ b/src/extension-api-v2/__tests__/migration/BC.41.migration.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.41 — S17.WV1
+// blast_radius: 4.09  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.41 migration — Widget values positional serialization fragility', () => {
+  it.todo('v1 widgets_values positional array round-trips correctly when deserialized via v2 loadWorkflow() without index shifting')
+  it.todo('adding a new input in v2 node schema does not shift existing widget value positions relative to a v1-serialized workflow')
+  it.todo('v2 named widget value serialization produces an equivalent deserialized widget state as v1 positional widgets_values for the same node type')
+  it.todo('v1 workflow with reordered widgets_values array loads into v2 editor with each widget at the correct named position')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.01.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.01.v1.test.ts
new file mode 100644
index 0000000000..a099204f99
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.01.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.01 — S2.N1,S2.N8
+// blast_radius: 37.56  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.01 v1 — Node lifecycle: creation', () => {
+  it.todo('nodeType.prototype.onNodeCreated is called when a node is instantiated via LiteGraph')
+  it.todo('app.registerExtension({ nodeCreated }) callback receives the newly created node instance')
+  it.todo('extensions registered with beforeRegisterNodeDef can mutate nodeType.prototype before first instantiation')
+  it.todo('widgets added to node.widgets during onNodeCreated are present on the node after creation')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.02.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.02.v1.test.ts
new file mode 100644
index 0000000000..35e2472ee4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.02.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.02 — S2.N4
+// blast_radius: 29.35  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.02 v1 — Node lifecycle: teardown', () => {
+  it.todo('nodeType.prototype.onRemoved is called when a node is removed from the graph')
+  it.todo('cleanup logic inside onRemoved fires before the node is detached from LiteGraph')
+  it.todo('DOM widgets created during onNodeCreated can be cleaned up inside onRemoved without errors')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.03.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.03.v1.test.ts
new file mode 100644
index 0000000000..539b8c27fb
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.03.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.03 — S1.H1,S2.N7
+// blast_radius: 15.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.03 v1 — Node lifecycle: hydration from saved workflows', () => {
+  it.todo('nodeType.prototype.onConfigure is called with saved node data when a workflow is loaded')
+  it.todo('app.registerExtension({ loadedGraphNode }) callback fires for each node during workflow load')
+  it.todo('widget values restored via onConfigure match the serialized workflow values exactly')
+  it.todo('extensions can augment node state inside onConfigure without overwriting restored widget values')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.04.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.04.v1.test.ts
new file mode 100644
index 0000000000..5d1249bbe1
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.04.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.04 — S2.N10,S2.N17,S2.N19
+// blast_radius: 38.07  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.04 v1 — Node interaction: pointer, selection, resize', () => {
+  it.todo('nodeType.prototype.onMouseDown receives canvas pointer events with correct local coordinates')
+  it.todo('nodeType.prototype.onSelected and onDeselected are called when the node enters and leaves selection')
+  it.todo('nodeType.prototype.onResize is called with updated size after a user drag-resize')
+  it.todo('nodeType.prototype.onDblClick fires on canvas double-click and can open a custom modal')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.05.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.05.v1.test.ts
new file mode 100644
index 0000000000..e7cdf3e01f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.05.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.05 — S4.W2,S2.N11
+// blast_radius: 33.35  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.05 v1 — Custom DOM widgets and node sizing', () => {
+  it.todo('node.addDOMWidget(name, type, element) mounts an HTMLElement inside the node body on the canvas')
+  it.todo('custom DOM widget reports its measured height back to LiteGraph so node.size updates correctly')
+  it.todo('nodeType.prototype.computeSize override controls node dimensions when DOM widgets are present')
+  it.todo('DOM widget element is removed from the canvas container when the node is removed')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.06.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.06.v1.test.ts
new file mode 100644
index 0000000000..809f7b9bf7
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.06.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.06 — S2.N9,S3.C1,S3.C2
+// blast_radius: 58.97  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.06 v1 — Custom canvas drawing (per-node and canvas-level)', () => {
+  it.todo('nodeType.prototype.onDrawBackground is called with the CanvasRenderingContext2D during each canvas repaint')
+  it.todo('nodeType.prototype.onDrawForeground is called after node content and widgets are drawn')
+  it.todo('app.registerExtension({ drawBackground }) canvas-level hook receives ctx and visible graph area')
+  it.todo('extension drawForeground hook fires after all nodes are painted, allowing overlay decorations')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.07.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.07.v1.test.ts
new file mode 100644
index 0000000000..5c1b75ccc6
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.07.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.07 — S2.N3,S2.N12,S2.N13
+// blast_radius: 51.08  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.07 v1 — Connection observation, intercept, and veto', () => {
+  it.todo('nodeType.prototype.onConnectInput is called before a link is established and can return false to veto')
+  it.todo('nodeType.prototype.onConnectionsChange fires after a link is added or removed with updated slot info')
+  it.todo('nodeType.prototype.onConnectOutput receives target node and slot and can veto the outgoing link')
+  it.todo('vetoing a connection via onConnectInput prevents the link from appearing in graph.links')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.08.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.08.v1.test.ts
new file mode 100644
index 0000000000..c0ff7fb8a3
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.08.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.08 — S10.D2
+// blast_radius: 11.81  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.08 v1 — Programmatic linking', () => {
+  it.todo('app.graph.connectNodes(srcId, srcSlot, dstId, dstSlot) creates a link visible in graph.links')
+  it.todo('programmatic link triggers onConnectionsChange on both source and destination nodes')
+  it.todo('link created via connectNodes survives a serialize → deserialize round-trip')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.09.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.09.v1.test.ts
new file mode 100644
index 0000000000..0c4d32e309
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.09.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.09 — S10.D1,S10.D3,S15.OS1
+// blast_radius: 38.63  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.09 v1 — Dynamic slot and output mutation', () => {
+  it.todo('node.addInput(name, type) appends a new input slot that is immediately connectable on the canvas')
+  it.todo('node.addOutput(name, type) appends a new output slot reflected in the serialized graph')
+  it.todo('node.removeInput(slot) removes the slot and disconnects any existing link without graph corruption')
+  it.todo('dynamically added outputs survive onConfigure reload when persisted in node.outputs')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.10.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.10.v1.test.ts
new file mode 100644
index 0000000000..3d32170bc3
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.10.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.10 — S4.W1,S2.N14
+// blast_radius: 32.22  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.10 v1 — Widget value subscription', () => {
+  it.todo('replacing widget.callback on an existing widget fires the custom callback when the widget value changes')
+  it.todo('nodeType.prototype.onWidgetChanged is called with (name, value, oldValue, widget) on every widget mutation')
+  it.todo('chaining the original widget.callback from within a replacement callback preserves default behavior')
+  it.todo('widget.callback replacement survives onConfigure re-hydration without being overwritten')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.11.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.11.v1.test.ts
new file mode 100644
index 0000000000..30b7fc97fc
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.11.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.11 — S4.W4,S4.W5,S2.N16
+// blast_radius: 28.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.11 v1 — Widget imperative state writes', () => {
+  it.todo('setting widget.value directly updates the displayed value on the next canvas repaint')
+  it.todo('calling widget.callback(newValue) after a direct widget.value write keeps value and callback in sync')
+  it.todo('nodeType.prototype.onExecuted can imperatively set widget.value to update UI from execution output')
+  it.todo('widget.options.min/max/step constraints are still enforced after a direct widget.value write')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.12.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.12.v1.test.ts
new file mode 100644
index 0000000000..9e94cf6748
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.12.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.12 — S4.W3
+// blast_radius: 27.94  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.12 v1 — Per-widget serialization transform', () => {
+  it.todo('widget.serializeValue(node, index) is called during graphToPrompt and its return value replaces widget.value in the API payload')
+  it.todo('widget.serializeValue returning a Promise resolves before the prompt is submitted')
+  it.todo('widgets without serializeValue fall back to serializing widget.value directly')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.13.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.13.v1.test.ts
new file mode 100644
index 0000000000..f312b2796d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.13.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.13 — S2.N6,S2.N15
+// blast_radius: 47.07  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.13 v1 — Per-node serialization interception', () => {
+  it.todo('nodeType.prototype.onSerialize is called with the serialized node object and can mutate it before save')
+  it.todo('extra keys written onto the serialized object inside onSerialize are persisted in the workflow JSON')
+  it.todo('nodeType.prototype.getExtraInfo returns an object that is merged into the serialized node under "properties"')
+  it.todo('round-tripping through serialize → loadJSON → onConfigure restores values written in onSerialize')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.14.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.14.v1.test.ts
new file mode 100644
index 0000000000..422f857943
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.14.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.14 — S6.A1
+// blast_radius: 46.66  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.14 v1 — Workflow → API serialization interception (graphToPrompt)', () => {
+  it.todo('app.registerExtension({ beforeRegisterNodeDef }) can add node-type hooks before graphToPrompt is called')
+  it.todo('app.registerExtension({ getCustomWidgets }) custom widget serializeValue is invoked during graphToPrompt')
+  it.todo('mutating the output object inside a graphToPrompt promise chain alters the final API payload sent to /prompt')
+  it.todo('graphToPrompt rejects cleanly if a widget.serializeValue throws, preventing partial prompt submission')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.15.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.15.v1.test.ts
new file mode 100644
index 0000000000..309a011a52
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.15.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.15 — S6.A2
+// blast_radius: 20.31  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.15 v1 — Workflow loading into the editor', () => {
+  it.todo('app.loadGraphData(graph) triggers app.registerExtension({ loadedGraphNode }) for every node in the workflow')
+  it.todo('extension loadedGraphNode callback can mutate node properties after hydration without breaking subsequent nodes')
+  it.todo('loading a workflow with unknown node types does not throw and leaves placeholder nodes intact')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.16.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.16.v1.test.ts
new file mode 100644
index 0000000000..1141af7b3f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.16.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.16 — S2.N2
+// blast_radius: 5.74  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.16 v1 — Execution output consumption (per-node)', () => {
+  it.todo('nodeType.prototype.onExecuted is called with the execution output object after the backend completes the node')
+  it.todo('onExecuted receives images/latents arrays and extensions can render them by updating node properties')
+  it.todo('onExecuted is not called for nodes that were cached and not re-executed in the current run')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.17.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.17.v1.test.ts
new file mode 100644
index 0000000000..c048be7dd9
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.17.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.17 — S5.A1,S5.A2,S5.A3
+// blast_radius: 51.25  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.17 v1 — Backend execution lifecycle and progress events', () => {
+  it.todo('app.registerExtension({ init }) callback can attach listeners to api.addEventListener("status", ...) for queue state')
+  it.todo('api.addEventListener("progress", handler) fires with { value, max, prompt_id, node } during execution')
+  it.todo('api.addEventListener("executed", handler) fires after each node completes with its output data')
+  it.todo('api.addEventListener("execution_error", handler) fires with error details when the backend aborts')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.18.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.18.v1.test.ts
new file mode 100644
index 0000000000..5c4d96d1dd
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.18.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.18 — S6.A3
+// blast_radius: 22.74  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.18 v1 — Backend HTTP calls', () => {
+  it.todo('api.fetchApi(route, options) resolves with a Response object for a successful GET to a ComfyUI endpoint')
+  it.todo('api.fetchApi correctly prefixes the configured api_base so relative routes resolve against the server origin')
+  it.todo('extensions can use api.fetchApi inside beforeRegisterNodeDef to pre-fetch model lists before nodes are registered')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.19.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.19.v1.test.ts
new file mode 100644
index 0000000000..1b2ca5475c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.19.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.19 — S6.A4
+// blast_radius: 12.65  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.19 v1 — Workflow execution trigger', () => {
+  it.todo('app.queuePrompt(number, batchCount) calls graphToPrompt and POSTs the result to /prompt')
+  it.todo('app.queuePrompt resolves with the response body containing { prompt_id } on success')
+  it.todo('extensions can intercept execution by wrapping app.queuePrompt before calling the original')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.20.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.20.v1.test.ts
new file mode 100644
index 0000000000..2b67916e5e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.20.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.20 — S1.H5,S1.H6,S8.P1
+// blast_radius: 27.49  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.20 v1 — Custom node-type registration (frontend-only / virtual)', () => {
+  it.todo('app.registerExtension({ registerCustomNodes }) can call LiteGraph.registerNodeType to add a frontend-only node type')
+  it.todo('a frontend-only node type registered via registerCustomNodes appears in the node search menu')
+  it.todo('app.registerExtension({ getCustomWidgets }) returns widget factories that are available during beforeRegisterNodeDef')
+  it.todo('custom node types registered with registerCustomNodes survive app.loadGraphData without being unregistered')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.21.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.21.v1.test.ts
new file mode 100644
index 0000000000..fc668075ce
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.21.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.21 — S1.H2
+// blast_radius: 7.17  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.21 v1 — Custom widget-type registration', () => {
+  it.todo('app.registerExtension({ getCustomWidgets }) callback is invoked and returns a widget type map keyed by string name')
+  it.todo('a widget type registered via getCustomWidgets is accessible on app.widgets[name] after registration')
+  it.todo('custom widget factory receives (node, inputName, inputData, app) arguments matching v1 signature')
+  it.todo('widget created by a v1 custom widget type is appended to node.widgets array')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.22.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.22.v1.test.ts
new file mode 100644
index 0000000000..bbe117d901
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.22.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.22 — S2.N5,S1.H3,S1.H4
+// blast_radius: 19.53  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.22 v1 — Context menu contributions (node and canvas)', () => {
+  it.todo('app.registerExtension({ getNodeMenuOptions }) receives (node, options) and can push entries into the options array')
+  it.todo('app.registerExtension({ getCanvasMenuOptions }) receives (options) and can push entries for canvas right-click menu')
+  it.todo('menu entries pushed via addCustomMenuEntries are rendered in the LiteGraph context menu without error')
+  it.todo('returning null or undefined from getNodeMenuOptions does not suppress the default node menu')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.23.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.23.v1.test.ts
new file mode 100644
index 0000000000..1a5bacf5e5
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.23.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.23 — S2.N18
+// blast_radius: 14.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.23 v1 — Node property bag mutations', () => {
+  it.todo('direct assignment to node.properties[key] is reflected when the graph is serialized to JSON')
+  it.todo('app.registerExtension({ nodeCreated }) can write arbitrary keys to node.properties without throwing')
+  it.todo('node.properties survives a graph load/save round-trip with v1-injected keys intact')
+  it.todo('mutations to node.properties do not interfere with node.widgets_values serialization')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.24.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.24.v1.test.ts
new file mode 100644
index 0000000000..1b2894d408
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.24.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.24 — S13.SC1
+// blast_radius: 22.43  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.24 v1 — Node-def schema inspection', () => {
+  it.todo('app.registerExtension({ beforeRegisterNodeDef }) receives (nodeType, nodeData) where nodeData matches the server-returned node definition schema')
+  it.todo('reading nodeData.input.required and nodeData.input.optional in beforeRegisterNodeDef returns the expected input slot descriptors')
+  it.todo('reading nodeData.output, nodeData.output_name, and nodeData.output_is_list provides correct output slot metadata')
+  it.todo('mutations to nodeData inside beforeRegisterNodeDef are visible to subsequently-registered extensions for the same node type')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.25.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.25.v1.test.ts
new file mode 100644
index 0000000000..53ac234137
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.25.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.25 — S12.UI1
+// blast_radius: 10.98  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.25 v1 — Shell UI registration (commands, sidebars, toasts)', () => {
+  it.todo('app.registerExtension({ commands }) registers command objects accessible via app.commands after setup')
+  it.todo('app.extensionManager.registerSidebarTab({ id, icon, title, render }) adds a sidebar tab that can be retrieved by id')
+  it.todo('app.extensionManager.toast.add({ severity, summary, detail }) dispatches a toast notification without throwing')
+  it.todo('a registered command object exposes at minimum { id, function } and is callable via app.commands[id]()')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.26.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.26.v1.test.ts
new file mode 100644
index 0000000000..9a4cc7b3ed
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.26.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.26 — S7.G1
+// blast_radius: 27.0  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.26 v1 — Globals as ABI (window.LiteGraph, window.comfyAPI)', () => {
+  it.todo('window.LiteGraph is defined and exposes LiteGraph.NODE_TITLE_HEIGHT and LiteGraph.registerNodeType')
+  it.todo('window.comfyAPI is defined and exposes at minimum { app, widgets, logging } namespaces used by v1 extensions')
+  it.todo('prototype properties added to window.LiteGraph.LGraphNode.prototype are present on all subsequently created node instances')
+  it.todo('window.app is the same reference as the module-level app singleton imported by the frontend')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.27.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.27.v1.test.ts
new file mode 100644
index 0000000000..618aeb3ecf
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.27.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.27 — S9.R1,S9.G1,S9.L1,S9.S1
+// blast_radius: 39.37  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.27 v1 — LiteGraph entity direct manipulation (reroute, group, link, slot)', () => {
+  it.todo('directly setting node.pos[0] and node.pos[1] moves the node and is reflected in graph.serialize()')
+  it.todo('graph.addGroup() creates a LGraphGroup whose title and bounding box are mutable via direct property assignment')
+  it.todo('a link object retrieved from graph.links[id] exposes { id, origin_id, origin_slot, target_id, target_slot, type } matching v1 shape')
+  it.todo('adding a reroute node via LiteGraph.createNode("Reroute") and connecting slots through it does not break link serialization')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.28.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.28.v1.test.ts
new file mode 100644
index 0000000000..16fb4e2703
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.28.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.28 — S9.SG1
+// blast_radius: 16.89  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.28 v1 — Subgraph fan-out via set/get virtual nodes', () => {
+  it.todo('a "SetNode" virtual node added to a subgraph exposes node.properties.slot_name readable by a corresponding "GetNode"')
+  it.todo('graph.findNodesByType("SetNode") returns all setter virtual nodes in the current graph scope')
+  it.todo('removing a SetNode does not throw and leaves no dangling link entries in graph.links')
+  it.todo('GetNode resolves its value from the matching SetNode slot_name within the same subgraph scope at execution time')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.29.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.29.v1.test.ts
new file mode 100644
index 0000000000..f8e3e8124b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.29.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.29 — S11.G2,S14.ID1
+// blast_radius: 23.56  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.29 v1 — Graph enumeration, mutation, and cross-scope identity', () => {
+  it.todo('app.graph.nodes is an array and iterating it via for-of yields all top-level LGraphNode instances')
+  it.todo('app.graph.getNodeById(id) returns the same object reference as app.graph.nodes.find(n => n.id === id)')
+  it.todo('node.id is stable across a serialize/configure round-trip when the graph JSON is re-loaded into the same app instance')
+  it.todo('app.graph.remove(node) removes the node from app.graph.nodes and cleans up connected links')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.30.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.30.v1.test.ts
new file mode 100644
index 0000000000..9682a07b1d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.30.v1.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.30 — S11.G1,S11.G3,S11.G4
+// blast_radius: 34.38  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.30 v1 — Graph change tracking, batching, and reactivity flush', () => {
+  it.todo('app.graph.change() increments an internal dirty counter observable by extensions listening to the onAfterChange event')
+  it.todo('mutations made inside a single synchronous callback are batched and produce exactly one afterChange event')
+  it.todo('app.graph.setDirtyCanvas(true, true) triggers a canvas redraw without throwing when called from an extension callback')
+  it.todo('app.registerExtension({ afterConfigureGraph }) is called after graph.configure() completes and app.graph.nodes is fully populated')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.31.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.31.v1.test.ts
new file mode 100644
index 0000000000..8a2b67ab1c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.31.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.31 — S16.DOM1,S16.DOM2,S16.DOM3,S16.DOM4
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.31 v1 — DOM injection and style management', () => {
+  it.todo('a <style> tag appended to document.head by an extension is present in the DOM after app setup completes')
+  it.todo('a DOM widget created by assigning node.widget = { type: "dom", element: HTMLElement } renders its element in the canvas overlay')
+  it.todo('document.getElementById on an id injected by an extension inside nodeCreated returns a non-null element')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.32.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.32.v1.test.ts
new file mode 100644
index 0000000000..b9ba363779
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.32.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.32 — S16.VUE1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.32 v1 — Embedded framework runtimes and Vue widget bundling', () => {
+  it.todo('an extension that imports and mounts its own Vue app into a DOM widget element does not conflict with the host Vue runtime')
+  it.todo('a Vue component mounted inside a node DOM widget can read and write node.widgets_values[index] without reactivity errors')
+  it.todo('unmounting an extension-owned Vue app on node removal does not throw and does not affect the host app\'s reactive state')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.33.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.33.v1.test.ts
new file mode 100644
index 0000000000..d9c044bcec
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.33.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.33 — S4.W6
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.33 v1 — Cross-extension DOM widget creation observation', () => {
+  it.todo('app.registerExtension({ nodeCreated }) is called after all other extensions have added their widgets to the node, making foreign widgets observable')
+  it.todo('an observer extension can read widget.name and widget.type on widgets created by a different extension in the same nodeCreated pass')
+  it.todo('wrapping a foreign widget\'s draw method via prototype patching in nodeCreated does not prevent the widget from rendering')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.34.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.34.v1.test.ts
new file mode 100644
index 0000000000..cc94101c88
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.34.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.34 — S12.UI3
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.34 v1 — Settings-panel custom dialog integration', () => {
+  it.todo('app.ui.settings.addSetting({ id, name, type, defaultValue }) registers a setting accessible via app.ui.settings.getSettingValue(id)')
+  it.todo('a setting registered with type "boolean" stores and retrieves a boolean without coercion to string')
+  it.todo('app.ui.settings.show() opens the settings dialog without throwing when called from an extension command callback')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.35.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.35.v1.test.ts
new file mode 100644
index 0000000000..730e2c4201
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.35.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.35 — S6.A5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.35 v1 — Pre-queue widget validation', () => {
+  it.todo('app.registerExtension({ beforeQueuePrompt }) is called before each queue submission and receives the prompt object')
+  it.todo('throwing an error inside beforeQueuePrompt cancels the queue submission and surfaces the error message to the user')
+  it.todo('returning false from beforeQueuePrompt cancels the submission without throwing an unhandled exception')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.36.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.36.v1.test.ts
new file mode 100644
index 0000000000..2fbdb430d5
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.36.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.36 — S4.W1,S4.W4,S4.W5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.36 v1 — PrimeVue widget component API surface', () => {
+  it.todo('a widget registered via getCustomWidgets that returns a VueNode wrapper exposes widget.value as a reactive ref readable from outside the component')
+  it.todo('setting widget.value from outside the component updates the rendered PrimeVue input on the next tick')
+  it.todo('calling widget.callback(value) on a PrimeVue-backed widget triggers the standard ComfyUI widget change pipeline')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.37.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.37.v1.test.ts
new file mode 100644
index 0000000000..58f87e269a
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.37.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.37 — S4.W5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.37 v1 — VueNode bridge timing — deferred mount access', () => {
+  it.todo('accessing widget.element synchronously inside nodeCreated returns null or undefined for a VueNode-backed widget not yet mounted')
+  it.todo('widget.element is non-null after awaiting nextTick following nodeCreated, indicating deferred mount has completed')
+  it.todo('an extension that defers its DOM manipulation to a Promise.resolve() tick reads a fully initialized VueNode element')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.38.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.38.v1.test.ts
new file mode 100644
index 0000000000..1ffd0d4b09
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.38.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.38 — S17.AM1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.38 v1 — Canvas mode observation', () => {
+  it.todo('app.canvas.read_only is a boolean that v1 extensions can read to detect whether the canvas is in read-only mode')
+  it.todo('app.canvas.state.isInteractingWithWidget reflects true while a widget is being manipulated and false otherwise')
+  it.todo('an extension listening to app.canvas on("mode_change") receives the new mode value when app.changeMode() is called')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.39.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.39.v1.test.ts
new file mode 100644
index 0000000000..55d3ff6b83
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.39.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.39 — S17.SB1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.39 v1 — Subgraph boundary event propagation', () => {
+  it.todo('a nodeCreated callback registered on the parent graph fires when a node is added inside an open subgraph')
+  it.todo('app.graph.change() called from within a subgraph propagates a dirty signal to the root graph observable')
+  it.todo('link events emitted at a subgraph boundary (input/output nodes) are observable from a root-level onConnectionChange extension hook')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.40.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.40.v1.test.ts
new file mode 100644
index 0000000000..747347847e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.40.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.40 — S17.FA1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.40 v1 — File upload and asset URL construction', () => {
+  it.todo('app.handleFile(file) returns a promise that resolves with an object containing a { name, type } matching the uploaded file')
+  it.todo('app.getPathImage(filename, type, subfolder) returns a URL string with the correct query parameters (?filename=, &type=, &subfolder=)')
+  it.todo('a LoadImage node whose widget value is set to an uploaded filename produces a URL via app.getPathImage that points to the /view endpoint')
+})
diff --git a/src/extension-api-v2/__tests__/v1/BC.41.v1.test.ts b/src/extension-api-v2/__tests__/v1/BC.41.v1.test.ts
new file mode 100644
index 0000000000..f9819d53e4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v1/BC.41.v1.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.41 — S17.WV1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.41 v1 — Widget values positional serialization fragility', () => {
+  it.todo('node.widgets_values is an ordered array whose index positions match the order widgets were appended to node.widgets')
+  it.todo('a graph JSON round-trip restores each widget.value from widgets_values[i] using the same positional index as before serialization')
+  it.todo('inserting a new widget at position 0 via node.widgets.unshift() shifts all subsequent widgets_values indices and breaks deserialization of an older snapshot')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.01.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.01.v2.test.ts
new file mode 100644
index 0000000000..f1c0ca5e75
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.01.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.01 — S2.N1,S2.N8
+// blast_radius: 37.56  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.01 v2 — Node lifecycle: creation', () => {
+  it.todo('defineNodeExtension nodeCreated callback receives a NodeHandle with valid entityId and comfyClass')
+  it.todo('nodeCreated is invoked once per node instance when the node is added to the graph')
+  it.todo('NodeHandle.getTitle() returns the node title at creation time')
+  it.todo('NodeHandle.getInputs() and getOutputs() reflect the node slot configuration at creation')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.02.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.02.v2.test.ts
new file mode 100644
index 0000000000..dd0d836946
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.02.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.02 — S2.N4
+// blast_radius: 29.35  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.02 v2 — Node lifecycle: teardown', () => {
+  it.todo('NodeHandle.on("removed", handler) fires when the node is removed from the graph')
+  it.todo('onNodeRemoved callback receives the NodeHandle of the node being torn down')
+  it.todo('removed event handler is not called again after the node is re-added as a new instance')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.03.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.03.v2.test.ts
new file mode 100644
index 0000000000..210075aab2
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.03.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.03 — S1.H1,S2.N7
+// blast_radius: 15.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.03 v2 — Node lifecycle: hydration from saved workflows', () => {
+  it.todo('defineNodeExtension loadedGraphNode callback is invoked when a workflow is loaded from JSON')
+  it.todo('loadedGraphNode receives a NodeHandle whose widget values reflect the saved workflow state')
+  it.todo('NodeHandle.on("configured", handler) fires after the node is hydrated from a saved graph')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.04.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.04.v2.test.ts
new file mode 100644
index 0000000000..0ce975b54d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.04.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.04 — S2.N10,S2.N17,S2.N19
+// blast_radius: 38.07  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.04 v2 — Node interaction: pointer, selection, resize', () => {
+  it.todo('NodeHandle.on("positionChanged", handler) fires with updated coordinates after node is moved')
+  it.todo('NodeHandle.on("sizeChanged", handler) fires with new dimensions after node is resized')
+  it.todo('NodeHandle.getPosition() returns current [x, y] after a position change event')
+  it.todo('NodeHandle.getSize() returns current [width, height] after a size change event')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.05.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.05.v2.test.ts
new file mode 100644
index 0000000000..b20efe5a04
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.05.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.05 — S4.W2,S2.N11
+// blast_radius: 33.35  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.05 v2 — Custom DOM widgets and node sizing', () => {
+  it.todo('onNodeMounted callback is invoked with the NodeHandle after the node DOM is ready')
+  it.todo('NodeHandle.getSize() reflects updated height after a custom DOM widget is inserted')
+  it.todo('WidgetHandle obtained inside onNodeMounted has a valid widgetType and name')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.06.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.06.v2.test.ts
new file mode 100644
index 0000000000..15c2c2ec14
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.06.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.06 — S2.N9,S3.C1,S3.C2
+// blast_radius: 58.97  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.06 v2 — Custom canvas drawing (per-node and canvas-level)', () => {
+  it.todo('defineNodeExtension nodeCreated can register a per-node draw callback via NodeHandle')
+  it.todo('defineExtension setup can register a canvas-level draw callback that fires each render frame')
+  it.todo('canvas-level draw callback receives a CanvasRenderingContext2D or equivalent drawing context')
+  it.todo('per-node draw callback is not invoked for nodes that belong to a different extension')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.07.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.07.v2.test.ts
new file mode 100644
index 0000000000..7212ad904f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.07.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.07 — S2.N3,S2.N12,S2.N13
+// blast_radius: 51.08  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.07 v2 — Connection observation, intercept, and veto', () => {
+  it.todo('NodeHandle.on("connected", handler) fires with slot index and connected node info when a link is made')
+  it.todo('NodeHandle.on("disconnected", handler) fires with slot index when a link is removed')
+  it.todo('connection intercept callback can return false to veto an incoming connection')
+  it.todo('connection veto does not fire the "connected" event on the target NodeHandle')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.08.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.08.v2.test.ts
new file mode 100644
index 0000000000..d35ab4255b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.08.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.08 — S10.D2
+// blast_radius: 11.81  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.08 v2 — Programmatic linking', () => {
+  it.todo('NodeHandle exposes an API to programmatically create a link between two nodes by slot index')
+  it.todo('programmatic link creation fires "connected" on the target NodeHandle')
+  it.todo('linking to an incompatible slot type is rejected without throwing an unhandled error')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.09.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.09.v2.test.ts
new file mode 100644
index 0000000000..592a10dc2e
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.09.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.09 — S10.D1,S10.D3,S15.OS1
+// blast_radius: 38.63  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.09 v2 — Dynamic slot and output mutation', () => {
+  it.todo('NodeHandle.getInputs() reflects newly added input slots after dynamic mutation')
+  it.todo('NodeHandle.getOutputs() reflects removed output slots after dynamic mutation')
+  it.todo('adding a slot via the v2 API updates the node visual without requiring a full graph reload')
+  it.todo('dynamically added output slot is serialized correctly in the workflow JSON')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.10.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.10.v2.test.ts
new file mode 100644
index 0000000000..5eb69c3f19
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.10.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.10 — S4.W1,S2.N14
+// blast_radius: 32.22  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.10 v2 — Widget value subscription', () => {
+  it.todo('WidgetHandle.on("valueChange", handler) fires with the new value when widget value changes')
+  it.todo('valueChange handler receives both the new value and the previous value')
+  it.todo('multiple subscribers on the same WidgetHandle all receive the valueChange event')
+  it.todo('WidgetHandle.getValue() returns the current value immediately after a valueChange fires')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.11.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.11.v2.test.ts
new file mode 100644
index 0000000000..e83002a6c1
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.11.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.11 — S4.W4,S4.W5,S2.N16
+// blast_radius: 28.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.11 v2 — Widget imperative state writes', () => {
+  it.todo('WidgetHandle.setValue() updates the underlying widget value and WidgetHandle.getValue() reflects it')
+  it.todo('WidgetHandle.setHidden(true) hides the widget; isHidden() returns true')
+  it.todo('WidgetHandle.setDisabled(true) disables the widget; isDisabled() returns true')
+  it.todo('setValue() triggers a valueChange event on the WidgetHandle')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.12.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.12.v2.test.ts
new file mode 100644
index 0000000000..f127e24097
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.12.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.12 — S4.W3
+// blast_radius: 27.94  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.12 v2 — Per-widget serialization transform', () => {
+  it.todo('WidgetHandle.on("beforeSerialize", handler) fires before the widget value is written to workflow JSON')
+  it.todo('beforeSerialize handler can return a transformed value that replaces the raw widget value in JSON')
+  it.todo('WidgetHandle.setSerializeEnabled(false) excludes the widget value from workflow serialization')
+  it.todo('isSerializeEnabled() reflects the current serialization-enabled state of the widget')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.13.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.13.v2.test.ts
new file mode 100644
index 0000000000..962603b76c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.13.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.13 — S2.N6,S2.N15
+// blast_radius: 47.07  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.13 v2 — Per-node serialization interception', () => {
+  it.todo('NodeHandle.on("beforeSerialize", handler) fires before the node is written to workflow JSON')
+  it.todo('beforeSerialize handler can mutate the serialized node object before it is written')
+  it.todo('per-node beforeSerialize fires for each node individually, not once for the whole graph')
+  it.todo('mutations made in beforeSerialize appear in the final workflow JSON output')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.14.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.14.v2.test.ts
new file mode 100644
index 0000000000..08ec6daaa2
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.14.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.14 — S6.A1
+// blast_radius: 46.66  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.14 v2 — Workflow → API serialization interception (graphToPrompt)', () => {
+  it.todo('defineExtension setup can register a graphToPrompt hook that intercepts the API payload')
+  it.todo('graphToPrompt hook receives the full prompt object before it is sent to the backend')
+  it.todo('mutations made in the graphToPrompt hook are reflected in the payload dispatched to the server')
+  it.todo('multiple extensions can each register a graphToPrompt hook and all are invoked in registration order')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.15.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.15.v2.test.ts
new file mode 100644
index 0000000000..1b89bb565a
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.15.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.15 — S6.A2
+// blast_radius: 20.31  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.15 v2 — Workflow loading into the editor', () => {
+  it.todo('defineExtension setup can register a loadWorkflow hook that fires when a workflow JSON is loaded')
+  it.todo('loadWorkflow hook receives the raw workflow object before nodes are instantiated')
+  it.todo('mutations made in the loadWorkflow hook are reflected in the graph after loading completes')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.16.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.16.v2.test.ts
new file mode 100644
index 0000000000..4b0b2e705a
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.16.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.16 — S2.N2
+// blast_radius: 5.74  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.16 v2 — Execution output consumption (per-node)', () => {
+  it.todo('NodeHandle.on("executed", handler) fires when the backend reports output for that node')
+  it.todo('executed handler receives the output data object associated with the node execution')
+  it.todo('executed event is not fired for nodes that were cached and not re-executed in the current run')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.17.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.17.v2.test.ts
new file mode 100644
index 0000000000..63fda17434
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.17.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.17 — S5.A1,S5.A2,S5.A3
+// blast_radius: 51.25  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.17 v2 — Backend execution lifecycle and progress events', () => {
+  it.todo('defineExtension setup can register an executionStart hook that fires when a queue run begins')
+  it.todo('defineExtension setup can register an executionComplete hook that fires when a run finishes')
+  it.todo('progress event handler receives a fraction (0–1) and the currently executing node id')
+  it.todo('executionError hook fires with an error descriptor when the backend reports a failure')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.18.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.18.v2.test.ts
new file mode 100644
index 0000000000..62a743cc4f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.18.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.18 — S6.A3
+// blast_radius: 22.74  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.18 v2 — Backend HTTP calls', () => {
+  it.todo('defineExtension setup exposes an api object with a fetchApi(path, init?) method')
+  it.todo('fetchApi prefixes the path with the ComfyUI server base URL automatically')
+  it.todo('fetchApi returns a Promise<Response> compatible with the Fetch API standard')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.19.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.19.v2.test.ts
new file mode 100644
index 0000000000..0dc7715390
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.19.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.19 — S6.A4
+// blast_radius: 12.65  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.19 v2 — Workflow execution trigger', () => {
+  it.todo('defineExtension setup exposes a queuePrompt() method that enqueues the current graph')
+  it.todo('queuePrompt() returns a Promise that resolves with the prompt id assigned by the server')
+  it.todo('queuePrompt() serializes the graph via graphToPrompt hooks before sending')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.20.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.20.v2.test.ts
new file mode 100644
index 0000000000..6d1daf0940
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.20.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.20 — S1.H5,S1.H6,S8.P1
+// blast_radius: 27.49  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.20 v2 — Custom node-type registration (frontend-only / virtual)', () => {
+  it.todo('defineNodeExtension with a nodeTypes filter restricts nodeCreated to only those node type names')
+  it.todo('a frontend-only virtual node type registered via defineNodeExtension does not require a backend counterpart')
+  it.todo('NodeHandle.type matches the registered nodeType string for a custom-registered node')
+  it.todo('custom node type can define default widgets that appear on nodeCreated without backend schema')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.21.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.21.v2.test.ts
new file mode 100644
index 0000000000..9e4c5f2a8d
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.21.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.21 — S1.H2
+// blast_radius: 7.17  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.21 v2 — Custom widget-type registration', () => {
+  it.todo('defineNodeExtension nodeCreated callback receives a NodeHandle with widgets() returning registered custom widget types')
+  it.todo('WidgetHandle.widgetType reflects the custom type string passed during widget registration')
+  it.todo('custom widget registered via v2 is accessible by name via NodeHandle.widget(name)')
+  it.todo('WidgetHandle.getOption/setOption round-trips custom widget options after registration')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.22.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.22.v2.test.ts
new file mode 100644
index 0000000000..9256e89cb4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.22.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.22 — S2.N5,S1.H3,S1.H4
+// blast_radius: 19.53  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.22 v2 — Context menu contributions (node and canvas)', () => {
+  it.todo('defineExtension shell.commandManager.registerCommand adds command visible in node context menu')
+  it.todo('defineExtension setup callback can contribute canvas-level context menu entries via CommandManager')
+  it.todo('context menu command registered via v2 receives NodeHandle as argument when triggered on a node')
+  it.todo('multiple extensions contributing context menu entries do not collide by command name')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.23.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.23.v2.test.ts
new file mode 100644
index 0000000000..a7c5c7b296
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.23.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.23 — S2.N18
+// blast_radius: 14.42  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.23 v2 — Node property bag mutations', () => {
+  it.todo('NodeHandle exposes typed property accessors rather than raw property bag mutation')
+  it.todo('setTitle() mutates the node title and getTitle() reflects the new value')
+  it.todo('NodeHandle.on("beforeSerialize") fires before serialization allowing property injection')
+  it.todo('NodeHandle.on("configured") fires after node properties are restored from serialized graph')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.24.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.24.v2.test.ts
new file mode 100644
index 0000000000..84a4034d15
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.24.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.24 — S13.SC1
+// blast_radius: 22.43  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.24 v2 — Node-def schema inspection', () => {
+  it.todo('NodeHandle.getInputs() returns typed input descriptors matching the server-side node definition')
+  it.todo('NodeHandle.getOutputs() returns typed output descriptors with correct slot indices')
+  it.todo('NodeHandle.comfyClass matches the node type string from the node-def schema')
+  it.todo('NodeHandle.type reflects the display name from the node-def schema')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.25.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.25.v2.test.ts
new file mode 100644
index 0000000000..a90a65c037
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.25.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.25 — S12.UI1
+// blast_radius: 10.98  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.25 v2 — Shell UI registration (commands, sidebars, toasts)', () => {
+  it.todo('defineExtension shell.commandManager.registerCommand registers a command retrievable by id')
+  it.todo('defineExtension shell with SidebarTabExtension adds a sidebar tab accessible by extensionId')
+  it.todo('defineExtension shell with BottomPanelExtension adds a bottom panel accessible by extensionId')
+  it.todo('defineExtension shell.toastManager.add displays a toast with the provided message and severity')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.26.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.26.v2.test.ts
new file mode 100644
index 0000000000..c213669d80
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.26.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.26 — S7.G1
+// blast_radius: 27.0  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.26 v2 — Globals as ABI (window.LiteGraph, window.comfyAPI)', () => {
+  it.todo('v2 extensions obtain graph access through defineExtension setup context, not window.LiteGraph')
+  it.todo('defineExtension init callback receives an api context object that replaces direct window.comfyAPI access')
+  it.todo('NodeHandle.entityId provides a stable identity without requiring window.LiteGraph node reference')
+  it.todo('v2 extension registered via defineExtension does not need to read window globals to function correctly')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.27.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.27.v2.test.ts
new file mode 100644
index 0000000000..677e0ef624
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.27.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.27 — S9.R1,S9.G1,S9.L1,S9.S1
+// blast_radius: 39.37  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.27 v2 — LiteGraph entity direct manipulation (reroute, group, link, slot)', () => {
+  it.todo('v2 path for reroute node manipulation is deferred — NodeHandle link/slot API not yet defined in v2 surface')
+  it.todo('v2 path for group manipulation is deferred — a GroupHandle abstraction is planned but not yet available')
+  it.todo('NodeHandle.on("connected") fires when a link is formed, providing slot and peer entityId without direct LiteGraph access')
+  it.todo('NodeHandle.on("disconnected") fires when a link is removed, providing slot index without direct LiteGraph access')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.28.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.28.v2.test.ts
new file mode 100644
index 0000000000..0e57e9e9bd
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.28.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.28 — S9.SG1
+// blast_radius: 16.89  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.28 v2 — Subgraph fan-out via set/get virtual nodes', () => {
+  it.todo('NodeHandle for a subgraph input virtual node exposes comfyClass reflecting the virtual node type')
+  it.todo('defineNodeExtension nodeCreated receives NodeHandle for virtual set/get nodes within subgraph scope')
+  it.todo('NodeHandle.entityId is stable across subgraph boundary crossings for the same virtual node instance')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.29.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.29.v2.test.ts
new file mode 100644
index 0000000000..5da9a6b9b0
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.29.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.29 — S11.G2,S14.ID1
+// blast_radius: 23.56  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.29 v2 — Graph enumeration, mutation, and cross-scope identity', () => {
+  it.todo('defineExtension setup context exposes a graph accessor that enumerates nodes as NodeHandle instances')
+  it.todo('NodeHandle.entityId is globally unique across nested subgraph scopes')
+  it.todo('graph mutation (node add/remove) dispatched through v2 API fires NodeHandle lifecycle events on affected handles')
+  it.todo('NodeHandle obtained before and after graph serialization round-trip resolves to same entityId')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.30.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.30.v2.test.ts
new file mode 100644
index 0000000000..ce135cb8f4
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.30.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.30 — S11.G1,S11.G3,S11.G4
+// blast_radius: 34.38  compat-floor: yes
+import { describe, it } from 'vitest'
+
+describe('BC.30 v2 — Graph change tracking, batching, and reactivity flush', () => {
+  it.todo('NodeHandle.on("positionChanged") fires after position mutation is flushed by the reactivity system')
+  it.todo('NodeHandle.on("sizeChanged") fires after size mutation and not during mid-batch intermediate states')
+  it.todo('batched graph mutations result in a single positionChanged event per node, not one per intermediate step')
+  it.todo('NodeHandle.on("modeChanged") fires when node enabled/disabled state is toggled through v2 API')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.31.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.31.v2.test.ts
new file mode 100644
index 0000000000..d671056c09
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.31.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.31 — S16.DOM1,S16.DOM2,S16.DOM3,S16.DOM4
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.31 v2 — DOM injection and style management', () => {
+  it.todo('v2 path for DOM injection is deferred — direct DOM manipulation has no v2 replacement yet; extensions should use SidebarTabExtension or BottomPanelExtension shell APIs instead')
+  it.todo('v2 path for style injection is deferred — scoped CSS via Vue SFC is the intended replacement but no bridge API exists yet')
+  it.todo('defineExtension shell SidebarTabExtension renders a Vue component without raw DOM injection')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.32.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.32.v2.test.ts
new file mode 100644
index 0000000000..92601d700b
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.32.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.32 — S16.VUE1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.32 v2 — Embedded framework runtimes and Vue widget bundling', () => {
+  it.todo('v2 path for embedded Vue widget bundling is deferred — extensions must not bundle their own Vue runtime; the host-provided Vue instance is the intended integration point')
+  it.todo('v2 path for embedded framework runtimes (React, Svelte) is deferred — no FrameworkBridge API exists yet in the v2 surface')
+  it.todo('defineExtension shell SidebarTabExtension accepts a Vue component using the host Vue instance without bundling a second runtime')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.33.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.33.v2.test.ts
new file mode 100644
index 0000000000..00004637e6
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.33.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.33 — S4.W6
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.33 v2 — Cross-extension DOM widget creation observation', () => {
+  it.todo('defineNodeExtension nodeCreated fires for nodes whose widgets were created by a different extension, allowing cross-extension observation via NodeHandle.widgets()')
+  it.todo('WidgetHandle obtained from NodeHandle.widgets() in a cross-extension observer has a valid widgetType reflecting the originating extension widget type')
+  it.todo('cross-extension widget observation does not require DOM querying — WidgetHandle is the sole observation surface')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.34.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.34.v2.test.ts
new file mode 100644
index 0000000000..38e14ba98f
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.34.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.34 — S12.UI3
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.34 v2 — Settings-panel custom dialog integration', () => {
+  it.todo('defineExtension shell CommandManager can register a command that opens a settings dialog without direct DOM manipulation')
+  it.todo('settings dialog integration via v2 shell API renders a Vue component provided by the extension, not injected HTML')
+  it.todo('settings registered via v2 shell are discoverable through CommandManager without coupling to settings-panel DOM structure')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.35.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.35.v2.test.ts
new file mode 100644
index 0000000000..6edd7e592c
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.35.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.35 — S6.A5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.35 v2 — Pre-queue widget validation', () => {
+  it.todo('defineExtension setup can register a pre-queue validator that receives NodeHandle instances for all nodes before execution')
+  it.todo('pre-queue validator accessing WidgetHandle.getValue() reads the current committed widget value synchronously')
+  it.todo('returning a validation error from the pre-queue hook prevents queue submission and surfaces the message via ToastManager')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.36.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.36.v2.test.ts
new file mode 100644
index 0000000000..292b1f35f9
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.36.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.36 — S4.W1,S4.W4,S4.W5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.36 v2 — PrimeVue widget component API surface', () => {
+  it.todo('WidgetHandle for a PrimeVue-backed widget returns widgetType "primevue" or the specific component name')
+  it.todo('WidgetHandle.getValue() and setValue() correctly proxy the underlying PrimeVue component model value')
+  it.todo('WidgetHandle.isHidden() and setHidden() correctly proxy the PrimeVue component visibility state')
+  it.todo('WidgetHandle.on("valueChange") fires when the PrimeVue component emits its native update event')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.37.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.37.v2.test.ts
new file mode 100644
index 0000000000..93ccf320fa
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.37.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.37 — S4.W5
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.37 v2 — VueNode bridge timing — deferred mount access', () => {
+  it.todo('defineNodeExtension loadedGraphNode callback fires after the VueNode component is mounted and NodeHandle.widgets() is non-empty')
+  it.todo('WidgetHandle accessed inside loadedGraphNode callback returns a fully initialized value from getValue()')
+  it.todo('NodeHandle.on("configured") guarantees widget handles are accessible before the handler returns, without requiring a nextTick deferral')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.38.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.38.v2.test.ts
new file mode 100644
index 0000000000..a96fc5afa6
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.38.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.38 — S17.AM1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.38 v2 — Canvas mode observation', () => {
+  it.todo('defineExtension setup context exposes a canvas mode observable that emits the current interaction mode without direct LiteGraph access')
+  it.todo('NodeHandle.on("modeChanged") fires when canvas switches between normal, bypass, and mute modes affecting a given node')
+  it.todo('canvas mode changes are observable via v2 setup context without polling window.LiteGraph.CANVAS_MODE')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.39.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.39.v2.test.ts
new file mode 100644
index 0000000000..f84c0e1611
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.39.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.39 — S17.SB1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.39 v2 — Subgraph boundary event propagation', () => {
+  it.todo('NodeHandle.on("executed") fires for nodes inside a subgraph when the subgraph execution completes, propagated through the subgraph boundary')
+  it.todo('NodeHandle.on("removed") fires for subgraph-interior nodes when the containing subgraph node is deleted from the parent graph')
+  it.todo('defineNodeExtension nodeCreated receives NodeHandle for nodes added dynamically inside a subgraph after initial load')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.40.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.40.v2.test.ts
new file mode 100644
index 0000000000..287d3cb174
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.40.v2.test.ts
@@ -0,0 +1,9 @@
+// DB cross-ref: BC.40 — S17.FA1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.40 v2 — File upload and asset URL construction', () => {
+  it.todo('defineExtension init context exposes a file upload helper that returns an asset URL without requiring window.comfyAPI.fileManager access')
+  it.todo('WidgetHandle for an upload widget returns a getValue() result whose URL is constructed through the v2 asset URL builder')
+  it.todo('asset URL constructed via v2 helper resolves consistently with the server base URL regardless of proxy configuration')
+})
diff --git a/src/extension-api-v2/__tests__/v2/BC.41.v2.test.ts b/src/extension-api-v2/__tests__/v2/BC.41.v2.test.ts
new file mode 100644
index 0000000000..2763d81782
--- /dev/null
+++ b/src/extension-api-v2/__tests__/v2/BC.41.v2.test.ts
@@ -0,0 +1,10 @@
+// DB cross-ref: BC.41 — S17.WV1
+// blast_radius: 0.0  compat-floor: no
+import { describe, it } from 'vitest'
+
+describe('BC.41 v2 — Widget values positional serialization fragility', () => {
+  it.todo('WidgetHandle.on("beforeSerialize") allows extensions to mutate the serialized value by name, not by positional index')
+  it.todo('WidgetHandle.isSerializeEnabled() and setSerializeEnabled(false) exclude the widget from positional serialization without shifting other widget indices')
+  it.todo('WidgetHandle.name is stable across serialization round-trips and does not depend on widget insertion order')
+  it.todo('NodeHandle.widget(name) resolves the correct WidgetHandle after a different widget on the same node has been removed')
+})
diff --git a/src/extension-api/README.md b/src/extension-api/README.md
new file mode 100644
index 0000000000..66f3b863ad
--- /dev/null
+++ b/src/extension-api/README.md
@@ -0,0 +1,65 @@
+# Extension API — Public Source of Truth
+
+> **Status**: scaffolded. Implementation pending PKG2 — see
+> `../../../plans/P2-extension-api-package.md` and
+> `../../../plans/prompts/PKG2-author-declaration.md` in the workspace
+> root.
+
+This folder is the single source of truth for the public ComfyUI extension
+API. Every file here is part of the published `@comfyorg/extension-api`
+npm package. Do not re-export from `/src` — this barrel is the **published
+package entry point**, which is the explicit exception to the project's
+"no barrel files in /src" rule (root AGENTS.md rule #19).
+
+## Intended structure (post-PKG2)
+
+```
+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
+```
+
+## What about v1?
+
+v1 (`ComfyExtension` interface in `../types/comfy.ts`, `app.registerExtension(...)`
+runtime entry point in `../scripts/app.ts`) **stays in its current locations**.
+Custom extensions in the wild consume the runtime entry point, not the type
+file — moving the type file would churn ~30 internal imports for zero runtime
+benefit. The v1↔v2 distinction is at the entry point (D6 Part 1), not the folder.
+
+## Authoring rules
+
+1. **Hand-authored**, not generated. This is a public API; we own the
+   shape.
+2. **No `any`, no `as any`, no `@ts-expect-error`.** If you need an
+   escape hatch, the type is wrong.
+3. Every public type has a TSDoc block with at minimum:
+   - 1-line summary
+   - `@stability` tag (`stable` | `experimental` | `deprecated`)
+   - `@example` block
+4. Naming follows D6 Part 3:
+   - Read-only invariants (set at construction): accessor (`get name()`)
+   - Read-only state (changes over time): method (`getValue()`)
+   - Mutating actions: method (`setValue(v)`)
+   - Boolean predicates: method (`isHidden()`)
+5. Events follow D5: typed payloads, no `Function`, split-channel events
+   (`valueChange`/`optionChange`/`propertyChange`).
+6. No internal types (`World`, `Component<T>`, branded `EntityId`)
+   leak through this barrel.
+
+## Cross-references
+
+- `decisions/D5-events-and-payload-typing.md`
+- `decisions/D6-parallel-paths-migration.md`
+- `decisions/D7-widget-shape-and-persistence.md` (gating blocker for
+  `widget.ts`)
+- `decisions/D8-world-vue-reactive-adapter.md`
+- `plans/P2-extension-api-package.md`
+- `plans/P1-comfy-extension-v2-api.md`
diff --git a/src/extension-api/events.ts b/src/extension-api/events.ts
new file mode 100644
index 0000000000..4b9e2dc543
--- /dev/null
+++ b/src/extension-api/events.ts
@@ -0,0 +1,42 @@
+/**
+ * Shared event infrastructure for the ComfyUI extension API.
+ *
+ * @stability stable
+ * @packageDocumentation
+ */
+
+/**
+ * A typed event handler function.
+ *
+ * @typeParam E - The event payload type.
+ * @stability stable
+ * @example
+ * ```ts
+ * const handler: Handler<WidgetValueChangeEvent<number>> = (e) => {
+ *   console.log(e.oldValue, '->', e.newValue)
+ * }
+ * ```
+ */
+export type Handler<E> = (event: E) => void
+
+/**
+ * A typed async-capable event handler. Only valid for events that explicitly
+ * support async handling (currently only `beforeSerialize`).
+ *
+ * @typeParam E - The event payload type.
+ * @stability stable
+ */
+export type AsyncHandler<E> = (event: E) => void | Promise<void>
+
+/**
+ * Cleanup function returned by `on()` — call to remove the listener.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * const off = node.on('executed', handler)
+ * // later:
+ * off()
+ * ```
+ */
+export type Unsubscribe = () => void
diff --git a/src/extension-api/identifiers.ts b/src/extension-api/identifiers.ts
new file mode 100644
index 0000000000..11ec1fb8e4
--- /dev/null
+++ b/src/extension-api/identifiers.ts
@@ -0,0 +1,25 @@
+/**
+ * Node identity helpers — re-exported from internal `nodeIdentification.ts`.
+ *
+ * `NodeLocatorId` and `NodeExecutionId` are the two stable node identity
+ * primitives in the public API. All extension-facing code that needs to
+ * reference a node across subgraph boundaries or execution runs should use
+ * these rather than raw LiteGraph integer node IDs.
+ *
+ * @stability stable
+ * @packageDocumentation
+ */
+
+export type {
+  NodeLocatorId,
+  NodeExecutionId
+} from '@/types/nodeIdentification'
+
+export {
+  isNodeLocatorId,
+  isNodeExecutionId,
+  parseNodeLocatorId,
+  createNodeLocatorId,
+  parseNodeExecutionId,
+  createNodeExecutionId
+} from '@/types/nodeIdentification'
diff --git a/src/extension-api/index.ts b/src/extension-api/index.ts
new file mode 100644
index 0000000000..dd73132a1d
--- /dev/null
+++ b/src/extension-api/index.ts
@@ -0,0 +1,125 @@
+/**
+ * @comfyorg/extension-api — Public Extension API for ComfyUI
+ *
+ * This barrel is the published package entry point. Every export here is
+ * part of the stable public contract that extension authors depend on.
+ *
+ * Import directly — no dependency on `window.app` at module evaluation time:
+ *
+ * ```ts
+ * import { defineNodeExtension, defineExtension } from '@comfyorg/extension-api'
+ * ```
+ *
+ * ## API surface overview
+ *
+ * | Export | Purpose |
+ * |--------|---------|
+ * | `defineNodeExtension` | Register a node-scoped extension (the primary entry point) |
+ * | `defineExtension` | Register an app-scoped extension (init, setup, shell UI) |
+ * | `onNodeMounted`, `onNodeRemoved` | Implicit-context lifecycle hooks (call inside nodeCreated) |
+ * | `NodeHandle` | Controlled access to node state and events |
+ * | `WidgetHandle` | Controlled access to widget state and events |
+ * | `WidgetBeforeQueueEvent` | Pre-queue validation event — call `reject(msg)` to cancel |
+ * | `SlotInfo` | Read-only slot snapshot |
+ * | `NodeEntityId`, `WidgetEntityId`, `SlotEntityId` | Branded entity IDs |
+ * | Shell UI types | `SidebarTabExtension`, `BottomPanelExtension`, `CommandManager`, etc. |
+ * | Identity helpers | `NodeLocatorId`, `NodeExecutionId`, parsers, type guards |
+ *
+ * ## API style (D3.3)
+ *
+ * The public API is **event + getter/setter**, not signals. Vue reactivity is
+ * the internal engine; extension authors never import from Vue or use
+ * `ref`/`computed`/`effect` directly. State is read via methods (`getValue()`,
+ * `getPosition()`), mutated via command-dispatch methods (`setValue()`,
+ * `setPosition()`), and observed via typed event subscriptions (`on('executed', fn)`).
+ * Read-only invariants (set at construction, never change) are exposed as
+ * accessors (`get entityId`, `get type`).
+ *
+ * ## Barrel-file rule exception
+ *
+ * ComfyUI_frontend AGENTS.md rule #19 normally forbids barrel files in `/src`.
+ * This barrel is the **published package entry point** — not an internal
+ * re-export — and is the explicit exception documented in AGENTS.md.
+ *
+ * @packageDocumentation
+ */
+
+// ── Registration function types ───────────────────────────────────────────────
+export type {
+  ExtensionOptions,
+  NodeExtensionOptions,
+  WidgetExtensionOptions
+} from './lifecycle'
+
+// ── Registration function implementations ────────────────────────────────────
+// Runtime implementations live in the service; the types above are the
+// public contract. The barrel re-exports the concrete fns from the service
+// so `import { defineNodeExtension } from '@comfyorg/extension-api'` works
+// at both typecheck and runtime.
+export {
+  defineExtension,
+  defineNodeExtension,
+  defineWidgetExtension,
+  startExtensionSystem
+} from '@/services/extension-api-service'
+
+// ── Implicit-context lifecycle hooks ─────────────────────────────────────────
+export { onNodeMounted, onNodeRemoved } from './lifecycle'
+
+// ── NodeHandle and related types ─────────────────────────────────────────────
+export type {
+  NodeHandle,
+  NodeEntityId,
+  SlotEntityId,
+  SlotInfo,
+  SlotDirection,
+  NodeMode,
+  Point,
+  Size,
+  NodeExecutedEvent,
+  NodeConnectedEvent,
+  NodeDisconnectedEvent,
+  NodePositionChangedEvent,
+  NodeSizeChangedEvent,
+  NodeModeChangedEvent,
+  NodeBeforeSerializeEvent
+} from './node'
+
+// ── WidgetHandle and related types ────────────────────────────────────────────
+export type {
+  WidgetHandle,
+  WidgetEntityId,
+  WidgetValue,
+  WidgetOptions,
+  WidgetValueChangeEvent,
+  WidgetOptionChangeEvent,
+  WidgetPropertyChangeEvent,
+  WidgetBeforeSerializeEvent,
+  WidgetBeforeQueueEvent
+} from './widget'
+
+// ── Shared event infrastructure ───────────────────────────────────────────────
+export type { Handler, AsyncHandler, Unsubscribe } from './events'
+
+// ── Shell UI types (sidebar, bottom panel, commands, toasts) ──────────────────
+export type {
+  SidebarTabExtension,
+  BottomPanelExtension,
+  VueExtension,
+  CustomExtension,
+  ToastMessageOptions,
+  ToastManager,
+  ExtensionManager,
+  CommandManager
+} from './shell'
+
+// ── Identity helpers ──────────────────────────────────────────────────────────
+export type { NodeLocatorId, NodeExecutionId } from './identifiers'
+export {
+  isNodeLocatorId,
+  isNodeExecutionId,
+  parseNodeLocatorId,
+  createNodeLocatorId,
+  parseNodeExecutionId,
+  createNodeExecutionId
+} from './identifiers'
diff --git a/src/extension-api/lifecycle.ts b/src/extension-api/lifecycle.ts
new file mode 100644
index 0000000000..7f86a6b067
--- /dev/null
+++ b/src/extension-api/lifecycle.ts
@@ -0,0 +1,306 @@
+/**
+ * Extension lifecycle — `defineExtension`, `defineNodeExtension`, and
+ * the implicit-context lifecycle hooks (`onNodeMounted`, `onNodeRemoved`).
+ *
+ * Design decisions (D10):
+ * - D10a: `currentExtension` global, Vue-style. Hook factories read the slot
+ *   implicitly. Lifecycle hooks must be called synchronously inside `setup()`.
+ * - D10b: Hook firing order = registration order with lexicographic tie-break
+ *   on extension name.
+ * - D10c: `setup()` is synchronous. `async setup` throws in dev, emits
+ *   console.error in prod.
+ * - D10d: The object returned by `setup()` is wrapped with `proxyRefs()` so
+ *   callers read `entity.extensionState['my-ext'].count` without `.value`.
+ *
+ * Entry-point design (D6 Part 1): module-level import only. Extensions do NOT
+ * depend on `window.app` being initialized at registration time.
+ *
+ * @stability stable
+ * @packageDocumentation
+ */
+
+import type { NodeHandle } from './node'
+import type { WidgetHandle } from './widget'
+
+// ─── Extension options ───────────────────────────────────────────────────────
+
+/**
+ * Options for `defineNodeExtension`. Describes an extension that reacts to
+ * node lifecycle events.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * import { defineNodeExtension } from '@comfyorg/extension-api'
+ *
+ * export default defineNodeExtension({
+ *   name: 'my-org.my-extension',
+ *   nodeTypes: ['KSampler'],
+ *
+ *   nodeCreated(node) {
+ *     node.on('executed', (e) => console.log('done', e.output))
+ *   }
+ * })
+ * ```
+ */
+export interface NodeExtensionOptions {
+  /**
+   * Globally unique extension name. Used for scope registry keying, hook
+   * ordering (D10b lexicographic tie-break), and debug messages.
+   *
+   * Convention: `'org.extension-name'` or `'Comfy.ExtensionName'`.
+   *
+   * @stability stable
+   */
+  name: string
+
+  /**
+   * Filter to specific `comfyClass` names. When omitted, the extension
+   * receives `nodeCreated` / `loadedGraphNode` for every node type.
+   *
+   * Replaces the v1 `beforeRegisterNodeDef` filtering pattern (DEP1).
+   *
+   * @stability stable
+   * @example
+   * ```ts
+   * nodeTypes: ['KSampler', 'KSamplerAdvanced']
+   * ```
+   */
+  nodeTypes?: string[]
+
+  /**
+   * Called once per node instance when the node is first created (typed in,
+   * pasted from clipboard, duplicated, or loaded without an existing workflow).
+   *
+   * - Runs inside a Vue `EffectScope`. All `watch` / `computed` / `onNodeMounted`
+   *   calls made here are captured and disposed automatically on node removal.
+   * - Must be synchronous (D10c). Kick off async work inside the body; use
+   *   `loading: ref(true)` for async-dependent state.
+   * - Called only once per entity ID lifetime. Copy/paste creates a fresh entity
+   *   and fires `nodeCreated` again on the new entity (D12 reset-to-fresh).
+   *
+   * @stability stable
+   */
+  nodeCreated?(node: NodeHandle): void
+
+  /**
+   * Called once per node instance when the node is restored from a saved
+   * workflow. Widget values are already populated when this fires.
+   *
+   * Same rules as `nodeCreated`. Exactly one of `nodeCreated` or
+   * `loadedGraphNode` fires per node entity, never both.
+   *
+   * Replaces the v1 `loadedGraphNode` hook (which had near-zero real usage per
+   * R4-P11) and `nodeType.prototype.onConfigure` patching.
+   *
+   * @stability stable
+   */
+  loadedGraphNode?(node: NodeHandle): void
+}
+
+/**
+ * Options for the global `defineExtension` entry point. Covers extension-wide
+ * lifecycle and shell UI contributions.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * import { defineExtension } from '@comfyorg/extension-api'
+ *
+ * export default defineExtension({
+ *   name: 'my-org.my-extension',
+ *   async setup() {
+ *     // App is ready; register commands, sidebar tabs, etc.
+ *   }
+ * })
+ * ```
+ */
+export interface ExtensionOptions {
+  /**
+   * Globally unique extension name. Matches the format of
+   * `NodeExtensionOptions.name`.
+   *
+   * @stability stable
+   */
+  name: string
+
+  /**
+   * Runs once during app initialization (after the app is mounted but before
+   * the first workflow is loaded). Equivalent to the v1 `ComfyExtension.init`.
+   *
+   * @stability stable
+   */
+  init?(): void | Promise<void>
+
+  /**
+   * Runs once after the app and all core extensions are initialized. Equivalent
+   * to the v1 `ComfyExtension.setup`. Safe to call shell UI registration APIs
+   * (`ExtensionManager`, `CommandManager`) here.
+   *
+   * @stability stable
+   */
+  setup?(): void | Promise<void>
+}
+
+// ─── Widget extension options ─────────────────────────────────────────────────
+
+/**
+ * Options for `defineWidgetExtension`. Describes an extension that provides a
+ * custom widget type with its own DOM rendering.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * import { defineWidgetExtension } from '@comfyorg/extension-api'
+ *
+ * export default defineWidgetExtension({
+ *   name: 'my-org.color-picker',
+ *   type: 'COLOR_PICKER',
+ *
+ *   widgetCreated(widget, node) {
+ *     return {
+ *       render(container) { /* mount color picker DOM *\/ },
+ *       destroy()        { /* cleanup *\/ }
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export interface WidgetExtensionOptions {
+  /** Globally unique extension name. */
+  name: string
+  /** Widget type string this extension provides (e.g. `'COLOR_PICKER'`). */
+  type: string
+
+  /**
+   * Called once per widget instance. Return a `{ render, destroy }` pair for
+   * custom DOM rendering, or `void` for non-visual widgets.
+   *
+   * @stability experimental
+   */
+  widgetCreated?(
+    widget: WidgetHandle,
+    parentNode: NodeHandle | null
+  ): { render(container: HTMLElement): void; destroy?(): void } | void
+}
+
+// ─── Registration functions ──────────────────────────────────────────────────
+
+/**
+ * Register a node extension. The runtime calls `nodeCreated` or
+ * `loadedGraphNode` once per node entity matching `nodeTypes`.
+ *
+ * This is the primary entry point for extensions that interact with nodes and
+ * widgets. Import directly from `@comfyorg/extension-api` — no dependency on
+ * `window.app` at module evaluation time (D6 Part 1).
+ *
+ * Hook firing order across multiple extensions on the same entity follows
+ * extension registration order with a lexicographic tie-break on `name` (D10b).
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * import { defineNodeExtension } from '@comfyorg/extension-api'
+ *
+ * export default defineNodeExtension({
+ *   name: 'Comfy.PreviewAny',
+ *   nodeTypes: ['PreviewAny'],
+ *
+ *   nodeCreated(node) {
+ *     const preview = node.addWidget('STRING', 'preview', '', {
+ *       multiline: true, readonly: true, serialize: false
+ *     })
+ *     node.on('executed', (e) => {
+ *       preview.setValue(String(e.output['text'] ?? ''))
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export declare function defineNodeExtension(
+  options: NodeExtensionOptions
+): NodeExtensionOptions
+
+/**
+ * Register an extension for app-wide lifecycle and shell UI contributions.
+ *
+ * Use `defineNodeExtension` for node/widget interactions. Use this for
+ * `init`, `setup`, sidebar tabs, commands, and other app-level concerns.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * import { defineExtension } from '@comfyorg/extension-api'
+ *
+ * export default defineExtension({
+ *   name: 'my-org.my-extension',
+ *   setup() {
+ *     console.log('Extension ready')
+ *   }
+ * })
+ * ```
+ */
+export declare function defineExtension(
+  options: ExtensionOptions
+): ExtensionOptions
+
+/**
+ * Register a custom widget type. Called once at module load time to declare
+ * a new widget kind.
+ *
+ * @stability experimental
+ */
+export declare function defineWidgetExtension(
+  options: WidgetExtensionOptions
+): WidgetExtensionOptions
+
+// ─── Implicit-context lifecycle hooks (D10a) ─────────────────────────────────
+//
+// These functions read the _currentScope global slot set by the runtime
+// immediately before invoking nodeCreated()/loadedGraphNode(). They must be
+// called synchronously during setup — calling them after an `await` is a no-op
+// in production and throws in development.
+//
+// The ctx.onNodeMounted(fn) form from D6 Part 1 examples is a thin alias on
+// NodeHandle that calls these same functions under the hood.
+
+export {
+  /**
+   * Register a callback to fire when the node entity is fully mounted to the
+   * graph (the reactive mount watcher has run, the scope is active, and
+   * `setup()` has completed).
+   *
+   * Must be called synchronously inside `nodeCreated` or `loadedGraphNode`.
+   *
+   * @stability experimental
+   * @example
+   * ```ts
+   * nodeCreated(node) {
+   *   onNodeMounted(() => {
+   *     // Safe to access DOM widgets, canvas, etc.
+   *   })
+   * }
+   * ```
+   */
+  onNodeMounted,
+  /**
+   * Register a callback to fire when the node entity is removed from the graph
+   * (NOT on subgraph promotion, which is a DOM-move, not an unmount).
+   *
+   * Replaces `nodeType.prototype.onRemoved` patching (S2.N4 — 7+ repos,
+   * 4.89 blast radius).
+   *
+   * Must be called synchronously inside `nodeCreated` or `loadedGraphNode`.
+   *
+   * @stability experimental
+   * @example
+   * ```ts
+   * nodeCreated(node) {
+   *   onNodeRemoved(() => {
+   *     cleanup()
+   *   })
+   * }
+   * ```
+   */
+  onNodeRemoved,
+} from '@/services/extension-api-service'
diff --git a/src/extension-api/node.ts b/src/extension-api/node.ts
new file mode 100644
index 0000000000..2d758126dc
--- /dev/null
+++ b/src/extension-api/node.ts
@@ -0,0 +1,524 @@
+/**
+ * NodeHandle — the controlled surface for node access in v2 extensions.
+ *
+ * Reads query ECS World components directly. Writes dispatch commands
+ * (undo-able, serializable, validatable). Events are backed by Vue
+ * reactivity watching World component changes.
+ *
+ * Design decisions:
+ * - Accessor/method hybrid per D6 Part 3: invariants = readonly, state = methods
+ * - Event channel naming per D5: camelCase, action-verb, `before` prefix for pre-mutation
+ * - No World/Component/Command types leak through this interface per D3.4
+ * - `node.properties` exposed as migration shim (v1 compat) per D7 Part 2
+ * - `beforeSerialize` event collapses four v1 serialization surfaces per D7 Part 4
+ *
+ * @stability stable
+ * @packageDocumentation
+ */
+
+import type { AsyncHandler, Handler, Unsubscribe } from './events'
+import type { WidgetHandle, WidgetOptions } from './widget'
+
+// ─── Entity ID ──────────────────────────────────────────────────────────────
+
+/**
+ * Branded entity ID for nodes. Prevents mixing node IDs with widget IDs
+ * at compile time. The underlying value is always `number`.
+ *
+ * @stability stable
+ */
+export type NodeEntityId = number & { readonly __brand: 'NodeEntityId' }
+
+// ─── Geometry ────────────────────────────────────────────────────────────────
+
+/**
+ * A 2D point as `[x, y]`.
+ *
+ * @stability stable
+ */
+export type Point = [x: number, y: number]
+
+/**
+ * A 2D size as `[width, height]`.
+ *
+ * @stability stable
+ */
+export type Size = [width: number, height: number]
+
+// ─── Enums ───────────────────────────────────────────────────────────────────
+
+/**
+ * LiteGraph node execution mode.
+ *
+ * - `0` — Always execute.
+ * - `1` — Never execute (muted).
+ * - `2` — Bypass (passthrough).
+ * - `3` — Execute once.
+ * - `4` — Execute on trigger.
+ *
+ * @stability stable
+ */
+export type NodeMode = 0 | 1 | 2 | 3 | 4
+
+/**
+ * Direction of a slot on a node.
+ *
+ * @stability stable
+ */
+export type SlotDirection = 'input' | 'output'
+
+// ─── Slot info ───────────────────────────────────────────────────────────────
+
+/**
+ * Read-only snapshot of a single slot (input or output) on a node.
+ *
+ * @stability stable
+ */
+export interface SlotInfo {
+  /** Branded entity ID for this slot. */
+  readonly entityId: SlotEntityId
+  /** Slot name as declared in `INPUT_TYPES` or `addInput`/`addOutput`. */
+  readonly name: string
+  /** Slot type string (e.g. `'IMAGE'`, `'LATENT'`, `'*'`). */
+  readonly type: string
+  /** Whether this is an input or output slot. */
+  readonly direction: SlotDirection
+  /** The node this slot belongs to. */
+  readonly nodeEntityId: NodeEntityId
+}
+
+/**
+ * Branded entity ID for slots. Prevents mixing slot IDs with node/widget IDs.
+ *
+ * @stability stable
+ */
+export type SlotEntityId = number & { readonly __brand: 'SlotEntityId' }
+
+// ─── Event payloads ─────────────────────────────────────────────────────────
+
+/**
+ * Payload for `node.on('executed', handler)`.
+ *
+ * Replaces the v1 `nodeType.prototype.onExecuted` patching pattern.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * node.on('executed', (e) => {
+ *   const text = e.output['text'] as string[]
+ *   previewWidget.setValue(text.join('\n'))
+ * })
+ * ```
+ */
+export interface NodeExecutedEvent {
+  /** The backend execution output for this node. Shape varies by node type. */
+  readonly output: Record<string, unknown>
+}
+
+/**
+ * Payload for `node.on('connected', handler)`.
+ *
+ * Replaces `nodeType.prototype.onConnectInput` / `onConnectOutput` and
+ * `nodeType.prototype.onConnectionsChange` patching.
+ *
+ * @stability stable
+ */
+export interface NodeConnectedEvent {
+  /** The local slot that was connected. */
+  readonly slot: SlotInfo
+  /** The remote slot on the other node. */
+  readonly remote: SlotInfo
+}
+
+/**
+ * Payload for `node.on('disconnected', handler)`.
+ *
+ * @stability stable
+ */
+export interface NodeDisconnectedEvent {
+  /** The local slot that was disconnected. */
+  readonly slot: SlotInfo
+}
+
+/**
+ * Payload for `node.on('positionChanged', handler)`.
+ *
+ * @stability stable
+ */
+export interface NodePositionChangedEvent {
+  /** The new position. */
+  readonly pos: Point
+}
+
+/**
+ * Payload for `node.on('sizeChanged', handler)`.
+ *
+ * @stability stable
+ */
+export interface NodeSizeChangedEvent {
+  /** The new size. */
+  readonly size: Size
+}
+
+/**
+ * Payload for `node.on('modeChanged', handler)`.
+ *
+ * @stability stable
+ */
+export interface NodeModeChangedEvent {
+  /** The new execution mode. */
+  readonly mode: NodeMode
+}
+
+/**
+ * Payload for `node.on('beforeSerialize', handler)`.
+ *
+ * The node-level equivalent of `WidgetBeforeSerializeEvent`. Replaces both
+ * `node.onSerialize` and `nodeType.prototype.serialize` patching patterns
+ * (v1 S2.N6, S2.N15 touch-points).
+ *
+ * Mutate `event.data` in place to append extra fields (replaces `onSerialize`).
+ * Call `event.replace(fn)` to wrap the entire serialized object (replaces
+ * `prototype.serialize = function(){ const r = orig.call(this); … }`).
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * // Append a field
+ * node.on('beforeSerialize', (e) => {
+ *   e.data['my_extra'] = computeExtra()
+ * })
+ *
+ * // Wrap the serialized object
+ * node.on('beforeSerialize', (e) => {
+ *   e.replace((orig) => ({ ...orig, wrapped: true }))
+ * })
+ * ```
+ */
+export interface NodeBeforeSerializeEvent {
+  /** Which serialization path triggered this. */
+  readonly context: 'workflow' | 'prompt' | 'clone' | 'subgraph-promote'
+
+  /**
+   * The mutable serialized node object. Mutate in place to append fields.
+   * Type intentionally loose — the exact shape is `ISerialisedNode`.
+   */
+  readonly data: Record<string, unknown>
+
+  /**
+   * Replace the serialized object by providing a transform function.
+   * `fn` receives the current `data` and should return the replacement.
+   * Calling this multiple times chains: each call's `fn` receives the
+   * previous call's output.
+   */
+  replace(fn: (orig: Record<string, unknown>) => Record<string, unknown>): void
+}
+
+// ─── NodeHandle ──────────────────────────────────────────────────────────────
+
+/**
+ * Controlled surface for node access. Reads query the ECS World; writes
+ * dispatch commands. Events are Vue-reactive watches on World components.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * import { defineNodeExtension } from '@comfyorg/extension-api'
+ *
+ * export default defineNodeExtension({
+ *   name: 'my-size-enforcer',
+ *   nodeTypes: ['MyCustomNode'],
+ *
+ *   nodeCreated(node) {
+ *     const [w, h] = node.getSize()
+ *     node.setSize([Math.max(w, 300), Math.max(h, 200)])
+ *
+ *     node.on('executed', (e) => {
+ *       console.log('output:', e.output)
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export interface NodeHandle {
+  // ── IDENTITY ──────────────────────────────────────────────────────────────
+
+  /**
+   * Stable entity ID for this node. Branded to prevent mixing with
+   * `WidgetEntityId` at compile time.
+   *
+   * @stability stable
+   */
+  readonly entityId: NodeEntityId
+
+  /**
+   * The LiteGraph node type string (e.g. `'KSampler'`).
+   * Read-only invariant: set at construction, never changes.
+   *
+   * @stability stable
+   */
+  readonly type: string
+
+  /**
+   * The ComfyUI backend class name (e.g. `'KSampler'`).
+   * Equal to `type` for most nodes; differs for reroute/virtual nodes.
+   * Read-only invariant.
+   *
+   * @stability stable
+   */
+  readonly comfyClass: string
+
+  // ── SPATIAL STATE ─────────────────────────────────────────────────────────
+
+  /**
+   * Returns the node's current canvas position as `[x, y]`.
+   *
+   * @stability stable
+   */
+  getPosition(): Point
+
+  /**
+   * Moves the node to a new canvas position. Dispatches a `MoveNode` command.
+   *
+   * @stability stable
+   */
+  setPosition(pos: Point): void
+
+  /**
+   * Returns the node's current size as `[width, height]`.
+   *
+   * @stability stable
+   */
+  getSize(): Size
+
+  /**
+   * Resizes the node. Dispatches a `ResizeNode` command.
+   *
+   * @stability stable
+   */
+  setSize(size: Size): void
+
+  // ── VISUAL STATE ──────────────────────────────────────────────────────────
+
+  /**
+   * Returns the node's display title. Defaults to the node type string.
+   *
+   * @stability stable
+   */
+  getTitle(): string
+
+  /**
+   * Sets the node's display title. Dispatches a `SetNodeVisual` command.
+   *
+   * @stability stable
+   */
+  setTitle(title: string): void
+
+  /**
+   * Returns `true` if the node is currently selected on the canvas.
+   *
+   * @stability stable
+   */
+  isSelected(): boolean
+
+  // ── EXECUTION MODE ────────────────────────────────────────────────────────
+
+  /**
+   * Returns the node's current execution mode.
+   *
+   * @stability stable
+   */
+  getMode(): NodeMode
+
+  /**
+   * Sets the node's execution mode. Dispatches a `SetNodeMode` command.
+   *
+   * @stability stable
+   */
+  setMode(mode: NodeMode): void
+
+  // ── PROPERTIES (migration shim) ───────────────────────────────────────────
+
+  /**
+   * Returns a per-node-instance property by key.
+   *
+   * In v2, prefer routing persistent state through widget values or
+   * `beforeSerialize` events. `node.properties` is kept as a migration shim
+   * for v1 extensions that used it for per-instance widget config (e.g. min/max).
+   *
+   * @stability stable
+   */
+  getProperty<T = unknown>(key: string): T | undefined
+
+  /**
+   * Returns a copy of all per-node-instance properties.
+   *
+   * @stability stable
+   */
+  getProperties(): Record<string, unknown>
+
+  /**
+   * Sets a per-node-instance property. Dispatches a `SetNodeProperty` command.
+   *
+   * In v2, prefer `widget.setOption(key, value)` for widget-scoped per-instance
+   * config (it persists to the `widget_options` sidecar in the workflow JSON).
+   *
+   * @stability stable
+   */
+  setProperty(key: string, value: unknown): void
+
+  // ── WIDGETS ───────────────────────────────────────────────────────────────
+
+  /**
+   * Returns a `WidgetHandle` for the named widget, or `undefined` if no such
+   * widget exists on this node.
+   *
+   * @stability stable
+   * @example
+   * ```ts
+   * const steps = node.widget('steps')
+   * if (steps) steps.setValue(20)
+   * ```
+   */
+  widget(name: string): WidgetHandle | undefined
+
+  /**
+   * Returns all widgets on this node as `WidgetHandle` instances.
+   *
+   * @stability stable
+   */
+  widgets(): readonly WidgetHandle[]
+
+  /**
+   * Adds a new widget to this node.
+   *
+   * @param type - Widget type string (e.g. `'INT'`, `'STRING'`, `'COMBO'`).
+   * @param name - Unique widget name on this node.
+   * @param defaultValue - Initial value.
+   * @param options - Optional type-specific options.
+   * @returns The new `WidgetHandle`.
+   * @stability stable
+   */
+  addWidget(
+    type: string,
+    name: string,
+    defaultValue: unknown,
+    options?: Partial<WidgetOptions>
+  ): WidgetHandle
+
+  // ── SLOTS ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns all input slots on this node.
+   *
+   * @stability stable
+   */
+  inputs(): readonly SlotInfo[]
+
+  /**
+   * Returns all output slots on this node.
+   *
+   * @stability stable
+   */
+  outputs(): readonly SlotInfo[]
+
+  // ── EVENTS ────────────────────────────────────────────────────────────────
+
+  /**
+   * Subscribe to node removal (graph deletion, not subgraph promotion).
+   *
+   * Replaces the v1 `nodeType.prototype.onRemoved` patching pattern.
+   * Does NOT fire on subgraph promotion — the node's entity ID is preserved
+   * across promotion (see D9 Phase A notes and D12).
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(event: 'removed', handler: Handler<void>): Unsubscribe
+
+  /**
+   * Subscribe to backend execution completion for this node.
+   *
+   * Replaces the v1 `nodeType.prototype.onExecuted` patching pattern (the
+   * most widely used anti-pattern per R4-P3; 5+ confirmed repos).
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(event: 'executed', handler: Handler<NodeExecutedEvent>): Unsubscribe
+
+  /**
+   * Subscribe to workflow hydration (node loaded from a saved workflow).
+   *
+   * Replaces the v1 `nodeType.prototype.onConfigure` / `loadedGraphNode`
+   * patterns. Fires after all widget values are restored from the workflow JSON.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(event: 'configured', handler: Handler<void>): Unsubscribe
+
+  /**
+   * Subscribe to slot connection events.
+   *
+   * Replaces `nodeType.prototype.onConnectInput`, `onConnectOutput`, and
+   * `onConnectionsChange` patching patterns (R4-P4: six distinct signatures
+   * in the wild — this single typed event resolves the confusion).
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(event: 'connected', handler: Handler<NodeConnectedEvent>): Unsubscribe
+
+  /**
+   * Subscribe to slot disconnection events.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(
+    event: 'disconnected',
+    handler: Handler<NodeDisconnectedEvent>
+  ): Unsubscribe
+
+  /**
+   * Subscribe to canvas position changes.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(
+    event: 'positionChanged',
+    handler: Handler<NodePositionChangedEvent>
+  ): Unsubscribe
+
+  /**
+   * Subscribe to node size changes.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(event: 'sizeChanged', handler: Handler<NodeSizeChangedEvent>): Unsubscribe
+
+  /**
+   * Subscribe to execution mode changes.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(event: 'modeChanged', handler: Handler<NodeModeChangedEvent>): Unsubscribe
+
+  /**
+   * Subscribe to node serialization. Async-capable.
+   *
+   * Replaces `nodeType.prototype.onSerialize` and `nodeType.prototype.serialize`
+   * patching patterns. Collapses four v1 serialization surfaces to one (D7 Part 4).
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability experimental
+   */
+  on(
+    event: 'beforeSerialize',
+    handler: AsyncHandler<NodeBeforeSerializeEvent>
+  ): Unsubscribe
+}
diff --git a/src/extension-api/shell.ts b/src/extension-api/shell.ts
new file mode 100644
index 0000000000..cb2fcb391e
--- /dev/null
+++ b/src/extension-api/shell.ts
@@ -0,0 +1,21 @@
+/**
+ * Shell UI extension types — sidebar tabs, bottom panels, commands, toasts.
+ *
+ * Moved from `src/types/extensionTypes.ts` with no shape changes. This
+ * re-export makes all shell types available from the single
+ * `@comfyorg/extension-api` package entry point.
+ *
+ * @stability stable
+ * @packageDocumentation
+ */
+
+export type {
+  SidebarTabExtension,
+  BottomPanelExtension,
+  VueExtension,
+  CustomExtension,
+  ToastMessageOptions,
+  ToastManager,
+  ExtensionManager,
+  CommandManager
+} from '@/types/extensionTypes'
diff --git a/src/extension-api/widget.ts b/src/extension-api/widget.ts
new file mode 100644
index 0000000000..6c83c24510
--- /dev/null
+++ b/src/extension-api/widget.ts
@@ -0,0 +1,537 @@
+/**
+ * WidgetHandle — the controlled surface for widget access in v2 extensions.
+ *
+ * All state reads and writes go through this interface. Internal ECS
+ * components and World references are never exposed.
+ *
+ * Design decisions:
+ * - First-class fields (every-widget) per D7 Part 1: label, hidden, disabled, serialize
+ * - Options bag (type-specific) per D7 Part 1: min/max/step etc. via getOption/setOption
+ * - Three-tier persistence model per D7 Part 2: value / options / extensionState
+ * - `beforeSerialize` is the single async-allowed event per D5 Part 3 + D10c
+ * - `valueChange` is the only shipped event channel in v1 per D5 Part 2
+ *
+ * @stability stable
+ * @packageDocumentation
+ */
+
+import type { AsyncHandler, Handler, Unsubscribe } from './events'
+
+// ─── Entity ID ──────────────────────────────────────────────────────────────
+
+/**
+ * Branded entity ID for widgets. Prevents mixing widget IDs with node IDs
+ * at compile time. The underlying value is always `number`.
+ *
+ * @stability stable
+ */
+export type WidgetEntityId = number & { readonly __brand: 'WidgetEntityId' }
+
+// ─── Widget value ────────────────────────────────────────────────────────────
+
+/**
+ * The union of all legal widget scalar values. Complex widgets (DOM, canvas)
+ * may return their own serializable shapes.
+ *
+ * @stability stable
+ */
+export type WidgetValue = string | number | boolean | null
+
+// ─── Event payloads ─────────────────────────────────────────────────────────
+
+/**
+ * Payload for `widget.on('valueChange', handler)`.
+ *
+ * Replaces the v1 `widget.callback` pattern.
+ *
+ * @typeParam T - The widget's value type.
+ * @stability stable
+ * @example
+ * ```ts
+ * widget.on('valueChange', (e) => {
+ *   console.log('changed from', e.oldValue, 'to', e.newValue)
+ * })
+ * ```
+ */
+export interface WidgetValueChangeEvent<T = WidgetValue> {
+  /** Value before the change. */
+  readonly oldValue: T
+  /** Value after the change. */
+  readonly newValue: T
+}
+
+/**
+ * Payload for `widget.on('optionChange', handler)`.
+ *
+ * Fires when a type-specific option is mutated via `setOption(key, value)`.
+ * The exact set of observable option keys is type-dependent (e.g. `min`,
+ * `max`, `step` for numeric widgets; `multiline` for strings).
+ *
+ * The data model for "options" vs "first-class fields" is defined in D7.
+ * This event covers the options-bag tier (type-specific, not every-widget).
+ *
+ * @stability experimental — full semantics deferred to D7
+ * @example
+ * ```ts
+ * widget.on('optionChange', (e) => {
+ *   if (e.key === 'min') clampValue(e.newValue as number)
+ * })
+ * ```
+ */
+export interface WidgetOptionChangeEvent {
+  /** The option key that changed (e.g. `'min'`, `'max'`, `'multiline'`). */
+  readonly key: string
+  /** Value before the change. */
+  readonly oldValue: unknown
+  /** Value after the change. */
+  readonly newValue: unknown
+}
+
+/**
+ * Payload for `widget.on('propertyChange', handler)`.
+ *
+ * Fires when a first-class every-widget property is mutated — specifically
+ * `hidden`, `disabled`, and `serialize` (the non-value first-class fields
+ * defined in D7 Part 1). Does NOT fire for `value` changes (use `valueChange`)
+ * or for options-bag mutations (use `optionChange`).
+ *
+ * @stability experimental — property enumeration finalised in D7
+ * @example
+ * ```ts
+ * widget.on('propertyChange', (e) => {
+ *   if (e.property === 'hidden') updateLayout(e.newValue as boolean)
+ * })
+ * ```
+ */
+export interface WidgetPropertyChangeEvent {
+  /**
+   * Which first-class property changed.
+   * - `'hidden'` — visibility toggled via `setHidden()`
+   * - `'disabled'` — enabled/disabled via `setDisabled()`
+   * - `'serialize'` — serialization opt-in/out via `setSerializeEnabled()`
+   */
+  readonly property: 'hidden' | 'disabled' | 'serialize'
+  /** Value before the change. */
+  readonly oldValue: boolean
+  /** Value after the change. */
+  readonly newValue: boolean
+}
+
+/**
+ * Payload for `widget.on('beforeSerialize', handler)`.
+ *
+ * This is the **only async-allowed event** in v1 (per D10c / D5 Part 3).
+ * Replaces `widget.serializeValue`, `widget.options.serialize = false`, and
+ * the v1 `widget.serializeValue = (workflowNode, widgetIndex) => ...` pattern.
+ *
+ * Call `event.setSerializedValue(v)` to override what is written to
+ * `widgets_values[i]` and the API prompt. Call `event.skip()` to exclude this
+ * widget from the prompt entirely. Do not call either to pass through the
+ * widget's current `getValue()` unchanged.
+ *
+ * @typeParam T - The widget's value type.
+ * @stability stable
+ * @example
+ * ```ts
+ * // Dynamic prompts: replace value at serialize time
+ * widget.on('beforeSerialize', (e) => {
+ *   if (e.context === 'prompt') {
+ *     e.setSerializedValue(processDynamicPrompt(widget.getValue()))
+ *   }
+ * })
+ *
+ * // Preview widget: exclude from prompt
+ * widget.on('beforeSerialize', (e) => {
+ *   if (e.context === 'prompt') e.skip()
+ * })
+ *
+ * // Async: webcam capture — materialize frame before prompt builds
+ * widget.on('beforeSerialize', async (e) => {
+ *   if (e.context === 'prompt') {
+ *     const frame = await captureFrame()
+ *     e.setSerializedValue(frame)
+ *   }
+ * })
+ * ```
+ */
+export interface WidgetBeforeSerializeEvent<T = WidgetValue> {
+  /**
+   * Which serialization path triggered this handler.
+   *
+   * - `'workflow'` — user is saving the workflow to disk (full round-trip).
+   * - `'prompt'` — user is queueing a run (only prompt-relevant data sent to backend).
+   * - `'clone'` — a copy/paste is happening; the framework already populated the
+   *   cloned entity's widget value from the source. Override only if the clone should
+   *   differ from the source. (See D12 for scope copy semantics.)
+   * - `'subgraph-promote'` — the widget is being promoted to a subgraph IO slot.
+   */
+  readonly context: 'workflow' | 'prompt' | 'clone' | 'subgraph-promote'
+
+  /**
+   * The widget's current value at the time of serialization (before any override).
+   * Equivalent to calling `widget.getValue()`.
+   */
+  readonly value: T
+
+  /**
+   * Override the serialized value. The provided value is written to
+   * `widgets_values[i]` (and to the API prompt for `context='prompt'`).
+   * Calling this multiple times keeps the last call's value.
+   *
+   * @param v - The value to serialize. Must be JSON-serializable.
+   */
+  setSerializedValue(v: unknown): void
+
+  /**
+   * Exclude this widget from the API prompt entirely.
+   * Only meaningful for `context='prompt'`; no-ops on other contexts.
+   * Replaces `widget.options.serialize = false` and `() => undefined` patterns.
+   */
+  skip(): void
+}
+
+/**
+ * Payload for `widget.on('beforeQueue', handler)`.
+ *
+ * Fires when the user triggers a prompt queue (before `graphToPrompt` runs).
+ * Call `event.reject(message)` to cancel the queue attempt with a user-visible
+ * error. Do not call `reject` to allow the queue to proceed.
+ *
+ * Replaces the v1 `app.queuePrompt` monkey-patching pattern (S6.A4/S6.A5)
+ * for per-widget validation (e.g. required field empty, value out of range).
+ * For cross-node/graph-wide rejection, see the app-level `beforePrompt` event
+ * (I-UWF.4 — not yet in the API).
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * // Reject if a required field is empty
+ * widget.on('beforeQueue', (e) => {
+ *   if (!widget.getValue()) {
+ *     e.reject('Prompt text is required before queueing.')
+ *   }
+ * })
+ *
+ * // Reject with a dynamic message
+ * widget.on('beforeQueue', (e) => {
+ *   const val = widget.getValue<number>()
+ *   const min = widget.getOption<number>('min') ?? 0
+ *   if (val < min) {
+ *     e.reject(`Value ${val} is below the minimum of ${min}.`)
+ *   }
+ * })
+ * ```
+ */
+export interface WidgetBeforeQueueEvent {
+  /**
+   * Reject the queue attempt, showing `message` to the user.
+   * Once any handler calls `reject`, the queue is cancelled — subsequent
+   * handlers still run but their `reject` calls are no-ops.
+   *
+   * @param message - Human-readable reason shown in the UI toast.
+   */
+  reject(message: string): void
+}
+
+// ─── WidgetHandle ────────────────────────────────────────────────────────────
+
+/**
+ * Controlled surface for widget access. Backed by ECS `WidgetValue` and
+ * `WidgetIdentity` components in the World. Reads query components directly;
+ * writes dispatch commands (undo-able, serializable, validatable).
+ *
+ * All views (node, properties panel, promoted copy) share the same backing
+ * `WidgetEntityId`, so mutations from any source trigger `valueChange`.
+ *
+ * @typeParam T - The type of `getValue()` / `setValue()`. Defaults to `WidgetValue`.
+ * @stability stable
+ * @example
+ * ```ts
+ * import { defineNodeExtension } from '@comfyorg/extension-api'
+ *
+ * export default defineNodeExtension({
+ *   name: 'my-extension',
+ *   nodeCreated(node) {
+ *     const steps = node.widget('steps')
+ *     if (!steps) return
+ *
+ *     steps.on('valueChange', (e) => console.log('steps =', e.newValue))
+ *     steps.setOption('min', 1)
+ *     steps.setOption('max', 150)
+ *   }
+ * })
+ * ```
+ */
+export interface WidgetHandle<T = WidgetValue> {
+  // ── IDENTITY ───────────────────────────────────────────────────────────────
+
+  /**
+   * Stable entity identifier for this widget. Branded to prevent mixing with
+   * `NodeEntityId` at compile time.
+   *
+   * @stability stable
+   */
+  readonly entityId: WidgetEntityId
+
+  /**
+   * The widget's name as registered in `INPUT_TYPES` or `addWidget`. Stable
+   * for the lifetime of the node; never changes after creation.
+   *
+   * @stability stable
+   */
+  readonly name: string
+
+  /**
+   * The widget's type string (e.g. `'INT'`, `'STRING'`, `'COMBO'`,
+   * `'MARKDOWN'`). Read-only invariant set at creation.
+   *
+   * @stability stable
+   */
+  readonly widgetType: string
+
+  // ── VALUE — first-class, every-widget ─────────────────────────────────────
+
+  /**
+   * Returns the widget's current user-edited value.
+   *
+   * @typeParam T - Narrows the return type when you know the widget type.
+   * @stability stable
+   * @example
+   * ```ts
+   * const steps = node.widget('steps')!.getValue<number>()
+   * ```
+   */
+  getValue(): T
+
+  /**
+   * Sets the widget's value. Dispatches a `SetWidgetValue` command (undo-able).
+   * Triggers `valueChange` handlers on all views.
+   *
+   * @stability stable
+   */
+  setValue(value: T): void
+
+  // ── VISIBILITY — first-class, every-widget ────────────────────────────────
+
+  /**
+   * Returns `true` if the widget is currently hidden from the node UI.
+   *
+   * @stability stable
+   */
+  isHidden(): boolean
+
+  /**
+   * Show or hide the widget. Dispatches a `SetWidgetHidden` command.
+   *
+   * @stability stable
+   * @example
+   * ```ts
+   * toggle.on('valueChange', (e) => {
+   *   detail.setHidden(!e.newValue)
+   * })
+   * ```
+   */
+  setHidden(hidden: boolean): void
+
+  // ── DISABLED — first-class, every-widget ─────────────────────────────────
+
+  /**
+   * Returns `true` if the widget is disabled (read-only in the UI).
+   *
+   * @stability stable
+   */
+  isDisabled(): boolean
+
+  /**
+   * Enable or disable the widget.
+   *
+   * @stability stable
+   */
+  setDisabled(disabled: boolean): void
+
+  // ── LABEL — first-class, every-widget ────────────────────────────────────
+
+  /**
+   * The widget's display label shown to the user. Defaults to the widget name.
+   * Read-only invariant per D6 Part 3 (set at creation, never changes after).
+   *
+   * To override at construction, pass `label` to `addWidget()` options.
+   *
+   * @stability stable
+   */
+  readonly label: string
+
+  // ── SERIALIZATION OPT-OUT — first-class, every-widget ────────────────────
+
+  /**
+   * Returns `true` if this widget is included in workflow and prompt
+   * serialization. Defaults to `true` for all widget types.
+   *
+   * @stability stable
+   */
+  isSerializeEnabled(): boolean
+
+  /**
+   * Enable or disable serialization for this widget. When disabled, the widget
+   * is excluded from both `widgets_values` in the workflow JSON and the API
+   * prompt payload. Equivalent to the v1 `widget.options.serialize = false`
+   * pattern.
+   *
+   * @stability stable
+   */
+  setSerializeEnabled(enabled: boolean): void
+
+  // ── OPTIONS BAG — type-specific overrides ─────────────────────────────────
+
+  /**
+   * Returns the per-instance override for `key`, or the class-default value
+   * from `INPUT_TYPES` if no override has been set, or `undefined` if the key
+   * is unknown for this widget type.
+   *
+   * Type-specific option names: `min`, `max`, `step` (INT/FLOAT); `multiline`,
+   * `dynamicPrompts` (STRING); `image_folder`, `upload_to` (upload widgets).
+   *
+   * @stability stable
+   * @example
+   * ```ts
+   * const min = widget.getOption<number>('min') ?? 0
+   * ```
+   */
+  getOption<K = unknown>(key: string): K | undefined
+
+  /**
+   * Set a per-instance option override. Persisted as a `widget_options` sidecar
+   * in the workflow JSON (additive, backward-compatible). Does not change the
+   * backend prompt schema unless the extension explicitly opts in via
+   * `beforeSerialize`.
+   *
+   * @stability stable
+   * @example
+   * ```ts
+   * // Primitive Int/Float per-instance config (replaces node.properties anti-pattern)
+   * widget.setOption('min', 0)
+   * widget.setOption('max', 100)
+   * widget.setOption('step', 1)
+   * ```
+   */
+  setOption(key: string, value: unknown): void
+
+  // ── EVENTS ────────────────────────────────────────────────────────────────
+
+  /**
+   * Subscribe to the widget's value changes.
+   *
+   * Replaces the v1 `widget.callback` pattern.
+   * Fires synchronously after the value is committed (per D10c).
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(
+    event: 'valueChange',
+    handler: Handler<WidgetValueChangeEvent<T>>
+  ): Unsubscribe
+
+  /**
+   * Subscribe to type-specific option mutations (`setOption(key, value)`).
+   *
+   * Fires for options-bag changes (e.g. `min`, `max`, `step`, `multiline`).
+   * Does NOT fire for value changes or first-class field changes.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability experimental
+   */
+  on(
+    event: 'optionChange',
+    handler: Handler<WidgetOptionChangeEvent>
+  ): Unsubscribe
+
+  /**
+   * Subscribe to first-class property mutations (`setHidden`, `setDisabled`,
+   * `setSerializeEnabled`).
+   *
+   * Does NOT fire for `setValue` (use `valueChange`) or options-bag mutations
+   * (use `optionChange`).
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability experimental
+   */
+  on(
+    event: 'propertyChange',
+    handler: Handler<WidgetPropertyChangeEvent>
+  ): Unsubscribe
+
+  /**
+   * Subscribe to widget serialization. The only async-allowed event (D10c / D5).
+   *
+   * Replaces `widget.serializeValue = fn` and the v1 `widget.options.serialize`
+   * flag. The handler may be sync or async; async handlers are awaited before
+   * the serialization payload is sent.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability stable
+   */
+  on(
+    event: 'beforeSerialize',
+    handler: AsyncHandler<WidgetBeforeSerializeEvent<T>>
+  ): Unsubscribe
+
+  /**
+   * Subscribe to pre-queue validation. Fires before `graphToPrompt` runs.
+   *
+   * Call `event.reject(message)` to cancel the queue with a user-visible error.
+   * Replaces the v1 `app.queuePrompt` monkey-patching pattern (S6.A4/S6.A5)
+   * for per-widget validation use cases.
+   *
+   * Handlers are sync-only — use for validation logic only, not I/O.
+   *
+   * @returns A cleanup function to remove the listener.
+   * @stability experimental
+   */
+  on(
+    event: 'beforeQueue',
+    handler: Handler<WidgetBeforeQueueEvent>
+  ): Unsubscribe
+}
+
+// ─── Widget construction options ─────────────────────────────────────────────
+
+/**
+ * Options passed to `node.addWidget()` when creating a new widget.
+ *
+ * Type-specific keys (e.g. `min`, `max`, `step` for numeric widgets;
+ * `multiline`, `dynamicPrompts` for strings) are passed through as-is.
+ *
+ * @stability stable
+ */
+export interface WidgetOptions {
+  /** If `true`, the widget is hidden from the node UI on creation. */
+  hidden?: boolean
+  /** If `true`, the widget is rendered read-only (no user editing). */
+  readonly?: boolean
+  /** If `false`, this widget is excluded from workflow/prompt serialization. */
+  serialize?: boolean
+  /** Display label override. Defaults to the widget `name`. */
+  label?: string
+  /** Toggle label shown when value is `true` (BOOLEAN widgets). */
+  labelOn?: string
+  /** Toggle label shown when value is `false` (BOOLEAN widgets). */
+  labelOff?: string
+  /** Multiline text input (STRING widgets). */
+  multiline?: boolean
+  /**
+   * When `true`, the widget value is processed for dynamic prompt syntax
+   * at serialize time. (STRING widgets with `dynamicPrompts: true`.)
+   */
+  dynamicPrompts?: boolean
+  /** Min value for numeric widgets (INT, FLOAT). */
+  min?: number
+  /** Max value for numeric widgets. */
+  max?: number
+  /** Step size for numeric widgets. */
+  step?: number
+  /** Default value at construction time. */
+  default?: unknown
+  /** Any additional type-specific option. */
+  [key: string]: unknown
+}
diff --git a/vitest.extension-api.config.mts b/vitest.extension-api.config.mts
new file mode 100644
index 0000000000..018e740edf
--- /dev/null
+++ b/vitest.extension-api.config.mts
@@ -0,0 +1,34 @@
+import { defineConfig } from 'vitest/config'
+
+/**
+ * Vitest config for the extension-api test suite (I-TF).
+ *
+ * Runs only the extension-api-v2 __tests__ stubs — isolated from the main
+ * unit suite so the compat-floor gate can run independently on PRs that
+ * touch src/extension-api/** or src/extension-api-v2/**.
+ *
+ * Coverage is scoped to src/extension-api/ (the public declaration files)
+ * and src/extension-api-v2/ (the impl + test stubs).
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'happy-dom',
+    setupFiles: ['./vitest.setup.ts'],
+    include: [
+      'src/extension-api-v2/__tests__/**/*.{test,spec}.{ts,mts}'
+    ],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'lcov'],
+      include: [
+        'src/extension-api/**/*.ts',
+        'src/extension-api-v2/**/*.ts'
+      ],
+      exclude: [
+        'src/extension-api-v2/__tests__/**'
+      ]
+    },
+    reporter: process.env.CI ? ['verbose', 'github-actions'] : ['verbose']
+  }
+})