fix: prevent auth errors for API key users on local/desktop

- Guard subscription status auto-fetch with isCloud check in
  useSubscription.ts to prevent Firebase auth errors on local/desktop
- Guard fetchBalance call in CurrentUserPopoverLegacy.vue for API key
  users since fetchBalance requires Firebase auth
- Add test to verify subscription status is not fetched when not on cloud
- Update CurrentUserPopoverLegacy test mock to include isApiKeyLogin

Fixes API key authentication showing "User not authenticated" errors
when users click profile icon or try to refresh balance on
local/desktop versions.

Slack: https://comfy-organization.slack.com/archives/C0A4XMHANP3/p1771896736700429?thread_ts=1771289819.003239&cid=C0A4XMHANP3

https://claude.ai/code/session_012jjZuGQbnnfcciowSwb4dc

.github/workflows/ci-lint-format.yaml

@@ -26,6 +26,14 @@ jobs:
       - name: Setup frontend
         uses: ./.github/actions/setup-frontend
 
+      - name: Detect browser_tests changes
+        id: changed-paths
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        with:
+          filters: |
+            browser_tests:
+              - 'browser_tests/**'
+
       - name: Run ESLint with auto-fix
         run: pnpm lint:fix
 
@@ -60,6 +68,10 @@ jobs:
           pnpm format:check
           pnpm knip
 
+      - name: Typecheck browser tests
+        if: steps.changed-paths.outputs.browser_tests == 'true'
+        run: pnpm typecheck:browser
+
       - name: Comment on PR about auto-fix
         if: steps.verify-changed-files.outputs.changed == 'true' && github.event.pull_request.head.repo.full_name == github.repository
         continue-on-error: true

.github/workflows/ci-tests-e2e.yaml

@@ -4,8 +4,10 @@ name: 'CI: Tests E2E'
 on:
   push:
     branches: [main, master, core/*, desktop/*]
+    paths-ignore: ['**/*.md']
   pull_request:
     branches-ignore: [wip/*, draft/*, temp/*]
+    paths-ignore: ['**/*.md']
   workflow_dispatch:
 
 concurrency:

.github/workflows/ci-tests-unit.yaml

@@ -4,8 +4,10 @@ name: 'CI: Tests Unit'
 on:
   push:
     branches: [main, master, dev*, core/*, desktop/*]
+    paths-ignore: ['**/*.md']
   pull_request:
     branches-ignore: [wip/*, draft/*, temp/*]
+    paths-ignore: ['**/*.md']
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

AGENTS.md

@@ -37,6 +37,10 @@ See @docs/guidance/\*.md for file-type-specific conventions (auto-loaded by glob
 
 The project uses **Nx** for build orchestration and task management
 
+## Package Manager
+
+This project uses **pnpm**. Always prefer scripts defined in `package.json` (e.g., `pnpm test:unit`, `pnpm lint`). To run arbitrary packages not in scripts, use `pnpx` or `pnpm dlx` — never `npx`.
+
 ## Build, Test, and Development Commands
 
 - `pnpm dev`: Start Vite dev server.

apps/desktop-ui/src/views/MaintenanceView.stories.ts

@@ -77,7 +77,7 @@ const createMockElectronAPI = () => {
 }
 
 const ensureElectronAPI = () => {
-  const globalWindow = window as unknown as { electronAPI?: unknown }
+  const globalWindow = window as { electronAPI?: unknown }
   if (!globalWindow.electronAPI) {
     globalWindow.electronAPI = createMockElectronAPI()
   }

browser_tests/assets/subgraphs/subgraph-with-multiple-promoted-previews.json

@@ -0,0 +1,394 @@
+{
+  "id": "43e9499c-2512-43b5-a5a1-2485eb65da32",
+  "revision": 0,
+  "last_node_id": 8,
+  "last_link_id": 10,
+  "nodes": [
+    {
+      "id": 1,
+      "type": "LoadImage",
+      "pos": [170.55728894250745, 515.6401487466619],
+      "size": [282.8166809082031, 363.8333435058594],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [7, 9]
+        },
+        {
+          "name": "MASK",
+          "type": "MASK",
+          "links": null
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "LoadImage"
+      },
+      "widgets_values": ["example.png", "image"]
+    },
+    {
+      "id": 7,
+      "type": "21dea088-e1b4-47a4-a01f-3d1bf4504001",
+      "pos": [500.2639113468392, 519.9960755960157],
+      "size": [464.95001220703125, 615.8333129882812],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "images",
+          "type": "IMAGE",
+          "link": 7
+        }
+      ],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [10]
+        }
+      ],
+      "properties": {
+        "proxyWidgets": [
+          ["2", "$$canvas-image-preview"],
+          ["4", "$$canvas-image-preview"]
+        ]
+      },
+      "widgets_values": []
+    },
+    {
+      "id": 8,
+      "type": "a7a0350a-af99-4d26-9391-450b4f726206",
+      "pos": [1000.5293620197185, 499.9253405678786],
+      "size": [225, 359.8333435058594],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image1",
+          "type": "IMAGE",
+          "link": 9
+        },
+        {
+          "name": "image2",
+          "type": "IMAGE",
+          "link": 10
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "proxyWidgets": [["6", "$$canvas-image-preview"]]
+      },
+      "widgets_values": []
+    }
+  ],
+  "links": [
+    [7, 1, 0, 7, 0, "IMAGE"],
+    [9, 1, 0, 8, 0, "IMAGE"],
+    [10, 7, 0, 8, 1, "IMAGE"]
+  ],
+  "groups": [],
+  "definitions": {
+    "subgraphs": [
+      {
+        "id": "21dea088-e1b4-47a4-a01f-3d1bf4504001",
+        "version": 1,
+        "state": {
+          "lastGroupId": 0,
+          "lastNodeId": 8,
+          "lastLinkId": 10,
+          "lastRerouteId": 0
+        },
+        "revision": 0,
+        "config": {},
+        "name": "New Subgraph",
+        "inputNode": {
+          "id": -10,
+          "bounding": [297.7833638107301, 502.6302057820892, 120, 60]
+        },
+        "outputNode": {
+          "id": -20,
+          "bounding": [1052.8175480718996, 502.6302057820892, 120, 60]
+        },
+        "inputs": [
+          {
+            "id": "afc8dbc3-12e6-4b3c-9840-9b398d06e6bd",
+            "name": "images",
+            "type": "IMAGE",
+            "linkIds": [1, 2],
+            "localized_name": "images",
+            "pos": [397.7833638107301, 522.6302057820892]
+          }
+        ],
+        "outputs": [
+          {
+            "id": "d0a84974-5f4d-4f4b-b23a-2e7288a9689d",
+            "name": "IMAGE",
+            "type": "IMAGE",
+            "linkIds": [5],
+            "localized_name": "IMAGE",
+            "pos": [1072.8175480718996, 522.6302057820892]
+          }
+        ],
+        "widgets": [],
+        "nodes": [
+          {
+            "id": 4,
+            "type": "PreviewImage",
+            "pos": [767.8225773415076, 602.8695134060456],
+            "size": [225, 303.8333435058594],
+            "flags": {},
+            "order": 2,
+            "mode": 0,
+            "inputs": [
+              {
+                "localized_name": "images",
+                "name": "images",
+                "type": "IMAGE",
+                "link": 3
+              }
+            ],
+            "outputs": [],
+            "properties": {
+              "Node name for S&R": "PreviewImage"
+            },
+            "widgets_values": []
+          },
+          {
+            "id": 2,
+            "type": "PreviewImage",
+            "pos": [754.9358989867657, 188.55375831225257],
+            "size": [225, 303.8333435058594],
+            "flags": {},
+            "order": 0,
+            "mode": 0,
+            "inputs": [
+              {
+                "localized_name": "images",
+                "name": "images",
+                "type": "IMAGE",
+                "link": 1
+              }
+            ],
+            "outputs": [],
+            "properties": {
+              "Node name for S&R": "PreviewImage"
+            },
+            "widgets_values": []
+          },
+          {
+            "id": 3,
+            "type": "ImageInvert",
+            "pos": [477.783932416778, 542.2440719627998],
+            "size": [225, 71.83333587646484],
+            "flags": {
+              "collapsed": false
+            },
+            "order": 1,
+            "mode": 0,
+            "inputs": [
+              {
+                "localized_name": "image",
+                "name": "image",
+                "type": "IMAGE",
+                "link": 2
+              }
+            ],
+            "outputs": [
+              {
+                "localized_name": "IMAGE",
+                "name": "IMAGE",
+                "type": "IMAGE",
+                "links": [3, 5]
+              }
+            ],
+            "properties": {
+              "Node name for S&R": "ImageInvert"
+            },
+            "widgets_values": []
+          }
+        ],
+        "groups": [],
+        "links": [
+          {
+            "id": 3,
+            "origin_id": 3,
+            "origin_slot": 0,
+            "target_id": 4,
+            "target_slot": 0,
+            "type": "IMAGE"
+          },
+          {
+            "id": 1,
+            "origin_id": -10,
+            "origin_slot": 0,
+            "target_id": 2,
+            "target_slot": 0,
+            "type": "IMAGE"
+          },
+          {
+            "id": 2,
+            "origin_id": -10,
+            "origin_slot": 0,
+            "target_id": 3,
+            "target_slot": 0,
+            "type": "IMAGE"
+          },
+          {
+            "id": 5,
+            "origin_id": 3,
+            "origin_slot": 0,
+            "target_id": -20,
+            "target_slot": 0,
+            "type": "IMAGE"
+          }
+        ],
+        "extra": {}
+      },
+      {
+        "id": "a7a0350a-af99-4d26-9391-450b4f726206",
+        "version": 1,
+        "state": {
+          "lastGroupId": 0,
+          "lastNodeId": 8,
+          "lastLinkId": 10,
+          "lastRerouteId": 0
+        },
+        "revision": 0,
+        "config": {},
+        "name": "New Subgraph",
+        "inputNode": {
+          "id": -10,
+          "bounding": [973.7423316105073, 561.9744246746379, 120, 80]
+        },
+        "outputNode": {
+          "id": -20,
+          "bounding": [1905.487372786412, 581.9744246746379, 120, 40]
+        },
+        "inputs": [
+          {
+            "id": "20ac4159-6814-4d40-a217-ea260152b689",
+            "name": "image1",
+            "type": "IMAGE",
+            "linkIds": [4],
+            "localized_name": "image1",
+            "pos": [1073.7423316105073, 581.9744246746379]
+          },
+          {
+            "id": "c3759a8c-914e-4450-bc41-ca683ffce96b",
+            "name": "image2",
+            "type": "IMAGE",
+            "linkIds": [8],
+            "localized_name": "image2",
+            "shape": 7,
+            "pos": [1073.7423316105073, 601.9744246746379]
+          }
+        ],
+        "outputs": [],
+        "widgets": [],
+        "nodes": [
+          {
+            "id": 5,
+            "type": "ImageStitch",
+            "pos": [1153.7423085222254, 396.2033931749105],
+            "size": [270, 225.1666717529297],
+            "flags": {},
+            "order": 0,
+            "mode": 0,
+            "inputs": [
+              {
+                "localized_name": "image1",
+                "name": "image1",
+                "type": "IMAGE",
+                "link": 4
+              },
+              {
+                "localized_name": "image2",
+                "name": "image2",
+                "shape": 7,
+                "type": "IMAGE",
+                "link": 8
+              }
+            ],
+            "outputs": [
+              {
+                "localized_name": "IMAGE",
+                "name": "IMAGE",
+                "type": "IMAGE",
+                "links": [6]
+              }
+            ],
+            "properties": {
+              "Node name for S&R": "ImageStitch"
+            },
+            "widgets_values": ["right", true, 0, "white"]
+          },
+          {
+            "id": 6,
+            "type": "PreviewImage",
+            "pos": [1620.4874189629757, 529.9122050216333],
+            "size": [225, 307.8333435058594],
+            "flags": {},
+            "order": 1,
+            "mode": 0,
+            "inputs": [
+              {
+                "localized_name": "images",
+                "name": "images",
+                "type": "IMAGE",
+                "link": 6
+              }
+            ],
+            "outputs": [],
+            "properties": {
+              "Node name for S&R": "PreviewImage"
+            },
+            "widgets_values": []
+          }
+        ],
+        "groups": [],
+        "links": [
+          {
+            "id": 6,
+            "origin_id": 5,
+            "origin_slot": 0,
+            "target_id": 6,
+            "target_slot": 0,
+            "type": "IMAGE"
+          },
+          {
+            "id": 4,
+            "origin_id": -10,
+            "origin_slot": 0,
+            "target_id": 5,
+            "target_slot": 0,
+            "type": "IMAGE"
+          },
+          {
+            "id": 8,
+            "origin_id": -10,
+            "origin_slot": 1,
+            "target_id": 5,
+            "target_slot": 1,
+            "type": "IMAGE"
+          }
+        ],
+        "extra": {}
+      }
+    ]
+  },
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 0.7269777827561446,
+      "offset": [-35.273237658266034, -55.17394203309256]
+    },
+    "frontendVersion": "1.40.8"
+  },
+  "version": 0.4
+}

browser_tests/assets/subgraphs/subgraph-with-preview-node.json

@@ -0,0 +1,170 @@
+{
+  "id": "preview-subgraph-test-001",
+  "revision": 0,
+  "last_node_id": 11,
+  "last_link_id": 2,
+  "nodes": [
+    {
+      "id": 5,
+      "type": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "pos": [318.6320139868054, 212.9091015141833],
+      "size": [225, 368],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "images",
+          "type": "IMAGE",
+          "link": 2
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "proxyWidgets": [
+          ["10", "filename_prefix"],
+          ["10", "$$canvas-image-preview"]
+        ],
+        "cnr_id": "comfy-core",
+        "ver": "0.13.0",
+        "ue_properties": {
+          "widget_ue_connectable": {},
+          "version": "7.6.2",
+          "input_ue_unconnectable": {}
+        }
+      },
+      "widgets_values": []
+    },
+    {
+      "id": 11,
+      "type": "LoadImage",
+      "pos": [-0.5080003681592018, 211.3051121416672],
+      "size": [282.8333435058594, 364],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [2]
+        },
+        {
+          "name": "MASK",
+          "type": "MASK",
+          "links": null
+        }
+      ],
+      "properties": {
+        "ue_properties": {
+          "widget_ue_connectable": {},
+          "input_ue_unconnectable": {}
+        },
+        "cnr_id": "comfy-core",
+        "ver": "0.13.0",
+        "Node name for S&R": "LoadImage"
+      },
+      "widgets_values": ["example.png", "image"]
+    }
+  ],
+  "links": [[2, 11, 0, 5, 0, "IMAGE"]],
+  "groups": [],
+  "definitions": {
+    "subgraphs": [
+      {
+        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+        "version": 1,
+        "state": {
+          "lastGroupId": 0,
+          "lastNodeId": 11,
+          "lastLinkId": 2,
+          "lastRerouteId": 0
+        },
+        "revision": 0,
+        "config": {},
+        "name": "New Subgraph",
+        "inputNode": {
+          "id": -10,
+          "bounding": [300, 350, 120, 60]
+        },
+        "outputNode": {
+          "id": -20,
+          "bounding": [900, 350, 120, 40]
+        },
+        "inputs": [
+          {
+            "id": "img-slot-001",
+            "name": "images",
+            "type": "IMAGE",
+            "linkIds": [1],
+            "pos": [400, 370]
+          }
+        ],
+        "outputs": [],
+        "widgets": [],
+        "nodes": [
+          {
+            "id": 10,
+            "type": "SaveImage",
+            "pos": [500.0046924937855, 300.0146992076527],
+            "size": [315, 340],
+            "flags": {},
+            "order": 0,
+            "mode": 0,
+            "inputs": [
+              {
+                "localized_name": "images",
+                "name": "images",
+                "type": "IMAGE",
+                "link": 1
+              }
+            ],
+            "outputs": [],
+            "properties": {
+              "cnr_id": "comfy-core",
+              "ver": "0.13.0",
+              "Node name for S&R": "SaveImage",
+              "ue_properties": {
+                "widget_ue_connectable": {},
+                "version": "7.6.2",
+                "input_ue_unconnectable": {}
+              }
+            },
+            "widgets_values": ["ComfyUI"]
+          }
+        ],
+        "groups": [],
+        "links": [
+          {
+            "id": 1,
+            "origin_id": -10,
+            "origin_slot": 0,
+            "target_id": 10,
+            "target_slot": 0,
+            "type": "IMAGE"
+          }
+        ],
+        "extra": {
+          "ue_links": [],
+          "links_added_by_ue": []
+        }
+      }
+    ]
+  },
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 1.1819400303977265,
+      "offset": [81.66005130613983, -19.028558221588725]
+    },
+    "frontendVersion": "1.40.3",
+    "ue_links": [],
+    "links_added_by_ue": [],
+    "VHS_latentpreview": false,
+    "VHS_latentpreviewrate": 0,
+    "VHS_MetadataImage": true,
+    "VHS_KeepIntermediate": true
+  },
+  "version": 0.4
+}

browser_tests/fixtures/helpers/CommandHelper.ts

@@ -11,7 +11,10 @@ export class CommandHelper {
   ): Promise<void> {
     await this.page.evaluate(
       ({ commandId, metadata }) => {
-        return window['app'].extensionManager.command.execute(commandId, {
+        const app = window.app
+        if (!app) throw new Error('window.app is not available')
+
+        return app.extensionManager.command.execute(commandId, {
           metadata
         })
       },

browser_tests/fixtures/helpers/DragDropHelper.ts

@@ -115,6 +115,16 @@ export class DragDropHelper {
       const dragOverEvent = new DragEvent('dragover', eventOptions)
       const dropEvent = new DragEvent('drop', eventOptions)
 
+      const graphCanvasElement = document.querySelector('#graph-canvas')
+
+      // Keep Litegraph's drag-over node tracking in sync when the drop target is a
+      // Vue node DOM overlay outside of the graph canvas element.
+      if (graphCanvasElement && !graphCanvasElement.contains(targetElement)) {
+        graphCanvasElement.dispatchEvent(
+          new DragEvent('dragover', eventOptions)
+        )
+      }
+
       Object.defineProperty(dropEvent, 'preventDefault', {
         value: () => {},
         writable: false

browser_tests/fixtures/helpers/NodeOperationsHelper.ts

@@ -33,6 +33,10 @@ export class NodeOperationsHelper {
     })
   }
 
+  async getNodeCount(): Promise<number> {
+    return await this.page.evaluate(() => window.app!.graph.nodes.length)
+  }
+
   async getNodes(): Promise<LGraphNode[]> {
     return await this.page.evaluate(() => {
       return window.app!.graph.nodes

browser_tests/fixtures/helpers/SubgraphHelper.ts

@@ -36,7 +36,7 @@ export class SubgraphHelper {
         const currentGraph = app.canvas!.graph!
 
         // Check if we're in a subgraph
-        if (currentGraph.constructor.name !== 'Subgraph') {
+        if (!('inputNode' in currentGraph)) {
           throw new Error(
             'Not in a subgraph - this method only works inside subgraphs'
           )
@@ -88,7 +88,7 @@ export class SubgraphHelper {
 
             if (node.onPointerDown) {
               node.onPointerDown(
-                event as unknown as CanvasPointerEvent,
+                event as Partial<CanvasPointerEvent> as CanvasPointerEvent,
                 app.canvas.pointer,
                 app.canvas.linkConnector
               )
@@ -121,7 +121,7 @@ export class SubgraphHelper {
 
           if (node.onPointerDown) {
             node.onPointerDown(
-              event as unknown as CanvasPointerEvent,
+              event as Partial<CanvasPointerEvent> as CanvasPointerEvent,
               app.canvas.pointer,
               app.canvas.linkConnector
             )
@@ -129,7 +129,7 @@ export class SubgraphHelper {
             // Trigger double-click
             if (app.canvas.pointer.onDoubleClick) {
               app.canvas.pointer.onDoubleClick(
-                event as unknown as CanvasPointerEvent
+                event as Partial<CanvasPointerEvent> as CanvasPointerEvent
               )
             }
           }

browser_tests/fixtures/selectors.ts

@@ -27,6 +27,7 @@ export const TestIds = {
     settingsContainer: 'settings-container',
     settingsTabAbout: 'settings-tab-about',
     confirm: 'confirm-dialog',
+    missingNodes: 'missing-nodes-warning',
     about: 'about-panel',
     whatsNewSection: 'whats-new-section'
   },
@@ -46,8 +47,12 @@ export const TestIds = {
   widgets: {
     decrement: 'decrement',
     increment: 'increment',
+    domWidgetTextarea: 'dom-widget-textarea',
     subgraphEnterButton: 'subgraph-enter-button'
   },
+  breadcrumb: {
+    subgraph: 'subgraph-breadcrumb'
+  },
   templates: {
     content: 'template-workflows-content',
     workflowCard: (id: string) => `template-workflow-${id}`
@@ -70,6 +75,7 @@ export type TestIdValue =
   | (typeof TestIds.propertiesPanel)[keyof typeof TestIds.propertiesPanel]
   | (typeof TestIds.node)[keyof typeof TestIds.node]
   | (typeof TestIds.widgets)[keyof typeof TestIds.widgets]
+  | (typeof TestIds.breadcrumb)[keyof typeof TestIds.breadcrumb]
   | Exclude<
       (typeof TestIds.templates)[keyof typeof TestIds.templates],
       (id: string) => string

browser_tests/fixtures/utils/litegraphUtils.ts

@@ -128,7 +128,8 @@ class NodeSlotReference {
             nodeSize: [node.size[0], node.size[1]],
             rawConnectionPos: [rawPos[0], rawPos[1]],
             convertedPos: [convertedPos[0], convertedPos[1]],
-            currentGraphType: window.app!.canvas.graph!.constructor.name
+            currentGraphType:
+              'inputNode' in window.app!.canvas.graph! ? 'Subgraph' : 'LGraph'
           }
         )
 
@@ -461,18 +462,44 @@ export class NodeReference {
     // Try multiple positions to avoid DOM widget interference
     const clickPositions = [
       { x: nodePos.x + nodeSize.width / 2, y: nodePos.y + titleHeight + 5 },
-      { x: nodePos.x + nodeSize.width / 2, y: nodePos.y + nodeSize.height / 2 },
+      {
+        x: nodePos.x + nodeSize.width / 2,
+        y: nodePos.y + nodeSize.height / 2
+      },
       { x: nodePos.x + 20, y: nodePos.y + titleHeight + 5 }
     ]
 
+    // Click the enter_subgraph title button (top-right of title bar).
+    // This is more reliable than dblclick on the node body because
+    // promoted DOM widgets can overlay the body and intercept events.
+    const subgraphButtonPos = {
+      x: nodePos.x + nodeSize.width - 15,
+      y: nodePos.y - titleHeight / 2
+    }
+
     const checkIsInSubgraph = async () => {
       return this.comfyPage.page.evaluate(() => {
         const graph = window.app!.canvas.graph
-        return graph?.constructor?.name === 'Subgraph'
+        return !!graph && 'inputNode' in graph
       })
     }
 
     await expect(async () => {
+      // Try just clicking the enter button first
+      await this.comfyPage.canvas.click({
+        position: { x: 250, y: 250 },
+        force: true
+      })
+      await this.comfyPage.nextFrame()
+
+      await this.comfyPage.canvas.click({
+        position: subgraphButtonPos,
+        force: true
+      })
+      await this.comfyPage.nextFrame()
+
+      if (await checkIsInSubgraph()) return
+
       for (const position of clickPositions) {
         // Clear any selection first
         await this.comfyPage.canvas.click({

browser_tests/fixtures/ws.ts

@@ -1,9 +1,5 @@
 import { test as base } from '@playwright/test'
 
-interface TestWindow extends Window {
-  __ws__?: Record<string, WebSocket>
-}
-
 export const webSocketFixture = base.extend<{
   ws: { trigger(data: unknown, url?: string): Promise<void> }
 }>({

browser_tests/helpers/promotedWidgets.ts

@@ -0,0 +1,64 @@
+import type { ComfyPage } from '../fixtures/ComfyPage'
+
+export type PromotedWidgetEntry = [string, string]
+
+export function isPromotedWidgetEntry(
+  entry: unknown
+): entry is PromotedWidgetEntry {
+  return (
+    Array.isArray(entry) &&
+    entry.length === 2 &&
+    typeof entry[0] === 'string' &&
+    typeof entry[1] === 'string'
+  )
+}
+
+export function normalizePromotedWidgets(
+  value: unknown
+): PromotedWidgetEntry[] {
+  if (!Array.isArray(value)) return []
+  return value.filter(isPromotedWidgetEntry)
+}
+
+export async function getPromotedWidgets(
+  comfyPage: ComfyPage,
+  nodeId: string
+): Promise<PromotedWidgetEntry[]> {
+  const raw = await comfyPage.page.evaluate((id) => {
+    const node = window.app!.canvas.graph!.getNodeById(id)
+    return node?.properties?.proxyWidgets ?? []
+  }, nodeId)
+
+  return normalizePromotedWidgets(raw)
+}
+
+export async function getPromotedWidgetNames(
+  comfyPage: ComfyPage,
+  nodeId: string
+): Promise<string[]> {
+  const promotedWidgets = await getPromotedWidgets(comfyPage, nodeId)
+  return promotedWidgets.map(([, widgetName]) => widgetName)
+}
+
+export async function getPromotedWidgetCount(
+  comfyPage: ComfyPage,
+  nodeId: string
+): Promise<number> {
+  const promotedWidgets = await getPromotedWidgets(comfyPage, nodeId)
+  return promotedWidgets.length
+}
+
+export async function getPromotedWidgetCountByName(
+  comfyPage: ComfyPage,
+  nodeId: string,
+  widgetName: string
+): Promise<number> {
+  return comfyPage.page.evaluate(
+    ([id, name]) => {
+      const node = window.app!.canvas.graph!.getNodeById(id)
+      const widgets = node?.widgets ?? []
+      return widgets.filter((widget) => widget.name === name).length
+    },
+    [nodeId, widgetName] as const
+  )
+}

browser_tests/tests/browserTabTitle.spec.ts

@@ -14,7 +14,9 @@ test.describe('Browser tab title', { tag: '@smoke' }, () => {
         return (window.app!.extensionManager as WorkspaceStore).workflow
           .activeWorkflow?.filename
       })
-      expect(await comfyPage.page.title()).toBe(`*${workflowName} - ComfyUI`)
+      await expect
+        .poll(() => comfyPage.page.title())
+        .toBe(`*${workflowName} - ComfyUI`)
     })
 
     // Failing on CI
@@ -51,7 +53,7 @@ test.describe('Browser tab title', { tag: '@smoke' }, () => {
     })
 
     test('Can display default title', async ({ comfyPage }) => {
-      expect(await comfyPage.page.title()).toBe('ComfyUI')
+      await expect.poll(() => comfyPage.page.title()).toBe('ComfyUI')
     })
   })
 })

browser_tests/tests/changeTracker.spec.ts

@@ -160,12 +160,12 @@ test.describe('Change Tracker', { tag: '@workflow' }, () => {
     })
     // Click empty space to trigger a change detection.
     await comfyPage.canvasOps.clickEmptySpace()
-    expect(await comfyPage.workflow.getUndoQueueSize()).toBe(1)
+    await expect.poll(() => comfyPage.workflow.getUndoQueueSize()).toBe(1)
   })
 
   test('Ignores changes in workflow.ds', async ({ comfyPage }) => {
     expect(await comfyPage.workflow.getUndoQueueSize()).toBe(0)
     await comfyPage.canvasOps.pan({ x: 10, y: 10 })
-    expect(await comfyPage.workflow.getUndoQueueSize()).toBe(0)
+    await expect.poll(() => comfyPage.workflow.getUndoQueueSize()).toBe(0)
   })
 })

browser_tests/tests/colorPalette.spec.ts

@@ -245,11 +245,18 @@ test.describe(
       await comfyPage.settings.setSetting('Comfy.ColorPalette', 'light')
       await comfyPage.nextFrame()
       const parsed = await comfyPage.page.evaluate(() => {
-        return window['app'].graph.serialize()
+        const graph = window.app!.graph!
+        if (typeof graph.serialize !== 'function') {
+          throw new Error('app.graph.serialize is not available')
+        }
+        return graph.serialize() as {
+          nodes: Array<{ bgcolor?: string; color?: string }>
+        }
       })
       expect(parsed.nodes).toBeDefined()
       expect(Array.isArray(parsed.nodes)).toBe(true)
-      for (const node of parsed.nodes) {
+      const nodes = parsed.nodes
+      for (const node of nodes) {
         if (node.bgcolor) expect(node.bgcolor).not.toMatch(/hsla/)
         if (node.color) expect(node.color).not.toMatch(/hsla/)
       }

browser_tests/tests/dialog.spec.ts

@@ -4,6 +4,7 @@ import { expect } from '@playwright/test'
 import type { Keybinding } from '../../src/platform/keybindings/types'
 import { comfyPageFixture as test } from '../fixtures/ComfyPage'
 import { DefaultGraphPositions } from '../fixtures/constants/defaultGraphPositions'
+import { TestIds } from '../fixtures/selectors'
 
 test.beforeEach(async ({ comfyPage }) => {
   await comfyPage.settings.setSetting('Comfy.UseNewMenu', 'Disabled')
@@ -15,8 +16,9 @@ test.describe('Load workflow warning', { tag: '@ui' }, () => {
   }) => {
     await comfyPage.workflow.loadWorkflow('missing/missing_nodes')
 
-    // Wait for the element with the .comfy-missing-nodes selector to be visible
-    const missingNodesWarning = comfyPage.page.locator('.comfy-missing-nodes')
+    const missingNodesWarning = comfyPage.page.getByTestId(
+      TestIds.dialogs.missingNodes
+    )
     await expect(missingNodesWarning).toBeVisible()
   })
 
@@ -25,8 +27,9 @@ test.describe('Load workflow warning', { tag: '@ui' }, () => {
   }) => {
     await comfyPage.workflow.loadWorkflow('missing/missing_nodes_in_subgraph')
 
-    // Wait for the element with the .comfy-missing-nodes selector to be visible
-    const missingNodesWarning = comfyPage.page.locator('.comfy-missing-nodes')
+    const missingNodesWarning = comfyPage.page.getByTestId(
+      TestIds.dialogs.missingNodes
+    )
     await expect(missingNodesWarning).toBeVisible()
 
     // Verify the missing node text includes subgraph context
@@ -38,13 +41,14 @@ test.describe('Load workflow warning', { tag: '@ui' }, () => {
 
 test('Does not report warning on undo/redo', async ({ comfyPage }) => {
   await comfyPage.settings.setSetting('Comfy.NodeSearchBoxImpl', 'v1 (legacy)')
+  const missingNodesWarning = comfyPage.page.getByTestId(
+    TestIds.dialogs.missingNodes
+  )
 
   await comfyPage.workflow.loadWorkflow('missing/missing_nodes')
-  await comfyPage.page
-    .locator('.p-dialog')
-    .getByRole('button', { name: 'Close' })
-    .click({ force: true })
-  await comfyPage.page.locator('.p-dialog').waitFor({ state: 'hidden' })
+  await expect(missingNodesWarning).toBeVisible()
+  await comfyPage.page.keyboard.press('Escape')
+  await expect(missingNodesWarning).not.toBeVisible()
 
   // Wait for any async operations to complete after dialog closes
   await comfyPage.nextFrame()
@@ -55,9 +59,14 @@ test('Does not report warning on undo/redo', async ({ comfyPage }) => {
 
   // Undo and redo the change
   await comfyPage.keyboard.undo()
-  await expect(comfyPage.page.locator('.comfy-missing-nodes')).not.toBeVisible()
+  await expect(async () => {
+    await expect(missingNodesWarning).not.toBeVisible()
+  }).toPass({ timeout: 5000 })
+
   await comfyPage.keyboard.redo()
-  await expect(comfyPage.page.locator('.comfy-missing-nodes')).not.toBeVisible()
+  await expect(async () => {
+    await expect(missingNodesWarning).not.toBeVisible()
+  }).toPass({ timeout: 5000 })
 })
 
 test.describe('Execution error', () => {
@@ -401,7 +410,7 @@ test.describe('Signin dialog', () => {
   test('Paste content to signin dialog should not paste node on canvas', async ({
     comfyPage
   }) => {
-    const nodeNum = (await comfyPage.nodeOps.getNodes()).length
+    const nodeNum = await comfyPage.nodeOps.getNodeCount()
     await comfyPage.canvas.click({
       position: DefaultGraphPositions.emptyLatentWidgetClick
     })
@@ -424,6 +433,6 @@ test.describe('Signin dialog', () => {
     await input.press('Control+v')
     await expect(input).toHaveValue('test_password')
 
-    expect(await comfyPage.nodeOps.getNodes()).toHaveLength(nodeNum)
+    expect(await comfyPage.nodeOps.getNodeCount()).toBe(nodeNum)
   })
 })

browser_tests/tests/menu.spec.ts

@@ -203,19 +203,19 @@ test.describe('Menu', { tag: '@ui' }, () => {
       await topbar.switchTheme('light')
 
       // Verify menu stays open and Light theme shows as active
-      await expect(menu).toBeVisible()
-      await expect(themeSubmenu).toBeVisible()
-
-      // Check that Light theme is active
-      expect(await topbar.isMenuItemActive(lightThemeItem)).toBe(true)
+      await expect(async () => {
+        await expect(menu).toBeVisible()
+        await expect(themeSubmenu).toBeVisible()
+        expect(await topbar.isMenuItemActive(lightThemeItem)).toBe(true)
+      }).toPass({ timeout: 5000 })
 
       // Screenshot with light theme active
       await comfyPage.attachScreenshot('theme-menu-light-active')
 
       // Verify ColorPalette setting is set to "light"
-      expect(await comfyPage.settings.getSetting('Comfy.ColorPalette')).toBe(
-        'light'
-      )
+      await expect
+        .poll(() => comfyPage.settings.getSetting('Comfy.ColorPalette'))
+        .toBe('light')
 
       // Close menu to see theme change
       await topbar.closeTopbarMenu()
@@ -228,20 +228,22 @@ test.describe('Menu', { tag: '@ui' }, () => {
       await topbar.switchTheme('dark')
 
       // Verify menu stays open and Dark theme shows as active
-      await expect(menu).toBeVisible()
-      await expect(themeItems2.submenu).toBeVisible()
-
-      // Check that Dark theme is active and Light theme is not
-      expect(await topbar.isMenuItemActive(themeItems2.darkTheme)).toBe(true)
-      expect(await topbar.isMenuItemActive(themeItems2.lightTheme)).toBe(false)
+      await expect(async () => {
+        await expect(menu).toBeVisible()
+        await expect(themeItems2.submenu).toBeVisible()
+        expect(await topbar.isMenuItemActive(themeItems2.darkTheme)).toBe(true)
+        expect(await topbar.isMenuItemActive(themeItems2.lightTheme)).toBe(
+          false
+        )
+      }).toPass({ timeout: 5000 })
 
       // Screenshot with dark theme active
       await comfyPage.attachScreenshot('theme-menu-dark-active')
 
       // Verify ColorPalette setting is set to "dark"
-      expect(await comfyPage.settings.getSetting('Comfy.ColorPalette')).toBe(
-        'dark'
-      )
+      await expect
+        .poll(() => comfyPage.settings.getSetting('Comfy.ColorPalette'))
+        .toBe('dark')
 
       // Close menu
       await topbar.closeTopbarMenu()

browser_tests/tests/sidebar/workflows.spec.ts

@@ -83,17 +83,15 @@ test.describe('Workflows sidebar', () => {
     const tab = comfyPage.menu.workflowsTab
     await tab.open()
     await comfyPage.command.executeCommand('Comfy.LoadDefaultWorkflow')
-    const originalNodeCount = (await comfyPage.nodeOps.getNodes()).length
+    const originalNodeCount = await comfyPage.nodeOps.getNodeCount()
 
     await tab.insertWorkflow(tab.getPersistedItem('workflow1.json'))
     await expect
-      .poll(() => comfyPage.nodeOps.getNodes().then((n) => n.length))
+      .poll(() => comfyPage.nodeOps.getNodeCount())
       .toEqual(originalNodeCount + 1)
 
     await tab.getPersistedItem('workflow1.json').click()
-    await expect
-      .poll(() => comfyPage.nodeOps.getNodes().then((n) => n.length))
-      .toEqual(1)
+    await expect.poll(() => comfyPage.nodeOps.getNodeCount()).toEqual(1)
   })
 
   test('Can rename nested workflow from opened workflow item', async ({

browser_tests/tests/subgraph.spec.ts

@@ -53,7 +53,7 @@ test.describe('Subgraph Operations', { tag: ['@slow', '@subgraph'] }, () => {
   ): Promise<boolean> {
     return await comfyPage.page.evaluate(() => {
       const graph = window.app!.canvas.graph
-      return graph?.constructor?.name === 'Subgraph'
+      return !!graph && 'inputNode' in graph
     })
   }
 

browser_tests/tests/subgraphPromotion.spec.ts

@@ -0,0 +1,622 @@
+import { expect } from '@playwright/test'
+
+import type { ComfyWorkflowJSON } from '@/platform/workflow/validation/schemas/workflowSchema'
+
+import type { ComfyPage } from '../fixtures/ComfyPage'
+import { comfyPageFixture as test } from '../fixtures/ComfyPage'
+import { TestIds } from '../fixtures/selectors'
+import { fitToViewInstant } from '../helpers/fitToView'
+import {
+  getPromotedWidgetNames,
+  getPromotedWidgetCount,
+  getPromotedWidgets
+} from '../helpers/promotedWidgets'
+
+/**
+ * Check whether we're currently in a subgraph.
+ */
+async function isInSubgraph(comfyPage: ComfyPage): Promise<boolean> {
+  return comfyPage.page.evaluate(() => {
+    const graph = window.app!.canvas.graph
+    return !!graph && 'inputNode' in graph
+  })
+}
+
+async function exitSubgraphViaBreadcrumb(comfyPage: ComfyPage): Promise<void> {
+  const breadcrumb = comfyPage.page.getByTestId(TestIds.breadcrumb.subgraph)
+  await breadcrumb.waitFor({ state: 'visible', timeout: 5000 })
+
+  const parentLink = breadcrumb.getByRole('link').first()
+  await expect(parentLink).toBeVisible()
+  await parentLink.click()
+  await comfyPage.nextFrame()
+}
+
+test.describe(
+  'Subgraph Widget Promotion',
+  { tag: ['@subgraph', '@widget'] },
+  () => {
+    test.describe('Auto-promotion on Convert to Subgraph', () => {
+      test('Recommended widgets are auto-promoted when creating a subgraph', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow('default')
+
+        // Select just the KSampler node (id 3) which has a "seed" widget
+        const ksampler = await comfyPage.nodeOps.getNodeRefById('3')
+        await ksampler.click('title')
+        const subgraphNode = await ksampler.convertToSubgraph()
+        await comfyPage.nextFrame()
+
+        // SubgraphNode should exist
+        expect(await subgraphNode.exists()).toBe(true)
+
+        // The KSampler has a "seed" widget which is in the recommended list.
+        // The promotion store should have at least the seed widget promoted.
+        const nodeId = String(subgraphNode.id)
+        const promotedNames = await getPromotedWidgetNames(comfyPage, nodeId)
+        expect(promotedNames).toContain('seed')
+
+        // SubgraphNode should have widgets (promoted views)
+        const widgetCount = await getPromotedWidgetCount(comfyPage, nodeId)
+        expect(widgetCount).toBeGreaterThan(0)
+      })
+
+      test('CLIPTextEncode text widget is auto-promoted', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow('default')
+
+        // Select the positive CLIPTextEncode node (id 6)
+        const clipNode = await comfyPage.nodeOps.getNodeRefById('6')
+        await clipNode.click('title')
+        const subgraphNode = await clipNode.convertToSubgraph()
+        await comfyPage.nextFrame()
+
+        const nodeId = String(subgraphNode.id)
+        const promotedNames = await getPromotedWidgetNames(comfyPage, nodeId)
+        expect(promotedNames.length).toBeGreaterThan(0)
+
+        // CLIPTextEncode is in the recommendedNodes list, so its text widget
+        // should be promoted
+        expect(promotedNames).toContain('text')
+      })
+
+      test('SaveImage/PreviewImage nodes get pseudo-widget promoted', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow('default')
+        await fitToViewInstant(comfyPage)
+
+        // Select the SaveImage node (id 9 in default workflow)
+        const saveNode = await comfyPage.nodeOps.getNodeRefById('9')
+        await saveNode.click('title')
+        const subgraphNode = await saveNode.convertToSubgraph()
+        await comfyPage.nextFrame()
+
+        const promotedNames = await getPromotedWidgetNames(
+          comfyPage,
+          String(subgraphNode.id)
+        )
+
+        // SaveImage is in the recommendedNodes list, so filename_prefix is promoted
+        expect(promotedNames).toContain('filename_prefix')
+      })
+    })
+
+    test.describe('Promoted Widget Visibility in LiteGraph Mode', () => {
+      test('Promoted text widget is visible on SubgraphNode', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.nextFrame()
+
+        // The subgraph node (id 11) should have a text widget promoted
+        const textarea = comfyPage.page.getByTestId(
+          TestIds.widgets.domWidgetTextarea
+        )
+        await expect(textarea).toBeVisible()
+        await expect(textarea).toHaveCount(1)
+      })
+
+      test('Multiple promoted widgets all render on SubgraphNode', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-multiple-promoted-widgets'
+        )
+        await comfyPage.nextFrame()
+
+        const textareas = comfyPage.page.getByTestId(
+          TestIds.widgets.domWidgetTextarea
+        )
+        await expect(textareas.first()).toBeVisible()
+        const count = await textareas.count()
+        expect(count).toBeGreaterThan(1)
+      })
+    })
+
+    test.describe('Promoted Widget Visibility in Vue Mode', () => {
+      test.beforeEach(async ({ comfyPage }) => {
+        await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', true)
+      })
+
+      test('Promoted text widget renders on SubgraphNode in Vue mode', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.vueNodes.waitForNodes()
+
+        // SubgraphNode (id 11) should render with its body
+        const subgraphVueNode = comfyPage.vueNodes.getNodeLocator('11')
+        await expect(subgraphVueNode).toBeVisible()
+
+        // It should have the Enter Subgraph button
+        const enterButton = subgraphVueNode.getByTestId('subgraph-enter-button')
+        await expect(enterButton).toBeVisible()
+
+        // The promoted text widget should render inside the node
+        const nodeBody = subgraphVueNode.locator('[data-testid="node-body-11"]')
+        await expect(nodeBody).toBeVisible()
+
+        // Widgets section should exist and have at least one widget
+        const widgets = nodeBody.locator('.lg-node-widgets > div')
+        await expect(widgets.first()).toBeVisible()
+      })
+
+      test('Enter Subgraph button navigates into subgraph in Vue mode', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.vueNodes.waitForNodes()
+
+        await comfyPage.vueNodes.enterSubgraph('11')
+        await comfyPage.nextFrame()
+
+        expect(await isInSubgraph(comfyPage)).toBe(true)
+      })
+
+      test('Multiple promoted widgets render on SubgraphNode in Vue mode', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-multiple-promoted-widgets'
+        )
+        await comfyPage.vueNodes.waitForNodes()
+
+        const subgraphVueNode = comfyPage.vueNodes.getNodeLocator('11')
+        await expect(subgraphVueNode).toBeVisible()
+
+        const nodeBody = subgraphVueNode.locator('[data-testid="node-body-11"]')
+        const widgets = nodeBody.locator('.lg-node-widgets > div')
+        const count = await widgets.count()
+        expect(count).toBeGreaterThan(1)
+      })
+    })
+
+    test.describe('Promoted Widget Reactivity', () => {
+      test('Value changes on promoted widget sync to interior widget', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.nextFrame()
+
+        const testContent = 'promoted-value-sync-test'
+
+        // Type into the promoted textarea on the SubgraphNode
+        const textarea = comfyPage.page.getByTestId(
+          TestIds.widgets.domWidgetTextarea
+        )
+        await textarea.fill(testContent)
+        await comfyPage.nextFrame()
+
+        // Navigate into subgraph
+        const subgraphNode = await comfyPage.nodeOps.getNodeRefById('11')
+        await subgraphNode.navigateIntoSubgraph()
+
+        // Interior CLIPTextEncode textarea should have the same value
+        const interiorTextarea = comfyPage.page.getByTestId(
+          TestIds.widgets.domWidgetTextarea
+        )
+        await expect(interiorTextarea).toHaveValue(testContent)
+      })
+
+      test('Value changes on interior widget sync to promoted widget', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.nextFrame()
+
+        const testContent = 'interior-value-sync-test'
+
+        // Navigate into subgraph
+        const subgraphNode = await comfyPage.nodeOps.getNodeRefById('11')
+        await subgraphNode.navigateIntoSubgraph()
+
+        // Type into the interior CLIPTextEncode textarea
+        const interiorTextarea = comfyPage.page.getByTestId(
+          TestIds.widgets.domWidgetTextarea
+        )
+        await interiorTextarea.fill(testContent)
+        await comfyPage.nextFrame()
+
+        // Navigate back to parent graph
+        await exitSubgraphViaBreadcrumb(comfyPage)
+
+        // Promoted textarea on SubgraphNode should have the same value
+        const promotedTextarea = comfyPage.page.getByTestId(
+          TestIds.widgets.domWidgetTextarea
+        )
+        await expect(promotedTextarea).toHaveValue(testContent)
+      })
+
+      test('Value persists through repeated navigation', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.nextFrame()
+
+        const testContent = 'persistence-through-navigation'
+
+        // Set value on promoted widget
+        const textarea = comfyPage.page.getByTestId(
+          TestIds.widgets.domWidgetTextarea
+        )
+        await textarea.fill(testContent)
+
+        // Navigate in and out multiple times
+        for (let i = 0; i < 3; i++) {
+          const subgraphNode = await comfyPage.nodeOps.getNodeRefById('11')
+          await subgraphNode.navigateIntoSubgraph()
+          const interiorTextarea = comfyPage.page.getByTestId(
+            TestIds.widgets.domWidgetTextarea
+          )
+          await expect(interiorTextarea).toHaveValue(testContent)
+
+          await exitSubgraphViaBreadcrumb(comfyPage)
+
+          const promotedTextarea = comfyPage.page.getByTestId(
+            TestIds.widgets.domWidgetTextarea
+          )
+          await expect(promotedTextarea).toHaveValue(testContent)
+        }
+      })
+    })
+
+    test.describe('Manual Promote/Demote via Context Menu', () => {
+      test.beforeEach(async ({ comfyPage }) => {
+        await comfyPage.settings.setSetting('Comfy.UseNewMenu', 'Top')
+      })
+
+      test('Can promote a widget from inside a subgraph', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow('subgraphs/basic-subgraph')
+
+        const subgraphNode = await comfyPage.nodeOps.getNodeRefById('2')
+        await subgraphNode.navigateIntoSubgraph()
+
+        // Get the KSampler node (id 1) inside the subgraph
+        const ksampler = await comfyPage.nodeOps.getNodeRefById('1')
+
+        // Right-click on the KSampler's "steps" widget (index 2) to promote it
+        const stepsWidget = await ksampler.getWidget(2)
+        const widgetPos = await stepsWidget.getPosition()
+        await comfyPage.canvas.click({
+          position: widgetPos,
+          button: 'right',
+          force: true
+        })
+        await comfyPage.nextFrame()
+
+        // Look for the Promote Widget menu entry
+        const promoteEntry = comfyPage.page
+          .locator('.litemenu-entry')
+          .filter({ hasText: /Promote Widget/ })
+
+        await expect(promoteEntry).toBeVisible()
+        await promoteEntry.click()
+        await comfyPage.nextFrame()
+
+        // Navigate back to parent
+        await exitSubgraphViaBreadcrumb(comfyPage)
+
+        // SubgraphNode should now have the promoted widget
+        const widgetCount = await getPromotedWidgetCount(comfyPage, '2')
+        expect(widgetCount).toBeGreaterThan(0)
+      })
+
+      test('Can un-promote a widget from inside a subgraph', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow('subgraphs/basic-subgraph')
+
+        // First promote a canvas-rendered widget (KSampler "steps")
+        const subgraphNode = await comfyPage.nodeOps.getNodeRefById('2')
+        await subgraphNode.navigateIntoSubgraph()
+
+        const ksampler = await comfyPage.nodeOps.getNodeRefById('1')
+        const stepsWidget = await ksampler.getWidget(2)
+        const widgetPos = await stepsWidget.getPosition()
+
+        await comfyPage.canvas.click({
+          position: widgetPos,
+          button: 'right',
+          force: true
+        })
+        await comfyPage.nextFrame()
+
+        const promoteEntry = comfyPage.page
+          .locator('.litemenu-entry')
+          .filter({ hasText: /Promote Widget/ })
+        await expect(promoteEntry).toBeVisible()
+        await promoteEntry.click()
+        await comfyPage.nextFrame()
+
+        // Navigate back and verify promotion took effect
+        await exitSubgraphViaBreadcrumb(comfyPage)
+        await fitToViewInstant(comfyPage)
+        await comfyPage.nextFrame()
+
+        const initialWidgetCount = await getPromotedWidgetCount(comfyPage, '2')
+        expect(initialWidgetCount).toBeGreaterThan(0)
+
+        // Navigate back in and un-promote
+        const subgraphNode2 = await comfyPage.nodeOps.getNodeRefById('2')
+        await subgraphNode2.navigateIntoSubgraph()
+        const stepsWidget2 = await (
+          await comfyPage.nodeOps.getNodeRefById('1')
+        ).getWidget(2)
+        const widgetPos2 = await stepsWidget2.getPosition()
+
+        await comfyPage.canvas.click({
+          position: widgetPos2,
+          button: 'right',
+          force: true
+        })
+        await comfyPage.nextFrame()
+
+        const unpromoteEntry = comfyPage.page
+          .locator('.litemenu-entry')
+          .filter({ hasText: /Un-Promote Widget/ })
+
+        await expect(unpromoteEntry).toBeVisible()
+        await unpromoteEntry.click()
+        await comfyPage.nextFrame()
+
+        // Navigate back to parent
+        await exitSubgraphViaBreadcrumb(comfyPage)
+
+        // SubgraphNode should have fewer widgets
+        const finalWidgetCount = await getPromotedWidgetCount(comfyPage, '2')
+        expect(finalWidgetCount).toBeLessThan(initialWidgetCount)
+      })
+    })
+
+    test.describe('Pseudo-Widget Promotion', () => {
+      test('Promotion store tracks pseudo-widget entries for subgraph with preview node', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-preview-node'
+        )
+        await comfyPage.nextFrame()
+
+        // The SaveImage node is in the recommendedNodes list, so its
+        // filename_prefix widget should be auto-promoted
+        const promotedNames = await getPromotedWidgetNames(comfyPage, '5')
+        expect(promotedNames.length).toBeGreaterThan(0)
+        expect(promotedNames).toContain('filename_prefix')
+      })
+
+      test('Converting SaveImage to subgraph promotes its widgets', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow('default')
+        await fitToViewInstant(comfyPage)
+
+        // Select SaveImage (id 9)
+        const saveNode = await comfyPage.nodeOps.getNodeRefById('9')
+        await saveNode.click('title')
+        const subgraphNode = await saveNode.convertToSubgraph()
+        await comfyPage.nextFrame()
+
+        // SaveImage is a recommended node, so filename_prefix should be promoted
+        const nodeId = String(subgraphNode.id)
+        const promotedNames = await getPromotedWidgetNames(comfyPage, nodeId)
+        expect(promotedNames.length).toBeGreaterThan(0)
+
+        const widgetCount = await getPromotedWidgetCount(comfyPage, nodeId)
+        expect(widgetCount).toBeGreaterThan(0)
+      })
+    })
+
+    test.describe('Legacy And Round-Trip Coverage', () => {
+      test('Legacy -1 proxyWidgets entries are hydrated to concrete interior node IDs', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-compressed-target-slot'
+        )
+        await comfyPage.nextFrame()
+
+        const promotedWidgets = await getPromotedWidgets(comfyPage, '2')
+        expect(promotedWidgets.length).toBeGreaterThan(0)
+        expect(
+          promotedWidgets.some(([interiorNodeId]) => interiorNodeId === '-1')
+        ).toBe(false)
+        expect(
+          promotedWidgets.some(
+            ([interiorNodeId, widgetName]) =>
+              interiorNodeId !== '-1' && widgetName === 'batch_size'
+          )
+        ).toBe(true)
+      })
+
+      test('Promoted widgets survive serialize -> loadGraphData round-trip', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.nextFrame()
+
+        const beforePromoted = await getPromotedWidgetNames(comfyPage, '11')
+        expect(beforePromoted).toContain('text')
+
+        const serialized = await comfyPage.page.evaluate(() => {
+          return window.app!.graph!.serialize()
+        })
+
+        await comfyPage.page.evaluate((workflow: ComfyWorkflowJSON) => {
+          return window.app!.loadGraphData(workflow)
+        }, serialized as ComfyWorkflowJSON)
+        await comfyPage.nextFrame()
+
+        const afterPromoted = await getPromotedWidgetNames(comfyPage, '11')
+        expect(afterPromoted).toContain('text')
+
+        const widgetCount = await getPromotedWidgetCount(comfyPage, '11')
+        expect(widgetCount).toBeGreaterThan(0)
+      })
+
+      test('Cloning a subgraph node keeps promoted widget entries on original and clone', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.nextFrame()
+
+        const originalNode = await comfyPage.nodeOps.getNodeRefById('11')
+        const originalPos = await originalNode.getPosition()
+
+        await comfyPage.page.mouse.move(originalPos.x + 16, originalPos.y + 16)
+        await comfyPage.page.keyboard.down('Alt')
+        await comfyPage.page.mouse.down()
+        await comfyPage.nextFrame()
+        await comfyPage.page.mouse.move(originalPos.x + 72, originalPos.y + 72)
+        await comfyPage.page.mouse.up()
+        await comfyPage.page.keyboard.up('Alt')
+        await comfyPage.nextFrame()
+
+        const subgraphNodeIds = await comfyPage.page.evaluate(() => {
+          const graph = window.app!.canvas.graph!
+          return graph.nodes
+            .filter(
+              (n) =>
+                typeof n.isSubgraphNode === 'function' && n.isSubgraphNode()
+            )
+            .map((n) => String(n.id))
+        })
+
+        expect(subgraphNodeIds.length).toBeGreaterThan(1)
+        for (const nodeId of subgraphNodeIds) {
+          const promotedWidgets = await getPromotedWidgets(comfyPage, nodeId)
+          expect(promotedWidgets.length).toBeGreaterThan(0)
+          expect(
+            promotedWidgets.some(([, widgetName]) => widgetName === 'text')
+          ).toBe(true)
+        }
+      })
+    })
+
+    test.describe('Vue Mode - Promoted Preview Content', () => {
+      test.beforeEach(async ({ comfyPage }) => {
+        await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', true)
+      })
+
+      test('SubgraphNode with preview node shows hasCustomContent area in Vue mode', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-preview-node'
+        )
+        await comfyPage.vueNodes.waitForNodes()
+
+        const subgraphVueNode = comfyPage.vueNodes.getNodeLocator('5')
+        await expect(subgraphVueNode).toBeVisible()
+
+        // The node body should exist
+        const nodeBody = subgraphVueNode.locator('[data-testid="node-body-5"]')
+        await expect(nodeBody).toBeVisible()
+      })
+    })
+
+    test.describe('Promotion Cleanup', () => {
+      test('Removing subgraph node clears promotion store entries', async ({
+        comfyPage
+      }) => {
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+        await comfyPage.nextFrame()
+
+        // Verify promotions exist
+        const namesBefore = await getPromotedWidgetNames(comfyPage, '11')
+        expect(namesBefore.length).toBeGreaterThan(0)
+
+        // Delete the subgraph node
+        const subgraphNode = await comfyPage.nodeOps.getNodeRefById('11')
+        await subgraphNode.click('title')
+        await comfyPage.page.keyboard.press('Delete')
+        await comfyPage.nextFrame()
+
+        // Node no longer exists, so promoted widgets should be gone
+        const nodeExists = await comfyPage.page.evaluate(() => {
+          return !!window.app!.canvas.graph!.getNodeById('11')
+        })
+        expect(nodeExists).toBe(false)
+      })
+
+      test('Removing I/O slot removes associated promoted widget', async ({
+        comfyPage
+      }) => {
+        await comfyPage.settings.setSetting('Comfy.UseNewMenu', 'Top')
+
+        await comfyPage.workflow.loadWorkflow(
+          'subgraphs/subgraph-with-promoted-text-widget'
+        )
+
+        const initialWidgetCount = await getPromotedWidgetCount(comfyPage, '11')
+        expect(initialWidgetCount).toBeGreaterThan(0)
+
+        // Navigate into subgraph
+        const subgraphNode = await comfyPage.nodeOps.getNodeRefById('11')
+        await subgraphNode.navigateIntoSubgraph()
+
+        // Remove the text input slot
+        await comfyPage.subgraph.rightClickInputSlot('text')
+        await comfyPage.contextMenu.clickLitegraphMenuItem('Remove Slot')
+        await comfyPage.nextFrame()
+
+        // Navigate back via breadcrumb
+        await comfyPage.page
+          .getByTestId(TestIds.breadcrumb.subgraph)
+          .waitFor({ state: 'visible', timeout: 5000 })
+        const homeBreadcrumb = comfyPage.page.getByRole('link', {
+          name: 'subgraph-with-promoted-text-widget'
+        })
+        await homeBreadcrumb.waitFor({ state: 'visible' })
+        await homeBreadcrumb.click()
+        await comfyPage.nextFrame()
+
+        // Widget count should be reduced
+        const finalWidgetCount = await getPromotedWidgetCount(comfyPage, '11')
+        expect(finalWidgetCount).toBeLessThan(initialWidgetCount)
+      })
+    })
+  }
+)

browser_tests/tests/vueNodes/interactions/node/imagePreview.spec.ts

@@ -2,15 +2,20 @@ import { expect } from '@playwright/test'
 
 import type { ComfyPage } from '../../../../fixtures/ComfyPage'
 import { comfyPageFixture as test } from '../../../../fixtures/ComfyPage'
+import {
+  getPromotedWidgetNames,
+  getPromotedWidgetCountByName
+} from '../../../../helpers/promotedWidgets'
 
 test.describe('Vue Nodes Image Preview', () => {
   test.beforeEach(async ({ comfyPage }) => {
     await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', true)
-    await comfyPage.workflow.loadWorkflow('widgets/load_image_widget')
-    await comfyPage.vueNodes.waitForNodes()
   })
 
   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]
@@ -25,16 +30,19 @@ test.describe('Vue Nodes Image Preview', () => {
     await expect(imagePreview.locator('img')).toBeVisible()
     await expect(imagePreview).toContainText('x')
 
-    return imagePreview
+    return {
+      imagePreview,
+      nodeId: String(loadImageNode.id)
+    }
   }
 
   // TODO(#8143): Re-enable after image preview sync is working in CI
   test.fixme('opens mask editor from image preview button', async ({
     comfyPage
   }) => {
-    const imagePreview = await loadImageOnNode(comfyPage)
+    const { imagePreview } = await loadImageOnNode(comfyPage)
 
-    await imagePreview.locator('[role="img"]').hover()
+    await imagePreview.locator('[role="img"]').focus()
     await comfyPage.page.getByLabel('Edit or mask image').click()
 
     await expect(comfyPage.page.locator('.mask-editor-dialog')).toBeVisible()
@@ -42,9 +50,11 @@ test.describe('Vue Nodes Image Preview', () => {
 
   // TODO(#8143): Re-enable after image preview sync is working in CI
   test.fixme('shows image context menu options', async ({ comfyPage }) => {
-    await loadImageOnNode(comfyPage)
+    const { nodeId } = await loadImageOnNode(comfyPage)
 
-    const nodeHeader = comfyPage.vueNodes.getNodeByTitle('Load Image')
+    const nodeHeader = comfyPage.vueNodes
+      .getNodeLocator(nodeId)
+      .locator('.lg-node-header')
     await nodeHeader.click()
     await nodeHeader.click({ button: 'right' })
 
@@ -55,4 +65,69 @@ test.describe('Vue Nodes Image Preview', () => {
     await expect(contextMenu.getByText('Save Image')).toBeVisible()
     await expect(contextMenu.getByText('Open in Mask Editor')).toBeVisible()
   })
+
+  test(
+    'renders promoted image previews for each subgraph node',
+    { tag: '@screenshot' },
+    async ({ comfyPage }) => {
+      await comfyPage.workflow.loadWorkflow(
+        'subgraphs/subgraph-with-multiple-promoted-previews'
+      )
+      await comfyPage.vueNodes.waitForNodes()
+
+      const firstSubgraphNode = comfyPage.vueNodes.getNodeLocator('7')
+      const secondSubgraphNode = comfyPage.vueNodes.getNodeLocator('8')
+
+      await expect(firstSubgraphNode).toBeVisible()
+      await expect(secondSubgraphNode).toBeVisible()
+
+      const firstPromotedWidgets = await getPromotedWidgetNames(comfyPage, '7')
+      const secondPromotedWidgets = await getPromotedWidgetNames(comfyPage, '8')
+      expect(firstPromotedWidgets).toEqual([
+        '$$canvas-image-preview',
+        '$$canvas-image-preview'
+      ])
+      expect(secondPromotedWidgets).toEqual(['$$canvas-image-preview'])
+
+      expect(
+        await getPromotedWidgetCountByName(
+          comfyPage,
+          '7',
+          '$$canvas-image-preview'
+        )
+      ).toBe(2)
+      expect(
+        await getPromotedWidgetCountByName(
+          comfyPage,
+          '8',
+          '$$canvas-image-preview'
+        )
+      ).toBe(1)
+
+      await expect(
+        firstSubgraphNode.locator('.lg-node-widgets')
+      ).not.toContainText('$$canvas-image-preview')
+      await expect(
+        secondSubgraphNode.locator('.lg-node-widgets')
+      ).not.toContainText('$$canvas-image-preview')
+
+      await comfyPage.command.executeCommand('Comfy.Canvas.FitView')
+      await comfyPage.command.executeCommand('Comfy.QueuePrompt')
+
+      const firstPreviewImages = firstSubgraphNode.locator('.image-preview img')
+      const secondPreviewImages =
+        secondSubgraphNode.locator('.image-preview img')
+
+      await expect(firstPreviewImages).toHaveCount(2, { timeout: 30_000 })
+      await expect(secondPreviewImages).toHaveCount(1, { timeout: 30_000 })
+
+      await expect(firstPreviewImages.first()).toBeVisible({ timeout: 30_000 })
+      await expect(firstPreviewImages.nth(1)).toBeVisible({ timeout: 30_000 })
+      await expect(secondPreviewImages.first()).toBeVisible({ timeout: 30_000 })
+
+      await expect(comfyPage.canvas).toHaveScreenshot(
+        'vue-node-multiple-promoted-previews.png'
+      )
+    }
+  )
 })

browser_tests/tests/vueNodes/widgets/load/uploadWidgets.spec.ts

@@ -9,17 +9,20 @@ test.describe('Vue Upload Widgets', () => {
     await comfyPage.vueNodes.waitForNodes()
   })
 
-  test(
-    'should hide canvas-only upload buttons',
-    { tag: '@screenshot' },
-    async ({ comfyPage }) => {
-      await comfyPage.setup()
-      await comfyPage.workflow.loadWorkflow('widgets/all_load_widgets')
-      await comfyPage.vueNodes.waitForNodes()
+  test('should hide canvas-only upload buttons', async ({ comfyPage }) => {
+    await comfyPage.setup()
+    await comfyPage.workflow.loadWorkflow('widgets/all_load_widgets')
+    await comfyPage.vueNodes.waitForNodes()
 
-      await expect(comfyPage.canvas).toHaveScreenshot(
-        'vue-nodes-upload-widgets.png'
-      )
-    }
-  )
+    await expect(
+      comfyPage.page.getByText('choose file to upload', { exact: true })
+    ).not.toBeVisible()
+
+    await expect
+      .poll(() => comfyPage.page.getByText('Error loading image').count())
+      .toBeGreaterThan(0)
+    await expect
+      .poll(() => comfyPage.page.getByText('Error loading video').count())
+      .toBeGreaterThan(0)
+  })
 })

docs/WIDGET_SERIALIZATION.md

@@ -24,6 +24,28 @@ These correspond to the two data formats in `ComfyMetadata` embedded in output f
 - `LGraphNode.serialize()` only writes `widgets_values` if `this.widgets` is truthy. Nodes that create widgets dynamically (like `PrimitiveNode`) will have no `widgets_values` in serialized output if serialized before widget creation — even if `this.widgets_values` exists on the instance from a prior `configure()` call.
 - `widget.options.serialize` is typed as `IWidgetOptions.serialize` — both properties share the name `serialize` but live at different levels of the widget object.
 
+## PrimitiveNode and copy/paste
+
+`PrimitiveNode` creates widgets dynamically on connection — it starts as an empty polymorphic node and morphs to match its target widget in `_onFirstConnection()`. This interacts badly with the copy/paste pipeline.
+
+### The clone→serialize gap
+
+`LGraphCanvas._serializeItems()` copies nodes via `item.clone()?.serialize()` (line 3911). For PrimitiveNode this fails:
+
+1. `clone()` calls `this.serialize()` on the **original** node (which has widgets, so `widgets_values` is captured correctly).
+2. `clone()` creates a **fresh** PrimitiveNode via `LiteGraph.createNode()` and calls `configure(data)` on it — this stores `widgets_values` on the instance.
+3. But the fresh PrimitiveNode has no `this.widgets` (widgets are created only on connection), so when `serialize()` is called on the clone, `LGraphNode.serialize()` skips the `widgets_values` block entirely (line 964: `if (widgets && this.serialize_widgets)`).
+
+Result: `widgets_values` is silently dropped from the clipboard data.
+
+### Why seed survives but control_after_generate doesn't
+
+When the pasted PrimitiveNode reconnects to the pasted target node, `_createWidget()` copies `theirWidget.value` from the target (line 254). This restores the **primary** widget value (e.g., `seed`).
+
+But `control_after_generate` is a **secondary** widget created by `addValueControlWidgets()`, which reads its initial value from `this.widgets_values?.[1]` (line 263). That value was lost during clone→serialize, so it falls back to `'fixed'` (line 265).
+
+See [ADR-0006](adr/0006-primitive-node-copy-paste-lifecycle.md) for proposed fixes and design tradeoffs.
+
 ## Code references
 
 - `widget.serialize` checked: `src/lib/litegraph/src/LGraphNode.ts` serialize() and configure()
@@ -31,3 +53,6 @@ These correspond to the two data formats in `ComfyMetadata` embedded in output f
 - `widget.options.serialize` set: `src/scripts/widgets.ts` addValueControlWidgets()
 - `widget.serialize` set: `src/composables/node/useNodeImage.ts`, `src/extensions/core/previewAny.ts`, etc.
 - Metadata types: `src/types/metadataTypes.ts`
+- PrimitiveNode: `src/extensions/core/widgetInputs.ts`
+- Copy/paste serialization: `src/lib/litegraph/src/LGraphCanvas.ts` `_serializeItems()`
+- Clone: `src/lib/litegraph/src/LGraphNode.ts` `clone()`

docs/adr/0006-primitive-node-copy-paste-lifecycle.md

@@ -0,0 +1,45 @@
+# 6. PrimitiveNode Copy/Paste Lifecycle
+
+Date: 2026-02-22
+
+## Status
+
+Proposed
+
+## Context
+
+PrimitiveNode creates widgets dynamically on connection. When copied, the clone has no `this.widgets`, so `LGraphNode.serialize()` drops `widgets_values` from the clipboard data. This causes secondary widget values (e.g., `control_after_generate`) to be lost on paste. See [WIDGET_SERIALIZATION.md](../WIDGET_SERIALIZATION.md#primitiveno-and-copypaste) for the full mechanism.
+
+Related: [#1757](https://github.com/Comfy-Org/ComfyUI_frontend/issues/1757), [#8938](https://github.com/Comfy-Org/ComfyUI_frontend/pull/8938)
+
+## Options
+
+### A. Minimal fix: override `serialize()` on PrimitiveNode
+
+Override `serialize()` to fall back to `this.widgets_values` (set during `configure()`) when the base implementation omits it due to missing `this.widgets`.
+
+- **Pro**: No change to connection lifecycle semantics. Lowest risk.
+- **Pro**: Doesn't affect workflow save/load (which already works via `onAfterGraphConfigured`).
+- **Con**: Doesn't address the deeper design issue — primitives are still empty on copy.
+
+### B. Clone-configured-instance lifecycle
+
+On copy, the primitive is a clone of the configured instance (with widgets intact). On disconnect or paste without connections, it returns to empty state.
+
+- **Pro**: Copy→serialize captures `widgets_values` correctly. Matches OOP expectations.
+- **Pro**: Secondary widget state survives round-trips without special-casing.
+- **Con**: `input.widget[CONFIG]` allows extensions to make PrimitiveNode create a _different_ widget than the target. Widget config is derived at connection time, not stored, so cloning the configured state may not be faithful.
+- **Con**: Deserialization ordering — `configure()` runs before links are restored. PrimitiveNode needs links to know what widgets to create. `onAfterGraphConfigured()` handles this for workflow load, but copy/paste uses a different code path.
+- **Con**: Higher risk of regressions in extension compatibility.
+
+### C. Projection model (like Subgraph widgets)
+
+Primitives act as a synchronization mechanism — no own state, just a projection of the target widget's resolved value.
+
+- **Pro**: Cleanest conceptual model. Eliminates state duplication.
+- **Con**: Primitives can connect to multiple targets. Projection with multiple targets is ambiguous.
+- **Con**: Major architectural change with broad impact.
+
+## Decision
+
+Pending. Option A is the most pragmatic first step. Option B can be revisited after Option A ships and stabilizes.

docs/guidance/playwright.md

@@ -57,7 +57,7 @@ settings: testData as any
 // Don't add test settings to src/schemas/apiSchema.ts
 
 // ❌ Don't chain through unknown to bypass types
-data as unknown as SomeType // Avoid; prefer explicit typings or helpers
+data as unknown as SomeType // Avoid; prefer `as Partial<SomeType> as SomeType` or explicit typings
 ```
 
 ### Accessing Internal State

docs/guidance/typescript.md

@@ -36,6 +36,25 @@ When you must handle uncertain types, prefer these approaches in order:
 - Don't expose internal implementation types (e.g., Pinia store internals)
 - Reactive refs (`ComputedRef<T>`) should be unwrapped before exposing
 
+## Avoiding Circular Dependencies
+
+Extract type guards and their associated interfaces into **leaf modules** — files with only `import type` statements. This keeps them safe to import from anywhere without pulling in heavy transitive dependencies.
+
+```typescript
+// ✅ myTypes.ts — leaf module (only type imports)
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+
+export interface MyView extends IBaseWidget {
+  /* ... */
+}
+export function isMyView(w: IBaseWidget): w is MyView {
+  return 'myProp' in w
+}
+
+// ❌ myView.ts — heavy module (runtime imports from stores, utils, etc.)
+//    Importing the type guard from here drags in the entire dependency tree.
+```
+
 ## Utility Libraries
 
 - Use `es-toolkit` for utility functions (not lodash)

lint-staged.config.ts

@@ -6,10 +6,19 @@ export default {
 
   './**/*.js': (stagedFiles: string[]) => formatAndEslint(stagedFiles),
 
-  './**/*.{ts,tsx,vue,mts}': (stagedFiles: string[]) => [
-    ...formatAndEslint(stagedFiles),
-    'pnpm typecheck'
-  ]
+  './**/*.{ts,tsx,vue,mts}': (stagedFiles: string[]) => {
+    const commands = [...formatAndEslint(stagedFiles), 'pnpm typecheck']
+
+    const hasBrowserTestsChanges = stagedFiles
+      .map((f) => path.relative(process.cwd(), f).replace(/\\/g, '/'))
+      .some((f) => f.startsWith('browser_tests/'))
+
+    if (hasBrowserTestsChanges) {
+      commands.push('pnpm typecheck:browser')
+    }
+
+    return commands
+  }
 }
 
 function formatAndEslint(fileNames: string[]) {

packages/design-system/src/css/style.css

@@ -99,6 +99,10 @@
   --color-magenta-300: #ceaac9;
   --color-magenta-700: #6a246a;
 
+  --color-ocean-300: #badde8;
+  --color-ocean-600: #2f687a;
+  --color-ocean-900: #253236;
+
   --color-danger-100: #c02323;
   --color-danger-200: #d62952;
 
@@ -113,6 +117,7 @@
   --color-interface-panel-job-progress-secondary: var(
     --color-alpha-azure-600-30
   );
+  --color-interface-panel-job-progress-border: var(--base-foreground);
 
   --color-blue-selection: rgb(from var(--color-azure-600) r g b / 0.3);
   --color-node-hover-100: rgb(from var(--color-charcoal-800) r g b/ 0.15);
@@ -154,6 +159,7 @@
   --comfy-menu-bg: #353535;
   --comfy-menu-secondary-bg: #292929;
   --comfy-topbar-height: 2.5rem;
+  --workflow-tabs-height: 2.375rem;
   --comfy-input-bg: #222;
   --input-text: #ddd;
   --descrip-text: #999;
@@ -218,6 +224,10 @@
   --interface-panel-surface: var(--color-white);
   --interface-stroke: var(--color-smoke-300);
 
+  --interface-builder-mode-background: var(--color-ocean-300);
+  --interface-builder-mode-button-background: var(--color-ocean-600);
+  --interface-builder-mode-button-foreground: var(--color-white);
+
   --nav-background: var(--color-white);
 
   --node-border: var(--color-smoke-300);
@@ -377,6 +387,10 @@
   --interface-panel-surface: var(--color-charcoal-800);
   --interface-stroke: var(--color-charcoal-400);
 
+  --interface-builder-mode-background: var(--color-ocean-900);
+  --interface-builder-mode-button-background: var(--color-ocean-600);
+  --interface-builder-mode-button-foreground: var(--color-white);
+
   --nav-background: var(--color-charcoal-800);
 
   --node-border: var(--color-charcoal-500);
@@ -412,6 +426,7 @@
   --color-interface-panel-job-progress-secondary: var(
     --color-alpha-azure-600-30
   );
+  --color-interface-panel-job-progress-border: var(--base-foreground);
 
   --text-secondary: var(--color-slate-100);
   --text-primary: var(--color-white);
@@ -510,6 +525,15 @@
   --color-comfy-menu-bg: var(--comfy-menu-bg);
   --color-comfy-menu-secondary: var(--comfy-menu-secondary-bg);
 
+  --color-interface-builder-mode-background: var(
+    --interface-builder-mode-background
+  );
+  --color-interface-builder-mode-button-background: var(
+    --interface-builder-mode-button-background
+  );
+  --color-interface-builder-mode-button-foreground: var(
+    --interface-builder-mode-button-foreground
+  );
   --color-interface-stroke: var(--interface-stroke);
   --color-nav-background: var(--nav-background);
   --color-node-border: var(--node-border);
@@ -1877,3 +1901,22 @@ audio.comfy-audio.empty-audio-widget {
   margin-left: 15px;
 }
 /* ===================== End of Mask Editor Styles ===================== */
+
+/* ===================== Skeleton Shimmer ===================== */
+.skeleton-shimmer {
+  background:
+    linear-gradient(135deg, rgb(188 188 188 / 0.5) 0%, rgb(0 0 0 / 0.5) 100%) 0
+      0 / 200% 200%,
+    #000;
+  animation: skeleton-shimmer 2s ease-in-out infinite;
+}
+
+@keyframes skeleton-shimmer {
+  0%,
+  100% {
+    background-position: 100% 100%;
+  }
+  50% {
+    background-position: 0 0;
+  }
+}

scripts/collect-i18n-general.ts

@@ -11,7 +11,7 @@ import {
 } from '../packages/shared-frontend-utils/src/formatUtil'
 import { CORE_MENU_COMMANDS } from '../src/constants/coreMenuCommands'
 import { SERVER_CONFIG_ITEMS } from '../src/constants/serverConfig'
-import type { FormItem, SettingParams } from '../src/platform/settings/types'
+import type { SettingParams } from '../src/platform/settings/types'
 import type { ComfyCommandImpl } from '../src/stores/commandStore'
 
 const localePath = './src/locales/en/main.json'
@@ -123,8 +123,8 @@ test('collect-i18n-general', async ({ comfyPage }) => {
     SERVER_CONFIG_ITEMS.map((config) => [
       normalizeI18nKey(config.id),
       {
-        name: (config as unknown as FormItem).name,
-        tooltip: (config as unknown as FormItem).tooltip
+        name: config.name,
+        tooltip: config.tooltip
       }
     ])
   )

src/base/common/downloadUtil.test.ts

@@ -190,7 +190,7 @@ describe('downloadUtil', () => {
         ok: false,
         status: 404,
         blob: vi.fn()
-      } as unknown as Response)
+      } as Partial<Response> as Response)
 
       downloadFile(testUrl)
 

src/components/appMode/AppModeToolbar.vue

@@ -0,0 +1,126 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import WorkflowActionsDropdown from '@/components/common/WorkflowActionsDropdown.vue'
+import Button from '@/components/ui/button/Button.vue'
+import { useWorkflowTemplateSelectorDialog } from '@/composables/useWorkflowTemplateSelectorDialog'
+import { useCommandStore } from '@/stores/commandStore'
+import { useWorkspaceStore } from '@/stores/workspaceStore'
+import { cn } from '@/utils/tailwindUtil'
+import { useAppModeStore } from '@/stores/appModeStore'
+
+const { t } = useI18n()
+const commandStore = useCommandStore()
+const workspaceStore = useWorkspaceStore()
+const appModeStore = useAppModeStore()
+const tooltipOptions = { showDelay: 300, hideDelay: 300 }
+
+const isAssetsActive = computed(
+  () => workspaceStore.sidebarTab.activeSidebarTab?.id === 'assets'
+)
+const isWorkflowsActive = computed(
+  () => workspaceStore.sidebarTab.activeSidebarTab?.id === 'workflows'
+)
+
+function enterBuilderMode() {
+  appModeStore.setMode('builder:select')
+}
+
+function openAssets() {
+  void commandStore.execute('Workspace.ToggleSidebarTab.assets')
+}
+
+function showApps() {
+  void commandStore.execute('Workspace.ToggleSidebarTab.workflows')
+}
+
+function openTemplates() {
+  useWorkflowTemplateSelectorDialog().show('sidebar')
+}
+</script>
+
+<template>
+  <div class="flex flex-col gap-2 pointer-events-auto">
+    <WorkflowActionsDropdown source="app_mode_toolbar">
+      <template #button>
+        <Button
+          v-tooltip.right="{
+            value: t('sideToolbar.labels.menu'),
+            ...tooltipOptions
+          }"
+          variant="secondary"
+          size="unset"
+          :aria-label="t('sideToolbar.labels.menu')"
+          class="h-10 rounded-lg pl-3 pr-2 gap-1 data-[state=open]:bg-secondary-background-hover data-[state=open]:shadow-interface"
+        >
+          <i class="icon-[lucide--panels-top-left] size-4" />
+          <i class="icon-[lucide--chevron-down] size-4 text-muted-foreground" />
+        </Button>
+      </template>
+    </WorkflowActionsDropdown>
+
+    <Button
+      v-if="appModeStore.enableAppBuilder"
+      v-tooltip.right="{
+        value: t('linearMode.appModeToolbar.appBuilder'),
+        ...tooltipOptions
+      }"
+      variant="secondary"
+      size="unset"
+      :aria-label="t('linearMode.appModeToolbar.appBuilder')"
+      class="size-10 rounded-lg"
+      @click="enterBuilderMode"
+    >
+      <i class="icon-[lucide--hammer] size-4" />
+    </Button>
+
+    <div
+      class="flex flex-col w-10 rounded-lg bg-secondary-background overflow-hidden"
+    >
+      <Button
+        v-tooltip.right="{
+          value: t('sideToolbar.mediaAssets.title'),
+          ...tooltipOptions
+        }"
+        variant="textonly"
+        size="unset"
+        :aria-label="t('sideToolbar.mediaAssets.title')"
+        :class="
+          cn('size-10', isAssetsActive && 'bg-secondary-background-hover')
+        "
+        @click="openAssets"
+      >
+        <i class="icon-[comfy--image-ai-edit] size-4" />
+      </Button>
+      <Button
+        v-tooltip.right="{
+          value: t('linearMode.appModeToolbar.apps'),
+          ...tooltipOptions
+        }"
+        variant="textonly"
+        size="unset"
+        :aria-label="t('linearMode.appModeToolbar.apps')"
+        :class="
+          cn('size-10', isWorkflowsActive && 'bg-secondary-background-hover')
+        "
+        @click="showApps"
+      >
+        <i class="icon-[lucide--panels-top-left] size-4" />
+      </Button>
+      <Button
+        v-tooltip.right="{
+          value: t('sideToolbar.templates'),
+          ...tooltipOptions
+        }"
+        variant="textonly"
+        size="unset"
+        :aria-label="t('sideToolbar.templates')"
+        class="size-10"
+        @click="openTemplates"
+      >
+        <i class="icon-[comfy--template] size-4" />
+      </Button>
+    </div>
+  </div>
+</template>

src/components/breadcrumb/SubgraphBreadcrumb.vue

@@ -1,6 +1,7 @@
 <template>
   <div
-    class="subgraph-breadcrumb flex w-auto drop-shadow-[var(--interface-panel-drop-shadow)]"
+    data-testid="subgraph-breadcrumb"
+    class="subgraph-breadcrumb flex w-auto drop-shadow-(--interface-panel-drop-shadow) items-center"
     :class="{
       'subgraph-breadcrumb-collapse': collapseTabs,
       'subgraph-breadcrumb-overflow': overflowingTabs
@@ -13,17 +14,10 @@
       '--p-breadcrumb-icon-width': `${ICON_WIDTH}px`
     }"
   >
-    <Button
-      class="context-menu-button pointer-events-auto h-8 w-8 shrink-0 border border-transparent bg-transparent p-0 transition-all hover:rounded-lg hover:border-interface-stroke hover:bg-comfy-menu-bg"
-      icon="pi pi-bars"
-      text
-      severity="secondary"
-      size="small"
-      @click="handleMenuClick"
-    />
+    <WorkflowActionsDropdown source="breadcrumb_subgraph_menu_selected" />
     <Button
       v-if="isInSubgraph"
-      class="back-button pointer-events-auto h-8 w-8 shrink-0 border border-transparent bg-transparent p-0 transition-all hover:rounded-lg hover:border-interface-stroke hover:bg-comfy-menu-bg"
+      class="back-button pointer-events-auto h-8 w-8 shrink-0 border border-transparent bg-transparent p-0 ml-1.5 transition-all hover:rounded-lg hover:border-interface-stroke hover:bg-comfy-menu-bg"
       text
       severity="secondary"
       size="small"
@@ -41,7 +35,6 @@
     >
       <template #item="{ item }">
         <SubgraphBreadcrumbItem
-          :ref="(el) => setItemRef(item, el)"
           :item="item"
           :is-active="item.key === activeItemKey"
         />
@@ -60,6 +53,7 @@ import type { MenuItem } from 'primevue/menuitem'
 import { computed, onUpdated, ref, watch } from 'vue'
 
 import SubgraphBreadcrumbItem from '@/components/breadcrumb/SubgraphBreadcrumbItem.vue'
+import WorkflowActionsDropdown from '@/components/common/WorkflowActionsDropdown.vue'
 import { useOverflowObserver } from '@/composables/element/useOverflowObserver'
 import { useTelemetry } from '@/platform/telemetry'
 import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
@@ -77,12 +71,6 @@ const ICON_WIDTH = 20
 const workflowStore = useWorkflowStore()
 const navigationStore = useSubgraphNavigationStore()
 const breadcrumbRef = ref<InstanceType<typeof Breadcrumb>>()
-const rootItemRef = ref<InstanceType<typeof SubgraphBreadcrumbItem>>()
-const setItemRef = (item: MenuItem, el: unknown) => {
-  if (item.key === 'root') {
-    rootItemRef.value = el as InstanceType<typeof SubgraphBreadcrumbItem>
-  }
-}
 const workflowName = computed(() => workflowStore.activeWorkflow?.filename)
 const isBlueprint = computed(() =>
   useSubgraphStore().isSubgraphBlueprint(workflowStore.activeWorkflow)
@@ -136,13 +124,6 @@ const items = computed(() => {
 
 const activeItemKey = computed(() => items.value.at(-1)?.key)
 
-const handleMenuClick = (event: MouseEvent) => {
-  useTelemetry()?.trackUiButtonClicked({
-    button_id: 'breadcrumb_subgraph_menu_selected'
-  })
-  rootItemRef.value?.toggleMenu(event)
-}
-
 const handleBackClick = () => {
   void useCommandStore().execute('Comfy.Graph.ExitSubgraph')
 }

src/components/breadcrumb/SubgraphBreadcrumbItem.vue

@@ -185,14 +185,6 @@ const inputBlur = async (doRename: boolean) => {
 
   isEditing.value = false
 }
-
-const toggleMenu = (event: MouseEvent) => {
-  menu.value?.toggle(event)
-}
-
-defineExpose({
-  toggleMenu
-})
 </script>
 
 <style scoped>

src/components/builder/BuilderDialog.vue

@@ -0,0 +1,41 @@
+<template>
+  <div class="flex w-full min-w-96 flex-col rounded-2xl bg-base-background">
+    <!-- Header -->
+    <div
+      class="flex h-12 items-center justify-between border-b border-border-default px-4"
+    >
+      <div class="flex items-center gap-2">
+        <slot name="header-icon" />
+        <h2 class="m-0 text-sm font-normal text-base-foreground">
+          <slot name="title" />
+        </h2>
+      </div>
+      <Button
+        variant="muted-textonly"
+        class="-mr-1"
+        :aria-label="$t('g.close')"
+        @click="$emit('close')"
+      >
+        <i class="pi pi-times size-4" />
+      </Button>
+    </div>
+
+    <!-- Body -->
+    <div class="flex flex-col gap-4 px-4 py-4">
+      <slot />
+    </div>
+
+    <!-- Footer -->
+    <div class="flex items-center justify-end gap-4 px-4 py-4">
+      <slot name="footer" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import Button from '@/components/ui/button/Button.vue'
+
+defineEmits<{
+  close: []
+}>()
+</script>

src/components/builder/BuilderSaveDialogContent.vue

@@ -0,0 +1,117 @@
+<template>
+  <BuilderDialog @close="onClose">
+    <template #title>
+      {{ $t('builderToolbar.saveAs') }}
+    </template>
+
+    <!-- Filename -->
+    <div class="flex flex-col gap-2">
+      <label :for="inputId" class="text-sm text-muted-foreground">
+        {{ $t('builderToolbar.filename') }}
+      </label>
+      <input
+        :id="inputId"
+        v-model="filename"
+        autofocus
+        type="text"
+        class="flex h-10 min-h-8 items-center self-stretch rounded-lg border-none bg-secondary-background pl-4 text-sm text-base-foreground focus:outline-none"
+        @keydown.enter="filename.trim() && onSave(filename.trim(), openAsApp)"
+      />
+    </div>
+
+    <!-- Save as type -->
+    <div class="flex flex-col gap-2">
+      <label class="text-sm text-muted-foreground">
+        {{ $t('builderToolbar.saveAsLabel') }}
+      </label>
+      <div role="radiogroup" class="flex flex-col gap-2">
+        <Button
+          v-for="option in saveTypeOptions"
+          :key="option.value.toString()"
+          role="radio"
+          :aria-checked="openAsApp === option.value"
+          :class="
+            cn(
+              itemClasses,
+              openAsApp === option.value && 'bg-secondary-background'
+            )
+          "
+          variant="textonly"
+          @click="openAsApp = option.value"
+        >
+          <div
+            class="flex size-8 min-h-8 items-center justify-center rounded-lg bg-secondary-background-hover"
+          >
+            <i :class="cn(option.icon, 'size-4')" />
+          </div>
+          <div class="mx-2 flex flex-1 flex-col items-start">
+            <span class="text-sm font-medium text-base-foreground">
+              {{ option.title }}
+            </span>
+            <span class="text-xs text-muted-foreground">
+              {{ option.subtitle }}
+            </span>
+          </div>
+          <i
+            v-if="openAsApp === option.value"
+            class="icon-[lucide--check] size-4 text-base-foreground"
+          />
+        </Button>
+      </div>
+    </div>
+
+    <template #footer>
+      <Button variant="muted-textonly" size="lg" @click="onClose">
+        {{ $t('g.cancel') }}
+      </Button>
+      <Button
+        variant="secondary"
+        size="lg"
+        :disabled="!filename.trim()"
+        @click="onSave(filename.trim(), openAsApp)"
+      >
+        {{ $t('g.save') }}
+      </Button>
+    </template>
+  </BuilderDialog>
+</template>
+
+<script setup lang="ts">
+import { ref, useId } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import Button from '@/components/ui/button/Button.vue'
+import { cn } from '@/utils/tailwindUtil'
+
+import BuilderDialog from './BuilderDialog.vue'
+
+const { t } = useI18n()
+
+const { defaultFilename, onSave, onClose } = defineProps<{
+  defaultFilename: string
+  onSave: (filename: string, openAsApp: boolean) => void
+  onClose: () => void
+}>()
+
+const inputId = useId()
+const filename = ref(defaultFilename)
+const openAsApp = ref(true)
+
+const saveTypeOptions = [
+  {
+    value: true,
+    icon: 'icon-[lucide--app-window]',
+    title: t('builderToolbar.app'),
+    subtitle: t('builderToolbar.appDescription')
+  },
+  {
+    value: false,
+    icon: 'icon-[comfy--workflow]',
+    title: t('builderToolbar.nodeGraph'),
+    subtitle: t('builderToolbar.nodeGraphDescription')
+  }
+]
+
+const itemClasses =
+  'flex h-14 cursor-pointer items-center gap-2 self-stretch rounded-lg border-none bg-transparent py-2 pr-4 pl-2 text-base-foreground transition-colors hover:bg-secondary-background'
+</script>

src/components/builder/BuilderSaveSuccessDialogContent.vue

@@ -0,0 +1,51 @@
+<template>
+  <BuilderDialog @close="onClose">
+    <template #header-icon>
+      <i class="icon-[lucide--circle-check-big] size-4 text-green-500" />
+    </template>
+    <template #title>
+      {{ $t('builderToolbar.saveSuccess') }}
+    </template>
+
+    <p v-if="savedAsApp" class="m-0 text-sm text-muted-foreground">
+      {{ $t('builderToolbar.saveSuccessAppMessage', { name: workflowName }) }}
+    </p>
+    <p v-if="savedAsApp" class="m-0 text-sm text-muted-foreground">
+      {{ $t('builderToolbar.saveSuccessAppPrompt') }}
+    </p>
+    <p v-else class="m-0 text-sm text-muted-foreground">
+      {{ $t('builderToolbar.saveSuccessGraphMessage', { name: workflowName }) }}
+    </p>
+
+    <template #footer>
+      <Button
+        :variant="savedAsApp ? 'muted-textonly' : 'secondary'"
+        size="lg"
+        @click="onClose"
+      >
+        {{ $t('g.close') }}
+      </Button>
+      <Button
+        v-if="savedAsApp && onViewApp"
+        variant="primary"
+        size="lg"
+        @click="onViewApp"
+      >
+        {{ $t('builderToolbar.viewApp') }}
+      </Button>
+    </template>
+  </BuilderDialog>
+</template>
+
+<script setup lang="ts">
+import Button from '@/components/ui/button/Button.vue'
+
+import BuilderDialog from './BuilderDialog.vue'
+
+defineProps<{
+  workflowName: string
+  savedAsApp: boolean
+  onViewApp?: () => void
+  onClose: () => void
+}>()
+</script>

src/components/builder/BuilderToolbar.vue

@@ -0,0 +1,105 @@
+<template>
+  <nav
+    class="fixed top-[calc(var(--workflow-tabs-height)+var(--spacing)*1.5)] left-1/2 z-[1000] -translate-x-1/2"
+    :aria-label="t('builderToolbar.label')"
+  >
+    <div
+      class="inline-flex items-center gap-1 rounded-2xl border border-border-default bg-base-background p-2 shadow-interface"
+    >
+      <template
+        v-for="(step, index) in [selectStep, arrangeStep]"
+        :key="step.id"
+      >
+        <button
+          :class="
+            cn(
+              stepClasses,
+              activeStep === step.id && 'bg-interface-builder-mode-background',
+              activeStep !== step.id &&
+                'hover:bg-secondary-background bg-transparent'
+            )
+          "
+          :aria-current="activeStep === step.id ? 'step' : undefined"
+          @click="appModeStore.setMode(step.id)"
+        >
+          <StepBadge :step :index :model-value="activeStep" />
+          <StepLabel :step />
+        </button>
+
+        <div class="mx-1 h-px w-4 bg-border-default" role="separator" />
+      </template>
+
+      <!-- Save -->
+      <ConnectOutputPopover
+        v-if="!appModeStore.hasOutputs"
+        :is-select-active="activeStep === 'builder:select'"
+        @switch="appModeStore.setMode('builder:select')"
+      >
+        <button :class="cn(stepClasses, 'opacity-30 bg-transparent')">
+          <StepBadge :step="saveStep" :index="2" :model-value="activeStep" />
+          <StepLabel :step="saveStep" />
+        </button>
+      </ConnectOutputPopover>
+      <button
+        v-else
+        :class="
+          cn(
+            stepClasses,
+            activeStep === 'save'
+              ? 'bg-interface-builder-mode-background'
+              : 'hover:bg-secondary-background bg-transparent'
+          )
+        "
+        @click="appModeStore.setBuilderSaving(true)"
+      >
+        <StepBadge :step="saveStep" :index="2" :model-value="activeStep" />
+        <StepLabel :step="saveStep" />
+      </button>
+    </div>
+  </nav>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+import { useAppModeStore } from '@/stores/appModeStore'
+import type { AppMode } from '@/stores/appModeStore'
+import { cn } from '@/utils/tailwindUtil'
+
+import ConnectOutputPopover from './ConnectOutputPopover.vue'
+import StepBadge from './StepBadge.vue'
+import StepLabel from './StepLabel.vue'
+import type { BuilderToolbarStep } from './types'
+
+const { t } = useI18n()
+const appModeStore = useAppModeStore()
+
+const activeStep = computed(() =>
+  appModeStore.isBuilderSaving ? 'save' : appModeStore.mode
+)
+
+const stepClasses =
+  'inline-flex h-14 min-h-8 cursor-pointer items-center gap-3 rounded-lg py-2 pr-4 pl-2 transition-colors border-none'
+
+const selectStep: BuilderToolbarStep<AppMode> = {
+  id: 'builder:select',
+  title: t('builderToolbar.select'),
+  subtitle: t('builderToolbar.selectDescription'),
+  icon: 'icon-[lucide--mouse-pointer-click]'
+}
+
+const arrangeStep: BuilderToolbarStep<AppMode> = {
+  id: 'builder:arrange',
+  title: t('builderToolbar.arrange'),
+  subtitle: t('builderToolbar.arrangeDescription'),
+  icon: 'icon-[lucide--layout-panel-left]'
+}
+
+const saveStep: BuilderToolbarStep<'save'> = {
+  id: 'save',
+  title: t('builderToolbar.save'),
+  subtitle: t('builderToolbar.saveDescription'),
+  icon: 'icon-[lucide--cloud-upload]'
+}
+</script>

src/components/builder/ConnectOutputPopover.vue

@@ -0,0 +1,78 @@
+<template>
+  <PopoverRoot>
+    <PopoverTrigger as-child>
+      <slot />
+    </PopoverTrigger>
+    <PopoverContent
+      side="bottom"
+      :side-offset="8"
+      :collision-padding="10"
+      class="z-[1001] w-80 rounded-xl border border-border-default bg-base-background shadow-interface will-change-[transform,opacity] data-[state=open]:data-[side=bottom]:animate-slideUpAndFade"
+    >
+      <div class="flex h-12 items-center justify-between px-4">
+        <h3 class="text-sm font-medium text-base-foreground">
+          {{ t('builderToolbar.connectOutput') }}
+        </h3>
+        <PopoverClose
+          :aria-label="t('g.close')"
+          class="flex cursor-pointer appearance-none items-center justify-center border-none bg-transparent p-0 text-muted-foreground hover:text-base-foreground"
+        >
+          <i class="icon-[lucide--x] size-4" />
+        </PopoverClose>
+      </div>
+      <div class="border-t border-border-default" />
+      <p class="mt-3 px-4 text-xs text-muted-foreground leading-relaxed">
+        {{ t('builderToolbar.connectOutputBody1') }}
+      </p>
+      <p
+        v-if="!isSelectActive"
+        class="mt-2 px-4 text-xs text-muted-foreground leading-relaxed"
+      >
+        {{ t('builderToolbar.connectOutputBody2') }}
+      </p>
+      <div class="mt-4 flex items-center justify-end gap-2 px-4 pb-4">
+        <template v-if="isSelectActive">
+          <PopoverClose as-child>
+            <Button variant="secondary" size="md">
+              {{ t('g.ok') }}
+            </Button>
+          </PopoverClose>
+        </template>
+        <template v-else>
+          <PopoverClose as-child>
+            <Button variant="muted-textonly" size="md">
+              {{ t('g.cancel') }}
+            </Button>
+          </PopoverClose>
+          <PopoverClose as-child>
+            <Button variant="secondary" size="md" @click="emit('switch')">
+              {{ t('builderToolbar.switchToSelect') }}
+            </Button>
+          </PopoverClose>
+        </template>
+      </div>
+    </PopoverContent>
+  </PopoverRoot>
+</template>
+
+<script setup lang="ts">
+import {
+  PopoverClose,
+  PopoverContent,
+  PopoverRoot,
+  PopoverTrigger
+} from 'reka-ui'
+import { useI18n } from 'vue-i18n'
+
+import Button from '@/components/ui/button/Button.vue'
+
+const { isSelectActive = false } = defineProps<{
+  isSelectActive?: boolean
+}>()
+
+const { t } = useI18n()
+
+const emit = defineEmits<{
+  switch: []
+}>()
+</script>

src/components/builder/StepBadge.vue

@@ -0,0 +1,22 @@
+<template>
+  <div
+    class="flex size-10 shrink-0 items-center justify-center rounded-lg bg-interface-builder-mode-button-background text-interface-builder-mode-button-foreground"
+  >
+    <i v-if="modelValue === step.id" :class="cn(step.icon, 'size-5')" />
+    <span v-else class="text-sm font-bold">
+      {{ index + 1 }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { cn } from '@/utils/tailwindUtil'
+
+import type { BuilderToolbarStep } from './types'
+
+defineProps<{
+  step: BuilderToolbarStep
+  index: number
+  modelValue: string
+}>()
+</script>

src/components/builder/StepLabel.vue

@@ -0,0 +1,20 @@
+<template>
+  <div class="flex flex-col gap-0.5 text-left">
+    <span class="text-sm font-medium text-base-foreground">
+      {{ step.title }}
+    </span>
+    <span
+      class="hidden whitespace-nowrap text-xs text-muted-foreground sm:inline"
+    >
+      {{ step.subtitle }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { BuilderToolbarStep } from './types'
+
+const { step } = defineProps<{
+  step: BuilderToolbarStep
+}>()
+</script>

src/components/builder/types.ts

@@ -0,0 +1,6 @@
+export interface BuilderToolbarStep<T extends string = string> {
+  id: T
+  title: string
+  subtitle: string
+  icon: string
+}

src/components/builder/useBuilderSave.ts

@@ -0,0 +1,124 @@
+import { watch } from 'vue'
+
+import { useWorkflowService } from '@/platform/workflow/core/services/workflowService'
+import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
+import { useDialogService } from '@/services/dialogService'
+import { useAppModeStore } from '@/stores/appModeStore'
+import { useDialogStore } from '@/stores/dialogStore'
+
+import BuilderSaveDialogContent from './BuilderSaveDialogContent.vue'
+import BuilderSaveSuccessDialogContent from './BuilderSaveSuccessDialogContent.vue'
+
+const SAVE_DIALOG_KEY = 'builder-save'
+const SUCCESS_DIALOG_KEY = 'builder-save-success'
+
+export function useBuilderSave() {
+  const appModeStore = useAppModeStore()
+  const workflowStore = useWorkflowStore()
+  const workflowService = useWorkflowService()
+  const dialogService = useDialogService()
+  const dialogStore = useDialogStore()
+
+  watch(
+    () => appModeStore.isBuilderSaving,
+    (saving) => {
+      if (saving) void onBuilderSave()
+    }
+  )
+
+  async function onBuilderSave() {
+    const workflow = workflowStore.activeWorkflow
+    if (!workflow) {
+      resetSaving()
+      return
+    }
+
+    // TODO: Update this to show the save dialog if it is temp OR if the user has not saved app mode before.
+    // If they have saved app mode before, just save the workflow, but use the initial app mode state not current.
+
+    if (!workflow.isTemporary) {
+      try {
+        workflow.changeTracker?.checkState()
+        await workflowService.saveWorkflow(workflow)
+        showSuccessDialog(workflow.filename, appModeStore.isAppMode)
+      } catch {
+        resetSaving()
+      }
+      return
+    }
+
+    showSaveDialog(workflow.filename)
+  }
+
+  function showSaveDialog(defaultFilename: string) {
+    dialogService.showLayoutDialog({
+      key: SAVE_DIALOG_KEY,
+      component: BuilderSaveDialogContent,
+      props: {
+        defaultFilename,
+        onSave: handleSave,
+        onClose: handleCancelSave
+      },
+      dialogComponentProps: {
+        onClose: resetSaving
+      }
+    })
+  }
+
+  function handleCancelSave() {
+    closeSaveDialog()
+    resetSaving()
+  }
+
+  async function handleSave(filename: string, openAsApp: boolean) {
+    try {
+      const workflow = workflowStore.activeWorkflow
+      if (!workflow) return
+
+      const saved = await workflowService.saveWorkflowAs(workflow, {
+        filename,
+        openAsApp
+      })
+
+      if (!saved) return
+
+      closeSaveDialog()
+      showSuccessDialog(filename, openAsApp)
+    } catch {
+      closeSaveDialog()
+      resetSaving()
+    }
+  }
+
+  function showSuccessDialog(workflowName: string, savedAsApp: boolean) {
+    dialogService.showLayoutDialog({
+      key: SUCCESS_DIALOG_KEY,
+      component: BuilderSaveSuccessDialogContent,
+      props: {
+        workflowName,
+        savedAsApp,
+        onViewApp: () => {
+          appModeStore.setMode('app')
+          closeSuccessDialog()
+        },
+        onClose: closeSuccessDialog
+      },
+      dialogComponentProps: {
+        onClose: resetSaving
+      }
+    })
+  }
+
+  function closeSaveDialog() {
+    dialogStore.closeDialog({ key: SAVE_DIALOG_KEY })
+  }
+
+  function closeSuccessDialog() {
+    dialogStore.closeDialog({ key: SUCCESS_DIALOG_KEY })
+    resetSaving()
+  }
+
+  function resetSaving() {
+    appModeStore.setBuilderSaving(false)
+  }
+}

src/components/common/WorkflowActionsDropdown.vue

@@ -0,0 +1,77 @@
+<script setup lang="ts">
+import {
+  DropdownMenuContent,
+  DropdownMenuPortal,
+  DropdownMenuRoot,
+  DropdownMenuTrigger
+} from 'reka-ui'
+import { useI18n } from 'vue-i18n'
+
+import WorkflowActionsList from '@/components/common/WorkflowActionsList.vue'
+import Button from '@/components/ui/button/Button.vue'
+import { useWorkflowActionsMenu } from '@/composables/useWorkflowActionsMenu'
+import { useTelemetry } from '@/platform/telemetry'
+import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
+import { useCommandStore } from '@/stores/commandStore'
+
+const { source, align = 'start' } = defineProps<{
+  source: string
+  align?: 'start' | 'center' | 'end'
+}>()
+
+const { t } = useI18n()
+const canvasStore = useCanvasStore()
+
+const { menuItems } = useWorkflowActionsMenu(
+  () => useCommandStore().execute('Comfy.RenameWorkflow'),
+  { isRoot: true }
+)
+
+function handleOpen(open: boolean) {
+  if (open) {
+    useTelemetry()?.trackUiButtonClicked({
+      button_id: source
+    })
+  }
+}
+</script>
+
+<template>
+  <DropdownMenuRoot @update:open="handleOpen">
+    <DropdownMenuTrigger as-child>
+      <slot name="button">
+        <Button
+          v-tooltip="{
+            value: t('breadcrumbsMenu.workflowActions'),
+            showDelay: 300,
+            hideDelay: 300
+          }"
+          variant="secondary"
+          size="unset"
+          :aria-label="t('breadcrumbsMenu.workflowActions')"
+          class="h-10 rounded-lg pl-3 pr-2 pointer-events-auto gap-1 data-[state=open]:bg-secondary-background-hover data-[state=open]:shadow-interface"
+        >
+          <i
+            class="size-4"
+            :class="
+              canvasStore.linearMode
+                ? 'icon-[lucide--panels-top-left]'
+                : 'icon-[comfy--workflow]'
+            "
+          />
+          <i class="icon-[lucide--chevron-down] size-4 text-muted-foreground" />
+        </Button>
+      </slot>
+    </DropdownMenuTrigger>
+    <DropdownMenuPortal>
+      <DropdownMenuContent
+        :align
+        :side-offset="5"
+        :collision-padding="10"
+        class="z-1000 rounded-lg px-2 py-3 min-w-56 bg-base-background shadow-interface border border-border-subtle"
+      >
+        <WorkflowActionsList :items="menuItems" />
+      </DropdownMenuContent>
+    </DropdownMenuPortal>
+  </DropdownMenuRoot>
+</template>

src/components/common/WorkflowActionsList.test.ts

@@ -0,0 +1,81 @@
+import { shallowMount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+
+import WorkflowActionsList from '@/components/common/WorkflowActionsList.vue'
+import type {
+  WorkflowMenuAction,
+  WorkflowMenuItem
+} from '@/types/workflowMenuItem'
+
+function createWrapper(items: WorkflowMenuItem[]) {
+  return shallowMount(WorkflowActionsList, {
+    props: { items },
+    global: { renderStubDefaultSlot: true }
+  })
+}
+
+describe('WorkflowActionsList', () => {
+  it('renders action items with label and icon', () => {
+    const items: WorkflowMenuItem[] = [
+      { label: 'Save', icon: 'pi pi-save', command: vi.fn() }
+    ]
+
+    const wrapper = createWrapper(items)
+
+    expect(wrapper.text()).toContain('Save')
+    expect(wrapper.find('.pi-save').exists()).toBe(true)
+  })
+
+  it('renders separator items', () => {
+    const items: WorkflowMenuItem[] = [
+      { label: 'Before', icon: 'pi pi-a', command: vi.fn() },
+      { separator: true },
+      { label: 'After', icon: 'pi pi-b', command: vi.fn() }
+    ]
+
+    const wrapper = createWrapper(items)
+    const html = wrapper.html()
+
+    expect(html).toContain('dropdown-menu-separator-stub')
+    expect(wrapper.text()).toContain('Before')
+    expect(wrapper.text()).toContain('After')
+  })
+
+  it('dispatches command on select', async () => {
+    const command = vi.fn()
+    const items: WorkflowMenuItem[] = [
+      { label: 'Action', icon: 'pi pi-play', command }
+    ]
+
+    const wrapper = createWrapper(items)
+    const item = wrapper.findComponent({ name: 'DropdownMenuItem' })
+    await item.vm.$emit('select')
+
+    expect(command).toHaveBeenCalledOnce()
+  })
+
+  it('renders badge when present', () => {
+    const items: WorkflowMenuItem[] = [
+      {
+        label: 'New Feature',
+        icon: 'pi pi-star',
+        command: vi.fn(),
+        badge: 'NEW'
+      }
+    ]
+
+    const wrapper = createWrapper(items)
+
+    expect(wrapper.text()).toContain('NEW')
+  })
+
+  it('does not render badge when absent', () => {
+    const items: WorkflowMenuAction[] = [
+      { label: 'Plain', icon: 'pi pi-check', command: vi.fn() }
+    ]
+
+    const wrapper = createWrapper(items)
+
+    expect(wrapper.text()).not.toContain('NEW')
+  })
+})

src/components/common/WorkflowActionsList.vue

@@ -0,0 +1,53 @@
+<script setup lang="ts">
+import { DropdownMenuItem, DropdownMenuSeparator } from 'reka-ui'
+import type { Component } from 'vue'
+
+import OverlayIcon from '@/components/common/OverlayIcon.vue'
+import type { WorkflowMenuItem } from '@/types/workflowMenuItem'
+import { cn } from '@/utils/tailwindUtil'
+
+const {
+  items,
+  itemComponent = DropdownMenuItem,
+  separatorComponent = DropdownMenuSeparator
+} = defineProps<{
+  items: WorkflowMenuItem[]
+  itemComponent?: Component
+  separatorComponent?: Component
+}>()
+</script>
+
+<template>
+  <template v-for="(item, index) in items" :key="index">
+    <component
+      :is="separatorComponent"
+      v-if="item.separator"
+      class="border-b w-full border-border-subtle my-1"
+    />
+    <component
+      :is="itemComponent"
+      v-else
+      :disabled="item.disabled"
+      :class="
+        cn(
+          'flex min-h-6 p-2 items-center gap-2 self-stretch rounded-sm outline-none',
+          !item.disabled && item.command && 'cursor-pointer',
+          'data-[highlighted]:bg-secondary-background-hover',
+          !item.disabled && 'hover:bg-secondary-background-hover',
+          'data-[disabled]:opacity-50 data-[disabled]:cursor-default'
+        )
+      "
+      @select="() => item.command?.()"
+    >
+      <OverlayIcon v-if="item.overlayIcon" v-bind="item.overlayIcon" />
+      <i v-else-if="item.icon" :class="item.icon" />
+      <span class="flex-1">{{ item.label }}</span>
+      <span
+        v-if="item.badge"
+        class="rounded-full uppercase ml-3 flex items-center gap-1 bg-[var(--primary-background)] px-1.5 py-0.5 text-xxs text-base-foreground"
+      >
+        {{ item.badge }}
+      </span>
+    </component>
+  </template>
+</template>

src/components/dialog/content/MissingNodesContent.vue

@@ -1,5 +1,6 @@
 <template>
   <div
+    data-testid="missing-nodes-warning"
     class="comfy-missing-nodes flex w-[490px] flex-col border-t border-border-default"
     :class="isCloud ? 'border-b' : ''"
   >

src/components/graph/DomWidgets.test.ts

@@ -0,0 +1,209 @@
+import { mount } from '@vue/test-utils'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import DomWidgets from '@/components/graph/DomWidgets.vue'
+import { Rectangle } from '@/lib/litegraph/src/infrastructure/Rectangle'
+import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { LGraphCanvas } from '@/lib/litegraph/src/LGraphCanvas'
+import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
+import type { BaseDOMWidget } from '@/scripts/domWidget'
+import { useDomWidgetStore } from '@/stores/domWidgetStore'
+import { createTestingPinia } from '@pinia/testing'
+
+type TestWidget = BaseDOMWidget<object | string>
+
+function createNode(
+  graph: LGraph,
+  id: number,
+  title: string,
+  pos: [number, number]
+) {
+  const node = new LGraphNode(title)
+  node.id = id
+  node.pos = [...pos]
+  node.size = [240, 120]
+  graph.add(node)
+  return node
+}
+
+function createWidget(id: string, node: LGraphNode, y = 12): TestWidget {
+  return {
+    id,
+    node,
+    name: 'test_widget',
+    type: 'custom',
+    value: '',
+    options: {},
+    y,
+    width: 120,
+    computedHeight: 40,
+    margin: 10,
+    isVisible: () => true
+  } as unknown as TestWidget
+}
+
+function createCanvas(graph: LGraph): LGraphCanvas {
+  return {
+    graph,
+    low_quality: false,
+    read_only: false,
+    isNodeVisible: vi.fn(() => true)
+  } as unknown as LGraphCanvas
+}
+
+function drawFrame(canvas: LGraphCanvas) {
+  canvas.onDrawForeground?.({} as CanvasRenderingContext2D, new Rectangle())
+}
+
+describe('DomWidgets transition grace characterization', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  it('applies transition grace for exactly one frame when override exists but is not active', () => {
+    const canvasStore = useCanvasStore()
+    const domWidgetStore = useDomWidgetStore()
+
+    const graphA = new LGraph()
+    const graphB = new LGraph()
+    const interiorNode = createNode(graphA, 1, 'interior', [100, 200])
+    const overrideNode = createNode(graphB, 2, 'override', [600, 700])
+
+    const widget = createWidget('widget-transition', interiorNode, 14)
+    const overrideWidget = createWidget('override-widget', overrideNode, 22)
+
+    domWidgetStore.registerWidget(widget)
+    domWidgetStore.setPositionOverride(widget.id, {
+      node: overrideNode,
+      widget: overrideWidget
+    })
+    domWidgetStore.deactivateWidget(widget.id)
+
+    const widgetState = domWidgetStore.widgetStates.get(widget.id)
+    if (!widgetState) throw new Error('Widget state not registered')
+    widgetState.visible = true
+    widgetState.pos = [321, 654]
+
+    const canvas = createCanvas(graphA)
+    canvasStore.canvas = canvas
+
+    mount(DomWidgets, {
+      global: {
+        stubs: {
+          DomWidget: true
+        }
+      }
+    })
+
+    drawFrame(canvas)
+    expect(widgetState.visible).toBe(true)
+    expect(widgetState.pos).toEqual([321, 654])
+
+    drawFrame(canvas)
+    expect(widgetState.visible).toBe(false)
+  })
+
+  it('uses override positioning while override node is in current graph even when widget is inactive', () => {
+    const canvasStore = useCanvasStore()
+    const domWidgetStore = useDomWidgetStore()
+
+    const graphA = new LGraph()
+    const graphB = new LGraph()
+    const interiorNode = createNode(graphA, 1, 'interior', [10, 20])
+    const overrideNode = createNode(graphB, 2, 'override', [300, 400])
+
+    const widget = createWidget('widget-override-active', interiorNode, 8)
+    const overrideWidget = createWidget(
+      'override-position-source',
+      overrideNode,
+      18
+    )
+
+    domWidgetStore.registerWidget(widget)
+    domWidgetStore.setPositionOverride(widget.id, {
+      node: overrideNode,
+      widget: overrideWidget
+    })
+    domWidgetStore.deactivateWidget(widget.id)
+
+    const widgetState = domWidgetStore.widgetStates.get(widget.id)
+    if (!widgetState) throw new Error('Widget state not registered')
+
+    const canvas = createCanvas(graphB)
+    canvasStore.canvas = canvas
+
+    mount(DomWidgets, {
+      global: {
+        stubs: {
+          DomWidget: true
+        }
+      }
+    })
+
+    drawFrame(canvas)
+
+    expect(widgetState.visible).toBe(true)
+    expect(widgetState.pos).toEqual([310, 428])
+  })
+
+  it('cleans orphaned transition-grace ids after widget removal', () => {
+    const canvasStore = useCanvasStore()
+    const domWidgetStore = useDomWidgetStore()
+
+    const graphA = new LGraph()
+    const graphB = new LGraph()
+    const interiorNode = createNode(graphA, 1, 'interior', [0, 0])
+    const overrideNode = createNode(graphB, 2, 'override', [200, 200])
+
+    const canvas = createCanvas(graphA)
+    canvasStore.canvas = canvas
+
+    mount(DomWidgets, {
+      global: {
+        stubs: {
+          DomWidget: true
+        }
+      }
+    })
+
+    const oldWidget = createWidget('shared-widget-id', interiorNode, 10)
+    const overrideWidget = createWidget(
+      'shared-override-widget',
+      overrideNode,
+      14
+    )
+
+    domWidgetStore.registerWidget(oldWidget)
+    domWidgetStore.setPositionOverride(oldWidget.id, {
+      node: overrideNode,
+      widget: overrideWidget
+    })
+    domWidgetStore.deactivateWidget(oldWidget.id)
+
+    drawFrame(canvas)
+    domWidgetStore.unregisterWidget(oldWidget.id)
+
+    drawFrame(canvas)
+
+    const replacementWidget = createWidget('shared-widget-id', interiorNode, 10)
+    domWidgetStore.registerWidget(replacementWidget)
+    domWidgetStore.setPositionOverride(replacementWidget.id, {
+      node: overrideNode,
+      widget: overrideWidget
+    })
+    domWidgetStore.deactivateWidget(replacementWidget.id)
+
+    const replacementState = domWidgetStore.widgetStates.get(
+      replacementWidget.id
+    )
+    if (!replacementState) throw new Error('Replacement widget missing state')
+    replacementState.visible = true
+    replacementState.pos = [999, 999]
+
+    drawFrame(canvas)
+
+    expect(replacementState.visible).toBe(true)
+    expect(replacementState.pos).toEqual([999, 999])
+  })
+})

src/components/graph/DomWidgets.vue

@@ -15,11 +15,13 @@ import { whenever } from '@vueuse/core'
 import { computed } from 'vue'
 
 import DomWidget from '@/components/graph/widgets/DomWidget.vue'
+import { getDomWidgetZIndex } from '@/components/graph/widgets/domWidgetZIndex'
 import { useChainCallback } from '@/composables/functional/useChainCallback'
 import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
 import { useDomWidgetStore } from '@/stores/domWidgetStore'
 
 const domWidgetStore = useDomWidgetStore()
+const overrideTransitionGrace = new Set<string>()
 
 const widgetStates = computed(() => [...domWidgetStore.widgetStates.values()])
 
@@ -29,37 +31,76 @@ const updateWidgets = () => {
 
   const lowQuality = lgCanvas.low_quality
   const currentGraph = lgCanvas.graph
+  const seenWidgetIds = new Set<string>()
 
   for (const widgetState of widgetStates.value) {
     const widget = widgetState.widget
+    seenWidgetIds.add(widget.id)
 
-    // Early exit for non-visible widgets
-    if (!widget.isVisible() || !widgetState.active) {
+    // Use position override only when the override node (SubgraphNode) is
+    // in the current graph. When the user enters the subgraph, the override
+    // node is no longer visible — fall back to the widget's own node.
+    // Use graph reference equality (IDs are not unique across graphs).
+    const override = widgetState.positionOverride
+    const useOverride = !!override && currentGraph === override.node.graph
+    const inOverrideTransitionGap =
+      !!override && !useOverride && !widgetState.active
+    const useTransitionGrace =
+      inOverrideTransitionGap && !overrideTransitionGrace.has(widget.id)
+
+    if (useTransitionGrace) {
+      overrideTransitionGrace.add(widget.id)
+    } else if (!inOverrideTransitionGap) {
+      overrideTransitionGrace.delete(widget.id)
+    }
+
+    // Early exit for non-visible widgets.
+    // When a position override is active (widget promoted to SubgraphNode),
+    // the interior widget's `active` flag is false (its node is in the
+    // subgraph, not the current graph) — bypass that check.
+    if (
+      !widget.isVisible() ||
+      (!widgetState.active && !useOverride && !useTransitionGrace)
+    ) {
       widgetState.visible = false
       continue
     }
 
-    // Check if the widget's node is in the current graph
-    const node = widget.node
-    const isInCorrectGraph = currentGraph?.nodes.includes(node)
+    // During graph transitions, hold the previous position for one frame
+    // so promoted widgets don't briefly disappear before activation flips.
+    if (useTransitionGrace) continue
+
+    const posNode = useOverride ? override.node : widget.node
+    const posWidget = useOverride ? override.widget : widget
+
+    const isInCorrectGraph = posNode.graph === currentGraph
+    const nodeVisible = lgCanvas.isNodeVisible(posNode)
 
     widgetState.visible =
-      !!isInCorrectGraph &&
-      lgCanvas.isNodeVisible(node) &&
+      isInCorrectGraph &&
+      nodeVisible &&
       !(widget.options.hideOnZoom && lowQuality)
 
-    if (widgetState.visible && node) {
+    if (widgetState.visible) {
       const margin = widget.margin
-      widgetState.pos = [node.pos[0] + margin, node.pos[1] + margin + widget.y]
-      widgetState.size = [
-        (widget.width ?? node.width) - margin * 2,
-        (widget.computedHeight ?? 50) - margin * 2
+      widgetState.pos = [
+        posNode.pos[0] + margin,
+        posNode.pos[1] + margin + posWidget.y
       ]
-      // TODO: optimize this logic as it's O(n), where n is the number of nodes
-      widgetState.zIndex = lgCanvas.graph?.nodes.indexOf(node) ?? -1
+      widgetState.size = [
+        (posWidget.width ?? posNode.width) - margin * 2,
+        (posWidget.computedHeight ?? 50) - margin * 2
+      ]
+      widgetState.zIndex = getDomWidgetZIndex(posNode, currentGraph)
       widgetState.readonly = lgCanvas.read_only
     }
   }
+
+  for (const widgetId of overrideTransitionGrace) {
+    if (!seenWidgetIds.has(widgetId)) {
+      overrideTransitionGrace.delete(widgetId)
+    }
+  }
 }
 
 const canvasStore = useCanvasStore()

src/components/graph/GraphCanvas.vue

@@ -6,7 +6,7 @@
     <template v-if="showUI" #workflow-tabs>
       <div
         v-if="workflowTabsPosition === 'Topbar'"
-        class="workflow-tabs-container pointer-events-auto relative h-9.5 w-full"
+        class="workflow-tabs-container pointer-events-auto relative w-full h-(--workflow-tabs-height)"
       >
         <!-- Native drag area for Electron -->
         <div
@@ -21,7 +21,7 @@
         </div>
       </div>
     </template>
-    <template v-if="showUI" #side-toolbar>
+    <template v-if="showUI && !appModeStore.isBuilderMode" #side-toolbar>
       <SideToolbar />
     </template>
     <template v-if="showUI" #side-bar-panel>
@@ -31,19 +31,27 @@
         <ExtensionSlot v-if="activeSidebarTab" :extension="activeSidebarTab" />
       </div>
     </template>
-    <template v-if="showUI" #topmenu>
+    <template v-if="showUI && !appModeStore.isBuilderMode" #topmenu>
       <TopMenuSection />
     </template>
     <template v-if="showUI" #bottom-panel>
       <BottomPanel />
     </template>
     <template v-if="showUI" #right-side-panel>
-      <NodePropertiesPanel />
+      <NodePropertiesPanel v-if="!appModeStore.isBuilderMode" />
     </template>
     <template #graph-canvas-panel>
-      <GraphCanvasMenu v-if="canvasMenuEnabled" class="pointer-events-auto" />
+      <GraphCanvasMenu
+        v-if="canvasMenuEnabled && !appModeStore.isBuilderMode"
+        class="pointer-events-auto"
+      />
       <MiniMap
-        v-if="comfyAppReady && minimapEnabled && betaMenuEnabled"
+        v-if="
+          comfyAppReady &&
+          minimapEnabled &&
+          betaMenuEnabled &&
+          !appModeStore.isBuilderMode
+        "
         class="pointer-events-auto"
       />
     </template>
@@ -174,6 +182,7 @@ import { useExecutionErrorStore } from '@/stores/executionErrorStore'
 import { useNodeDefStore } from '@/stores/nodeDefStore'
 import { useColorPaletteStore } from '@/stores/workspace/colorPaletteStore'
 import { useSearchBoxStore } from '@/stores/workspace/searchBoxStore'
+import { useAppModeStore } from '@/stores/appModeStore'
 import { useWorkspaceStore } from '@/stores/workspaceStore'
 import { isNativeWindow } from '@/utils/envUtil'
 import { forEachNode } from '@/utils/graphTraversalUtil'
@@ -194,6 +203,7 @@ const nodeSearchboxPopoverRef = shallowRef<InstanceType<
 const settingStore = useSettingStore()
 const nodeDefStore = useNodeDefStore()
 const workspaceStore = useWorkspaceStore()
+const appModeStore = useAppModeStore()
 const canvasStore = useCanvasStore()
 const workflowStore = useWorkflowStore()
 const executionStore = useExecutionStore()

src/components/graph/widgets/DomWidget.vue

@@ -68,7 +68,11 @@ const updateDomClipping = () => {
     return
   }
 
-  const isSelected = selectedNode === widgetState.widget.node
+  const override = widgetState.positionOverride
+  const overrideInGraph =
+    override && lgCanvas.graph?.getNodeById(override.node.id)
+  const ownerNode = overrideInGraph ? override.node : widgetState.widget.node
+  const isSelected = selectedNode === ownerNode
   const renderArea = selectedNode?.renderArea
   const offset = lgCanvas.ds.offset
   const scale = lgCanvas.ds.scale
@@ -143,8 +147,17 @@ onMounted(() => {
     widget.options.selectOn ?? ['focus', 'click'],
     () => {
       const lgCanvas = canvasStore.canvas
-      lgCanvas?.selectNode(widgetState.widget.node)
-      lgCanvas?.bringToFront(widgetState.widget.node)
+      if (!lgCanvas) return
+
+      const override = widgetState.positionOverride
+      const overrideInGraph =
+        override && lgCanvas.graph?.getNodeById(override.node.id)
+      const ownerNode = overrideInGraph
+        ? override.node
+        : widgetState.widget.node
+
+      lgCanvas.selectNode(ownerNode)
+      lgCanvas.bringToFront(ownerNode)
     }
   )
 })

src/components/graph/widgets/domWidgetZIndex.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+
+import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph'
+
+import { getDomWidgetZIndex } from './domWidgetZIndex'
+
+describe('getDomWidgetZIndex', () => {
+  it('follows graph node ordering when node.order is stale', () => {
+    const graph = new LGraph()
+    const first = new LGraphNode('first')
+    const second = new LGraphNode('second')
+    graph.add(first)
+    graph.add(second)
+
+    first.order = 0
+    second.order = 1
+
+    const nodes = (graph as unknown as { _nodes: LGraphNode[] })._nodes
+    nodes.splice(nodes.indexOf(first), 1)
+    nodes.push(first)
+
+    expect(first.order).toBe(0)
+    expect(second.order).toBe(1)
+
+    expect(getDomWidgetZIndex(first, graph)).toBe(1)
+    expect(getDomWidgetZIndex(second, graph)).toBe(0)
+  })
+
+  it('falls back to node.order when node is not in current graph', () => {
+    const graph = new LGraph()
+    const node = new LGraphNode('orphan')
+    node.order = 7
+
+    expect(getDomWidgetZIndex(node, graph)).toBe(7)
+    expect(getDomWidgetZIndex(node, undefined)).toBe(7)
+  })
+})

src/components/graph/widgets/domWidgetZIndex.ts

@@ -0,0 +1,13 @@
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
+
+export function getDomWidgetZIndex(
+  node: LGraphNode,
+  currentGraph: LGraphNode['graph'] | undefined
+): number {
+  if (!currentGraph) return node.order ?? -1
+
+  const graphOrder = currentGraph.nodes.indexOf(node)
+  if (graphOrder === -1) return node.order ?? -1
+
+  return graphOrder
+}

src/components/queue/QueueInlineProgress.test.ts

@@ -6,8 +6,8 @@ import type { Ref } from 'vue'
 import QueueInlineProgress from '@/components/queue/QueueInlineProgress.vue'
 
 const mockProgress = vi.hoisted(() => ({
-  totalPercent: null as unknown as Ref<number>,
-  currentNodePercent: null as unknown as Ref<number>
+  totalPercent: null! as Ref<number>,
+  currentNodePercent: null! as Ref<number>
 }))
 
 vi.mock('@/composables/queue/useQueueProgress', () => ({

src/components/queue/job/useJobErrorReporting.test.ts

@@ -39,7 +39,7 @@ describe('useJobErrorReporting', () => {
     dialog = {
       showErrorDialog,
       showExecutionErrorDialog
-    } as unknown as JobErrorDialogService
+    } as Partial<JobErrorDialogService> as JobErrorDialogService
     composable = useJobErrorReporting({
       taskForJob,
       copyToClipboard: copyToClipboard as (

src/components/rightSidePanel/RightSidePanel.vue

@@ -8,7 +8,6 @@ import Tab from '@/components/tab/Tab.vue'
 import TabList from '@/components/tab/TabList.vue'
 import Button from '@/components/ui/button/Button.vue'
 import { useGraphHierarchy } from '@/composables/graph/useGraphHierarchy'
-import type { ProxyWidgetsProperty } from '@/core/schemas/proxyWidget'
 import { st } from '@/i18n'
 import { SubgraphNode } from '@/lib/litegraph/src/litegraph'
 import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
@@ -106,7 +105,7 @@ const hasContainerInternalError = computed(() => {
   if (allErrorExecutionIds.value.length === 0) return false
   return selectedNodes.value.some((node) => {
     if (!(node instanceof SubgraphNode || isGroupNode(node))) return false
-    return executionErrorStore.hasInternalErrorForNode(node.id)
+    return executionErrorStore.isContainerWithInternalError(node)
   })
 })
 
@@ -229,12 +228,6 @@ function handleTitleEdit(newTitle: string) {
 function handleTitleCancel() {
   isEditing.value = false
 }
-
-function handleProxyWidgetsUpdate(value: ProxyWidgetsProperty) {
-  if (!selectedSingleNode.value) return
-  ;(selectedSingleNode.value as SubgraphNode).properties.proxyWidgets = value
-  canvasStore.canvas?.setDirty(true, true)
-}
 </script>
 
 <template>
@@ -330,7 +323,6 @@ function handleProxyWidgetsUpdate(value: ProxyWidgetsProperty) {
         <TabSubgraphInputs
           v-if="activeTab === 'parameters' && isSingleSubgraphNode"
           :node="selectedSingleNode as SubgraphNode"
-          @update:proxy-widgets="handleProxyWidgetsUpdate"
         />
         <TabNormalInputs
           v-else-if="activeTab === 'parameters'"

src/components/rightSidePanel/errors/useErrorGroups.ts

@@ -13,6 +13,7 @@ import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
 
 import {
   getNodeByExecutionId,
+  getExecutionIdByNode,
   getRootParentNode
 } from '@/utils/graphTraversalUtil'
 import { resolveNodeDisplayName } from '@/utils/nodeTitleUtil'
@@ -20,6 +21,7 @@ import { isLGraphNode } from '@/utils/litegraphUtil'
 import { isGroupNode } from '@/utils/executableGroupNodeDto'
 import { st } from '@/i18n'
 import type { ErrorCardData, ErrorGroup, ErrorItem } from './types'
+import type { NodeExecutionId } from '@/types/nodeIdentification'
 import { isNodeExecutionId } from '@/types/nodeIdentification'
 
 const PROMPT_CARD_ID = '__prompt__'
@@ -200,26 +202,30 @@ export function useErrorGroups(
   const selectedNodeInfo = computed(() => {
     const items = canvasStore.selectedItems
     const nodeIds = new Set<string>()
-    const containerIds = new Set<string>()
+    const containerExecutionIds = new Set<NodeExecutionId>()
 
     for (const item of items) {
       if (!isLGraphNode(item)) continue
       nodeIds.add(String(item.id))
-      if (item instanceof SubgraphNode || isGroupNode(item)) {
-        containerIds.add(String(item.id))
+      if (
+        (item instanceof SubgraphNode || isGroupNode(item)) &&
+        app.rootGraph
+      ) {
+        const execId = getExecutionIdByNode(app.rootGraph, item)
+        if (execId) containerExecutionIds.add(execId)
       }
     }
 
     return {
       nodeIds: nodeIds.size > 0 ? nodeIds : null,
-      containerIds
+      containerExecutionIds
     }
   })
 
   const isSingleNodeSelected = computed(
     () =>
       selectedNodeInfo.value.nodeIds?.size === 1 &&
-      selectedNodeInfo.value.containerIds.size === 0
+      selectedNodeInfo.value.containerExecutionIds.size === 0
   )
 
   const errorNodeCache = computed(() => {
@@ -238,8 +244,9 @@ export function useErrorGroups(
     const graphNode = errorNodeCache.value.get(executionNodeId)
     if (graphNode && nodeIds.has(String(graphNode.id))) return true
 
-    for (const containerId of selectedNodeInfo.value.containerIds) {
-      if (executionNodeId.startsWith(`${containerId}:`)) return true
+    for (const containerExecId of selectedNodeInfo.value
+      .containerExecutionIds) {
+      if (executionNodeId.startsWith(`${containerExecId}:`)) return true
     }
 
     return false

src/components/rightSidePanel/parameters/SectionWidgets.vue

@@ -3,10 +3,10 @@ import { computed, inject, provide, ref, shallowRef, watchEffect } from 'vue'
 import { useI18n } from 'vue-i18n'
 
 import Button from '@/components/ui/button/Button.vue'
-import { isProxyWidget } from '@/core/graph/subgraph/proxyWidget'
-import { parseProxyWidgets } from '@/core/schemas/proxyWidget'
+import { isPromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetTypes'
 import type { LGraphGroup, LGraphNode } from '@/lib/litegraph/src/litegraph'
 import { SubgraphNode } from '@/lib/litegraph/src/litegraph'
+import { usePromotionStore } from '@/stores/promotionStore'
 import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
 import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
 import { useExecutionErrorStore } from '@/stores/executionErrorStore'
@@ -69,27 +69,28 @@ const { t } = useI18n()
 
 const getNodeParentGroup = inject(GetNodeParentGroupKey, null)
 
+const promotionStore = usePromotionStore()
+
 function isWidgetShownOnParents(
   widgetNode: LGraphNode,
   widget: IBaseWidget
 ): boolean {
-  if (!parents.length) return false
-  const proxyWidgets = parseProxyWidgets(parents[0].properties.proxyWidgets)
-
-  // For proxy widgets (already promoted), check using overlay information
-  if (isProxyWidget(widget)) {
-    return proxyWidgets.some(
-      ([nodeId, widgetName]) =>
-        widget._overlay.nodeId == nodeId &&
-        widget._overlay.widgetName === widgetName
+  return parents.some((parent) => {
+    if (isPromotedWidgetView(widget)) {
+      return promotionStore.isPromoted(
+        parent.rootGraph.id,
+        parent.id,
+        widget.sourceNodeId,
+        widget.sourceWidgetName
+      )
+    }
+    return promotionStore.isPromoted(
+      parent.rootGraph.id,
+      parent.id,
+      String(widgetNode.id),
+      widget.name
     )
-  }
-
-  // For regular widgets (not yet promoted), check using node ID and widget name
-  return proxyWidgets.some(
-    ([nodeId, widgetName]) =>
-      widgetNode.id == nodeId && widget.name === widgetName
-  )
+  })
 }
 
 const isEmpty = computed(() => widgets.value.length === 0)
@@ -121,7 +122,7 @@ const hasContainerInternalError = computed(() => {
     targetNode.value instanceof SubgraphNode || isGroupNode(targetNode.value)
   if (!isContainer) return false
 
-  return executionErrorStore.hasInternalErrorForNode(targetNode.value.id)
+  return executionErrorStore.isContainerWithInternalError(targetNode.value)
 })
 
 const nodeHasError = computed(() => {

src/components/rightSidePanel/parameters/TabSubgraphInputs.vue

@@ -3,25 +3,22 @@ import { useMounted, watchDebounced } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
 import {
   computed,
-  customRef,
   nextTick,
   onBeforeUnmount,
   onMounted,
   ref,
   shallowRef,
-  triggerRef,
   useTemplateRef,
   watch
 } from 'vue'
 import { useI18n } from 'vue-i18n'
 
-import { isProxyWidget } from '@/core/graph/subgraph/proxyWidget'
-import { parseProxyWidgets } from '@/core/schemas/proxyWidget'
-import type { ProxyWidgetsProperty } from '@/core/schemas/proxyWidget'
+import { isPromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetTypes'
 import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
 import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
 import FormSearchInput from '@/renderer/extensions/vueNodes/widgets/components/form/FormSearchInput.vue'
 import { DraggableList } from '@/scripts/ui/draggableList'
+import { usePromotionStore } from '@/stores/promotionStore'
 import { useRightSidePanelStore } from '@/stores/workspace/rightSidePanelStore'
 
 import { searchWidgets } from '../shared'
@@ -32,12 +29,9 @@ const { node } = defineProps<{
   node: SubgraphNode
 }>()
 
-const emit = defineEmits<{
-  'update:proxyWidgets': [value: ProxyWidgetsProperty]
-}>()
-
 const { t } = useI18n()
 const canvasStore = useCanvasStore()
+const promotionStore = usePromotionStore()
 const rightSidePanelStore = useRightSidePanelStore()
 const { focusedSection, searchQuery } = storeToRefs(rightSidePanelStore)
 
@@ -46,18 +40,9 @@ const draggableList = ref<DraggableList | undefined>(undefined)
 const sectionWidgetsRef = useTemplateRef('sectionWidgetsRef')
 const advancedInputsSectionRef = useTemplateRef('advancedInputsSectionRef')
 
-// Use customRef to track proxyWidgets changes
-const proxyWidgets = customRef<ProxyWidgetsProperty>((track, trigger) => ({
-  get() {
-    track()
-    return parseProxyWidgets(node.properties.proxyWidgets)
-  },
-  set(value?: ProxyWidgetsProperty) {
-    trigger()
-    if (!value) return
-    emit('update:proxyWidgets', value)
-  }
-}))
+const promotionEntries = computed(() =>
+  promotionStore.getPromotions(node.rootGraph.id, node.id)
+)
 
 watch(
   focusedSection,
@@ -81,22 +66,18 @@ watch(
 )
 
 const widgetsList = computed((): NodeWidgetsList => {
-  const proxyWidgetsOrder = proxyWidgets.value
+  const entries = promotionEntries.value
   const { widgets = [] } = node
 
-  // Map proxyWidgets to actual proxy widgets in the correct order
   const result: NodeWidgetsList = []
-  for (const [nodeId, widgetName] of proxyWidgetsOrder) {
-    // Find the proxy widget that matches this nodeId and widgetName
+  for (const { interiorNodeId, widgetName } of entries) {
     const widget = widgets.find((w) => {
-      // Check if this is a proxy widget with _overlay
-      if (isProxyWidget(w)) {
+      if (isPromotedWidgetView(w)) {
         return (
-          String(w._overlay.nodeId) === nodeId &&
-          w._overlay.widgetName === widgetName
+          String(w.sourceNodeId) === interiorNodeId &&
+          w.sourceWidgetName === widgetName
         )
       }
-      // For non-proxy widgets (like linked widgets), match by name
       return w.name === widgetName
     })
     if (widget) {
@@ -108,9 +89,7 @@ const widgetsList = computed((): NodeWidgetsList => {
 
 const advancedInputsWidgets = computed((): NodeWidgetsList => {
   const interiorNodes = node.subgraph.nodes
-  const proxyWidgetsValue = parseProxyWidgets(node.properties.proxyWidgets)
 
-  // Get all widgets from interior nodes
   const allInteriorWidgets = interiorNodes.flatMap((interiorNode) => {
     const { widgets = [] } = interiorNode
     return widgets
@@ -118,13 +97,15 @@ const advancedInputsWidgets = computed((): NodeWidgetsList => {
       .map((widget) => ({ node: interiorNode, widget }))
   })
 
-  // Filter out widgets that are already promoted using tuple matching
-  return allInteriorWidgets.filter(({ node: interiorNode, widget }) => {
-    return !proxyWidgetsValue.some(
-      ([nodeId, widgetName]) =>
-        interiorNode.id == nodeId && widget.name === widgetName
-    )
-  })
+  return allInteriorWidgets.filter(
+    ({ node: interiorNode, widget }) =>
+      !promotionStore.isPromoted(
+        node.rootGraph.id,
+        node.id,
+        String(interiorNode.id),
+        widget.name
+      )
+  )
 })
 
 const parents = computed<SubgraphNode[]>(() => [node])
@@ -181,13 +162,13 @@ function setDraggableState() {
       this.draggableItem as HTMLElement
     )
 
-    // Update proxyWidgets order
-    const pw = proxyWidgets.value
-    const [w] = pw.splice(oldPosition, 1)
-    pw.splice(newPosition, 0, w)
-    proxyWidgets.value = pw
+    promotionStore.movePromotion(
+      node.rootGraph.id,
+      node.id,
+      oldPosition,
+      newPosition
+    )
     canvasStore.canvas?.setDirty(true, true)
-    triggerRef(proxyWidgets)
   }
 }
 

src/components/rightSidePanel/parameters/WidgetActions.vue

@@ -5,11 +5,12 @@ import { useI18n } from 'vue-i18n'
 
 import MoreButton from '@/components/button/MoreButton.vue'
 import Button from '@/components/ui/button/Button.vue'
-import { isProxyWidget } from '@/core/graph/subgraph/proxyWidget'
+import { isPromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetTypes'
+import { resolvePromotedWidgetSource } from '@/core/graph/subgraph/resolvePromotedWidgetSource'
 import {
   demoteWidget,
   promoteWidget
-} from '@/core/graph/subgraph/proxyWidgetUtils'
+} from '@/core/graph/subgraph/promotionUtils'
 import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
 import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
 import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
@@ -80,26 +81,14 @@ async function handleRename() {
 function handleHideInput() {
   if (!parents?.length) return
 
-  // For proxy widgets (already promoted), we need to find the original interior node and widget
-  if (isProxyWidget(widget)) {
-    const subgraph = parents[0].subgraph
-    const interiorNode = subgraph.getNodeById(parseInt(widget._overlay.nodeId))
-
-    if (!interiorNode) {
-      console.error('Could not find interior node for proxy widget')
+  if (isPromotedWidgetView(widget)) {
+    const sourceWidget = resolvePromotedWidgetSource(node, widget)
+    if (!sourceWidget) {
+      console.error('Could not resolve source widget for promoted widget')
       return
     }
 
-    const originalWidget = interiorNode.widgets?.find(
-      (w) => w.name === widget._overlay.widgetName
-    )
-
-    if (!originalWidget) {
-      console.error('Could not find original widget for proxy widget')
-      return
-    }
-
-    demoteWidget(interiorNode, originalWidget, parents)
+    demoteWidget(sourceWidget.node, sourceWidget.widget, parents)
   } else {
     // For regular widgets (not yet promoted), use them directly
     demoteWidget(node, widget, parents)

src/components/rightSidePanel/parameters/WidgetItem.test.ts

@@ -0,0 +1,204 @@
+import { createTestingPinia } from '@pinia/testing'
+import { mount } from '@vue/test-utils'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createI18n } from 'vue-i18n'
+
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+import WidgetItem from './WidgetItem.vue'
+
+const { mockGetInputSpecForWidget, StubWidgetComponent } = vi.hoisted(() => ({
+  mockGetInputSpecForWidget: vi.fn(),
+  StubWidgetComponent: {
+    name: 'StubWidget',
+    props: ['widget', 'modelValue', 'nodeId', 'nodeType'],
+    template: '<div class="stub-widget" />'
+  }
+}))
+
+vi.mock('@/stores/nodeDefStore', () => ({
+  useNodeDefStore: () => ({
+    getInputSpecForWidget: mockGetInputSpecForWidget
+  })
+}))
+
+vi.mock('@/renderer/core/canvas/canvasStore', () => ({
+  useCanvasStore: () => ({
+    canvas: { setDirty: vi.fn() }
+  })
+}))
+
+vi.mock('@/stores/workspace/favoritedWidgetsStore', () => ({
+  useFavoritedWidgetsStore: () => ({
+    isFavorited: vi.fn().mockReturnValue(false),
+    toggleFavorite: vi.fn()
+  })
+}))
+
+vi.mock('@/composables/graph/useGraphNodeManager', () => ({
+  getControlWidget: vi.fn(() => undefined)
+}))
+
+vi.mock('@/core/graph/subgraph/resolvePromotedWidgetSource', () => ({
+  resolvePromotedWidgetSource: vi.fn(() => undefined)
+}))
+
+vi.mock(
+  '@/renderer/extensions/vueNodes/widgets/registry/widgetRegistry',
+  () => ({
+    getComponent: () => StubWidgetComponent,
+    shouldExpand: () => false
+  })
+)
+
+vi.mock(
+  '@/renderer/extensions/vueNodes/widgets/components/WidgetLegacy.vue',
+  () => ({
+    default: StubWidgetComponent
+  })
+)
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      rightSidePanel: {
+        fallbackNodeTitle: 'Untitled'
+      }
+    }
+  }
+})
+
+function createMockNode(overrides: Partial<LGraphNode> = {}): LGraphNode {
+  return {
+    id: 1,
+    type: 'TestNode',
+    isSubgraphNode: () => false,
+    graph: { rootGraph: { id: 'test-graph-id' } },
+    ...overrides
+  } as unknown as LGraphNode
+}
+
+function createMockWidget(overrides: Partial<IBaseWidget> = {}): IBaseWidget {
+  return {
+    name: 'test_widget',
+    type: 'combo',
+    value: 'option_a',
+    y: 0,
+    options: {
+      values: ['option_a', 'option_b', 'option_c']
+    },
+    ...overrides
+  } as IBaseWidget
+}
+
+/**
+ * Creates a mock PromotedWidgetView that mirrors the real class:
+ * properties like name, type, value, options are prototype getters,
+ * NOT own properties — so object spread loses them.
+ */
+function createMockPromotedWidgetView(
+  sourceOptions: IBaseWidget['options'] = {
+    values: ['model_a.safetensors', 'model_b.safetensors']
+  }
+): IBaseWidget {
+  class MockPromotedWidgetView {
+    readonly sourceNodeId = '42'
+    readonly sourceWidgetName = 'ckpt_name'
+    readonly serialize = false
+
+    get name(): string {
+      return 'ckpt_name'
+    }
+    get type(): string {
+      return 'combo'
+    }
+    get value(): unknown {
+      return 'model_a.safetensors'
+    }
+    get options(): IBaseWidget['options'] {
+      return sourceOptions
+    }
+    get label(): string | undefined {
+      return undefined
+    }
+    get y(): number {
+      return 0
+    }
+  }
+  return new MockPromotedWidgetView() as unknown as IBaseWidget
+}
+
+function mountWidgetItem(
+  widget: IBaseWidget,
+  node: LGraphNode = createMockNode()
+) {
+  return mount(WidgetItem, {
+    props: { widget, node },
+    global: {
+      plugins: [i18n],
+      stubs: {
+        EditableText: { template: '<span />' },
+        WidgetActions: { template: '<span />' }
+      }
+    }
+  })
+}
+
+describe('WidgetItem', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    vi.clearAllMocks()
+  })
+
+  describe('promoted widget options', () => {
+    it('passes options from a regular widget to the widget component', () => {
+      const widget = createMockWidget({
+        options: { values: ['a', 'b', 'c'] }
+      })
+      const wrapper = mountWidgetItem(widget)
+      const stub = wrapper.findComponent(StubWidgetComponent)
+
+      expect(stub.props('widget').options).toEqual({
+        values: ['a', 'b', 'c']
+      })
+    })
+
+    it('passes options from a PromotedWidgetView to the widget component', () => {
+      const expectedOptions = {
+        values: ['model_a.safetensors', 'model_b.safetensors']
+      }
+      const widget = createMockPromotedWidgetView(expectedOptions)
+      const wrapper = mountWidgetItem(widget)
+      const stub = wrapper.findComponent(StubWidgetComponent)
+
+      expect(stub.props('widget').options).toEqual(expectedOptions)
+    })
+
+    it('passes type from a PromotedWidgetView to the widget component', () => {
+      const widget = createMockPromotedWidgetView()
+      const wrapper = mountWidgetItem(widget)
+      const stub = wrapper.findComponent(StubWidgetComponent)
+
+      expect(stub.props('widget').type).toBe('combo')
+    })
+
+    it('passes name from a PromotedWidgetView to the widget component', () => {
+      const widget = createMockPromotedWidgetView()
+      const wrapper = mountWidgetItem(widget)
+      const stub = wrapper.findComponent(StubWidgetComponent)
+
+      expect(stub.props('widget').name).toBe('ckpt_name')
+    })
+
+    it('passes value from a PromotedWidgetView to the widget component', () => {
+      const widget = createMockPromotedWidgetView()
+      const wrapper = mountWidgetItem(widget)
+      const stub = wrapper.findComponent(StubWidgetComponent)
+
+      expect(stub.props('widget').value).toBe('model_a.safetensors')
+    })
+  })
+})

src/components/rightSidePanel/parameters/WidgetItem.vue

@@ -3,8 +3,8 @@ import { computed, customRef, ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 
 import EditableText from '@/components/common/EditableText.vue'
-import { getSharedWidgetEnhancements } from '@/composables/graph/useGraphNodeManager'
-import { isProxyWidget } from '@/core/graph/subgraph/proxyWidget'
+import { getControlWidget } from '@/composables/graph/useGraphNodeManager'
+import { resolvePromotedWidgetSource } from '@/core/graph/subgraph/resolvePromotedWidgetSource'
 import { st } from '@/i18n'
 import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
 import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
@@ -15,8 +15,13 @@ import {
   getComponent,
   shouldExpand
 } from '@/renderer/extensions/vueNodes/widgets/registry/widgetRegistry'
+import { useNodeDefStore } from '@/stores/nodeDefStore'
+import {
+  useWidgetValueStore,
+  stripGraphPrefix
+} from '@/stores/widgetValueStore'
 import { useFavoritedWidgetsStore } from '@/stores/workspace/favoritedWidgetsStore'
-import { getNodeByExecutionId } from '@/utils/graphTraversalUtil'
+import type { SimplifiedWidget } from '@/types/simplifiedWidget'
 import { resolveNodeDisplayName } from '@/utils/nodeTitleUtil'
 import { cn } from '@/utils/tailwindUtil'
 import { renameWidget } from '@/utils/widgetUtil'
@@ -50,6 +55,8 @@ const emit = defineEmits<{
 const { t } = useI18n()
 
 const canvasStore = useCanvasStore()
+const nodeDefStore = useNodeDefStore()
+const widgetValueStore = useWidgetValueStore()
 const favoritedWidgetsStore = useFavoritedWidgetsStore()
 const isEditing = ref(false)
 
@@ -58,18 +65,32 @@ const widgetComponent = computed(() => {
   return component || WidgetLegacy
 })
 
-const enhancedWidget = computed(() => {
-  // Get shared enhancements (reactive value, controlWidget, spec, nodeType, etc.)
-  const enhancements = getSharedWidgetEnhancements(node, widget)
-  return { ...widget, ...enhancements }
+function resolveSourceWidget(): { node: LGraphNode; widget: IBaseWidget } {
+  const source = resolvePromotedWidgetSource(node, widget)
+  return source ?? { node, widget }
+}
+
+const simplifiedWidget = computed((): SimplifiedWidget => {
+  const { node: sourceNode, widget: sourceWidget } = resolveSourceWidget()
+  const graphId = node.graph?.rootGraph?.id
+  const bareNodeId = stripGraphPrefix(String(sourceNode.id))
+  const widgetState = graphId
+    ? widgetValueStore.getWidget(graphId, bareNodeId, sourceWidget.name)
+    : undefined
+
+  return {
+    name: widget.name,
+    type: widget.type,
+    value: widgetState?.value ?? widget.value,
+    label: widgetState?.label ?? widget.label,
+    options: widgetState?.options ?? widget.options,
+    spec: nodeDefStore.getInputSpecForWidget(sourceNode, sourceWidget.name),
+    controlWidget: getControlWidget(sourceWidget)
+  }
 })
 
 const sourceNodeName = computed((): string | null => {
-  let sourceNode: LGraphNode | null = node
-  if (isProxyWidget(widget)) {
-    const { graph, nodeId } = widget._overlay
-    sourceNode = getNodeByExecutionId(graph, nodeId)
-  }
+  const sourceNode = resolvePromotedWidgetSource(node, widget)?.node ?? node
   if (!sourceNode) return null
   const fallbackNodeTitle = t('rightSidePanel.fallbackNodeTitle')
   return resolveNodeDisplayName(sourceNode, {
@@ -176,7 +197,7 @@ const displayLabel = customRef((track, trigger) => {
     <component
       :is="widgetComponent"
       v-model="widgetValue"
-      :widget="enhancedWidget"
+      :widget="simplifiedWidget"
       :node-id="String(node.id)"
       :node-type="node.type"
       :class="cn('col-span-1', shouldExpand(widget.type) && 'min-h-36')"

src/components/rightSidePanel/subgraph/SubgraphEditor.vue

@@ -1,63 +1,43 @@
 <script setup lang="ts">
 import { storeToRefs } from 'pinia'
-import {
-  computed,
-  customRef,
-  onBeforeUnmount,
-  onMounted,
-  ref,
-  triggerRef,
-  watch
-} from 'vue'
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useI18n } from 'vue-i18n'
 
 import Button from '@/components/ui/button/Button.vue'
 import {
   demoteWidget,
+  getPromotableWidgets,
+  getWidgetName,
   isRecommendedWidget,
-  matchesPropertyItem,
-  matchesWidgetItem,
   promoteWidget,
-  pruneDisconnected,
-  widgetItemToProperty
-} from '@/core/graph/subgraph/proxyWidgetUtils'
-import type { WidgetItem } from '@/core/graph/subgraph/proxyWidgetUtils'
-import { parseProxyWidgets } from '@/core/schemas/proxyWidget'
-import type { ProxyWidgetsProperty } from '@/core/schemas/proxyWidget'
+  pruneDisconnected
+} from '@/core/graph/subgraph/promotionUtils'
+import type { WidgetItem } from '@/core/graph/subgraph/promotionUtils'
 import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
 import { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
-import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
 import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
 import FormSearchInput from '@/renderer/extensions/vueNodes/widgets/components/form/FormSearchInput.vue'
 import { DraggableList } from '@/scripts/ui/draggableList'
 import { useLitegraphService } from '@/services/litegraphService'
+import { usePromotionStore } from '@/stores/promotionStore'
 import { useRightSidePanelStore } from '@/stores/workspace/rightSidePanelStore'
 
 import SubgraphNodeWidget from './SubgraphNodeWidget.vue'
 
+const { t } = useI18n()
 const canvasStore = useCanvasStore()
+const promotionStore = usePromotionStore()
 const rightSidePanelStore = useRightSidePanelStore()
 const { searchQuery } = storeToRefs(rightSidePanelStore)
 
 const draggableList = ref<DraggableList | undefined>(undefined)
 const draggableItems = ref()
-const proxyWidgets = customRef<ProxyWidgetsProperty>((track, trigger) => ({
-  get() {
-    track()
-    const node = activeNode.value
-    if (!node) return []
-    return parseProxyWidgets(node.properties.proxyWidgets)
-  },
-  set(value?: ProxyWidgetsProperty) {
-    trigger()
-    const node = activeNode.value
-    if (!value) return
-    if (!node) {
-      console.error('Attempted to toggle widgets with no node selected')
-      return
-    }
-    node.properties.proxyWidgets = value
-  }
-}))
+
+const promotionEntries = computed(() => {
+  const node = activeNode.value
+  if (!node) return []
+  return promotionStore.getPromotions(node.rootGraph.id, node.id)
+})
 
 const activeNode = computed(() => {
   const node = canvasStore.selectedItems[0]
@@ -67,21 +47,27 @@ const activeNode = computed(() => {
 
 const activeWidgets = computed<WidgetItem[]>({
   get() {
-    if (!activeNode.value) return []
     const node = activeNode.value
-    function mapWidgets([id, name]: [string, string]): WidgetItem[] {
-      if (id === '-1') {
-        const widget = node.widgets.find((w) => w.name === name)
+    if (!node) return []
+
+    return promotionEntries.value.flatMap(
+      ({ interiorNodeId, widgetName }): WidgetItem[] => {
+        if (interiorNodeId === '-1') {
+          const widget = node.widgets.find((w) => w.name === widgetName)
+          if (!widget) return []
+          return [
+            [{ id: -1, title: t('subgraphStore.linked'), type: '' }, widget]
+          ]
+        }
+        const wNode = node.subgraph._nodes_by_id[interiorNodeId]
+        if (!wNode) return []
+        const widget = getPromotableWidgets(wNode).find(
+          (w) => w.name === widgetName
+        )
         if (!widget) return []
-        return [[{ id: -1, title: '(Linked)', type: '' }, widget]]
+        return [[wNode, widget]]
       }
-      const wNode = node.subgraph._nodes_by_id[id]
-      if (!wNode?.widgets) return []
-      const widget = wNode.widgets.find((w) => w.name === name)
-      if (!widget) return []
-      return [[wNode, widget]]
-    }
-    return proxyWidgets.value.flatMap(mapWidgets)
+    )
   },
   set(value: WidgetItem[]) {
     const node = activeNode.value
@@ -89,7 +75,14 @@ const activeWidgets = computed<WidgetItem[]>({
       console.error('Attempted to toggle widgets with no node selected')
       return
     }
-    proxyWidgets.value = value.map(widgetItemToProperty)
+    promotionStore.setPromotions(
+      node.rootGraph.id,
+      node.id,
+      value.map(([n, w]) => ({
+        interiorNodeId: String(n.id),
+        widgetName: getWidgetName(w)
+      }))
+    )
   }
 })
 
@@ -110,9 +103,14 @@ const interiorWidgets = computed<WidgetItem[]>(() => {
 const candidateWidgets = computed<WidgetItem[]>(() => {
   const node = activeNode.value
   if (!node) return []
-  const widgets = proxyWidgets.value
   return interiorWidgets.value.filter(
-    (widgetItem: WidgetItem) => !widgets.some(matchesPropertyItem(widgetItem))
+    ([n, w]: WidgetItem) =>
+      !promotionStore.isPromoted(
+        node.rootGraph.id,
+        node.id,
+        String(n.id),
+        w.name
+      )
   )
 })
 const filteredCandidates = computed<WidgetItem[]>(() => {
@@ -145,47 +143,56 @@ function toKey(item: WidgetItem) {
   return `${item[0].id}: ${item[1].name}`
 }
 function nodeWidgets(n: LGraphNode): WidgetItem[] {
-  if (!n.widgets) return []
-  return n.widgets.map((w: IBaseWidget) => [n, w])
+  return getPromotableWidgets(n).map((w) => [n, w])
 }
 function demote([node, widget]: WidgetItem) {
   const subgraphNode = activeNode.value
-  if (!subgraphNode) return []
+  if (!subgraphNode) return
   demoteWidget(node, widget, [subgraphNode])
-  triggerRef(proxyWidgets)
+  promotionStore.demote(
+    subgraphNode.rootGraph.id,
+    subgraphNode.id,
+    String(node.id),
+    getWidgetName(widget)
+  )
 }
 function promote([node, widget]: WidgetItem) {
   const subgraphNode = activeNode.value
-  if (!subgraphNode) return []
+  if (!subgraphNode) return
   promoteWidget(node, widget, [subgraphNode])
-  triggerRef(proxyWidgets)
+  promotionStore.promote(
+    subgraphNode.rootGraph.id,
+    subgraphNode.id,
+    String(node.id),
+    widget.name
+  )
 }
 function showAll() {
   const node = activeNode.value
   if (!node) return
-  const widgets = proxyWidgets.value
-  const toAdd: ProxyWidgetsProperty =
-    filteredCandidates.value.map(widgetItemToProperty)
-  widgets.push(...toAdd)
-  proxyWidgets.value = widgets
+  for (const [n, w] of filteredCandidates.value) {
+    promotionStore.promote(node.rootGraph.id, node.id, String(n.id), w.name)
+  }
 }
 function hideAll() {
   const node = activeNode.value
   if (!node) return
-  proxyWidgets.value = proxyWidgets.value.filter(
-    (propertyItem) =>
-      !filteredActive.value.some(matchesWidgetItem(propertyItem)) ||
-      propertyItem[0] === '-1'
-  )
+  for (const [n, w] of filteredActive.value) {
+    if (String(n.id) === '-1') continue
+    promotionStore.demote(
+      node.rootGraph.id,
+      node.id,
+      String(n.id),
+      getWidgetName(w)
+    )
+  }
 }
 function showRecommended() {
   const node = activeNode.value
   if (!node) return
-  const widgets = proxyWidgets.value
-  const toAdd: ProxyWidgetsProperty =
-    recommendedWidgets.value.map(widgetItemToProperty)
-  widgets.push(...toAdd)
-  proxyWidgets.value = widgets
+  for (const [n, w] of recommendedWidgets.value) {
+    promotionStore.promote(node.rootGraph.id, node.id, String(n.id), w.name)
+  }
 }
 
 function setDraggableState() {

src/components/searchbox/v2/NodeSearchInput.test.ts

@@ -31,7 +31,10 @@ function createFilter(
     filterDef: {
       id,
       matches: vi.fn(() => true)
-    } as unknown as FuseFilter<ComfyNodeDefImpl, string>,
+    } as Partial<FuseFilter<ComfyNodeDefImpl, string>> as FuseFilter<
+      ComfyNodeDefImpl,
+      string
+    >,
     value
   }
 }
@@ -43,7 +46,10 @@ function createActiveFilter(label: string): FilterChip {
     filter: {
       id: label.toLowerCase(),
       matches: vi.fn(() => true)
-    } as unknown as FuseFilter<ComfyNodeDefImpl, string>
+    } as Partial<FuseFilter<ComfyNodeDefImpl, string>> as FuseFilter<
+      ComfyNodeDefImpl,
+      string
+    >
   }
 }
 

src/components/sidebar/SideToolbar.vue

@@ -45,9 +45,6 @@
         <SidebarBottomPanelToggleButton v-if="!isCloud" :is-small="isSmall" />
         <SidebarShortcutsToggleButton :is-small="isSmall" />
         <SidebarSettingsButton :is-small="isSmall" />
-        <ModeToggle
-          v-if="menuItemStore.hasSeenLinear || flags.linearToggleEnabled"
-        />
       </div>
     </div>
     <HelpCenterPopups :is-small="isSmall" />
@@ -62,18 +59,15 @@ import { useI18n } from 'vue-i18n'
 
 import HelpCenterPopups from '@/components/helpcenter/HelpCenterPopups.vue'
 import ComfyMenuButton from '@/components/sidebar/ComfyMenuButton.vue'
-import ModeToggle from '@/components/sidebar/ModeToggle.vue'
 import SidebarBottomPanelToggleButton from '@/components/sidebar/SidebarBottomPanelToggleButton.vue'
 import SidebarSettingsButton from '@/components/sidebar/SidebarSettingsButton.vue'
 import SidebarShortcutsToggleButton from '@/components/sidebar/SidebarShortcutsToggleButton.vue'
-import { useFeatureFlags } from '@/composables/useFeatureFlags'
 import { isCloud } from '@/platform/distribution/types'
 import { useSettingStore } from '@/platform/settings/settingStore'
 import { useTelemetry } from '@/platform/telemetry'
 import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
 import { useCommandStore } from '@/stores/commandStore'
 import { useKeybindingStore } from '@/platform/keybindings/keybindingStore'
-import { useMenuItemStore } from '@/stores/menuItemStore'
 import { useUserStore } from '@/stores/userStore'
 import { useWorkspaceStore } from '@/stores/workspaceStore'
 import type { SidebarTabExtension } from '@/types/extensionTypes'
@@ -90,11 +84,9 @@ const settingStore = useSettingStore()
 const userStore = useUserStore()
 const commandStore = useCommandStore()
 const canvasStore = useCanvasStore()
-const menuItemStore = useMenuItemStore()
 const sideToolbarRef = ref<HTMLElement>()
 const topToolbarRef = ref<HTMLElement>()
 const bottomToolbarRef = ref<HTMLElement>()
-const { flags } = useFeatureFlags()
 
 const isSmall = computed(
   () => settingStore.get('Comfy.Sidebar.Size') === 'small'

src/components/topbar/CurrentUserPopoverLegacy.test.ts

@@ -57,7 +57,8 @@ vi.mock('@/composables/auth/useCurrentUser', () => ({
     userPhotoUrl: 'https://example.com/avatar.jpg',
     userDisplayName: 'Test User',
     userEmail: 'test@example.com',
-    handleSignOut: mockHandleSignOut
+    handleSignOut: mockHandleSignOut,
+    isApiKeyLogin: { value: false }
   }))
 }))
 

src/components/topbar/CurrentUserPopoverLegacy.vue

@@ -162,8 +162,13 @@ const emit = defineEmits<{
 
 const { buildDocsUrl, docsPaths } = useExternalLink()
 
-const { userDisplayName, userEmail, userPhotoUrl, handleSignOut } =
-  useCurrentUser()
+const {
+  userDisplayName,
+  userEmail,
+  userPhotoUrl,
+  handleSignOut,
+  isApiKeyLogin
+} = useCurrentUser()
 const authActions = useFirebaseAuthActions()
 const authStore = useFirebaseAuthStore()
 const settingsDialog = useSettingsDialog()
@@ -244,6 +249,8 @@ const handleSubscribed = async () => {
 }
 
 onMounted(() => {
-  void authActions.fetchBalance()
+  if (!isApiKeyLogin.value) {
+    void authActions.fetchBalance()
+  }
 })
 </script>

src/components/topbar/WorkflowTab.vue

@@ -1,36 +1,53 @@
 <template>
-  <div
-    ref="workflowTabRef"
-    class="workflow-tab group flex gap-2 p-2"
-    v-bind="$attrs"
-    @mouseenter="handleMouseEnter"
-    @mouseleave="handleMouseLeave"
-    @click="handleClick"
-  >
-    <i
-      v-if="workflowOption.workflow.activeState?.extra?.linearMode"
-      class="icon-[lucide--panels-top-left] bg-primary-background"
-    />
-    <span class="workflow-label inline-block max-w-[150px] truncate text-sm">
-      {{ workflowOption.workflow.filename }}
-    </span>
-    <div class="relative">
-      <span
-        v-if="shouldShowStatusIndicator"
-        class="absolute top-1/2 left-1/2 z-10 w-4 -translate-1/2 bg-(--comfy-menu-bg) text-2xl font-bold group-hover:hidden"
-        >•</span
+  <ContextMenuRoot>
+    <ContextMenuTrigger as-child>
+      <div
+        ref="workflowTabRef"
+        class="workflow-tab group flex gap-2 p-2"
+        v-bind="$attrs"
+        @mouseenter="handleMouseEnter"
+        @mouseleave="handleMouseLeave"
+        @click="handleClick"
       >
-      <Button
-        class="close-button invisible w-auto p-0"
-        variant="muted-textonly"
-        size="icon-sm"
-        :aria-label="t('g.close')"
-        @click.stop="onCloseWorkflow(workflowOption)"
+        <i
+          v-if="workflowOption.workflow.activeState?.extra?.linearMode"
+          class="icon-[lucide--panels-top-left] bg-primary-background"
+        />
+        <span
+          class="workflow-label inline-block max-w-[150px] truncate text-sm"
+        >
+          {{ workflowOption.workflow.filename }}
+        </span>
+        <div class="relative">
+          <span
+            v-if="shouldShowStatusIndicator"
+            class="absolute top-1/2 left-1/2 z-10 w-4 -translate-1/2 bg-(--comfy-menu-bg) text-2xl font-bold group-hover:hidden"
+            >•</span
+          >
+          <Button
+            class="close-button invisible w-auto p-0"
+            variant="muted-textonly"
+            size="icon-sm"
+            :aria-label="t('g.close')"
+            @click.stop="onCloseWorkflow(workflowOption)"
+          >
+            <i class="pi pi-times" />
+          </Button>
+        </div>
+      </div>
+    </ContextMenuTrigger>
+    <ContextMenuPortal>
+      <ContextMenuContent
+        class="z-1000 rounded-lg px-2 py-3 min-w-56 bg-base-background shadow-interface border border-border-subtle"
       >
-        <i class="pi pi-times" />
-      </Button>
-    </div>
-  </div>
+        <WorkflowActionsList
+          :items="contextMenuItems"
+          :item-component="ContextMenuItem"
+          :separator-component="ContextMenuSeparator"
+        />
+      </ContextMenuContent>
+    </ContextMenuPortal>
+  </ContextMenuRoot>
 
   <WorkflowTabPopover
     ref="popoverRef"
@@ -41,20 +58,32 @@
 </template>
 
 <script setup lang="ts">
+import {
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuPortal,
+  ContextMenuRoot,
+  ContextMenuSeparator,
+  ContextMenuTrigger
+} from 'reka-ui'
 import { computed, onUnmounted, ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 
+import WorkflowActionsList from '@/components/common/WorkflowActionsList.vue'
 import Button from '@/components/ui/button/Button.vue'
 import {
   usePragmaticDraggable,
   usePragmaticDroppable
 } from '@/composables/usePragmaticDragAndDrop'
+import { useWorkflowActionsMenu } from '@/composables/useWorkflowActionsMenu'
 import { useSettingStore } from '@/platform/settings/settingStore'
 import { useWorkflowService } from '@/platform/workflow/core/services/workflowService'
 import type { ComfyWorkflow } from '@/platform/workflow/management/stores/workflowStore'
 import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'
 import { useWorkflowThumbnail } from '@/renderer/core/thumbnail/useWorkflowThumbnail'
+import { useCommandStore } from '@/stores/commandStore'
 import { useWorkspaceStore } from '@/stores/workspaceStore'
+import type { WorkflowMenuItem } from '@/types/workflowMenuItem'
 
 import WorkflowTabPopover from './WorkflowTabPopover.vue'
 
@@ -65,6 +94,8 @@ interface WorkflowOption {
 
 const props = defineProps<{
   workflowOption: WorkflowOption
+  isFirst: boolean
+  isLast: boolean
 }>()
 
 const { t } = useI18n()
@@ -148,6 +179,67 @@ const closeWorkflows = async (options: WorkflowOption[]) => {
 const onCloseWorkflow = async (option: WorkflowOption) => {
   await closeWorkflows([option])
 }
+
+const emit = defineEmits<{
+  closeToLeft: []
+  closeToRight: []
+  closeOthers: []
+}>()
+
+const commandStore = useCommandStore()
+const workflow = computed(() => props.workflowOption.workflow)
+
+const { menuItems: baseMenuItems } = useWorkflowActionsMenu(
+  () => commandStore.execute('Comfy.RenameWorkflow'),
+  { includeDelete: false, workflow }
+)
+
+const contextMenuItems = computed<WorkflowMenuItem[]>(() => [
+  ...baseMenuItems.value,
+  { separator: true },
+  {
+    label: t('tabMenu.closeTab'),
+    icon: 'pi pi-times',
+    command: () => onCloseWorkflow(props.workflowOption)
+  },
+  {
+    label: t('tabMenu.closeTabsToLeft'),
+    overlayIcon: {
+      mainIcon: 'pi pi-times',
+      subIcon: 'pi pi-arrow-left',
+      positionX: 'right',
+      positionY: 'bottom',
+      subIconScale: 0.5
+    },
+    command: () => emit('closeToLeft'),
+    disabled: props.isFirst
+  },
+  {
+    label: t('tabMenu.closeTabsToRight'),
+    overlayIcon: {
+      mainIcon: 'pi pi-times',
+      subIcon: 'pi pi-arrow-right',
+      positionX: 'right',
+      positionY: 'bottom',
+      subIconScale: 0.5
+    },
+    command: () => emit('closeToRight'),
+    disabled: props.isLast
+  },
+  {
+    label: t('tabMenu.closeOtherTabs'),
+    overlayIcon: {
+      mainIcon: 'pi pi-times',
+      subIcon: 'pi pi-arrows-h',
+      positionX: 'right',
+      positionY: 'bottom',
+      subIconScale: 0.5
+    },
+    command: () => emit('closeOthers'),
+    disabled: props.isFirst && props.isLast
+  }
+])
+
 const tabGetter = () => workflowTabRef.value as HTMLElement
 
 usePragmaticDraggable(tabGetter, {

src/components/topbar/WorkflowTabs.vue

@@ -32,11 +32,20 @@
         data-key="value"
         @update:model-value="onWorkflowChange"
       >
-        <template #option="{ option }">
+        <template #option="{ option, index }">
           <WorkflowTab
             :workflow-option="option"
-            @contextmenu="showContextMenu($event, option)"
+            :is-first="index === 0"
+            :is-last="index === options.length - 1"
             @click.middle="onCloseWorkflow(option)"
+            @close-to-left="closeWorkflows(options.slice(0, index))"
+            @close-to-right="closeWorkflows(options.slice(index + 1))"
+            @close-others="
+              closeWorkflows([
+                ...options.slice(index + 1),
+                ...options.slice(0, index)
+              ])
+            "
           />
         </template>
       </SelectButton>
@@ -58,7 +67,10 @@
       :active-workflow="workflowStore.activeWorkflow"
     />
     <Button
-      v-tooltip="{ value: $t('sideToolbar.newBlankWorkflow'), showDelay: 300 }"
+      v-tooltip="{
+        value: $t('sideToolbar.newBlankWorkflow'),
+        showDelay: 300
+      }"
       class="new-blank-workflow-button no-drag shrink-0 rounded-none h-full w-auto aspect-square"
       variant="muted-textonly"
       size="icon"
@@ -80,27 +92,17 @@
       />
       <LoginButton v-else-if="isDesktop" class="p-1" />
     </div>
-    <ContextMenu ref="menu" :model="contextMenuItems">
-      <template #itemicon="{ item }">
-        <OverlayIcon v-if="item.overlayIcon" v-bind="item.overlayIcon" />
-        <i v-else-if="item.icon" :class="item.icon" />
-      </template>
-    </ContextMenu>
     <div v-if="isDesktop" class="window-actions-spacer app-drag shrink-0" />
   </div>
 </template>
 
 <script setup lang="ts">
 import { useScroll } from '@vueuse/core'
-import ContextMenu from 'primevue/contextmenu'
 import ScrollPanel from 'primevue/scrollpanel'
 import SelectButton from 'primevue/selectbutton'
 import { computed, nextTick, onUpdated, ref, watch } from 'vue'
 import type { WatchStopHandle } from 'vue'
-import { useI18n } from 'vue-i18n'
 
-import OverlayIcon from '@/components/common/OverlayIcon.vue'
-import type { OverlayIconProps } from '@/components/common/OverlayIcon.vue'
 import CurrentUserButton from '@/components/topbar/CurrentUserButton.vue'
 import LoginButton from '@/components/topbar/LoginButton.vue'
 import TopMenuHelpButton from '@/components/topbar/TopMenuHelpButton.vue'
@@ -108,7 +110,6 @@ import WorkflowTab from '@/components/topbar/WorkflowTab.vue'
 import Button from '@/components/ui/button/Button.vue'
 import { useCurrentUser } from '@/composables/auth/useCurrentUser'
 import { useOverflowObserver } from '@/composables/element/useOverflowObserver'
-import { useWorkflowActionsMenu } from '@/composables/useWorkflowActionsMenu'
 import { useSettingStore } from '@/platform/settings/settingStore'
 import { useWorkflowService } from '@/platform/workflow/core/services/workflowService'
 import type { ComfyWorkflow } from '@/platform/workflow/management/stores/workflowStore'
@@ -129,7 +130,6 @@ const props = defineProps<{
   class?: string
 }>()
 
-const { t } = useI18n()
 const settingStore = useSettingStore()
 const workspaceStore = useWorkspaceStore()
 const workflowStore = useWorkflowStore()
@@ -141,8 +141,6 @@ const isIntegratedTabBar = computed(
   () => settingStore.get('Comfy.UI.TabBarLayout') === 'Integrated'
 )
 
-const rightClickedTab = ref<WorkflowOption | undefined>()
-const menu = ref()
 const containerRef = ref<HTMLElement | null>(null)
 const showOverflowArrows = ref(false)
 const leftArrowEnabled = ref(false)
@@ -192,78 +190,6 @@ const onCloseWorkflow = async (option: WorkflowOption) => {
   await closeWorkflows([option])
 }
 
-const showContextMenu = (event: MouseEvent, option: WorkflowOption) => {
-  rightClickedTab.value = option
-  menu.value.show(event)
-}
-
-const rightClickedWorkflow = computed(
-  () => rightClickedTab.value?.workflow ?? null
-)
-
-const { menuItems: baseMenuItems } = useWorkflowActionsMenu(
-  () => commandStore.execute('Comfy.RenameWorkflow'),
-  {
-    includeDelete: false,
-    workflow: rightClickedWorkflow
-  }
-)
-
-const contextMenuItems = computed(() => {
-  const tab = rightClickedTab.value
-  if (!tab) return []
-  const index = options.value.findIndex((v) => v.workflow === tab.workflow)
-
-  return [
-    ...baseMenuItems.value,
-    {
-      label: t('tabMenu.closeTab'),
-      icon: 'pi pi-times',
-      command: () => onCloseWorkflow(tab)
-    },
-    {
-      label: t('tabMenu.closeTabsToLeft'),
-      overlayIcon: {
-        mainIcon: 'pi pi-times',
-        subIcon: 'pi pi-arrow-left',
-        positionX: 'right',
-        positionY: 'bottom',
-        subIconScale: 0.5
-      } as OverlayIconProps,
-      command: () => closeWorkflows(options.value.slice(0, index)),
-      disabled: index <= 0
-    },
-    {
-      label: t('tabMenu.closeTabsToRight'),
-      overlayIcon: {
-        mainIcon: 'pi pi-times',
-        subIcon: 'pi pi-arrow-right',
-        positionX: 'right',
-        positionY: 'bottom',
-        subIconScale: 0.5
-      } as OverlayIconProps,
-      command: () => closeWorkflows(options.value.slice(index + 1)),
-      disabled: index === options.value.length - 1
-    },
-    {
-      label: t('tabMenu.closeOtherTabs'),
-      overlayIcon: {
-        mainIcon: 'pi pi-times',
-        subIcon: 'pi pi-arrows-h',
-        positionX: 'right',
-        positionY: 'bottom',
-        subIconScale: 0.5
-      } as OverlayIconProps,
-      command: () =>
-        closeWorkflows([
-          ...options.value.slice(index + 1),
-          ...options.value.slice(0, index)
-        ]),
-      disabled: options.value.length <= 1
-    }
-  ]
-})
-
 // Horizontal scroll on wheel
 const handleWheel = (event: WheelEvent) => {
   const scrollElement = event.currentTarget as HTMLElement

src/composables/README.md

@@ -245,10 +245,10 @@ General-purpose composables:
 | `useServerLogs`             | Manages server log display                                |
 | `useTemplateWorkflows`      | Manages template workflow loading, selection, and display |
 | `useTreeExpansion`          | Handles tree node expansion state                         |
-| `useValueTransform`         | Transforms values between formats                         |
-| `useWorkflowAutoSave`       | Handles automatic workflow saving                         |
-| `useWorkflowPersistence`    | Manages workflow persistence                              |
-| `useWorkflowValidation`     | Validates workflow integrity                              |
+
+| `useWorkflowAutoSave` | Handles automatic workflow saving |
+| `useWorkflowPersistence` | Manages workflow persistence |
+| `useWorkflowValidation` | Validates workflow integrity |
 
 ## Usage Guidelines
 

src/composables/canvas/useSelectedLiteGraphItems.test.ts

@@ -20,16 +20,15 @@ vi.mock('@/scripts/app', () => ({
 }))
 
 // Mock the litegraph module
-vi.mock('@/lib/litegraph/src/litegraph', () => ({
-  Reroute: class Reroute {
-    constructor() {}
-  },
-  LGraphEventMode: {
-    ALWAYS: 0,
-    NEVER: 2,
-    BYPASS: 4
+vi.mock('@/lib/litegraph/src/litegraph', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>
+  return {
+    ...actual,
+    Reroute: class Reroute {
+      constructor() {}
+    }
   }
-}))
+})
 
 // Mock Positionable objects
 

src/composables/graph/useGraphNodeManager.test.ts

@@ -5,7 +5,12 @@ import { computed, nextTick, watch } from 'vue'
 
 import { useGraphNodeManager } from '@/composables/graph/useGraphNodeManager'
 import { BaseWidget, LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph'
+import {
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
 import { NodeSlotType } from '@/lib/litegraph/src/types/globalEnums'
+import { usePromotionStore } from '@/stores/promotionStore'
 import { useWidgetValueStore } from '@/stores/widgetValueStore'
 
 describe('Node Reactivity', () => {
@@ -26,7 +31,7 @@ describe('Node Reactivity', () => {
   }
 
   it('widget values are reactive through the store', async () => {
-    const { node } = createTestGraph()
+    const { node, graph } = createTestGraph()
     const store = useWidgetValueStore()
     const widget = node.widgets![0]
 
@@ -36,12 +41,13 @@ describe('Node Reactivity', () => {
     expect((widget as BaseWidget).node.id).toBe(node.id)
 
     // Initial value should be in store after setNodeId was called
-    expect(store.getWidget(node.id, 'testnum')?.value).toBe(2)
+    expect(store.getWidget(graph.id, node.id, 'testnum')?.value).toBe(2)
+
+    const state = store.getWidget(graph.id, node.id, 'testnum')
+    if (!state) throw new Error('Expected widget state to exist')
 
     const onValueChange = vi.fn()
-    const widgetValue = computed(
-      () => store.getWidget(node.id, 'testnum')?.value
-    )
+    const widgetValue = computed(() => state.value)
     watch(widgetValue, onValueChange)
 
     widget.value = 42
@@ -62,9 +68,10 @@ describe('Node Reactivity', () => {
     })
     await nextTick()
 
-    const widgetValue = computed(
-      () => store.getWidget(node.id, 'testnum')?.value
-    )
+    const state = store.getWidget(graph.id, node.id, 'testnum')
+    if (!state) throw new Error('Expected widget state to exist')
+
+    const widgetValue = computed(() => state.value)
     watch(widgetValue, onValueChange)
 
     node.widgets![0].value = 99
@@ -74,3 +81,36 @@ describe('Node Reactivity', () => {
     expect(widgetValue.value).toBe(99)
   })
 })
+
+describe('Subgraph Promoted Pseudo Widgets', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  it('marks promoted $$ widgets as canvasOnly for Vue widget rendering', () => {
+    const subgraph = createTestSubgraph()
+    const interiorNode = new LGraphNode('interior')
+    interiorNode.id = 10
+    subgraph.add(interiorNode)
+
+    const subgraphNode = createTestSubgraphNode(subgraph, { id: 123 })
+    const graph = subgraphNode.graph as LGraph
+    graph.add(subgraphNode)
+
+    usePromotionStore().promote(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      '10',
+      '$$canvas-image-preview'
+    )
+
+    const { vueNodeData } = useGraphNodeManager(graph)
+    const vueNode = vueNodeData.get(String(subgraphNode.id))
+    const promotedWidget = vueNode?.widgets?.find(
+      (widget) => widget.name === '$$canvas-image-preview'
+    )
+
+    expect(promotedWidget).toBeDefined()
+    expect(promotedWidget?.options?.canvasOnly).toBe(true)
+  })
+})