[automated] Apply ESLint and Oxfmt fixes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/skills/contain-audit/SKILL.md

@@ -1,99 +0,0 @@
----
-name: contain-audit
-description: 'Detect DOM elements where CSS contain:layout+style would improve rendering performance. Runs a Playwright-based audit on a large workflow, scores candidates by subtree size and sizing constraints, measures performance impact, and generates a ranked report.'
----
-
-# CSS Containment Audit
-
-Automatically finds DOM elements where adding `contain: layout style` would reduce browser recalculation overhead.
-
-## What It Does
-
-1. Loads a large workflow (245 nodes) in a real browser
-2. Walks the DOM tree and scores every element as a containment candidate
-3. For each high-scoring candidate, applies `contain: layout style` via JavaScript
-4. Measures rendering performance (style recalcs, layouts, task duration) before and after
-5. Takes before/after screenshots to detect visual breakage
-6. Generates a ranked report with actionable recommendations
-
-## When to Use
-
-- After adding new Vue components to the node rendering pipeline
-- When investigating rendering performance on large workflows
-- Before and after refactoring node DOM structure
-- As part of periodic performance audits
-
-## How to Run
-
-```bash
-# Start the dev server first
-pnpm dev &
-
-# Run the audit (uses the @audit tag, not included in normal CI runs)
-pnpm exec playwright test browser_tests/tests/containAudit.spec.ts --project=audit
-
-# View the HTML report
-pnpm exec playwright show-report
-```
-
-## How to Read Results
-
-The audit outputs a table to the console:
-
-```text
-CSS Containment Audit Results
-=======================================================
-Rank | Selector                        | Subtree | Score | DRecalcs | DLayouts | Visual
-  1  | [data-testid="node-inner-wrap"] |     18  |  72   |    -34%  |    -12%  |   OK
-  2  | .node-body                      |     12  |  48   |     -8%  |     -3%  |   OK
-  3  | .node-header                    |      4  |  16   |     +1%  |      0%  |   OK
-```
-
-- **Subtree**: Number of descendant elements (higher = more to skip)
-- **Score**: Composite heuristic score (subtree size x sizing constraint bonus)
-- **DRecalcs / DLayouts**: Change in style recalcs / layout counts vs baseline (negative = improvement)
-- **Visual**: OK if no pixel change, DIFF if screenshot differs (may include subpixel noise — verify manually)
-
-## Candidate Scoring
-
-An element is a good containment candidate when:
-
-1. **Large subtree** -- many descendants that the browser can skip recalculating
-2. **Externally constrained size** -- width/height determined by CSS variables, flex, or explicit values (not by content)
-3. **No existing containment** -- `contain` is not already applied
-4. **Not a leaf** -- has at least a few child elements
-
-Elements that should NOT get containment:
-
-- Elements whose children overflow visually beyond bounds (e.g., absolute-positioned overlays with negative inset)
-- Elements whose height is determined by content and affects sibling layout
-- Very small subtrees (overhead of containment context outweighs benefit)
-
-## Limitations
-
-- Cannot fully guarantee `contain` safety -- visual review of screenshots is required
-- Performance measurements have natural variance; run multiple times for confidence
-- Only tests idle and pan scenarios; widget interactions may differ
-- The audit modifies styles at runtime via JS, which doesn't account for Tailwind purging or build-time optimizations
-
-## Example PR
-
-[#9946 — fix: add CSS contain:layout contain:style to node inner wrapper](https://github.com/Comfy-Org/ComfyUI_frontend/pull/9946)
-
-This PR added `contain-layout contain-style` to the node inner wrapper div in `LGraphNode.vue`. The audit tool would have flagged this element as a high-scoring candidate because:
-
-- **Large subtree** (18+ descendants: header, slots, widgets, content, badges)
-- **Externally constrained size** (`w-(--node-width)`, `flex-1` — dimensions set by CSS variables and flex parent)
-- **Natural isolation boundary** between frequently-changing content (widgets) and infrequently-changing overlays (selection outlines, borders)
-
-The actual change was a single line: adding `'contain-layout contain-style'` to the inner wrapper's class list at `src/renderer/extensions/vueNodes/components/LGraphNode.vue:79`.
-
-## Reference
-
-| Resource          | Path                                                    |
-| ----------------- | ------------------------------------------------------- |
-| Audit test        | `browser_tests/tests/containAudit.spec.ts`              |
-| PerformanceHelper | `browser_tests/fixtures/helpers/PerformanceHelper.ts`   |
-| Perf tests        | `browser_tests/tests/performance.spec.ts`               |
-| Large workflow    | `browser_tests/assets/large-graph-workflow.json`        |
-| Example PR        | https://github.com/Comfy-Org/ComfyUI_frontend/pull/9946 |

.gitignore

@@ -66,6 +66,7 @@ dist.zip
 
 /temp/
 /tmp/
+.superpowers/
 
 # Generated JSON Schemas
 /schemas/

AGENTS.md

@@ -208,7 +208,7 @@ See @docs/testing/\*.md for detailed patterns.
 3. Keep your module mocks contained  
    Do not use global mutable state within the test file  
    Use `vi.hoisted()` if necessary to allow for per-test Arrange phase manipulation of deeper mock state
-4. For Component testing, prefer [@testing-library/vue](https://testing-library.com/docs/vue-testing-library/intro/) with `@testing-library/user-event` for user-centric, behavioral tests. [Vue Test Utils](https://test-utils.vuejs.org/) is also accepted, especially for tests that need direct access to the component wrapper (e.g., `findComponent`, `emitted()`). Follow the advice [about making components easy to test](https://test-utils.vuejs.org/guide/essentials/easy-to-test.html)
+4. For Component testing, use [Vue Test Utils](https://test-utils.vuejs.org/) and especially follow the advice [about making components easy to test](https://test-utils.vuejs.org/guide/essentials/easy-to-test.html)
 5. Aim for behavioral coverage of critical and new features
 
 ### Playwright / Browser / E2E Tests

apps/architecture-adventure/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Codebase Caverns — ComfyUI Architecture Adventure</title>
+    <meta
+      name="description"
+      content="A prestige-driven architecture adventure game. Discover problems, learn patterns, make decisions, and watch the consequences unfold."
+    />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

apps/architecture-adventure/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@comfyorg/architecture-adventure",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "vite": "catalog:"
+  },
+  "nx": {
+    "tags": [
+      "scope:docs",
+      "type:app"
+    ],
+    "targets": {
+      "dev": {
+        "executor": "nx:run-commands",
+        "continuous": true,
+        "options": {
+          "cwd": "apps/architecture-adventure",
+          "command": "vite"
+        }
+      },
+      "build": {
+        "executor": "nx:run-commands",
+        "cache": true,
+        "options": {
+          "command": "vite build --config apps/architecture-adventure/vite.config.ts"
+        },
+        "outputs": [
+          "{projectRoot}/dist"
+        ]
+      },
+      "preview": {
+        "executor": "nx:run-commands",
+        "continuous": true,
+        "dependsOn": [
+          "build"
+        ],
+        "options": {
+          "cwd": "apps/architecture-adventure",
+          "command": "vite preview"
+        }
+      },
+      "typecheck": {
+        "executor": "nx:run-commands",
+        "cache": true,
+        "options": {
+          "cwd": "apps/architecture-adventure",
+          "command": "tsc --noEmit"
+        }
+      }
+    }
+  }
+}

apps/architecture-adventure/src/main.ts

@@ -0,0 +1,7 @@
+function main(): void {
+  const app = document.getElementById('app')
+  if (!app) throw new Error('Missing #app element')
+  app.textContent = 'Codebase Caverns v2 — Loading...'
+}
+
+main()

apps/architecture-adventure/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "baseUrl": "."
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"]
+}

apps/architecture-adventure/vite.config.ts

@@ -0,0 +1,26 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+
+const projectRoot = fileURLToPath(new URL('.', import.meta.url))
+
+export default defineConfig({
+  root: projectRoot,
+  base: './',
+  build: {
+    target: 'es2022',
+    outDir: 'dist',
+    assetsInlineLimit: 1_000_000,
+    cssCodeSplit: false,
+    rolldownOptions: {
+      output: {
+        inlineDynamicImports: true
+      }
+    }
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(projectRoot, 'src')
+    }
+  }
+})

browser_tests/assets/widgets/painter_widget.json

@@ -1,48 +0,0 @@
-{
-  "last_node_id": 1,
-  "last_link_id": 0,
-  "nodes": [
-    {
-      "id": 1,
-      "type": "Painter",
-      "pos": [50, 50],
-      "size": [450, 550],
-      "flags": {},
-      "order": 0,
-      "mode": 0,
-      "inputs": [
-        {
-          "name": "image",
-          "type": "IMAGE",
-          "link": null
-        }
-      ],
-      "outputs": [
-        {
-          "name": "IMAGE",
-          "type": "IMAGE",
-          "links": null
-        },
-        {
-          "name": "MASK",
-          "type": "MASK",
-          "links": null
-        }
-      ],
-      "properties": {
-        "Node name for S&R": "Painter"
-      },
-      "widgets_values": ["", 512, 512, "#000000"]
-    }
-  ],
-  "links": [],
-  "groups": [],
-  "config": {},
-  "extra": {
-    "ds": {
-      "offset": [0, 0],
-      "scale": 1
-    }
-  },
-  "version": 0.4
-}

browser_tests/fixtures/ComfyPage.ts

@@ -19,12 +19,10 @@ import { ContextMenu } from './components/ContextMenu'
 import { SettingDialog } from './components/SettingDialog'
 import { BottomPanel } from './components/BottomPanel'
 import {
-  AssetsSidebarTab,
   NodeLibrarySidebarTab,
   WorkflowsSidebarTab
 } from './components/SidebarTab'
 import { Topbar } from './components/Topbar'
-import { AssetsHelper } from './helpers/AssetsHelper'
 import { CanvasHelper } from './helpers/CanvasHelper'
 import { PerformanceHelper } from './helpers/PerformanceHelper'
 import { QueueHelper } from './helpers/QueueHelper'
@@ -57,7 +55,6 @@ class ComfyPropertiesPanel {
 }
 
 class ComfyMenu {
-  private _assetsTab: AssetsSidebarTab | null = null
   private _nodeLibraryTab: NodeLibrarySidebarTab | null = null
   private _workflowsTab: WorkflowsSidebarTab | null = null
   private _topbar: Topbar | null = null
@@ -81,11 +78,6 @@ class ComfyMenu {
     return this._nodeLibraryTab
   }
 
-  get assetsTab() {
-    this._assetsTab ??= new AssetsSidebarTab(this.page)
-    return this._assetsTab
-  }
-
   get workflowsTab() {
     this._workflowsTab ??= new WorkflowsSidebarTab(this.page)
     return this._workflowsTab
@@ -200,7 +192,6 @@ export class ComfyPage {
   public readonly command: CommandHelper
   public readonly bottomPanel: BottomPanel
   public readonly perf: PerformanceHelper
-  public readonly assets: AssetsHelper
   public readonly queue: QueueHelper
 
   /** Worker index to test user ID */
@@ -247,7 +238,6 @@ export class ComfyPage {
     this.command = new CommandHelper(page)
     this.bottomPanel = new BottomPanel(page)
     this.perf = new PerformanceHelper(page)
-    this.assets = new AssetsHelper(page)
     this.queue = new QueueHelper(page)
   }
 
@@ -462,13 +452,12 @@ export const comfyPageFixture = base.extend<{
 
     await comfyPage.setup()
 
-    const needsPerf =
-      testInfo.tags.includes('@perf') || testInfo.tags.includes('@audit')
-    if (needsPerf) await comfyPage.perf.init()
+    const isPerf = testInfo.tags.includes('@perf')
+    if (isPerf) await comfyPage.perf.init()
 
     await use(comfyPage)
 
-    if (needsPerf) await comfyPage.perf.dispose()
+    if (isPerf) await comfyPage.perf.dispose()
   },
   comfyMouse: async ({ comfyPage }, use) => {
     const comfyMouse = new ComfyMouse(comfyPage)

browser_tests/fixtures/components/SidebarTab.ts

@@ -168,32 +168,3 @@ export class WorkflowsSidebarTab extends SidebarTab {
       .click()
   }
 }
-
-export class AssetsSidebarTab extends SidebarTab {
-  constructor(public override readonly page: Page) {
-    super(page, 'assets')
-  }
-
-  get generatedTab() {
-    return this.page.getByRole('tab', { name: 'Generated' })
-  }
-
-  get importedTab() {
-    return this.page.getByRole('tab', { name: 'Imported' })
-  }
-
-  get emptyStateMessage() {
-    return this.page.getByText(
-      'Upload files or generate content to see them here'
-    )
-  }
-
-  emptyStateTitle(title: string) {
-    return this.page.getByText(title)
-  }
-
-  override async open() {
-    await super.open()
-    await this.generatedTab.waitFor({ state: 'visible' })
-  }
-}

browser_tests/fixtures/helpers/AppModeHelper.ts

@@ -142,29 +142,6 @@ export class AppModeHelper {
       .getByTestId(TestIds.builder.widgetActionsMenu)
   }
 
-  /** The builder footer nav containing save/navigation buttons. */
-  private get builderFooterNav(): Locator {
-    return this.page
-      .getByRole('button', { name: 'Exit app builder' })
-      .locator('..')
-  }
-
-  /** Get a button in the builder footer by its accessible name. */
-  getFooterButton(name: string | RegExp): Locator {
-    return this.builderFooterNav.getByRole('button', { name })
-  }
-
-  /** Click the save/save-as button in the builder footer. */
-  async clickSave() {
-    await this.getFooterButton(/^Save/).first().click()
-    await this.comfyPage.nextFrame()
-  }
-
-  /** The "Opens as" popover tab above the builder footer. */
-  get opensAsPopover(): Locator {
-    return this.page.getByTestId(TestIds.builder.opensAs)
-  }
-
   /**
    * Rename a widget by clicking its popover trigger, selecting "Rename",
    * and filling in the dialog.

browser_tests/fixtures/helpers/AssetsHelper.ts

@@ -1,147 +0,0 @@
-import type { Page, Route } from '@playwright/test'
-
-import type { RawJobListItem } from '../../../src/platform/remote/comfyui/jobs/jobTypes'
-
-const jobsListRoutePattern = /\/api\/jobs(?:\?.*)?$/
-const inputFilesRoutePattern = /\/internal\/files\/input(?:\?.*)?$/
-
-function parseLimit(url: URL, total: number): number {
-  const value = Number(url.searchParams.get('limit'))
-  if (!Number.isInteger(value) || value <= 0) {
-    return total
-  }
-  return value
-}
-
-function parseOffset(url: URL): number {
-  const value = Number(url.searchParams.get('offset'))
-  if (!Number.isInteger(value) || value < 0) {
-    return 0
-  }
-  return value
-}
-
-function getExecutionDuration(job: RawJobListItem): number {
-  const start = job.execution_start_time ?? 0
-  const end = job.execution_end_time ?? 0
-  return end - start
-}
-
-export class AssetsHelper {
-  private jobsRouteHandler: ((route: Route) => Promise<void>) | null = null
-  private inputFilesRouteHandler: ((route: Route) => Promise<void>) | null =
-    null
-  private generatedJobs: RawJobListItem[] = []
-  private importedFiles: string[] = []
-
-  constructor(private readonly page: Page) {}
-
-  async mockOutputHistory(jobs: RawJobListItem[]): Promise<void> {
-    this.generatedJobs = [...jobs]
-
-    if (this.jobsRouteHandler) {
-      return
-    }
-
-    this.jobsRouteHandler = async (route: Route) => {
-      const url = new URL(route.request().url())
-      const statuses = url.searchParams
-        .get('status')
-        ?.split(',')
-        .map((status) => status.trim())
-        .filter(Boolean)
-      const workflowId = url.searchParams.get('workflow_id')
-      const sortBy = url.searchParams.get('sort_by')
-      const sortOrder = url.searchParams.get('sort_order') === 'asc' ? 1 : -1
-
-      let filteredJobs = [...this.generatedJobs]
-
-      if (statuses?.length) {
-        filteredJobs = filteredJobs.filter((job) =>
-          statuses.includes(job.status)
-        )
-      }
-
-      if (workflowId) {
-        filteredJobs = filteredJobs.filter(
-          (job) => job.workflow_id === workflowId
-        )
-      }
-
-      filteredJobs.sort((left, right) => {
-        const leftValue =
-          sortBy === 'execution_duration'
-            ? getExecutionDuration(left)
-            : left.create_time
-        const rightValue =
-          sortBy === 'execution_duration'
-            ? getExecutionDuration(right)
-            : right.create_time
-
-        return (leftValue - rightValue) * sortOrder
-      })
-
-      const offset = parseOffset(url)
-      const total = filteredJobs.length
-      const limit = parseLimit(url, total)
-      const visibleJobs = filteredJobs.slice(offset, offset + limit)
-
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          jobs: visibleJobs,
-          pagination: {
-            offset,
-            limit,
-            total,
-            has_more: offset + visibleJobs.length < total
-          }
-        })
-      })
-    }
-
-    await this.page.route(jobsListRoutePattern, this.jobsRouteHandler)
-  }
-
-  async mockInputFiles(files: string[]): Promise<void> {
-    this.importedFiles = [...files]
-
-    if (this.inputFilesRouteHandler) {
-      return
-    }
-
-    this.inputFilesRouteHandler = async (route: Route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify(this.importedFiles)
-      })
-    }
-
-    await this.page.route(inputFilesRoutePattern, this.inputFilesRouteHandler)
-  }
-
-  async mockEmptyState(): Promise<void> {
-    await this.mockOutputHistory([])
-    await this.mockInputFiles([])
-  }
-
-  async clearMocks(): Promise<void> {
-    this.generatedJobs = []
-    this.importedFiles = []
-
-    if (this.jobsRouteHandler) {
-      await this.page.unroute(jobsListRoutePattern, this.jobsRouteHandler)
-      this.jobsRouteHandler = null
-    }
-
-    if (this.inputFilesRouteHandler) {
-      await this.page.unroute(
-        inputFilesRoutePattern,
-        this.inputFilesRouteHandler
-      )
-      this.inputFilesRouteHandler = null
-    }
-  }
-}

browser_tests/fixtures/selectors.ts

@@ -20,12 +20,7 @@ export const TestIds = {
     main: 'graph-canvas',
     contextMenu: 'canvas-context-menu',
     toggleMinimapButton: 'toggle-minimap-button',
-    toggleLinkVisibilityButton: 'toggle-link-visibility-button',
-    zoomControlsButton: 'zoom-controls-button',
-    zoomInAction: 'zoom-in-action',
-    zoomOutAction: 'zoom-out-action',
-    zoomToFitAction: 'zoom-to-fit-action',
-    zoomPercentageInput: 'zoom-percentage-input'
+    toggleLinkVisibilityButton: 'toggle-link-visibility-button'
   },
   dialogs: {
     settings: 'settings-dialog',
@@ -34,8 +29,6 @@ export const TestIds = {
     confirm: 'confirm-dialog',
     errorOverlay: 'error-overlay',
     errorOverlaySeeErrors: 'error-overlay-see-errors',
-    errorOverlayDismiss: 'error-overlay-dismiss',
-    errorOverlayMessages: 'error-overlay-messages',
     runtimeErrorPanel: 'runtime-error-panel',
     missingNodeCard: 'missing-node-card',
     errorCardFindOnGithub: 'error-card-find-on-github',
@@ -79,8 +72,7 @@ export const TestIds = {
   builder: {
     ioItem: 'builder-io-item',
     ioItemTitle: 'builder-io-item-title',
-    widgetActionsMenu: 'widget-actions-menu',
-    opensAs: 'builder-opens-as'
+    widgetActionsMenu: 'widget-actions-menu'
   },
   breadcrumb: {
     subgraph: 'subgraph-breadcrumb'

browser_tests/helpers/builderTestUtils.ts

@@ -1,118 +0,0 @@
-import { expect } from '@playwright/test'
-
-import type { ComfyPage } from '../fixtures/ComfyPage'
-import type { NodeReference } from '../fixtures/utils/litegraphUtils'
-
-import { fitToViewInstant } from './fitToView'
-import { getPromotedWidgetNames } from './promotedWidgets'
-
-/** Click the first SaveImage/PreviewImage node on the canvas. */
-async function selectOutputNode(comfyPage: ComfyPage) {
-  const { page } = comfyPage
-
-  const saveImageNodeId = await page.evaluate(() =>
-    String(
-      window.app!.rootGraph.nodes.find(
-        (n: { type?: string }) =>
-          n.type === 'SaveImage' || n.type === 'PreviewImage'
-      )?.id
-    )
-  )
-  const saveImageRef = await comfyPage.nodeOps.getNodeRefById(saveImageNodeId)
-  await saveImageRef.centerOnNode()
-
-  const canvasBox = await page.locator('#graph-canvas').boundingBox()
-  if (!canvasBox) throw new Error('Canvas not found')
-  await page.mouse.click(
-    canvasBox.x + canvasBox.width / 2,
-    canvasBox.y + canvasBox.height / 2
-  )
-  await comfyPage.nextFrame()
-}
-
-/** Center on a node and click its first widget to select it as input. */
-async function selectInputWidget(comfyPage: ComfyPage, node: NodeReference) {
-  const { page } = comfyPage
-
-  await comfyPage.canvasOps.setScale(1)
-  await node.centerOnNode()
-
-  const widgetRef = await node.getWidget(0)
-  const widgetPos = await widgetRef.getPosition()
-  const titleHeight = await page.evaluate(
-    () => window.LiteGraph!['NODE_TITLE_HEIGHT'] as number
-  )
-  await page.mouse.click(widgetPos.x, widgetPos.y + titleHeight)
-  await comfyPage.nextFrame()
-}
-
-/**
- * Enter builder on the default workflow and select I/O.
- *
- * Loads the default workflow, optionally transforms it (e.g. convert a node
- * to subgraph), then enters builder mode and selects inputs + outputs.
- *
- * @param comfyPage - The page fixture.
- * @param getInputNode - Returns the node to click for input selection.
- *   Receives the KSampler node ref and can transform the graph before
- *   returning the target node. Defaults to using KSampler directly.
- * @returns The node used for input selection.
- */
-export async function setupBuilder(
-  comfyPage: ComfyPage,
-  getInputNode?: (ksampler: NodeReference) => Promise<NodeReference>
-): Promise<NodeReference> {
-  const { appMode } = comfyPage
-  await comfyPage.workflow.loadWorkflow('default')
-
-  const ksampler = await comfyPage.nodeOps.getNodeRefById('3')
-  const inputNode = getInputNode ? await getInputNode(ksampler) : ksampler
-
-  await fitToViewInstant(comfyPage)
-  await appMode.enterBuilder()
-  await appMode.goToInputs()
-  await selectInputWidget(comfyPage, inputNode)
-
-  await appMode.goToOutputs()
-  await selectOutputNode(comfyPage)
-
-  return inputNode
-}
-
-/**
- * Convert the KSampler to a subgraph, then enter builder with I/O selected.
- *
- * Returns the subgraph node reference for further interaction.
- */
-export async function setupSubgraphBuilder(
-  comfyPage: ComfyPage
-): Promise<NodeReference> {
-  return setupBuilder(comfyPage, async (ksampler) => {
-    await ksampler.click('title')
-    const subgraphNode = await ksampler.convertToSubgraph()
-    await comfyPage.nextFrame()
-
-    const promotedNames = await getPromotedWidgetNames(
-      comfyPage,
-      String(subgraphNode.id)
-    )
-    expect(promotedNames).toContain('seed')
-
-    return subgraphNode
-  })
-}
-
-/** Save the workflow, reopen it, and enter app mode. */
-export async function saveAndReopenInAppMode(
-  comfyPage: ComfyPage,
-  workflowName: string
-) {
-  await comfyPage.menu.topbar.saveWorkflow(workflowName)
-
-  const { workflowsTab } = comfyPage.menu
-  await workflowsTab.open()
-  await workflowsTab.getPersistedItem(workflowName).dblclick()
-  await comfyPage.nextFrame()
-
-  await comfyPage.appMode.toggleAppMode()
-}

browser_tests/tests/appModeWidgetRename.spec.ts

@@ -1,11 +1,89 @@
+import type { ComfyPage } from '../fixtures/ComfyPage'
 import {
   comfyPageFixture as test,
   comfyExpect as expect
 } from '../fixtures/ComfyPage'
-import {
-  saveAndReopenInAppMode,
-  setupSubgraphBuilder
-} from '../helpers/builderTestUtils'
+import { fitToViewInstant } from '../helpers/fitToView'
+import { getPromotedWidgetNames } from '../helpers/promotedWidgets'
+
+/**
+ * Convert the KSampler (id 3) in the default workflow to a subgraph,
+ * enter builder, select the promoted seed widget as input and
+ * SaveImage/PreviewImage as output.
+ *
+ * Returns the subgraph node reference for further interaction.
+ */
+async function setupSubgraphBuilder(comfyPage: ComfyPage) {
+  const { page, appMode } = comfyPage
+  await comfyPage.workflow.loadWorkflow('default')
+
+  const ksampler = await comfyPage.nodeOps.getNodeRefById('3')
+  await ksampler.click('title')
+  const subgraphNode = await ksampler.convertToSubgraph()
+  await comfyPage.nextFrame()
+
+  const subgraphNodeId = String(subgraphNode.id)
+  const promotedNames = await getPromotedWidgetNames(comfyPage, subgraphNodeId)
+  expect(promotedNames).toContain('seed')
+
+  await fitToViewInstant(comfyPage)
+  await appMode.enterBuilder()
+  await appMode.goToInputs()
+
+  // Reset zoom to 1 and center on the subgraph node so click coords are accurate
+  await comfyPage.canvasOps.setScale(1)
+  await subgraphNode.centerOnNode()
+
+  // Click the promoted seed widget on the canvas to select it
+  const seedWidgetRef = await subgraphNode.getWidget(0)
+  const seedPos = await seedWidgetRef.getPosition()
+  const titleHeight = await page.evaluate(
+    () => window.LiteGraph!['NODE_TITLE_HEIGHT'] as number
+  )
+
+  await page.mouse.click(seedPos.x, seedPos.y + titleHeight)
+  await comfyPage.nextFrame()
+
+  // Select an output node
+  await appMode.goToOutputs()
+
+  const saveImageNodeId = await page.evaluate(() =>
+    String(
+      window.app!.rootGraph.nodes.find(
+        (n: { type?: string }) =>
+          n.type === 'SaveImage' || n.type === 'PreviewImage'
+      )?.id
+    )
+  )
+  const saveImageRef = await comfyPage.nodeOps.getNodeRefById(saveImageNodeId)
+  await saveImageRef.centerOnNode()
+
+  // Node is centered on screen, so click the canvas center
+  const canvasBox = await page.locator('#graph-canvas').boundingBox()
+  if (!canvasBox) throw new Error('Canvas not found')
+  await page.mouse.click(
+    canvasBox.x + canvasBox.width / 2,
+    canvasBox.y + canvasBox.height / 2
+  )
+  await comfyPage.nextFrame()
+
+  return subgraphNode
+}
+
+/** Save the workflow, reopen it, and enter app mode. */
+async function saveAndReopenInAppMode(
+  comfyPage: ComfyPage,
+  workflowName: string
+) {
+  await comfyPage.menu.topbar.saveWorkflow(workflowName)
+
+  const { workflowsTab } = comfyPage.menu
+  await workflowsTab.open()
+  await workflowsTab.getPersistedItem(workflowName).dblclick()
+  await comfyPage.nextFrame()
+
+  await comfyPage.appMode.toggleAppMode()
+}
 
 test.describe('App mode widget rename', { tag: ['@ui', '@subgraph'] }, () => {
   test.beforeEach(async ({ comfyPage }) => {

browser_tests/tests/builderSaveFlow.spec.ts

@@ -1,251 +0,0 @@
-import {
-  comfyPageFixture as test,
-  comfyExpect as expect
-} from '../fixtures/ComfyPage'
-import { setupSubgraphBuilder } from '../helpers/builderTestUtils'
-import { fitToViewInstant } from '../helpers/fitToView'
-
-test.describe('Builder save flow', { tag: ['@ui', '@subgraph'] }, () => {
-  test.beforeEach(async ({ comfyPage }) => {
-    await comfyPage.page.evaluate(() => {
-      window.app!.api.serverFeatureFlags.value = {
-        ...window.app!.api.serverFeatureFlags.value,
-        linear_toggle_enabled: true
-      }
-    })
-    await comfyPage.settings.setSetting('Comfy.UseNewMenu', 'Top')
-    await comfyPage.settings.setSetting(
-      'Comfy.AppBuilder.VueNodeSwitchDismissed',
-      true
-    )
-  })
-
-  test('Save as dialog appears for unsaved workflow', async ({ comfyPage }) => {
-    const { page, appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-    await appMode.goToPreview()
-    await appMode.clickSave()
-
-    // The save-as dialog should appear with filename input and view type selection
-    const dialog = page.getByRole('dialog')
-    await expect(dialog).toBeVisible({ timeout: 5000 })
-    await expect(dialog.getByRole('textbox')).toBeVisible()
-    await expect(dialog.getByText('Save as')).toBeVisible()
-
-    // View type radio group should be present
-    const radioGroup = dialog.getByRole('radiogroup')
-    await expect(radioGroup).toBeVisible()
-  })
-
-  test('Save as dialog allows entering filename and saving', async ({
-    comfyPage
-  }) => {
-    const { page, appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-    await appMode.goToPreview()
-    await appMode.clickSave()
-
-    const dialog = page.getByRole('dialog')
-    await expect(dialog).toBeVisible({ timeout: 5000 })
-
-    const workflowName = `${Date.now()} builder-save-test`
-    const input = dialog.getByRole('textbox')
-    await input.fill(workflowName)
-
-    // Save button should be enabled now
-    const saveButton = dialog.getByRole('button', { name: 'Save' })
-    await expect(saveButton).toBeEnabled()
-    await saveButton.click()
-
-    // Success dialog should appear
-    const successDialog = page.getByRole('dialog')
-    await expect(successDialog.getByText('Successfully saved')).toBeVisible({
-      timeout: 5000
-    })
-  })
-
-  test('Save as dialog disables save when filename is empty', async ({
-    comfyPage
-  }) => {
-    const { page, appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-    await appMode.goToPreview()
-    await appMode.clickSave()
-
-    const dialog = page.getByRole('dialog')
-    await expect(dialog).toBeVisible({ timeout: 5000 })
-
-    // Clear the filename input
-    const input = dialog.getByRole('textbox')
-    await input.fill('')
-
-    // Save button should be disabled
-    const saveButton = dialog.getByRole('button', { name: 'Save' })
-    await expect(saveButton).toBeDisabled()
-  })
-
-  test('Builder step navigation works correctly', async ({ comfyPage }) => {
-    const { appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-
-    // Should start at outputs (we ended there in setup)
-    // Navigate to inputs
-    await appMode.goToInputs()
-
-    // Back button should be disabled on first step
-    const backButton = appMode.getFooterButton('Back')
-    await expect(backButton).toBeDisabled()
-
-    // Next button should be enabled
-    const nextButton = appMode.getFooterButton('Next')
-    await expect(nextButton).toBeEnabled()
-
-    // Navigate forward
-    await appMode.next()
-
-    // Back button should now be enabled
-    await expect(backButton).toBeEnabled()
-
-    // Navigate to preview (last step)
-    await appMode.next()
-
-    // Next button should be disabled on last step
-    await expect(nextButton).toBeDisabled()
-  })
-
-  test('Escape key exits builder mode', async ({ comfyPage }) => {
-    const { page } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-
-    // Verify builder toolbar is visible
-    const toolbar = page.getByRole('navigation', { name: 'App Builder' })
-    await expect(toolbar).toBeVisible()
-
-    // Press Escape
-    await page.keyboard.press('Escape')
-    await comfyPage.nextFrame()
-
-    // Builder toolbar should be gone
-    await expect(toolbar).not.toBeVisible()
-  })
-
-  test('Exit builder button exits builder mode', async ({ comfyPage }) => {
-    const { page, appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-
-    const toolbar = page.getByRole('navigation', { name: 'App Builder' })
-    await expect(toolbar).toBeVisible()
-
-    await appMode.exitBuilder()
-
-    await expect(toolbar).not.toBeVisible()
-  })
-
-  test('Save button directly saves for previously saved workflow', async ({
-    comfyPage
-  }) => {
-    const { page, appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-    await appMode.goToPreview()
-
-    // First save via builder save-as to make it non-temporary
-    await appMode.clickSave()
-    const saveAsDialog = page.getByRole('dialog')
-    await expect(saveAsDialog).toBeVisible({ timeout: 5000 })
-    const workflowName = `${Date.now()} builder-direct-save`
-    await saveAsDialog.getByRole('textbox').fill(workflowName)
-    await saveAsDialog.getByRole('button', { name: 'Save' }).click()
-
-    // Dismiss the success dialog
-    const successDialog = page.getByRole('dialog')
-    await expect(successDialog.getByText('Successfully saved')).toBeVisible({
-      timeout: 5000
-    })
-    await successDialog.getByText('Close', { exact: true }).click()
-    await comfyPage.nextFrame()
-
-    // Now click save again — should save directly
-    await appMode.clickSave()
-
-    await expect(page.getByRole('dialog')).not.toBeVisible({ timeout: 2000 })
-    await expect(appMode.getFooterButton(/^Save$/)).toBeDisabled()
-  })
-
-  test('Split button chevron opens save-as for saved workflow', async ({
-    comfyPage
-  }) => {
-    const { page, appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-    await appMode.goToPreview()
-
-    // First save via builder save-as to make it non-temporary
-    await appMode.clickSave()
-    const saveAsDialog = page.getByRole('dialog')
-    await expect(saveAsDialog).toBeVisible({ timeout: 5000 })
-    const workflowName = `${Date.now()} builder-split-btn`
-    await saveAsDialog.getByRole('textbox').fill(workflowName)
-    await saveAsDialog.getByRole('button', { name: 'Save' }).click()
-
-    // Dismiss the success dialog
-    const successDialog = page.getByRole('dialog')
-    await expect(successDialog.getByText('Successfully saved')).toBeVisible({
-      timeout: 5000
-    })
-    await successDialog.getByText('Close', { exact: true }).click()
-    await comfyPage.nextFrame()
-
-    // Click the chevron dropdown trigger
-    const chevronButton = appMode.getFooterButton('Save as')
-    await chevronButton.click()
-
-    // "Save as" menu item should appear
-    const menuItem = page.getByRole('menuitem', { name: 'Save as' })
-    await expect(menuItem).toBeVisible({ timeout: 5000 })
-    await menuItem.click()
-
-    // Save-as dialog should appear
-    const newSaveAsDialog = page.getByRole('dialog')
-    await expect(newSaveAsDialog.getByText('Save as')).toBeVisible({
-      timeout: 5000
-    })
-    await expect(newSaveAsDialog.getByRole('textbox')).toBeVisible()
-  })
-
-  test('Connect output popover appears when no outputs selected', async ({
-    comfyPage
-  }) => {
-    const { page, appMode } = comfyPage
-    await comfyPage.workflow.loadWorkflow('default')
-    await fitToViewInstant(comfyPage)
-    await appMode.enterBuilder()
-
-    // Without selecting any outputs, click the save button
-    // It should trigger the connect-output popover
-    await appMode.clickSave()
-
-    // The popover should show a message about connecting outputs
-    await expect(
-      page.getByText('Connect an output', { exact: false })
-    ).toBeVisible({ timeout: 5000 })
-  })
-
-  test('View type can be toggled in save-as dialog', async ({ comfyPage }) => {
-    const { page, appMode } = comfyPage
-    await setupSubgraphBuilder(comfyPage)
-    await appMode.goToPreview()
-    await appMode.clickSave()
-
-    const dialog = page.getByRole('dialog')
-    await expect(dialog).toBeVisible({ timeout: 5000 })
-
-    // App should be selected by default
-    const appRadio = dialog.getByRole('radio', { name: /App/ })
-    await expect(appRadio).toHaveAttribute('aria-checked', 'true')
-
-    // Click Node graph option
-    const graphRadio = dialog.getByRole('radio', { name: /Node graph/ })
-    await graphRadio.click()
-    await expect(graphRadio).toHaveAttribute('aria-checked', 'true')
-    await expect(appRadio).toHaveAttribute('aria-checked', 'false')
-  })
-})

browser_tests/tests/changeTrackerLoadGuard.spec.ts

@@ -1,66 +0,0 @@
-import {
-  comfyExpect as expect,
-  comfyPageFixture as test
-} from '../fixtures/ComfyPage'
-import type { WorkspaceStore } from '../types/globals'
-
-test.describe(
-  'Change Tracker - isLoadingGraph guard',
-  { tag: '@workflow' },
-  () => {
-    test.beforeEach(async ({ comfyPage }) => {
-      await comfyPage.workflow.setupWorkflowsDirectory({})
-    })
-
-    test('Prevents checkState from corrupting workflow state during tab switch', async ({
-      comfyPage
-    }) => {
-      // Tab 0: default workflow (7 nodes)
-      expect(await comfyPage.nodeOps.getGraphNodesCount()).toBe(7)
-
-      // Save tab 0 so it has a unique name for tab switching
-      await comfyPage.menu.topbar.saveWorkflow('workflow-a')
-
-      // Register an extension that forces checkState during graph loading.
-      // This simulates the bug scenario where a user clicks during graph loading
-      // which triggers a checkState call on the wrong graph, corrupting the activeState.
-      await comfyPage.page.evaluate(() => {
-        window.app!.registerExtension({
-          name: 'TestCheckStateDuringLoad',
-          afterConfigureGraph() {
-            const workflow = (window.app!.extensionManager as WorkspaceStore)
-              .workflow.activeWorkflow
-            if (!workflow) throw new Error('No workflow found')
-            // Bypass the guard to reproduce the corruption bug:
-            // ; (workflow.changeTracker.constructor as unknown as { isLoadingGraph: boolean }).isLoadingGraph = false
-
-            // Simulate the user clicking during graph loading
-            workflow.changeTracker.checkState()
-          }
-        })
-      })
-
-      // Create tab 1: blank workflow (0 nodes)
-      await comfyPage.menu.topbar.triggerTopbarCommand(['New'])
-      await comfyPage.nextFrame()
-      expect(await comfyPage.nodeOps.getGraphNodesCount()).toBe(0)
-
-      // Switch back to tab 0 (workflow-a).
-      const tab0 = comfyPage.menu.topbar.getWorkflowTab('workflow-a')
-      await tab0.click()
-      await comfyPage.nextFrame()
-      expect(await comfyPage.nodeOps.getGraphNodesCount()).toBe(7)
-
-      // switch to blank tab and back to verify no corruption
-      const tab1 = comfyPage.menu.topbar.getWorkflowTab('Unsaved Workflow')
-      await tab1.click()
-      await comfyPage.nextFrame()
-      expect(await comfyPage.nodeOps.getGraphNodesCount()).toBe(0)
-
-      // switch again and verify no corruption
-      await tab0.click()
-      await comfyPage.nextFrame()
-      expect(await comfyPage.nodeOps.getGraphNodesCount()).toBe(7)
-    })
-  }
-)

browser_tests/tests/containAudit.spec.ts

@@ -1,276 +0,0 @@
-import { expect } from '@playwright/test'
-
-import type { PerfMeasurement } from '../fixtures/helpers/PerformanceHelper'
-
-import { comfyPageFixture as test } from '../fixtures/ComfyPage'
-
-interface ContainCandidate {
-  selector: string
-  testId: string | null
-  tagName: string
-  className: string
-  subtreeSize: number
-  hasFixedWidth: boolean
-  isFlexChild: boolean
-  hasExplicitDimensions: boolean
-  alreadyContained: boolean
-  score: number
-}
-
-interface AuditResult {
-  candidate: ContainCandidate
-  baseline: Pick<PerfMeasurement, 'styleRecalcs' | 'layouts' | 'taskDurationMs'>
-  withContain: Pick<
-    PerfMeasurement,
-    'styleRecalcs' | 'layouts' | 'taskDurationMs'
-  >
-  deltaRecalcsPct: number
-  deltaLayoutsPct: number
-  visuallyBroken: boolean
-}
-
-function formatPctDelta(value: number): string {
-  const sign = value >= 0 ? '+' : ''
-  return `${sign}${value.toFixed(1)}%`
-}
-
-function pctChange(baseline: number, measured: number): number {
-  if (baseline === 0) return 0
-  return ((measured - baseline) / baseline) * 100
-}
-
-const STABILIZATION_FRAMES = 60
-const SETTLE_FRAMES = 10
-
-test.describe('CSS Containment Audit', { tag: ['@audit'] }, () => {
-  test('scan large graph for containment candidates', async ({ comfyPage }) => {
-    await comfyPage.workflow.loadWorkflow('large-graph-workflow')
-
-    for (let i = 0; i < STABILIZATION_FRAMES; i++) {
-      await comfyPage.nextFrame()
-    }
-
-    // Walk the DOM and find candidates
-    const candidates = await comfyPage.page.evaluate((): ContainCandidate[] => {
-      const results: ContainCandidate[] = []
-
-      const graphContainer =
-        document.querySelector('.graph-canvas-container') ??
-        document.querySelector('[class*="comfy-vue-node"]')?.parentElement ??
-        document.querySelector('.lg-node')?.parentElement
-
-      const root = graphContainer ?? document.body
-      const allElements = root.querySelectorAll('*')
-
-      allElements.forEach((el) => {
-        if (!(el instanceof HTMLElement)) return
-
-        const subtreeSize = el.querySelectorAll('*').length
-        if (subtreeSize < 5) return
-
-        const computed = getComputedStyle(el)
-
-        const containValue = computed.contain || 'none'
-        const alreadyContained =
-          containValue.includes('layout') || containValue.includes('strict')
-
-        const hasFixedWidth =
-          computed.width !== 'auto' &&
-          !computed.width.includes('%') &&
-          computed.width !== '0px'
-
-        const isFlexChild =
-          el.parentElement !== null &&
-          getComputedStyle(el.parentElement).display.includes('flex') &&
-          (computed.flexGrow !== '0' || computed.flexShrink !== '1')
-
-        const hasExplicitDimensions =
-          hasFixedWidth ||
-          (computed.minWidth !== '0px' && computed.minWidth !== 'auto') ||
-          (computed.maxWidth !== 'none' && computed.maxWidth !== '0px')
-
-        let score = subtreeSize
-        if (hasExplicitDimensions) score *= 2
-        if (isFlexChild) score *= 1.5
-        if (alreadyContained) score = 0
-
-        let selector = el.tagName.toLowerCase()
-        const testId = el.getAttribute('data-testid')
-        if (testId) {
-          selector = `[data-testid="${testId}"]`
-        } else if (el.id) {
-          selector = `#${el.id}`
-        } else if (el.parentElement) {
-          // Use nth-child to disambiguate instead of fragile first-class fallback
-          // (e.g. Tailwind utilities like .flex, .relative are shared across many elements)
-          const children = Array.from(el.parentElement.children)
-          const index = children.indexOf(el) + 1
-          const parentTestId = el.parentElement.getAttribute('data-testid')
-          if (parentTestId) {
-            selector = `[data-testid="${parentTestId}"] > :nth-child(${index})`
-          } else if (el.parentElement.id) {
-            selector = `#${el.parentElement.id} > :nth-child(${index})`
-          } else {
-            const tag = el.tagName.toLowerCase()
-            selector = `${tag}:nth-child(${index})`
-          }
-        }
-
-        results.push({
-          selector,
-          testId,
-          tagName: el.tagName.toLowerCase(),
-          className:
-            typeof el.className === 'string' ? el.className.slice(0, 80) : '',
-          subtreeSize,
-          hasFixedWidth,
-          isFlexChild,
-          hasExplicitDimensions,
-          alreadyContained,
-          score
-        })
-      })
-
-      results.sort((a, b) => b.score - a.score)
-      return results.slice(0, 20)
-    })
-
-    console.log(`\nFound ${candidates.length} containment candidates\n`)
-
-    // Deduplicate candidates by selector (keep highest score)
-    const seen = new Set<string>()
-    const uniqueCandidates = candidates.filter((c) => {
-      if (seen.has(c.selector)) return false
-      seen.add(c.selector)
-      return true
-    })
-
-    // Measure baseline performance (idle)
-    await comfyPage.perf.startMeasuring()
-    for (let i = 0; i < STABILIZATION_FRAMES; i++) {
-      await comfyPage.nextFrame()
-    }
-    const baseline = await comfyPage.perf.stopMeasuring('baseline-idle')
-
-    // Take a baseline screenshot for visual comparison
-    const baselineScreenshot = await comfyPage.page.screenshot()
-
-    // For each candidate, apply contain and measure
-    const results: AuditResult[] = []
-
-    const testCandidates = uniqueCandidates
-      .filter((c) => !c.alreadyContained && c.score > 0)
-      .slice(0, 10)
-
-    for (const candidate of testCandidates) {
-      const applied = await comfyPage.page.evaluate((sel: string) => {
-        const elements = document.querySelectorAll(sel)
-        let count = 0
-        elements.forEach((el) => {
-          if (el instanceof HTMLElement) {
-            el.style.contain = 'layout style'
-            count++
-          }
-        })
-        return count
-      }, candidate.selector)
-
-      if (applied === 0) continue
-
-      for (let i = 0; i < SETTLE_FRAMES; i++) {
-        await comfyPage.nextFrame()
-      }
-
-      // Measure with containment
-      await comfyPage.perf.startMeasuring()
-      for (let i = 0; i < STABILIZATION_FRAMES; i++) {
-        await comfyPage.nextFrame()
-      }
-      const withContain = await comfyPage.perf.stopMeasuring(
-        `contain-${candidate.selector}`
-      )
-
-      // Take screenshot with containment applied to detect visual breakage.
-      // Note: PNG byte comparison can produce false positives from subpixel
-      // rendering and anti-aliasing. Treat "DIFF" as "needs manual review".
-      const containScreenshot = await comfyPage.page.screenshot()
-      const visuallyBroken = !baselineScreenshot.equals(containScreenshot)
-
-      // Remove containment
-      await comfyPage.page.evaluate((sel: string) => {
-        document.querySelectorAll(sel).forEach((el) => {
-          if (el instanceof HTMLElement) {
-            el.style.contain = ''
-          }
-        })
-      }, candidate.selector)
-
-      for (let i = 0; i < SETTLE_FRAMES; i++) {
-        await comfyPage.nextFrame()
-      }
-
-      results.push({
-        candidate,
-        baseline: {
-          styleRecalcs: baseline.styleRecalcs,
-          layouts: baseline.layouts,
-          taskDurationMs: baseline.taskDurationMs
-        },
-        withContain: {
-          styleRecalcs: withContain.styleRecalcs,
-          layouts: withContain.layouts,
-          taskDurationMs: withContain.taskDurationMs
-        },
-        deltaRecalcsPct: pctChange(
-          baseline.styleRecalcs,
-          withContain.styleRecalcs
-        ),
-        deltaLayoutsPct: pctChange(baseline.layouts, withContain.layouts),
-        visuallyBroken
-      })
-    }
-
-    // Print the report
-    const divider = '='.repeat(100)
-    const thinDivider = '-'.repeat(100)
-    console.log('\n')
-    console.log('CSS Containment Audit Results')
-    console.log(divider)
-    console.log(
-      'Rank | Selector                                   | Subtree | Score | DRecalcs   | DLayouts   | Visual'
-    )
-    console.log(thinDivider)
-
-    results
-      .sort((a, b) => a.deltaRecalcsPct - b.deltaRecalcsPct)
-      .forEach((r, i) => {
-        const sel = r.candidate.selector.padEnd(42)
-        const sub = String(r.candidate.subtreeSize).padStart(7)
-        const score = String(Math.round(r.candidate.score)).padStart(5)
-        const dr = formatPctDelta(r.deltaRecalcsPct)
-        const dl = formatPctDelta(r.deltaLayoutsPct)
-        const vis = r.visuallyBroken ? 'DIFF' : 'OK'
-        console.log(
-          `  ${String(i + 1).padStart(2)}  | ${sel} | ${sub} | ${score} | ${dr.padStart(10)} | ${dl.padStart(10)} | ${vis}`
-        )
-      })
-
-    console.log(divider)
-    console.log(
-      `\nBaseline: ${baseline.styleRecalcs} style recalcs, ${baseline.layouts} layouts, ${baseline.taskDurationMs.toFixed(1)}ms task duration\n`
-    )
-
-    const alreadyContained = uniqueCandidates.filter((c) => c.alreadyContained)
-    if (alreadyContained.length > 0) {
-      console.log('Already contained elements:')
-      alreadyContained.forEach((c) => {
-        console.log(`  ${c.selector} (subtree: ${c.subtreeSize})`)
-      })
-    }
-
-    expect(results.length).toBeGreaterThan(0)
-  })
-
-  // Pan interaction perf measurement removed — covered by PR #10001 (performance.spec.ts).
-  // The containment fix itself is tracked in PR #9946.
-})

browser_tests/tests/dialog.spec.ts

@@ -28,11 +28,8 @@ test.describe('Missing nodes in Error Overlay', { tag: '@ui' }, () => {
     )
     await expect(errorOverlay).toBeVisible()
 
-    const messages = errorOverlay.getByTestId(
-      TestIds.dialogs.errorOverlayMessages
-    )
-    await expect(messages).toBeVisible()
-    await expect(messages).toHaveText(/missing.*installed/i)
+    const missingNodesTitle = errorOverlay.getByText(/Missing Node Packs/)
+    await expect(missingNodesTitle).toBeVisible()
   })
 
   test('Should show error overlay when loading a workflow with missing nodes in subgraphs', async ({
@@ -45,11 +42,8 @@ test.describe('Missing nodes in Error Overlay', { tag: '@ui' }, () => {
     )
     await expect(errorOverlay).toBeVisible()
 
-    const messages = errorOverlay.getByTestId(
-      TestIds.dialogs.errorOverlayMessages
-    )
-    await expect(messages).toBeVisible()
-    await expect(messages).toHaveText(/missing.*installed/i)
+    const missingNodesTitle = errorOverlay.getByText(/Missing Node Packs/)
+    await expect(missingNodesTitle).toBeVisible()
 
     // Click "See Errors" to open the errors tab and verify subgraph node content
     await errorOverlay
@@ -108,7 +102,7 @@ test('Does not resurface missing nodes on undo/redo', async ({ comfyPage }) => {
   await expect(errorOverlay).toBeVisible()
 
   // Dismiss the error overlay
-  await errorOverlay.getByTestId(TestIds.dialogs.errorOverlayDismiss).click()
+  await errorOverlay.getByRole('button', { name: 'Dismiss' }).click()
   await expect(errorOverlay).not.toBeVisible()
 
   // Make a change to the graph by moving a node
@@ -216,11 +210,8 @@ test.describe('Missing models in Error Tab', () => {
     )
     await expect(errorOverlay).toBeVisible()
 
-    const messages = errorOverlay.getByTestId(
-      TestIds.dialogs.errorOverlayMessages
-    )
-    await expect(messages).toBeVisible()
-    await expect(messages).toHaveText(/required model.*missing/i)
+    const missingModelsTitle = errorOverlay.getByText(/Missing Models/)
+    await expect(missingModelsTitle).toBeVisible()
   })
 
   test('Should show missing models from node properties', async ({
@@ -235,11 +226,8 @@ test.describe('Missing models in Error Tab', () => {
     )
     await expect(errorOverlay).toBeVisible()
 
-    const messages = errorOverlay.getByTestId(
-      TestIds.dialogs.errorOverlayMessages
-    )
-    await expect(messages).toBeVisible()
-    await expect(messages).toHaveText(/required model.*missing/i)
+    const missingModelsTitle = errorOverlay.getByText(/Missing Models/)
+    await expect(missingModelsTitle).toBeVisible()
   })
 
   test('Should not show missing models when widget values have changed', async ({
@@ -252,9 +240,7 @@ test.describe('Missing models in Error Tab', () => {
     await expect(
       comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
     ).not.toBeVisible()
-    await expect(
-      comfyPage.page.getByTestId(TestIds.dialogs.errorOverlayMessages)
-    ).not.toBeVisible()
+    await expect(comfyPage.page.getByText(/Missing Models/)).not.toBeVisible()
   })
 
   // Flaky test after parallelization

browser_tests/tests/errorOverlaySeeErrors.spec.ts

@@ -4,7 +4,6 @@ import {
   comfyPageFixture as test,
   comfyExpect as expect
 } from '../fixtures/ComfyPage'
-import { TestIds } from '../fixtures/selectors'
 
 test.describe('Error overlay See Errors flow', { tag: '@ui' }, () => {
   test.beforeEach(async ({ comfyPage }) => {
@@ -30,14 +29,14 @@ test.describe('Error overlay See Errors flow', { tag: '@ui' }, () => {
     await triggerExecutionError(comfyPage)
 
     await expect(
-      comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
+      comfyPage.page.locator('[data-testid="error-overlay"]')
     ).toBeVisible()
   })
 
   test('Error overlay shows error message', async ({ comfyPage }) => {
     await triggerExecutionError(comfyPage)
 
-    const overlay = comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
+    const overlay = comfyPage.page.locator('[data-testid="error-overlay"]')
     await expect(overlay).toBeVisible()
     await expect(overlay).toHaveText(/\S/)
   })
@@ -45,10 +44,10 @@ test.describe('Error overlay See Errors flow', { tag: '@ui' }, () => {
   test('"See Errors" opens right side panel', async ({ comfyPage }) => {
     await triggerExecutionError(comfyPage)
 
-    const overlay = comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
+    const overlay = comfyPage.page.locator('[data-testid="error-overlay"]')
     await expect(overlay).toBeVisible()
 
-    await overlay.getByTestId(TestIds.dialogs.errorOverlaySeeErrors).click()
+    await overlay.getByRole('button', { name: /See Errors/i }).click()
 
     await expect(comfyPage.page.getByTestId('properties-panel')).toBeVisible()
   })
@@ -56,10 +55,10 @@ test.describe('Error overlay See Errors flow', { tag: '@ui' }, () => {
   test('"See Errors" dismisses the overlay', async ({ comfyPage }) => {
     await triggerExecutionError(comfyPage)
 
-    const overlay = comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
+    const overlay = comfyPage.page.locator('[data-testid="error-overlay"]')
     await expect(overlay).toBeVisible()
 
-    await overlay.getByTestId(TestIds.dialogs.errorOverlaySeeErrors).click()
+    await overlay.getByRole('button', { name: /See Errors/i }).click()
 
     await expect(overlay).not.toBeVisible()
   })
@@ -69,10 +68,10 @@ test.describe('Error overlay See Errors flow', { tag: '@ui' }, () => {
   }) => {
     await triggerExecutionError(comfyPage)
 
-    const overlay = comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
+    const overlay = comfyPage.page.locator('[data-testid="error-overlay"]')
     await expect(overlay).toBeVisible()
 
-    await overlay.getByTestId(TestIds.dialogs.errorOverlayDismiss).click()
+    await overlay.getByRole('button', { name: /Dismiss/i }).click()
 
     await expect(overlay).not.toBeVisible()
     await expect(
@@ -83,7 +82,7 @@ test.describe('Error overlay See Errors flow', { tag: '@ui' }, () => {
   test('Close button (X) dismisses overlay', async ({ comfyPage }) => {
     await triggerExecutionError(comfyPage)
 
-    const overlay = comfyPage.page.getByTestId(TestIds.dialogs.errorOverlay)
+    const overlay = comfyPage.page.locator('[data-testid="error-overlay"]')
     await expect(overlay).toBeVisible()
 
     await overlay.getByRole('button', { name: /close/i }).click()

browser_tests/tests/execution.spec.ts

@@ -1,7 +1,6 @@
 import { expect } from '@playwright/test'
 
 import { comfyPageFixture as test } from '../fixtures/ComfyPage'
-import { TestIds } from '../fixtures/selectors'
 
 test.beforeEach(async ({ comfyPage }) => {
   await comfyPage.settings.setSetting('Comfy.UseNewMenu', 'Disabled')
@@ -25,14 +24,16 @@ test.describe('Execution', { tag: ['@smoke', '@workflow'] }, () => {
       await comfyPage.page.keyboard.press('Escape')
 
       await comfyPage.command.executeCommand('Comfy.QueuePrompt')
-      const errorOverlay = comfyPage.page.getByTestId(
-        TestIds.dialogs.errorOverlay
-      )
-      await expect(errorOverlay).toBeVisible()
-      await errorOverlay
-        .getByTestId(TestIds.dialogs.errorOverlayDismiss)
+      await expect(
+        comfyPage.page.locator('[data-testid="error-overlay"]')
+      ).toBeVisible()
+      await comfyPage.page
+        .locator('[data-testid="error-overlay"]')
+        .getByRole('button', { name: 'Dismiss' })
         .click()
-      await errorOverlay.waitFor({ state: 'hidden' })
+      await comfyPage.page
+        .locator('[data-testid="error-overlay"]')
+        .waitFor({ state: 'hidden' })
       await expect(comfyPage.canvas).toHaveScreenshot(
         'execution-error-unconnected-slot.png'
       )

browser_tests/tests/maskEditor.spec.ts

@@ -1,92 +0,0 @@
-import { expect } from '@playwright/test'
-
-import type { ComfyPage } from '../fixtures/ComfyPage'
-import { comfyPageFixture as test } from '../fixtures/ComfyPage'
-
-test.describe('Mask Editor', () => {
-  test.beforeEach(async ({ comfyPage }) => {
-    await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', true)
-  })
-
-  async function loadImageOnNode(comfyPage: ComfyPage) {
-    await comfyPage.workflow.loadWorkflow('widgets/load_image_widget')
-    await comfyPage.vueNodes.waitForNodes()
-
-    const loadImageNode = (
-      await comfyPage.nodeOps.getNodeRefsByType('LoadImage')
-    )[0]
-    const { x, y } = await loadImageNode.getPosition()
-
-    await comfyPage.dragDrop.dragAndDropFile('image64x64.webp', {
-      dropPosition: { x, y }
-    })
-
-    const imagePreview = comfyPage.page.locator('.image-preview')
-    await expect(imagePreview).toBeVisible()
-    await expect(imagePreview.locator('img')).toBeVisible()
-    await expect(imagePreview).toContainText('x')
-
-    return {
-      imagePreview,
-      nodeId: String(loadImageNode.id)
-    }
-  }
-
-  test(
-    'opens mask editor from image preview button',
-    { tag: ['@smoke', '@screenshot'] },
-    async ({ comfyPage }) => {
-      const { imagePreview } = await loadImageOnNode(comfyPage)
-
-      // Hover over the image panel to reveal action buttons
-      await imagePreview.getByRole('region').hover()
-      await comfyPage.page.getByLabel('Edit or mask image').click()
-
-      const dialog = comfyPage.page.locator('.mask-editor-dialog')
-      await expect(dialog).toBeVisible()
-
-      await expect(
-        dialog.getByRole('heading', { name: 'Mask Editor' })
-      ).toBeVisible()
-
-      const canvasContainer = dialog.locator('#maskEditorCanvasContainer')
-      await expect(canvasContainer).toBeVisible()
-      await expect(canvasContainer.locator('canvas')).toHaveCount(4)
-
-      await expect(dialog.locator('.maskEditor-ui-container')).toBeVisible()
-      await expect(dialog.getByText('Save')).toBeVisible()
-      await expect(dialog.getByText('Cancel')).toBeVisible()
-
-      await expect(dialog).toHaveScreenshot('mask-editor-dialog-open.png')
-    }
-  )
-
-  test(
-    'opens mask editor from context menu',
-    { tag: ['@smoke', '@screenshot'] },
-    async ({ comfyPage }) => {
-      const { nodeId } = await loadImageOnNode(comfyPage)
-
-      const nodeHeader = comfyPage.vueNodes
-        .getNodeLocator(nodeId)
-        .locator('.lg-node-header')
-      await nodeHeader.click()
-      await nodeHeader.click({ button: 'right' })
-
-      const contextMenu = comfyPage.page.locator('.p-contextmenu')
-      await expect(contextMenu).toBeVisible()
-
-      await contextMenu.getByText('Open in Mask Editor').click()
-
-      const dialog = comfyPage.page.locator('.mask-editor-dialog')
-      await expect(dialog).toBeVisible()
-      await expect(
-        dialog.getByRole('heading', { name: 'Mask Editor' })
-      ).toBeVisible()
-
-      await expect(dialog).toHaveScreenshot(
-        'mask-editor-dialog-from-context-menu.png'
-      )
-    }
-  )
-})

browser_tests/tests/painter.spec.ts

@@ -1,92 +0,0 @@
-import { expect } from '@playwright/test'
-
-import { comfyPageFixture as test } from '../fixtures/ComfyPage'
-
-test.describe('Painter', () => {
-  test.beforeEach(async ({ comfyPage }) => {
-    await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', true)
-    await comfyPage.workflow.loadWorkflow('widgets/painter_widget')
-    await comfyPage.vueNodes.waitForNodes()
-  })
-
-  test(
-    'Renders canvas and controls',
-    { tag: ['@smoke', '@screenshot'] },
-    async ({ comfyPage }) => {
-      const node = comfyPage.vueNodes.getNodeLocator('1')
-      await expect(node).toBeVisible()
-
-      const painterWidget = node.locator('.widget-expands')
-      await expect(painterWidget).toBeVisible()
-
-      await expect(painterWidget.locator('canvas')).toBeVisible()
-      await expect(painterWidget.getByText('Brush')).toBeVisible()
-      await expect(painterWidget.getByText('Eraser')).toBeVisible()
-      await expect(painterWidget.getByText('Clear')).toBeVisible()
-      await expect(
-        painterWidget.locator('input[type="color"]').first()
-      ).toBeVisible()
-
-      await expect(node).toHaveScreenshot('painter-default-state.png')
-    }
-  )
-
-  test(
-    'Drawing a stroke changes the canvas',
-    { tag: ['@smoke', '@screenshot'] },
-    async ({ comfyPage }) => {
-      const node = comfyPage.vueNodes.getNodeLocator('1')
-      const canvas = node.locator('.widget-expands canvas')
-      await expect(canvas).toBeVisible()
-
-      const isEmptyBefore = await canvas.evaluate((el) => {
-        const ctx = (el as HTMLCanvasElement).getContext('2d')
-        if (!ctx) return true
-        const data = ctx.getImageData(
-          0,
-          0,
-          (el as HTMLCanvasElement).width,
-          (el as HTMLCanvasElement).height
-        )
-        return data.data.every((v, i) => (i % 4 === 3 ? v === 0 : true))
-      })
-      expect(isEmptyBefore).toBe(true)
-
-      const box = await canvas.boundingBox()
-      if (!box) throw new Error('Canvas bounding box not found')
-
-      await comfyPage.page.mouse.move(
-        box.x + box.width * 0.3,
-        box.y + box.height * 0.5
-      )
-      await comfyPage.page.mouse.down()
-      await comfyPage.page.mouse.move(
-        box.x + box.width * 0.7,
-        box.y + box.height * 0.5,
-        { steps: 10 }
-      )
-      await comfyPage.page.mouse.up()
-      await comfyPage.nextFrame()
-
-      await expect(async () => {
-        const hasContent = await canvas.evaluate((el) => {
-          const ctx = (el as HTMLCanvasElement).getContext('2d')
-          if (!ctx) return false
-          const data = ctx.getImageData(
-            0,
-            0,
-            (el as HTMLCanvasElement).width,
-            (el as HTMLCanvasElement).height
-          )
-          for (let i = 3; i < data.data.length; i += 4) {
-            if (data.data[i] > 0) return true
-          }
-          return false
-        })
-        expect(hasContent).toBe(true)
-      }).toPass()
-
-      await expect(node).toHaveScreenshot('painter-after-stroke.png')
-    }
-  )
-})

browser_tests/tests/sidebar/assets.spec.ts

@@ -1,30 +0,0 @@
-import { expect } from '@playwright/test'
-
-import { comfyPageFixture as test } from '../../fixtures/ComfyPage'
-
-test.describe('Assets sidebar', () => {
-  test.beforeEach(async ({ comfyPage }) => {
-    await comfyPage.assets.mockEmptyState()
-    await comfyPage.setup()
-  })
-
-  test.afterEach(async ({ comfyPage }) => {
-    await comfyPage.assets.clearMocks()
-  })
-
-  test('Shows empty-state copy for generated and imported tabs', async ({
-    comfyPage
-  }) => {
-    const tab = comfyPage.menu.assetsTab
-
-    await tab.open()
-
-    await expect(tab.emptyStateTitle('No generated files found')).toBeVisible()
-    await expect(tab.emptyStateMessage).toBeVisible()
-
-    await tab.importedTab.click()
-
-    await expect(tab.emptyStateTitle('No imported files found')).toBeVisible()
-    await expect(tab.emptyStateMessage).toBeVisible()
-  })
-})

browser_tests/tests/sidebar/workflows.spec.ts

@@ -247,7 +247,7 @@ test.describe('Workflows sidebar', () => {
     await expect(errorOverlay).toBeVisible()
 
     // Dismiss the error overlay
-    await errorOverlay.getByTestId(TestIds.dialogs.errorOverlayDismiss).click()
+    await errorOverlay.getByRole('button', { name: 'Dismiss' }).click()
     await expect(errorOverlay).not.toBeVisible()
 
     // Load blank workflow

browser_tests/tests/subgraphViewport.spec.ts

@@ -1,114 +0,0 @@
-import { expect } from '@playwright/test'
-
-import { comfyPageFixture as test } from '../fixtures/ComfyPage'
-
-function hasVisibleNodeInViewport() {
-  const canvas = window.app!.canvas
-  if (!canvas?.graph?._nodes?.length) return false
-
-  const ds = canvas.ds
-  const cw = canvas.canvas.width / window.devicePixelRatio
-  const ch = canvas.canvas.height / window.devicePixelRatio
-  const visLeft = -ds.offset[0]
-  const visTop = -ds.offset[1]
-  const visRight = visLeft + cw / ds.scale
-  const visBottom = visTop + ch / ds.scale
-
-  for (const node of canvas.graph._nodes) {
-    const [nx, ny] = node.pos
-    const [nw, nh] = node.size
-    if (
-      nx + nw > visLeft &&
-      nx < visRight &&
-      ny + nh > visTop &&
-      ny < visBottom
-    )
-      return true
-  }
-  return false
-}
-
-test.describe('Subgraph viewport restoration', { tag: '@subgraph' }, () => {
-  test('first visit fits viewport to subgraph nodes (LG)', async ({
-    comfyPage
-  }) => {
-    await comfyPage.workflow.loadWorkflow(
-      'subgraphs/subgraph-with-promoted-text-widget'
-    )
-    await comfyPage.nextFrame()
-
-    await comfyPage.page.evaluate(() => {
-      const canvas = window.app!.canvas
-      const graph = canvas.graph!
-      const sgNode = graph._nodes.find((n) =>
-        'isSubgraphNode' in n
-          ? (n as unknown as { isSubgraphNode: () => boolean }).isSubgraphNode()
-          : false
-      ) as unknown as { subgraph?: typeof graph } | undefined
-      if (!sgNode?.subgraph) throw new Error('No subgraph node')
-
-      canvas.setGraph(sgNode.subgraph)
-    })
-
-    await expect
-      .poll(() => comfyPage.page.evaluate(hasVisibleNodeInViewport), {
-        timeout: 2000
-      })
-      .toBe(true)
-  })
-
-  test('first visit fits viewport to subgraph nodes (Vue)', async ({
-    comfyPage
-  }) => {
-    await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', true)
-    await comfyPage.workflow.loadWorkflow(
-      'subgraphs/subgraph-with-promoted-text-widget'
-    )
-    await comfyPage.vueNodes.waitForNodes()
-
-    await comfyPage.vueNodes.enterSubgraph('11')
-
-    await expect
-      .poll(() => comfyPage.page.evaluate(hasVisibleNodeInViewport), {
-        timeout: 2000
-      })
-      .toBe(true)
-  })
-
-  test('viewport is restored when returning to root (Vue)', async ({
-    comfyPage
-  }) => {
-    await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', true)
-    await comfyPage.workflow.loadWorkflow(
-      'subgraphs/subgraph-with-promoted-text-widget'
-    )
-    await comfyPage.vueNodes.waitForNodes()
-
-    const rootViewport = await comfyPage.page.evaluate(() => {
-      const ds = window.app!.canvas.ds
-      return { scale: ds.scale, offset: [...ds.offset] }
-    })
-
-    await comfyPage.vueNodes.enterSubgraph('11')
-    await comfyPage.nextFrame()
-
-    await comfyPage.subgraph.exitViaBreadcrumb()
-
-    await expect
-      .poll(
-        () =>
-          comfyPage.page.evaluate(() => {
-            const ds = window.app!.canvas.ds
-            return { scale: ds.scale, offset: [...ds.offset] }
-          }),
-        { timeout: 2000 }
-      )
-      .toEqual({
-        scale: expect.closeTo(rootViewport.scale, 2),
-        offset: [
-          expect.closeTo(rootViewport.offset[0], 0),
-          expect.closeTo(rootViewport.offset[1], 0)
-        ]
-      })
-  })
-})

browser_tests/tests/zoomControls.spec.ts

@@ -1,138 +0,0 @@
-import { expect } from '@playwright/test'
-
-import { comfyPageFixture as test } from '../fixtures/ComfyPage'
-import { TestIds } from '../fixtures/selectors'
-
-test.describe('Zoom Controls', { tag: '@canvas' }, () => {
-  test.beforeEach(async ({ comfyPage }) => {
-    await comfyPage.settings.setSetting('Comfy.Graph.CanvasMenu', true)
-    await comfyPage.workflow.loadWorkflow('default')
-    await comfyPage.page.waitForFunction(() => window.app && window.app.canvas)
-  })
-
-  test('Default zoom is 100% and node has a size', async ({ comfyPage }) => {
-    const nodeSize = await comfyPage.page.evaluate(
-      () => window.app!.graph.nodes[0].size
-    )
-    expect(nodeSize[0]).toBeGreaterThan(0)
-    expect(nodeSize[1]).toBeGreaterThan(0)
-
-    const zoomButton = comfyPage.page.getByTestId(
-      TestIds.canvas.zoomControlsButton
-    )
-    await expect(zoomButton).toContainText('100%')
-
-    const scale = await comfyPage.canvasOps.getScale()
-    expect(scale).toBeCloseTo(1.0, 1)
-  })
-
-  test('Zoom to fit reduces percentage', async ({ comfyPage }) => {
-    const zoomButton = comfyPage.page.getByTestId(
-      TestIds.canvas.zoomControlsButton
-    )
-    await zoomButton.click()
-    await comfyPage.nextFrame()
-
-    const zoomToFit = comfyPage.page.getByTestId(TestIds.canvas.zoomToFitAction)
-    await expect(zoomToFit).toBeVisible()
-    await zoomToFit.click()
-
-    await expect
-      .poll(() => comfyPage.canvasOps.getScale(), { timeout: 2000 })
-      .toBeLessThan(1.0)
-
-    await expect(zoomButton).not.toContainText('100%')
-  })
-
-  test('Zoom out reduces percentage', async ({ comfyPage }) => {
-    const initialScale = await comfyPage.canvasOps.getScale()
-
-    const zoomButton = comfyPage.page.getByTestId(
-      TestIds.canvas.zoomControlsButton
-    )
-    await zoomButton.click()
-    await comfyPage.nextFrame()
-
-    const zoomOut = comfyPage.page.getByTestId(TestIds.canvas.zoomOutAction)
-    await zoomOut.click()
-    await comfyPage.nextFrame()
-
-    const newScale = await comfyPage.canvasOps.getScale()
-    expect(newScale).toBeLessThan(initialScale)
-  })
-
-  test('Zoom out clamps at 10% minimum', async ({ comfyPage }) => {
-    const zoomButton = comfyPage.page.getByTestId(
-      TestIds.canvas.zoomControlsButton
-    )
-    await zoomButton.click()
-    await comfyPage.nextFrame()
-
-    const zoomOut = comfyPage.page.getByTestId(TestIds.canvas.zoomOutAction)
-    for (let i = 0; i < 30; i++) {
-      await zoomOut.click()
-    }
-    await comfyPage.nextFrame()
-
-    await expect
-      .poll(() => comfyPage.canvasOps.getScale(), { timeout: 2000 })
-      .toBeCloseTo(0.1, 1)
-
-    await expect(zoomButton).toContainText('10%')
-  })
-
-  test('Manual percentage entry allows zoom in and zoom out', async ({
-    comfyPage
-  }) => {
-    const zoomButton = comfyPage.page.getByTestId(
-      TestIds.canvas.zoomControlsButton
-    )
-    await zoomButton.click()
-    await comfyPage.nextFrame()
-
-    const input = comfyPage.page
-      .getByTestId(TestIds.canvas.zoomPercentageInput)
-      .locator('input')
-    await input.focus()
-    await comfyPage.page.keyboard.press('Control+a')
-    await input.pressSequentially('100')
-    await input.press('Enter')
-    await comfyPage.nextFrame()
-
-    await expect
-      .poll(() => comfyPage.canvasOps.getScale(), { timeout: 2000 })
-      .toBeCloseTo(1.0, 1)
-
-    const zoomIn = comfyPage.page.getByTestId(TestIds.canvas.zoomInAction)
-    await zoomIn.click()
-    await comfyPage.nextFrame()
-
-    const scaleAfterZoomIn = await comfyPage.canvasOps.getScale()
-    expect(scaleAfterZoomIn).toBeGreaterThan(1.0)
-
-    const zoomOut = comfyPage.page.getByTestId(TestIds.canvas.zoomOutAction)
-    await zoomOut.click()
-    await comfyPage.nextFrame()
-
-    const scaleAfterZoomOut = await comfyPage.canvasOps.getScale()
-    expect(scaleAfterZoomOut).toBeLessThan(scaleAfterZoomIn)
-  })
-
-  test('Clicking zoom button toggles zoom controls visibility', async ({
-    comfyPage
-  }) => {
-    const zoomButton = comfyPage.page.getByTestId(
-      TestIds.canvas.zoomControlsButton
-    )
-    await zoomButton.click()
-    await comfyPage.nextFrame()
-
-    const zoomToFit = comfyPage.page.getByTestId(TestIds.canvas.zoomToFitAction)
-    await expect(zoomToFit).toBeVisible()
-
-    await zoomButton.click()
-    await comfyPage.nextFrame()
-
-    await expect(zoomToFit).not.toBeVisible()
-  })
-})

docs/architecture/WALKTHROUGH.txt

@@ -0,0 +1,683 @@
+===============================================================================
+   ____          _      _                       ____
+  / ___|___   __| | ___| |__   __ _ ___  ___   / ___|__ ___   _____ _ __ _ __  ___
+ | |   / _ \ / _` |/ _ \ '_ \ / _` / __|/ _ \ | |   / _` \ \ / / _ \ '__| '_ \/ __|
+ | |__| (_) | (_| |  __/ |_) | (_| \__ \  __/ | |__| (_| |\ V /  __/ |  | | | \__ \
+  \____\___/ \__,_|\___|_.__/ \__,_|___/\___|  \____\__,_| \_/ \___|_|  |_| |_|___/
+
+       ComfyUI Frontend Architecture Adventure - Complete Walkthrough
+===============================================================================
+
+  Platform:     Web Browser (any modern browser)
+  Version:      1.0
+  Author:       An Architect Who Has Seen Things
+  Last Updated: 2026-03-24
+  Spoilers:     YES. This guide contains ALL solutions and ALL endings.
+
+===============================================================================
+                         TABLE OF CONTENTS
+===============================================================================
+
+  I.    Introduction & Controls
+  II.   Game Mechanics
+  III.  Room Guide & Map
+  IV.   Challenge Solutions (SPOILERS)
+  V.    Optimal Route - "The ECS Enlightenment" Speedrun
+  VI.   All Four Endings
+  VII.  Achievements
+  VIII. Artifacts Checklist
+  IX.   Pro Tips & Secrets
+
+===============================================================================
+ I.  INTRODUCTION & CONTROLS
+===============================================================================
+
+  Codebase Caverns is an interactive choose-your-own-adventure game that
+  teaches you the architecture of the ComfyUI frontend codebase. You explore
+  10 rooms representing different architectural layers, face 9 real engineering
+  challenges, collect artifacts, and reach one of 4 endings based on your
+  decisions.
+
+  Every challenge in this game is based on REAL architectural problems
+  documented in the ComfyUI frontend repo. The "correct" answers match the
+  actual migration strategy being used in production.
+
+  CONTROLS:
+  =========
+    1, 2, 3      Navigate between rooms (press the number key)
+    A, B, C      Choose a challenge option (press the letter key)
+    M            Toggle the map overlay
+    Escape       Close the map / close ending preview
+
+  BUTTONS:
+  ========
+    Map [M]      Opens the room map overlay
+    Restart      Resets the current run (keeps achievements)
+    Play Again   After an ending, starts a new run
+
+  Your progress auto-saves to localStorage. Close the tab and come back
+  later - you'll pick up right where you left off.
+
+===============================================================================
+ II.  GAME MECHANICS
+===============================================================================
+
+  STATS
+  =====
+  You have four stats tracked in the HUD at the top:
+
+    Debt     [||||||||..] 50   Technical debt. LOWER is better.
+    Quality  [|||.......] 30   Code quality. HIGHER is better.
+    Morale   [||||||....] 60   Team morale. HIGHER is better.
+    ECS      [.........] 0/5   Migration progress. 5 is max.
+
+  Each challenge choice modifies these stats. Your final stats determine
+  which of the 4 endings you get.
+
+  CHALLENGES
+  ==========
+  9 of the 10 rooms contain a one-time challenge - an architectural dilemma
+  with 2-3 options. Each option has a rating:
+
+    [GOOD]   Best practice. Matches the real migration strategy.
+             Usually: Debt down, Quality up, +1 ECS progress.
+
+    [OK]     Pragmatic but imperfect. Gets the job done.
+             Mixed stat effects.
+
+    [BAD]    Tempting but harmful. Short-term gain, long-term pain.
+             Usually: Debt up or Morale down.
+
+  After choosing, you see your result, the recommended answer, and a link
+  to the real architecture documentation that explains why.
+
+  ARTIFACTS
+  =========
+  Rooms contain collectible artifacts - key files and concepts from the
+  codebase. These are auto-collected when you enter a room. They appear
+  as icons in your Inventory sidebar.
+
+  ENDINGS
+  =======
+  After resolving all 8 challenges, you get one of 4 endings based on
+  your accumulated stats. See Section VI for details.
+
+  ACHIEVEMENTS
+  ============
+  Each ending you reach is permanently saved as an achievement badge.
+  Achievements persist across runs - even after restarting. Click an
+  unlocked badge to review that ending's screen.
+
+===============================================================================
+ III.  ROOM GUIDE & MAP
+===============================================================================
+
+               +-------------------+
+               |    ENTRY POINT    |
+               |   (src/main.ts)   |
+               +-+--------+------+-+
+                 |        |      |
+      +----------+        |      +-----------+
+      |                   |                  |
+  +---v----------+  +-----v--------+  +------v---------+
+  |  COMPONENT   |  |    STORE     |  |    SERVICE     |
+  |   GALLERY    |  |    VAULTS    |  |   CORRIDORS    |
+  | [Challenge]  |  | [Challenge]  |  |  [Challenge]   |
+  +--+------+----+  +--+------+----+  +--------+-------+
+     |      |          |      |               |
+     |      |     +----v---+  |        +------v-------+
+     |      |     |  ECS   |  |        | COMPOSABLES  |
+     |      |     | CHAMB. |  |        |  WORKSHOP    |
+     |      |     | [Chal] |  |        | [Challenge]  |
+     |      |     +---+----+  |        +--------------+
+     |      |         |  +----v------+
+     |      |    +----v--+--+        |
+     |      |    |SUBGRAPH| RENDERER |
+     |      |    | DEPTHS | OVERLOOK |
+     |      |    | [Chal] |  [Chal]  |
+     |      |    +--------+----------+
+     |      |
+  +--v------v----+
+  |  LITEGRAPH   |
+  |   ENGINE     |
+  | [Challenge]  |
+  +------+-------+
+         |
+  +------v-------+
+  | COMMAND      |
+  |   FORGE      |
+  | [Challenge]  |
+  +--------------+
+
+  ROOM DETAILS:
+  =============
+
+  1. THE ENTRY POINT [src/main.ts]
+     No challenge. No artifacts. Starting room.
+     Exits: Components (1), Stores (2), Services (3)
+
+  2. THE COMPONENT GALLERY [Presentation]
+     Challenge: The Circular Dependency
+     Artifacts: GraphView.vue
+     Exits: Litegraph (1), Command Forge (2), Entry (3)
+
+  3. THE STORE VAULTS [State]
+     Challenge: The Scattered Mutations
+     Artifacts: widgetValueStore.ts, layoutStore.ts
+     Exits: ECS (1), Renderer (2), Entry (3)
+
+  4. THE SERVICE CORRIDORS [Services]
+     Challenge: The Migration Question
+     Artifacts: litegraphService.ts, Extension Migration Guide
+     Exits: Composables (1), Entry (2)
+
+  5. THE LITEGRAPH ENGINE ROOM [Graph Engine]
+     Challenge: The God Object Dilemma
+     Artifacts: LGraphCanvas.ts, LGraphNode.ts
+     Exits: ECS (1), Components (2), Entry (3)
+
+  6. THE ECS ARCHITECT'S CHAMBER [ECS]
+     Challenge: The ID Crossroads
+     Artifacts: World Registry, Branded Entity IDs
+     Exits: Subgraph Depths (1), Renderer (2), Entry (3)
+
+  7. THE SUBGRAPH DEPTHS [Graph Boundaries]
+     Challenge: The Widget Promotion Decision
+     Artifacts: SubgraphStructure, Typed Interface Contracts
+     Exits: ECS (1), Litegraph (2), Entry (3)
+
+  8. THE RENDERER OVERLOOK [Renderer]
+     Challenge: The Render-Time Mutation
+     Artifacts: QuadTree Spatial Index, Y.js CRDT Layout
+     Exits: ECS (1), Entry (2)
+
+  9. THE COMPOSABLES WORKSHOP [Composables]
+     Challenge: The Collaboration Protocol
+     Artifacts: useCoreCommands.ts
+     Exits: Stores (1), Entry (2)
+
+ 10. THE COMMAND FORGE [Commands & Intent]
+     Challenge: The Mutation Gateway
+     Artifacts: CommandExecutor, Command Interface
+     Exits: Components (1), Stores (2), Entry (3)
+
+===============================================================================
+ IV.  CHALLENGE SOLUTIONS (SPOILERS)
+===============================================================================
+
+  *** WARNING: FULL SOLUTIONS BELOW ***
+  *** SCROLL PAST SECTION VI IF YOU WANT TO PLAY BLIND ***
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 1: The Circular Dependency          | Room: Components   |
+  |------------------------------------------------------------------  |
+  | Subgraph extends LGraph, but LGraph creates Subgraph instances.    |
+  | Circular import forces order-dependent barrel exports.             |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. Composition over inheritance  [GOOD] <<<                    |
+  |     Debt -10, Quality +15, Morale +5, ECS +1                       |
+  |     A subgraph IS a graph - just a node with SubgraphStructure.    |
+  |     Under graph unification, no class inheritance at all.          |
+  |                                                                    |
+  |   B. Barrel file reordering  [BAD]                                 |
+  |     Debt +10, Quality -5, Morale -5                                |
+  |     Band-aid. The coupling remains and will break again.           |
+  |                                                                    |
+  |   C. Factory injection  [OK]                                       |
+  |     Debt -5, Quality +10                                           |
+  |     Pragmatic fix but classes stay coupled at runtime.             |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 2: The Scattered Mutations            | Room: Stores     |
+  |------------------------------------------------------------------  |
+  | graph._version++ appears in 19 locations across 7 files.           |
+  | One missed site = silent data loss.                                |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. Centralize into graph.incrementVersion()  [GOOD] <<<        |
+  |     Debt -15, Quality +15, ECS +1                                  |
+  |     This is Phase 0a of the real migration plan.                   |
+  |     19 sites -> 1 method. Auditable change tracking.               |
+  |                                                                    |
+  |   B. Add a JavaScript Proxy  [OK]                                  |
+  |     Debt +5, Quality +5, Morale -5                                 |
+  |     Catches mutations but adds opaque runtime overhead.            |
+  |                                                                    |
+  |   C. Leave it as-is  [BAD]                                         |
+  |     Debt +10, Morale +5                                            |
+  |     "It works, don't touch it" - until it doesn't.                 |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 3: The Migration Question           | Room: Services     |
+  |------------------------------------------------------------------  |
+  | Legacy litegraph works. How to migrate to ECS without breaking     |
+  | production for thousands of users?                                 |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. 5-phase incremental plan  [GOOD] <<<                        |
+  |     Quality +15, Morale +10, ECS +1                                |
+  |     Foundation -> Types -> Bridge -> Systems -> Legacy Removal.    |
+  |     Each phase independently shippable. This is the real plan.     |
+  |                                                                    |
+  |   B. Big bang rewrite  [BAD]                                       |
+  |     Debt -10, Quality +5, Morale -20                               |
+  |     Feature freeze + scope creep + burnout = disaster.             |
+  |                                                                    |
+  |   C. Strangler fig pattern  [OK]                                   |
+  |     Quality +10, Morale +5                                         |
+  |     Solid pattern but lacks clear milestones without a plan.       |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 4: The God Object Dilemma          | Room: Litegraph     |
+  |------------------------------------------------------------------  |
+  | LGraphCanvas: ~9,100 lines. LGraphNode: ~4,300 lines.              |
+  | God objects mixing rendering, serialization, connectivity, etc.    |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  |   A. Rewrite from scratch  [BAD]                                   |
+  |     Debt -20, Quality +5, Morale -25                               |
+  |     Heroic rewrite stalls at month three. Team burns out.          |
+  |                                                                    |
+  | >>> B. Extract incrementally  [GOOD] <<<                           |
+  |     Debt -10, Quality +15, Morale +5, ECS +1                       |
+  |     Position -> Connectivity -> Rendering. Small testable PRs.     |
+  |     This matches the actual migration strategy.                    |
+  |                                                                    |
+  |   C. Add a facade layer  [OK]                                      |
+  |     Debt +5, Quality +5, Morale +10                                |
+  |     Nicer API but complexity lives behind the facade.              |
+  |                                                                    |
+  | NOTE: This is the only challenge where A is NOT the best answer!   |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 5: The ID Crossroads                     | Room: ECS     |
+  |------------------------------------------------------------------  |
+  | NodeId is number | string. Nothing prevents passing a LinkId       |
+  | where a NodeId is expected. Six entity kinds share one ID space.   |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. Branded types with cast helpers  [GOOD] <<<                 |
+  |     Debt -15, Quality +20, ECS +1                                  |
+  |     type NodeEntityId = number & { __brand: 'NodeEntityId' }       |
+  |     Compile-time safety, zero runtime cost. Phase 1a.              |
+  |                                                                    |
+  |   B. String prefixes at runtime  [OK]                              |
+  |     Debt +5, Quality +5, Morale -5                                 |
+  |     "node:42" - parsing overhead everywhere.                       |
+  |                                                                    |
+  |   C. Keep plain numbers  [BAD]                                     |
+  |     Debt +15, Quality -5                                           |
+  |     "Just be careful" - someone WILL pass the wrong ID.            |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 6: The Widget Promotion Decision   | Room: Subgraph     |
+  |------------------------------------------------------------------  |
+  | A user promotes a widget from inside a subgraph to the parent.     |
+  | Today this needs PromotionStore + ViewManager + PromotedWidgetView |
+  | — a parallel state system. Two ECS candidates.                     |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. Connections-only: promotion = typed input  [GOOD] <<<       |
+  |     Debt -15, Quality +15, Morale +5, ECS +1                      |
+  |     Promotion = adding an interface input. Type->widget mapping    |
+  |     creates the widget automatically. Eliminates PromotionStore,   |
+  |     ViewManager, and PromotedWidgetView entirely.                  |
+  |                                                                    |
+  |   B. Simplified component promotion  [OK]                          |
+  |     Debt -5, Quality +10, Morale +5                                |
+  |     WidgetPromotion component on widget entities. Removes           |
+  |     ViewManager but keeps promotion as a distinct concept.         |
+  |     Shared subgraph instance ambiguity remains.                    |
+  |                                                                    |
+  |   C. Keep the current three-layer system  [BAD]                    |
+  |     Debt +10, Quality -5, Morale -5                                |
+  |     The parallel state system persists indefinitely.               |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 7: The Render-Time Mutation          | Room: Renderer    |
+  |------------------------------------------------------------------  |
+  | drawNode() calls _setConcreteSlots() and arrange() during the      |
+  | render pass. Draw order affects layout. Classic mutation-in-       |
+  | render bug.                                                        |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. Separate update and render phases  [GOOD] <<<               |
+  |     Debt -15, Quality +15, ECS +1                                  |
+  |     Input -> Update (layout) -> Render (read-only).                |
+  |     Matches the ECS system pipeline design.                        |
+  |                                                                    |
+  |   B. Dirty flags and deferred render  [OK]                         |
+  |     Debt -5, Quality +5, Morale +5                                 |
+  |     Reduces symptoms but render pass can still mutate.             |
+  |                                                                    |
+  | NOTE: Only 2 options here. Both are reasonable; A is optimal.      |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 8: The Collaboration Protocol     | Room: Composables    |
+  |------------------------------------------------------------------  |
+  | Multiple users want to edit the same workflow simultaneously.      |
+  | layoutStore already extracts position data. How to sync?           |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. Y.js CRDTs  [GOOD] <<<                                      |
+  |     Debt -10, Quality +15, Morale +10                              |
+  |     Conflict-free replicated data types. Already proven.           |
+  |     This is what the real layoutStore uses.                        |
+  |                                                                    |
+  |   B. Polling-based sync  [BAD]                                     |
+  |     Debt +10, Quality -5, Morale -5                                |
+  |     Flickering, lag, silent data loss. Support nightmare.          |
+  |                                                                    |
+  |   C. Skip collaboration for now  [OK]                              |
+  |     Morale +5                                                      |
+  |     Pragmatic delay but cloud team won't be happy.                 |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  | CHALLENGE 9: The Mutation Gateway        | Room: Command Forge     |
+  |------------------------------------------------------------------  |
+  | The World's imperative API (world.setComponent()) vs. the command  |
+  | pattern requirement from ADR 0003. How should external callers     |
+  | mutate the World?                                                  |
+  |------------------------------------------------------------------  |
+  |                                                                    |
+  | >>> A. Commands as intent; systems as handlers; World as store <<< |
+  |     Debt -10, Quality +15, Morale +5, ECS +1               [GOOD] |
+  |     Caller -> Command -> System -> World -> Y.js. Commands are     |
+  |     serializable. ADR 0003 and ADR 0008 are complementary.        |
+  |                                                                    |
+  |   B. Make World.setComponent() itself serializable  [OK]           |
+  |     Debt +5, Quality +5, Morale -5                                |
+  |     Conflates store with command layer. Batch ops become noisy.   |
+  |                                                                    |
+  |   C. Skip commands - let callers mutate directly  [BAD]            |
+  |     Debt +15, Quality -10                                         |
+  |     No undo/redo, no replay, no CRDT sync, no audit trail.       |
+  '--------------------------------------------------------------------'
+
+===============================================================================
+ V.  OPTIMAL ROUTE - "THE ECS ENLIGHTENMENT" SPEEDRUN
+===============================================================================
+
+  This route hits all 8 challenges picking the GOOD answer, collecting
+  all 13 artifacts, visiting all 10 rooms. Order matters for efficiency
+  (fewest key presses).
+
+  Starting stats: Debt 50, Quality 30, Morale 60, ECS 0/5
+
+    ENTRY POINT
+      Press 1 -> Component Gallery
+
+    COMPONENT GALLERY
+      Challenge: The Circular Dependency -> Press A (Composition)
+      [Debt 40, Quality 45, Morale 65, ECS 1/5]
+      Press 2 -> Command Forge
+
+    THE COMMAND FORGE
+      Challenge: The Mutation Gateway -> Press A (Commands as intent)
+      [Debt 30, Quality 60, Morale 70, ECS 2/5]
+      Press 2 -> Store Vaults
+
+    STORE VAULTS
+      Challenge: The Scattered Mutations -> Press A (Centralize)
+      [Debt 15, Quality 75, Morale 70, ECS 3/5]
+      Press 1 -> ECS Chamber
+
+    ECS ARCHITECT'S CHAMBER
+      Challenge: The ID Crossroads -> Press A (Branded types)
+      [Debt 0, Quality 95, Morale 70, ECS 4/5]
+      Press 1 -> Subgraph Depths
+
+    SUBGRAPH DEPTHS
+      Challenge: The Widget Promotion Decision -> Press A (Connections-only)
+      [Debt 0, Quality 100, Morale 75, ECS 5/5]
+      Press 1 -> ECS Chamber
+      Press 2 -> Renderer
+
+    RENDERER OVERLOOK
+      Challenge: The Render-Time Mutation -> Press A (Separate phases)
+      [Debt 0, Quality 100, Morale 75, ECS 5/5]
+      Press 2 -> Entry Point
+
+    ENTRY POINT
+      Press 3 -> Services
+
+    SERVICE CORRIDORS
+      Challenge: The Migration Question -> Press A (5-phase plan)
+      [Debt 0, Quality 100, Morale 85, ECS 5/5]
+      Press 1 -> Composables
+
+    COMPOSABLES WORKSHOP
+      Challenge: The Collaboration Protocol -> Press A (Y.js CRDTs)
+      [Debt 0, Quality 100, Morale 95, ECS 5/5]
+      Press 2 -> Entry Point
+
+    ENTRY POINT
+      Press 1 -> Components
+      Press 1 -> Litegraph
+
+    LITEGRAPH ENGINE ROOM
+      Challenge: The God Object Dilemma -> Press B (Extract incrementally)
+      [Debt 0, Quality 100, Morale 100, ECS 5/5]
+
+  FINAL STATS: Debt 0 | Quality 100 | Morale 100 | ECS 5/5
+
+  *** ENDING: THE ECS ENLIGHTENMENT ***
+
+  Total key presses: 28 (including challenge answers)
+  Rooms visited: 10/10
+  Artifacts: 16/16
+  Challenges: 9/9 correct
+
+===============================================================================
+ VI.  ALL FOUR ENDINGS
+===============================================================================
+
+  Endings are checked in order. First match wins.
+
+  .--------------------------------------------------------------------.
+  |                                                                    |
+  |   ENDING 1: THE ECS ENLIGHTENMENT                          [BEST]  |
+  |                                                                    |
+  |   Requirements: Debt < 25 AND Quality >= 75 AND Morale >= 60       |
+  |                                                                    |
+  |   "The World registry hums with clean data. Node removal:          |
+  |    30 lines instead of 107. Serialization: one system instead      |
+  |    of six scattered methods. Branded IDs catch bugs at compile     |
+  |    time. Y.js CRDTs enable real-time collaboration. The team       |
+  |    ships features faster than ever."                               |
+  |                                                                    |
+  |   HOW TO GET IT: Pick ALL good answers. Hard to miss if you        |
+  |   read the hints carefully.                                        |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  |                                                                    |
+  |   ENDING 2: THE CLEAN ARCHITECTURE                          [GOOD] |
+  |                                                                    |
+  |   Requirements: Debt < 40 AND Quality >= 50                        |
+  |                                                                    |
+  |   "The migration completes on schedule. Systems hum along,         |
+  |    the ECS World holds most entity state, and the worst god        |
+  |    objects have been tamed."                                       |
+  |                                                                    |
+  |   HOW TO GET IT: Pick mostly good answers, 1-2 OK answers.         |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  |                                                                    |
+  |   ENDING 3: THE ETERNAL REFACTOR                            [MEH]  |
+  |                                                                    |
+  |   Requirements: Debt < 70                                          |
+  |                                                                    |
+  |   "The migration... continues. Every sprint has a 'cleanup'        |
+  |    ticket that never quite closes."                                |
+  |                                                                    |
+  |   HOW TO GET IT: Mix of OK and BAD answers. The "safe" middle.     |
+  '--------------------------------------------------------------------'
+
+  .--------------------------------------------------------------------.
+  |                                                                    |
+  |   ENDING 4: THE SPAGHETTI SINGULARITY                     [WORST]  |
+  |                                                                    |
+  |   Requirements: Debt >= 70 (catch-all)                             |
+  |                                                                    |
+  |   "The god objects grew sentient. LGraphCanvas hit 12,000 lines    |
+  |    and developed a circular dependency with itself."               |
+  |                                                                    |
+  |   HOW TO GET IT: Pick all BAD answers. You have to try.            |
+  |   Starting debt is 50, so you need +20 from bad choices.           |
+  '--------------------------------------------------------------------'
+
+===============================================================================
+ VII.  ACHIEVEMENTS
+===============================================================================
+
+  Achievements are permanently saved across runs. You need 4 playthroughs
+  (minimum) to unlock all endings, since each run can only reach one.
+
+    [x] The ECS Enlightenment    - All good answers
+    [x] The Clean Architecture   - Mostly good, few OK
+    [x] The Eternal Refactor     - Mix of OK and bad
+    [x] The Spaghetti Singularity - Maximize debt (see pro tip below)
+
+  Click any unlocked achievement badge in the Endings sidebar panel
+  to review that ending's screen without resetting your current game.
+
+  PRO TIP: "The Spaghetti Singularity" requires Debt >= 70. This is
+  TRICKY because some "bad" answers actually LOWER debt! Rewrites
+  (Litegraph A: Debt -20) and big bang rewrites (Services B: Debt -10)
+  reduce debt short-term even though they tank morale.
+
+  To hit Debt >= 70 you must pick options that ADD debt or leave it
+  alone. Here's the proven path (starting at Debt 50):
+
+    Components:    B (Barrel file reordering)    Debt +10 -> 60
+    Command Forge: C (Skip commands)             Debt +15 -> 75
+    Stores:        C (Leave it as-is)            Debt +10 -> 85
+    Services:      C (Strangler fig)             Debt  +0 -> 85
+    Litegraph:     C (Add a facade)              Debt  +5 -> 90
+    ECS:           C (Keep plain numbers)        Debt +15 -> 100
+    Subgraph:      C (Keep three-layer system)   Debt +10 -> 100
+    Renderer:      B (Dirty flags)               Debt  -5 -> 95
+    Composables:   B (Polling-based sync)        Debt +10 -> 100
+
+  Final: Debt 100 / Quality 10 / Morale 50 -> SPAGHETTI SINGULARITY
+
+  WARNING: Picking "all bad-rated answers" does NOT work! The bad
+  answers for Litegraph (A: Rewrite, Debt -20) and Services (B: Big
+  bang, Debt -10) have negative debt effects that pull you back
+  under 70.
+
+===============================================================================
+ VIII.  ARTIFACTS CHECKLIST
+===============================================================================
+
+  Room              | Artifact                   | Type
+  ==================|============================|==================
+  Component Gallery | GraphView.vue              | Component
+  Store Vaults      | widgetValueStore.ts        | Proto-ECS Store
+  Store Vaults      | layoutStore.ts             | Proto-ECS Store
+  Service Corridors | litegraphService.ts        | Service
+  Service Corridors | Extension Migration Guide  | Design Pattern
+  Litegraph Engine  | LGraphCanvas.ts            | God Object
+  Litegraph Engine  | LGraphNode.ts              | God Object
+  ECS Chamber       | World Registry             | ECS Core
+  ECS Chamber       | Branded Entity IDs         | Type Safety
+  Subgraph Depths   | SubgraphStructure          | ECS Component
+  Subgraph Depths   | Typed Interface Contracts  | Design Pattern
+  Renderer Overlook | QuadTree Spatial Index     | Data Structure
+  Renderer Overlook | Y.js CRDT Layout           | Collaboration
+  Composables       | useCoreCommands.ts         | Composable
+  Command Forge     | CommandExecutor            | ECS Core
+  Command Forge     | Command Interface          | Design Pattern
+
+  Total: 16 artifacts across 9 rooms.
+  Entry Point has no artifacts.
+
+===============================================================================
+ IX.  PRO TIPS & SECRETS
+===============================================================================
+
+  * Your game auto-saves after every room change and challenge. Close
+    the tab and come back anytime - you won't lose progress.
+
+  * The Restart button in the HUD resets your run but KEEPS your
+    achievement badges. Use it to go for a different ending.
+
+  * Every code reference in the room descriptions is a clickable link
+    to the actual file on GitHub. Open them in new tabs to read the
+    real code while you play.
+
+  * After each challenge, the "Read more" link takes you to the
+    architecture documentation that explains the real engineering
+    rationale behind the recommended answer.
+
+  * The map overlay (press M) shows challenge badges:
+    [?] = challenge available but not yet attempted
+    [v] = challenge completed
+
+  * Room navigation preloads images for adjacent rooms, so transitions
+    should be instant after the first visit.
+
+  * The Command Forge (formerly the Side Panel) teaches the Command
+    Pattern - how commands relate to systems and the World. Its challenge
+    covers the architectural layering from ADR 0003 and ADR 0008.
+
+  * The ECS Migration Progress stat maxes at 5, matching the 5 phases
+    of the real migration plan. But 9 challenges can give +1 each
+    (8 of the 9 GOOD answers grant +1 ECS). The Services challenge
+    ("5-phase plan") gives +1 ECS but no debt reduction - it's pure
+    planning, not implementation.
+
+  * There are between 2-3 choices per challenge, giving
+    3*3*3*3*3*3*2*3*3 = 13,122 possible playthroughs. But only 4
+    distinct endings. Most paths lead to "The Clean Architecture"
+    or "The Eternal Refactor."
+
+  * If you want to learn the ComfyUI frontend architecture for real,
+    the recommended reading order matches the optimal speedrun route:
+    1. src/main.ts (entry point)
+    2. src/views/GraphView.vue (main canvas)
+    3. src/stores/ (state management)
+    4. src/ecs/ (the future)
+    5. docs/architecture/ecs-world-command-api.md (command layer)
+    6. src/renderer/core/ (canvas pipeline)
+    7. docs/architecture/ecs-migration-plan.md (the plan)
+    8. src/composables/ (Vue logic hooks)
+    9. src/lib/litegraph/src/ (the legacy engine)
+
+  * The pixel art images were generated using the Z-Image Turbo
+    pipeline on the same ComfyUI that this frontend controls.
+    Meta, isn't it?
+
+===============================================================================
+
+  This document Copyright (c) 2026 A Concerned Architect
+  ComfyUI is maintained by Comfy-Org: https://github.com/Comfy-Org
+
+  "In a world of god objects, be an entity-component-system."
+
+                            ___
+                           |   |
+                        ___|   |___
+                       |           |
+                       | COMFY  UI |
+                       | FRONTEND  |
+                       |___________|
+                       | | | | | | |
+                       | | | | | | |
+                      _| | | | | | |_
+                     |_______________|
+
+                        GG. GIT GUD.
+
+===============================================================================

docs/architecture/adventure-achievement-icon-prompts.json

@@ -0,0 +1,26 @@
+{
+  "meta": {
+    "style": "Pixel art badge/medal icon, 128x128, dark background, achievement unlock style",
+    "usage": "Each key matches an ending ID. Shown in achievements panel when that ending has been reached.",
+    "model": "Z-Image Turbo (no LoRA)",
+    "resolution": "128x128"
+  },
+  "achievements": {
+    "great": {
+      "title": "The ECS Enlightenment",
+      "prompt": "Pixel art achievement badge of a radiant crystal temple with clean geometric architecture, bright green and gold triumphant glow, laurel wreath border, dark background"
+    },
+    "good": {
+      "title": "The Clean Architecture",
+      "prompt": "Pixel art achievement badge of a solid fortress with neat organized blocks, blue and silver steady glow, star emblem, dark background"
+    },
+    "mediocre": {
+      "title": "The Eternal Refactor",
+      "prompt": "Pixel art achievement badge of an hourglass with sand still flowing endlessly, amber and grey weary glow, circular border, dark background"
+    },
+    "disaster": {
+      "title": "The Spaghetti Singularity",
+      "prompt": "Pixel art achievement badge of a tangled mass of spaghetti code wires collapsing into a black hole, red and purple chaotic glow, cracked border, dark background"
+    }
+  }
+}

docs/architecture/adventure-choice-icon-prompts.json

@@ -0,0 +1,114 @@
+{
+  "meta": {
+    "style": "Pixel art icon, 128x128, dark background, game UI button icon style, clean readable silhouette",
+    "usage": "Each key is {room}-{choiceKey lowercase}. Used in challenge choice buttons in adventure.html.",
+    "model": "Z-Image Turbo (no LoRA)",
+    "resolution": "128x128"
+  },
+  "choices": {
+    "components-a": {
+      "label": "Composition over inheritance",
+      "prompt": "Pixel art icon of puzzle pieces snapping together cleanly, green glow, dark background, game UI icon"
+    },
+    "components-b": {
+      "label": "Barrel file reordering",
+      "prompt": "Pixel art icon of a stack of files being shuffled with arrows, amber warning glow, dark background, game UI icon"
+    },
+    "components-c": {
+      "label": "Factory injection",
+      "prompt": "Pixel art icon of a factory building with a syringe injecting into it, blue mechanical glow, dark background, game UI icon"
+    },
+    "stores-a": {
+      "label": "Centralize into graph.incrementVersion()",
+      "prompt": "Pixel art icon of scattered dots converging into a single glowing funnel point, green glow, dark background, game UI icon"
+    },
+    "stores-b": {
+      "label": "Add a JavaScript Proxy",
+      "prompt": "Pixel art icon of a shield proxy intercepting arrows mid-flight, amber translucent glow, dark background, game UI icon"
+    },
+    "stores-c": {
+      "label": "Leave it as-is",
+      "prompt": "Pixel art icon of a shrug gesture with cobwebs on old machinery, grey muted glow, dark background, game UI icon"
+    },
+    "services-a": {
+      "label": "5-phase incremental plan",
+      "prompt": "Pixel art icon of five stepping stones ascending in a staircase with checkmarks, green glow, dark background, game UI icon"
+    },
+    "services-b": {
+      "label": "Big bang rewrite",
+      "prompt": "Pixel art icon of a dynamite stick with lit fuse and explosion sparks, red danger glow, dark background, game UI icon"
+    },
+    "services-c": {
+      "label": "Strangler fig pattern",
+      "prompt": "Pixel art icon of vines growing around and enveloping an old tree trunk, green and brown organic glow, dark background, game UI icon"
+    },
+    "litegraph-a": {
+      "label": "Rewrite from scratch",
+      "prompt": "Pixel art icon of a wrecking ball demolishing a building into rubble, red destructive glow, dark background, game UI icon"
+    },
+    "litegraph-b": {
+      "label": "Extract incrementally",
+      "prompt": "Pixel art icon of surgical tweezers carefully extracting a glowing module from a larger block, green precise glow, dark background, game UI icon"
+    },
+    "litegraph-c": {
+      "label": "Add a facade layer",
+      "prompt": "Pixel art icon of a decorative mask covering a cracked wall, yellow cosmetic glow, dark background, game UI icon"
+    },
+    "ecs-a": {
+      "label": "Branded types with cast helpers",
+      "prompt": "Pixel art icon of ID badges with distinct colored stamps and a compiler checkmark, green type-safe glow, dark background, game UI icon"
+    },
+    "ecs-b": {
+      "label": "String prefixes at runtime",
+      "prompt": "Pixel art icon of text labels being parsed with a magnifying glass at runtime, amber slow glow, dark background, game UI icon"
+    },
+    "ecs-c": {
+      "label": "Keep plain numbers",
+      "prompt": "Pixel art icon of bare numbers floating unprotected with a question mark, red risky glow, dark background, game UI icon"
+    },
+    "renderer-a": {
+      "label": "Separate update and render phases",
+      "prompt": "Pixel art icon of two clean pipeline stages labeled U and R with an arrow between them, green orderly glow, dark background, game UI icon"
+    },
+    "renderer-b": {
+      "label": "Dirty flags and deferred render",
+      "prompt": "Pixel art icon of a flag with a smudge mark and a clock showing delay, amber patch glow, dark background, game UI icon"
+    },
+    "composables-a": {
+      "label": "Y.js CRDTs",
+      "prompt": "Pixel art icon of two documents merging seamlessly with sync arrows and no conflicts, green collaboration glow, dark background, game UI icon"
+    },
+    "composables-b": {
+      "label": "Polling-based sync",
+      "prompt": "Pixel art icon of a clock with circular refresh arrows and flickering signal, red laggy glow, dark background, game UI icon"
+    },
+    "composables-c": {
+      "label": "Skip collaboration for now",
+      "prompt": "Pixel art icon of a single person at a desk with a pause symbol, grey neutral glow, dark background, game UI icon"
+    },
+    "subgraph-a": {
+      "label": "Connections-only: promotion = adding a typed input",
+      "prompt": "Pixel art icon of a function signature with typed input slots and a green checkmark, clean minimal glow, dark background, game UI icon"
+    },
+    "subgraph-b": {
+      "label": "Simplified component promotion",
+      "prompt": "Pixel art icon of a widget being lifted up with a promotion arrow and a component badge, amber glow, dark background, game UI icon"
+    },
+    "subgraph-c": {
+      "label": "Keep the current three-layer system",
+      "prompt": "Pixel art icon of three stacked translucent layers with proxy shadows underneath, red complex glow, dark background, game UI icon"
+    },
+    "sidepanel-a": {
+      "label": "Commands as intent; systems as handlers; World as store",
+      "prompt": "Pixel art icon of a layered architectural diagram with arrows flowing top-to-bottom through five labeled tiers, green glow, dark background, game UI icon"
+    },
+    "sidepanel-b": {
+      "label": "Make World.setComponent() itself serializable",
+      "prompt": "Pixel art icon of a database with every cell being logged into a scroll, amber overflow glow, dark background, game UI icon"
+    },
+    "sidepanel-c": {
+      "label": "Skip commands — let callers mutate directly",
+      "prompt": "Pixel art icon of multiple hands reaching into a glowing orb simultaneously causing cracks, red chaos glow, dark background, game UI icon"
+    }
+  }
+}

docs/architecture/adventure-icon-prompts.json

@@ -0,0 +1,90 @@
+{
+  "meta": {
+    "style": "Pixel art icon on transparent black background, 128x128, clean edges, glowing accent color, game inventory item style",
+    "usage": "Each key is an artifact ID used in adventure.html. Generate one icon per artifact.",
+    "model": "Z-Image Turbo (no LoRA)",
+    "resolution": "128x128"
+  },
+  "artifacts": {
+    "graphview": {
+      "name": "GraphView.vue",
+      "type": "Component",
+      "prompt": "Pixel art icon of a glowing canvas frame with connected nodes and wires inside, blue accent glow, dark background, game inventory item"
+    },
+    "widgetvaluestore": {
+      "name": "widgetValueStore.ts",
+      "type": "Proto-ECS Store",
+      "prompt": "Pixel art icon of a vault door with a glowing slider widget embossed on it, purple and gold accents, dark background, game inventory item"
+    },
+    "layoutstore": {
+      "name": "layoutStore.ts",
+      "type": "Proto-ECS Store",
+      "prompt": "Pixel art icon of a grid blueprint with glowing position markers, purple accent lines, dark background, game inventory item"
+    },
+    "litegraphservice": {
+      "name": "litegraphService.ts",
+      "type": "Service",
+      "prompt": "Pixel art icon of a gear with a graph node symbol in the center, copper and blue metallic glow, dark background, game inventory item"
+    },
+    "lgraphcanvas": {
+      "name": "LGraphCanvas.ts",
+      "type": "God Object",
+      "prompt": "Pixel art icon of a massive cracked monolith radiating red warning light, labeled 9100, ominous dark background, game inventory item"
+    },
+    "lgraphnode": {
+      "name": "LGraphNode.ts",
+      "type": "God Object",
+      "prompt": "Pixel art icon of an oversized cube with tangled wires bursting from every face, red and amber glow, dark background, game inventory item"
+    },
+    "world-registry": {
+      "name": "World Registry",
+      "type": "ECS Core",
+      "prompt": "Pixel art icon of a glowing crystalline orb containing tiny entity symbols, bright blue and white aura, dark background, game inventory item"
+    },
+    "branded-ids": {
+      "name": "Branded Entity IDs",
+      "type": "Type Safety",
+      "prompt": "Pixel art icon of a set of ID cards with distinct colored borders and brand stamps, green checkmark glow, dark background, game inventory item"
+    },
+    "quadtree": {
+      "name": "QuadTree Spatial Index",
+      "type": "Data Structure",
+      "prompt": "Pixel art icon of a square recursively divided into four quadrants with glowing dots at intersections, teal accent, dark background, game inventory item"
+    },
+    "yjs-crdt": {
+      "name": "Y.js CRDT Layout",
+      "type": "Collaboration",
+      "prompt": "Pixel art icon of two overlapping document layers merging with sync arrows, purple and green glow, dark background, game inventory item"
+    },
+    "usecorecommands": {
+      "name": "useCoreCommands.ts",
+      "type": "Composable",
+      "prompt": "Pixel art icon of a hook tool with keyboard key symbols orbiting it, yellow and blue glow, dark background, game inventory item"
+    },
+    "subgraph-structure": {
+      "name": "SubgraphStructure",
+      "type": "ECS Component",
+      "prompt": "Pixel art icon of nested rectangular frames inside each other like Russian dolls with glowing typed connections at each boundary, purple and teal accent, dark background, game inventory item"
+    },
+    "typed-contracts": {
+      "name": "Typed Interface Contracts",
+      "type": "Architecture",
+      "prompt": "Pixel art icon of a sealed scroll with a glowing typed signature stamp and interface brackets, gold and blue accent, dark background, game inventory item"
+    },
+    "command-executor": {
+      "name": "CommandExecutor",
+      "type": "ECS Core",
+      "prompt": "Pixel art icon of a glowing anvil with a gear and execute arrow symbol, blue-purple forge glow, dark background, game inventory item"
+    },
+    "command-interface": {
+      "name": "Command Interface",
+      "type": "Design Pattern",
+      "prompt": "Pixel art icon of a sealed scroll with a type discriminator tag and execute method seal, blue glow, dark background, game inventory item"
+    },
+    "extension-migration": {
+      "name": "Extension Migration Guide",
+      "type": "Design Pattern",
+      "prompt": "Pixel art icon of a scroll with legacy code on left transforming via arrow to ECS code on right, green transition glow, dark background, game inventory item"
+    }
+  }
+}

docs/architecture/adventure-image-prompts.json

@@ -0,0 +1,61 @@
+{
+  "meta": {
+    "style": "Pixel art, 16:9 aspect ratio, dark moody palette with glowing accent lighting",
+    "usage": "Each key corresponds to a room ID in adventure.html. Generate images with generate-images.py.",
+    "model": "Z-Image Turbo (no LoRA)",
+    "resolution": "1152x640",
+    "generated": "2026-03-24"
+  },
+  "rooms": {
+    "entry": {
+      "title": "The Entry Point",
+      "prompt": "Pixel art of a glowing terminal in a vast dark server room, Vue.js and TypeScript logos floating as holographic projections, three corridors branching ahead lit by blue, green, and purple lights",
+      "path": "images/entry.png"
+    },
+    "components": {
+      "title": "The Component Gallery",
+      "prompt": "Pixel art gallery hall with framed Vue component cards hung on stone walls, a massive canvas painting labeled 'GraphView' in the center, smaller panels flanking either side, warm torchlight",
+      "path": "images/components.png"
+    },
+    "stores": {
+      "title": "The Store Vaults",
+      "prompt": "Pixel art underground vault with 60 glowing vault doors lining the walls, three doors in front glow brightest (labeled widget, layout, promotion), a Pinia pineapple emblem etched in stone above",
+      "path": "images/stores.png"
+    },
+    "services": {
+      "title": "The Service Corridors",
+      "prompt": "Pixel art clean corridors with labeled pipes connecting rooms overhead, data flowing as glowing particles through transparent tubes, service names etched on brass plaques",
+      "path": "images/services.png"
+    },
+    "litegraph": {
+      "title": "The Litegraph Engine Room",
+      "prompt": "Pixel art dark engine room with three massive monolith machines labeled 9100, 4300, and 3100 lines of code, warning lights flashing amber, tangled wires and cables everywhere",
+      "path": "images/litegraph.png"
+    },
+    "ecs": {
+      "title": "The ECS Architect's Chamber",
+      "prompt": "Pixel art architect's drafting room with blueprints pinned to walls showing entity-component diagrams, a glowing World orb floating in the center, branded ID cards scattered across the desk",
+      "path": "images/ecs.png"
+    },
+    "subgraph": {
+      "title": "The Subgraph Depths",
+      "prompt": "Pixel art recursive fractal chamber where identical rooms nest inside each other like Russian dolls, typed contract scrolls float at each boundary doorway, a DAG tree diagram glows on the ceiling",
+      "path": "images/subgraph.png"
+    },
+    "renderer": {
+      "title": "The Renderer Overlook",
+      "prompt": "Pixel art observation deck overlooking a vast canvas being painted by precise robotic arms, Y.js CRDT symbols floating in the air, a QuadTree grid visible on the floor below",
+      "path": "images/renderer.png"
+    },
+    "composables": {
+      "title": "The Composables Workshop",
+      "prompt": "Pixel art workshop with hooks hanging from a pegboard wall, each labeled (useCoreCommands, useCanvasDrop, etc.), workbenches for auth, canvas, and queue domains, cozy lantern light",
+      "path": "images/composables.png"
+    },
+    "sidepanel": {
+      "title": "The Command Forge",
+      "prompt": "Pixel art anvil forge where glowing command scrolls are being hammered into structured objects, a layered diagram on the wall showing five architectural tiers connected by arrows, blue and purple forge light, dark background",
+      "path": "images/sidepanel.png"
+    }
+  }
+}

docs/architecture/generate-icons.py

@@ -0,0 +1,196 @@
+"""
+Generate pixel art inventory icons for the Architecture Adventure game.
+Uses Z-Image Turbo pipeline via local ComfyUI server (no LoRA).
+Skips icons that already exist on disk.
+
+Usage: python docs/architecture/generate-icons.py
+"""
+
+import json
+import os
+import time
+import urllib.request
+import urllib.error
+
+COMFY_URL = "http://localhost:8188"
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+ARTIFACT_PROMPTS = os.path.join(SCRIPT_DIR, "adventure-icon-prompts.json")
+CHOICE_PROMPTS = os.path.join(SCRIPT_DIR, "adventure-choice-icon-prompts.json")
+ACHIEVEMENT_PROMPTS = os.path.join(SCRIPT_DIR, "adventure-achievement-icon-prompts.json")
+OUTPUT_DIR = os.path.join(SCRIPT_DIR, "icons")
+BASE_SEED = 7777
+WIDTH = 128
+HEIGHT = 128
+
+
+def build_workflow(prompt_text, seed, prefix):
+    return {
+        "1": {
+            "class_type": "UNETLoader",
+            "inputs": {
+                "unet_name": "ZIT\\z_image_turbo_bf16.safetensors",
+                "weight_dtype": "default",
+            },
+        },
+        "2": {
+            "class_type": "CLIPLoader",
+            "inputs": {
+                "clip_name": "qwen_3_4b.safetensors",
+                "type": "lumina2",
+                "device": "default",
+            },
+        },
+        "3": {
+            "class_type": "VAELoader",
+            "inputs": {"vae_name": "ae.safetensors"},
+        },
+        "4": {
+            "class_type": "ModelSamplingAuraFlow",
+            "inputs": {"shift": 3, "model": ["1", 0]},
+        },
+        "6": {
+            "class_type": "CLIPTextEncode",
+            "inputs": {"text": prompt_text, "clip": ["2", 0]},
+        },
+        "7": {
+            "class_type": "ConditioningZeroOut",
+            "inputs": {"conditioning": ["6", 0]},
+        },
+        "8": {
+            "class_type": "EmptySD3LatentImage",
+            "inputs": {"width": WIDTH, "height": HEIGHT, "batch_size": 1},
+        },
+        "9": {
+            "class_type": "KSampler",
+            "inputs": {
+                "seed": seed,
+                "control_after_generate": "fixed",
+                "steps": 8,
+                "cfg": 1,
+                "sampler_name": "res_multistep",
+                "scheduler": "simple",
+                "denoise": 1,
+                "model": ["4", 0],
+                "positive": ["6", 0],
+                "negative": ["7", 0],
+                "latent_image": ["8", 0],
+            },
+        },
+        "10": {
+            "class_type": "VAEDecode",
+            "inputs": {"samples": ["9", 0], "vae": ["3", 0]},
+        },
+        "11": {
+            "class_type": "SaveImage",
+            "inputs": {"filename_prefix": prefix, "images": ["10", 0]},
+        },
+    }
+
+
+def submit_prompt(workflow):
+    payload = json.dumps({"prompt": workflow}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{COMFY_URL}/prompt",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        resp = urllib.request.urlopen(req)
+        return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()
+        raise RuntimeError(f"HTTP {e.code}: {body}")
+
+
+def poll_history(prompt_id, timeout=120):
+    start = time.time()
+    while time.time() - start < timeout:
+        try:
+            resp = urllib.request.urlopen(f"{COMFY_URL}/history/{prompt_id}")
+            data = json.loads(resp.read())
+            if prompt_id in data:
+                return data[prompt_id]
+        except Exception:
+            pass
+        time.sleep(2)
+    return None
+
+
+def download_image(filename, subfolder, dest_path):
+    url = f"{COMFY_URL}/view?filename={urllib.request.quote(filename)}&subfolder={urllib.request.quote(subfolder)}&type=output"
+    urllib.request.urlretrieve(url, dest_path)
+
+
+def main():
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+    # Collect all icons from both prompt files
+    all_icons = {}
+
+    with open(ARTIFACT_PROMPTS) as f:
+        data = json.load(f)
+    for icon_id, entry in data["artifacts"].items():
+        all_icons[icon_id] = entry["prompt"]
+
+    if os.path.exists(CHOICE_PROMPTS):
+        with open(CHOICE_PROMPTS) as f:
+            data = json.load(f)
+        for icon_id, entry in data["choices"].items():
+            all_icons[icon_id] = entry["prompt"]
+
+    if os.path.exists(ACHIEVEMENT_PROMPTS):
+        with open(ACHIEVEMENT_PROMPTS) as f:
+            data = json.load(f)
+        for icon_id, entry in data["achievements"].items():
+            all_icons[f"ending-{icon_id}"] = entry["prompt"]
+
+    # Filter out already-generated icons
+    to_generate = {}
+    for icon_id, prompt in all_icons.items():
+        dest = os.path.join(OUTPUT_DIR, f"{icon_id}.png")
+        if os.path.exists(dest):
+            print(f"  Skipping {icon_id}.png (already exists)")
+        else:
+            to_generate[icon_id] = prompt
+
+    if not to_generate:
+        print("All icons already generated. Nothing to do.")
+        return
+
+    # Submit jobs
+    jobs = []
+    for i, (icon_id, prompt) in enumerate(to_generate.items()):
+        prefix = f"adventure-icons/{icon_id}"
+        wf = build_workflow(prompt, BASE_SEED + i, prefix)
+        result = submit_prompt(wf)
+        prompt_id = result["prompt_id"]
+        jobs.append((icon_id, prompt_id))
+        print(f"  Submitted: {icon_id} -> {prompt_id}")
+
+    print(f"\n{len(jobs)} jobs queued. Polling for completion...\n")
+
+    # Poll for completion
+    completed = set()
+    while len(completed) < len(jobs):
+        for icon_id, prompt_id in jobs:
+            if prompt_id in completed:
+                continue
+            history = poll_history(prompt_id, timeout=5)
+            if history:
+                completed.add(prompt_id)
+                outputs = history.get("outputs", {})
+                for node_out in outputs.values():
+                    for img in node_out.get("images", []):
+                        src_filename = img["filename"]
+                        subfolder = img.get("subfolder", "")
+                        dest = os.path.join(OUTPUT_DIR, f"{icon_id}.png")
+                        download_image(src_filename, subfolder, dest)
+                        print(f"  [{len(completed)}/{len(jobs)}] {icon_id}.png downloaded")
+        if len(completed) < len(jobs):
+            time.sleep(2)
+
+    print(f"\nDone! {len(completed)} icons saved to {OUTPUT_DIR}/")
+
+
+if __name__ == "__main__":
+    main()

docs/architecture/generate-images.py

@@ -0,0 +1,165 @@
+"""
+Generate pixel art room images for the Architecture Adventure game.
+Uses Z-Image Turbo pipeline via local ComfyUI server (no LoRA).
+
+Usage: python docs/architecture/generate-images.py
+"""
+
+import json
+import os
+import time
+import urllib.request
+
+COMFY_URL = "http://localhost:8188"
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+PROMPTS_FILE = os.path.join(SCRIPT_DIR, "adventure-image-prompts.json")
+OUTPUT_DIR = os.path.join(SCRIPT_DIR, "images")
+BASE_SEED = 2024
+WIDTH = 1152
+HEIGHT = 640
+
+
+def build_workflow(prompt_text, seed, prefix):
+    return {
+        "1": {
+            "class_type": "UNETLoader",
+            "inputs": {
+                "unet_name": "ZIT\\z_image_turbo_bf16.safetensors",
+                "weight_dtype": "default",
+            },
+        },
+        "2": {
+            "class_type": "CLIPLoader",
+            "inputs": {
+                "clip_name": "qwen_3_4b.safetensors",
+                "type": "lumina2",
+                "device": "default",
+            },
+        },
+        "3": {
+            "class_type": "VAELoader",
+            "inputs": {"vae_name": "ae.safetensors"},
+        },
+        "4": {
+            "class_type": "ModelSamplingAuraFlow",
+            "inputs": {"shift": 3, "model": ["1", 0]},
+        },
+        "6": {
+            "class_type": "CLIPTextEncode",
+            "inputs": {"text": prompt_text, "clip": ["2", 0]},
+        },
+        "7": {
+            "class_type": "ConditioningZeroOut",
+            "inputs": {"conditioning": ["6", 0]},
+        },
+        "8": {
+            "class_type": "EmptySD3LatentImage",
+            "inputs": {"width": WIDTH, "height": HEIGHT, "batch_size": 1},
+        },
+        "9": {
+            "class_type": "KSampler",
+            "inputs": {
+                "seed": seed,
+                "control_after_generate": "fixed",
+                "steps": 8,
+                "cfg": 1,
+                "sampler_name": "res_multistep",
+                "scheduler": "simple",
+                "denoise": 1,
+                "model": ["4", 0],
+                "positive": ["6", 0],
+                "negative": ["7", 0],
+                "latent_image": ["8", 0],
+            },
+        },
+        "10": {
+            "class_type": "VAEDecode",
+            "inputs": {"samples": ["9", 0], "vae": ["3", 0]},
+        },
+        "11": {
+            "class_type": "SaveImage",
+            "inputs": {"filename_prefix": prefix, "images": ["10", 0]},
+        },
+    }
+
+
+def submit_prompt(workflow):
+    payload = json.dumps({"prompt": workflow}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{COMFY_URL}/prompt",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        resp = urllib.request.urlopen(req)
+        return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()
+        raise RuntimeError(f"HTTP {e.code}: {body}")
+
+
+def poll_history(prompt_id, timeout=120):
+    start = time.time()
+    while time.time() - start < timeout:
+        try:
+            resp = urllib.request.urlopen(f"{COMFY_URL}/history/{prompt_id}")
+            data = json.loads(resp.read())
+            if prompt_id in data:
+                return data[prompt_id]
+        except Exception:
+            pass
+        time.sleep(2)
+    return None
+
+
+def download_image(filename, subfolder, dest_path):
+    url = f"{COMFY_URL}/view?filename={urllib.request.quote(filename)}&subfolder={urllib.request.quote(subfolder)}&type=output"
+    urllib.request.urlretrieve(url, dest_path)
+
+
+def main():
+    with open(PROMPTS_FILE) as f:
+        data = json.load(f)
+
+    rooms = data["rooms"]
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+    # Submit all jobs
+    jobs = []
+    for i, (room_id, room) in enumerate(rooms.items()):
+        prefix = f"adventure/{room_id}"
+        wf = build_workflow(room["prompt"], BASE_SEED + i, prefix)
+        result = submit_prompt(wf)
+        prompt_id = result["prompt_id"]
+        jobs.append((room_id, prompt_id, prefix))
+        print(f"  Submitted: {room_id} -> {prompt_id}")
+
+    print(f"\n{len(jobs)} jobs queued. Polling for completion...\n")
+
+    # Poll for completion
+    completed = set()
+    while len(completed) < len(jobs):
+        for room_id, prompt_id, prefix in jobs:
+            if prompt_id in completed:
+                continue
+            history = poll_history(prompt_id, timeout=5)
+            if history:
+                completed.add(prompt_id)
+                # Find output filename
+                outputs = history.get("outputs", {})
+                for node_id, node_out in outputs.items():
+                    images = node_out.get("images", [])
+                    for img in images:
+                        src_filename = img["filename"]
+                        subfolder = img.get("subfolder", "")
+                        dest = os.path.join(OUTPUT_DIR, f"{room_id}.png")
+                        download_image(src_filename, subfolder, dest)
+                        print(f"  [{len(completed)}/{len(jobs)}] {room_id}.png downloaded")
+        if len(completed) < len(jobs):
+            time.sleep(2)
+
+    print(f"\nDone! {len(completed)} images saved to {OUTPUT_DIR}/")
+
+
+if __name__ == "__main__":
+    main()