feat: synthetic widgets getter for SubgraphNode (proxy-widget-v2) (#8856)

## Summary

Replace the Proxy-based proxy widget system with a store-driven
architecture where `promotionStore` and `widgetValueStore` are the
single sources of truth for subgraph widget promotion and widget values,
and `SubgraphNode.widgets` is a synthetic getter composing lightweight
`PromotedWidgetView` objects from store state.

## Motivation

The subgraph widget promotion system previously scattered state across
multiple unsynchronized layers:

- **Persistence**: `node.properties.proxyWidgets` (tuples on the
LiteGraph node)
- **Runtime**: Proxy-based `proxyWidget.ts` with `Overlay` objects,
`DisconnectedWidget` singleton, and `isProxyWidget` type guards
- **UI**: Each Vue component independently calling `parseProxyWidgets()`
via `customRef` hacks
- **Mutation flags**: Imperative `widget.promoted = true/false` set on
`subgraph-opened` events

This led to 4+ independent parsings of the same data, complex cache
invalidation, and no reactive contract between the promotion state and
the rendering layer. Widget values were similarly owned by LiteGraph
with no Vue-reactive backing.

The core principle driving these changes: **Vue owns truth**. Pinia
stores are the canonical source; LiteGraph objects delegate to stores
via getters/setters; Vue components react to store state directly.

## Changes

### New stores (single sources of truth)

- **`promotionStore`** — Reactive `Map<NodeId, PromotionEntry[]>`
tracking which interior widgets are promoted on which SubgraphNode
instances. Graph-scoped by root graph ID to prevent cross-workflow state
collision. Replaces `properties.proxyWidgets` parsing, `customRef`
hacks, `widget.promoted` mutation, and the `subgraph-opened` event
listener.
- **`widgetValueStore`** — Graph-scoped `Map<WidgetKey, WidgetState>`
that is the canonical owner of widget values. `BaseWidget.value`
delegates to this store via getter/setter when a node ID is assigned.
Eliminates the need for Proxy-based value forwarding.

### Synthetic widgets getter (SubgraphNode)

`SubgraphNode.widgets` is now a getter that reads
`promotionStore.getPromotions(rootGraphId, nodeId)` and returns cached
`PromotedWidgetView` objects. No stubs, no Proxies, no fake widgets
persisted in the array. The setter is a no-op — mutations go through
`promotionStore`.

### PromotedWidgetView

A class behind a `createPromotedWidgetView` factory, implementing the
`PromotedWidgetView` interface. Delegates value/type/options/drawing to
the resolved interior widget and stores. Owns positional state (`y`,
`computedHeight`) for canvas layout. Cached by
`PromotedWidgetViewManager` for object-identity stability across frames.

### DOM widget promotion

Promoted DOM widgets (textarea, image upload, etc.) render on the
SubgraphNode surface via `positionOverride` in `domWidgetStore`.
`DomWidgets.vue` checks for overrides and uses the SubgraphNode's
coordinates instead of the interior node's.

### Promoted previews

New `usePromotedPreviews` composable resolves image/audio/video preview
widgets from promoted entries, enabling SubgraphNodes to display
previews of interior preview nodes.

### Deleted

- `proxyWidget.ts` (257 lines) — Proxy handler, `Overlay`,
`newProxyWidget`, `isProxyWidget`
- `DisconnectedWidget.ts` (39 lines) — Singleton Proxy target
- `useValueTransform.ts` (32 lines) — Replaced by store delegation

### Key architectural changes

- `BaseWidget.value` getter/setter delegates to `widgetValueStore` when
node ID is set
- `LGraph.add()` reordered: `node.graph` assigned before widget
`setNodeId` (enables store registration)
- `LGraph.clear()` cleans up graph-scoped stores to prevent stale
entries across workflow switches
- `promotionStore` and `widgetValueStore` state nested under root graph
UUID for multi-workflow isolation
- `SubgraphNode.serialize()` writes promotions back to
`properties.proxyWidgets` for persistence compatibility
- Legacy `-1` promotion entries resolved and migrated on first load with
dev warning

## Test coverage

- **3,700+ lines of new/updated tests** across 36 test files
- **Unit**: `promotionStore.test.ts`, `widgetValueStore.test.ts`,
`promotedWidgetView.test.ts` (921 lines),
`subgraphNodePromotion.test.ts`, `proxyWidgetUtils.test.ts`,
`DomWidgets.test.ts`, `PromotedWidgetViewManager.test.ts`,
`usePromotedPreviews.test.ts`, `resolvePromotedWidget.test.ts`,
`subgraphPseudoWidgetCache.test.ts`
- **E2E**: `subgraphPromotion.spec.ts` (622 lines) — promote/demote,
manual/auto promotion, paste preservation, seed control augmentation,
image preview promotion; `imagePreview.spec.ts` extended with
multi-promoted-preview coverage
- **Fixtures**: 2 new subgraph workflow fixtures for preview promotion
scenarios

## Review focus

- Graph-scoped store keying (`rootGraphId`) — verify isolation across
workflows/tabs and cleanup on `LGraph.clear()`
- `PromotedWidgetView` positional stability — `_arrangeWidgets` writes
to `y`/`computedHeight` on cached objects; getter returns fresh array
but stable object references
- DOM widget position override lifecycle — overrides set on promote,
cleared on demote/removal/subgraph navigation
- Legacy `-1` entry migration — resolved and written back on first load;
unresolvable entries dropped with dev warning
- Serialization round-trip — `promotionStore` state →
`properties.proxyWidgets` on serialize, hydrated back on configure

## Diff breakdown (excluding lockfile)

- 153 files changed, ~7,500 insertions, ~1,900 deletions (excluding
pnpm-lock.yaml churn)
- ~3,700 lines are tests
- ~300 lines deleted (proxyWidget.ts, DisconnectedWidget.ts,
useValueTransform.ts)

<!-- Fixes #ISSUE_NUMBER -->

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-8856-feat-synthetic-widgets-getter-for-SubgraphNode-proxy-widget-v2-3076d73d365081c7b517f5ec7cb514f3)
by [Unito](https://www.unito.io)

---------

Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: GitHub Action <action@github.com>

.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

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.

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'
           )

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/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[]) {

src/components/breadcrumb/SubgraphBreadcrumb.vue

@@ -1,6 +1,7 @@
 <template>
   <div
-    class="subgraph-breadcrumb flex w-auto drop-shadow-[var(--interface-panel-drop-shadow)] items-center"
+    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

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/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/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'
@@ -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/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)

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/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)
+  })
+})

src/composables/graph/useGraphNodeManager.ts

@@ -6,7 +6,8 @@ import { reactiveComputed } from '@vueuse/core'
 import { reactive, shallowReactive } from 'vue'
 
 import { useChainCallback } from '@/composables/functional/useChainCallback'
-import { isProxyWidget } from '@/core/graph/subgraph/proxyWidget'
+import { isPromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetTypes'
+import { resolvePromotedWidgetSource } from '@/core/graph/subgraph/resolvePromotedWidgetSource'
 import type {
   INodeInputSlot,
   INodeOutputSlot
@@ -108,7 +109,21 @@ export interface GraphNodeManager {
   cleanup(): void
 }
 
-function getControlWidget(widget: IBaseWidget): SafeControlWidget | undefined {
+function isPromotedDOMWidget(widget: IBaseWidget): boolean {
+  if (!isPromotedWidgetView(widget)) return false
+  const sourceWidget = resolvePromotedWidgetSource(widget.node, widget)
+  if (!sourceWidget) return false
+
+  const innerWidget = sourceWidget.widget
+  return (
+    ('element' in innerWidget && !!innerWidget.element) ||
+    ('component' in innerWidget && !!innerWidget.component)
+  )
+}
+
+export function getControlWidget(
+  widget: IBaseWidget
+): SafeControlWidget | undefined {
   const cagWidget = widget.linkedWidgets?.find(
     (w) => w.name == 'control_after_generate'
   )
@@ -119,22 +134,12 @@ function getControlWidget(widget: IBaseWidget): SafeControlWidget | undefined {
   }
 }
 
-/**
- * Shared widget enhancements used by both safeWidgetMapper and Right Side Panel
- */
 interface SharedWidgetEnhancements {
-  /** Control widget for seed randomization/increment/decrement */
   controlWidget?: SafeControlWidget
-  /** Input specification from node definition */
   spec?: InputSpec
 }
 
-/**
- * Extracts common widget enhancements shared across different rendering contexts.
- * This function centralizes the logic for extracting metadata from widgets.
- * Note: Value and metadata (label, options, hidden, etc.) are accessed via widgetValueStore.
- */
-export function getSharedWidgetEnhancements(
+function getSharedWidgetEnhancements(
   node: LGraphNode,
   widget: IBaseWidget
 ): SharedWidgetEnhancements {
@@ -199,6 +204,9 @@ function safeWidgetMapper(
         node.widgets?.forEach((w) => w.triggerDraw?.())
       }
 
+      const isPromotedPseudoWidget =
+        isPromotedWidgetView(widget) && widget.sourceWidgetName.startsWith('$$')
+
       // Extract only render-critical options (canvasOnly, advanced, read_only)
       const options = widget.options
         ? {
@@ -210,13 +218,13 @@ function safeWidgetMapper(
         : undefined
       const subgraphId = node.isSubgraphNode() && node.subgraph.id
 
-      const localId = isProxyWidget(widget)
-        ? widget._overlay?.nodeId
+      const localId = isPromotedWidgetView(widget)
+        ? widget.sourceNodeId
         : undefined
       const nodeId =
         subgraphId && localId ? `${subgraphId}:${localId}` : undefined
-      const name = isProxyWidget(widget)
-        ? widget._overlay.widgetName
+      const name = isPromotedWidgetView(widget)
+        ? widget.sourceWidgetName
         : widget.name
 
       return {
@@ -226,8 +234,10 @@ function safeWidgetMapper(
         ...sharedEnhancements,
         callback,
         hasLayoutSize: typeof widget.computeLayoutSize === 'function',
-        isDOMWidget: isDOMWidget(widget),
-        options,
+        isDOMWidget: isDOMWidget(widget) || isPromotedDOMWidget(widget),
+        options: isPromotedPseudoWidget
+          ? { ...options, canvasOnly: true }
+          : options,
         slotMetadata: slotInfo
       }
     } catch (error) {
@@ -249,15 +259,40 @@ export function extractVueNodeData(node: LGraphNode): VueNodeData {
   // Extract safe widget data
   const slotMetadata = new Map<string, WidgetSlotMetadata>()
 
+  const existingWidgetsDescriptor = Object.getOwnPropertyDescriptor(
+    node,
+    'widgets'
+  )
   const reactiveWidgets = shallowReactive<IBaseWidget[]>(node.widgets ?? [])
-  Object.defineProperty(node, 'widgets', {
-    get() {
-      return reactiveWidgets
-    },
-    set(v) {
-      reactiveWidgets.splice(0, reactiveWidgets.length, ...v)
-    }
-  })
+  if (existingWidgetsDescriptor?.get) {
+    // Node has a custom widgets getter (e.g. SubgraphNode's synthetic getter).
+    // Preserve it but sync results into a reactive array for Vue.
+    const originalGetter = existingWidgetsDescriptor.get
+    Object.defineProperty(node, 'widgets', {
+      get() {
+        const current: IBaseWidget[] = originalGetter.call(node) ?? []
+        if (
+          current.length !== reactiveWidgets.length ||
+          current.some((w, i) => w !== reactiveWidgets[i])
+        ) {
+          reactiveWidgets.splice(0, reactiveWidgets.length, ...current)
+        }
+        return reactiveWidgets
+      },
+      set: existingWidgetsDescriptor.set ?? (() => {}),
+      configurable: true,
+      enumerable: true
+    })
+  } else {
+    Object.defineProperty(node, 'widgets', {
+      get() {
+        return reactiveWidgets
+      },
+      set(v) {
+        reactiveWidgets.splice(0, reactiveWidgets.length, ...v)
+      }
+    })
+  }
   const reactiveInputs = shallowReactive<INodeInputSlot[]>(node.inputs ?? [])
   Object.defineProperty(node, 'inputs', {
     get() {

src/composables/node/useNodeCanvasImagePreview.test.ts

@@ -0,0 +1,68 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import {
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
+
+import { useNodeCanvasImagePreview } from './useNodeCanvasImagePreview'
+
+const imagePreviewWidget = vi.hoisted(() => vi.fn())
+
+vi.mock(
+  '@/renderer/extensions/vueNodes/widgets/composables/useImagePreviewWidget',
+  () => ({
+    useImagePreviewWidget: () => imagePreviewWidget
+  })
+)
+
+describe('useNodeCanvasImagePreview', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    vi.clearAllMocks()
+  })
+
+  it('does not add preview widget when node has no images', () => {
+    const node = new LGraphNode('test')
+
+    useNodeCanvasImagePreview().showCanvasImagePreview(node)
+
+    expect(imagePreviewWidget).not.toHaveBeenCalled()
+  })
+
+  it('adds preview widget for regular nodes with images', () => {
+    const node = new LGraphNode('test')
+    node.imgs = [new Image()]
+
+    useNodeCanvasImagePreview().showCanvasImagePreview(node)
+
+    expect(imagePreviewWidget).toHaveBeenCalledTimes(1)
+    expect(imagePreviewWidget).toHaveBeenCalledWith(node, {
+      type: 'IMAGE_PREVIEW',
+      name: '$$canvas-image-preview'
+    })
+  })
+
+  it('does not add duplicate preview widget when already present', () => {
+    const node = new LGraphNode('test')
+    node.imgs = [new Image()]
+    node.addWidget('text', '$$canvas-image-preview', '', () => undefined, {})
+
+    useNodeCanvasImagePreview().showCanvasImagePreview(node)
+
+    expect(imagePreviewWidget).not.toHaveBeenCalled()
+  })
+
+  it('does not add preview widget directly on SubgraphNode', () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    subgraphNode.imgs = [new Image()]
+
+    useNodeCanvasImagePreview().showCanvasImagePreview(subgraphNode)
+
+    expect(imagePreviewWidget).not.toHaveBeenCalled()
+  })
+})

src/composables/node/useNodeCanvasImagePreview.ts

@@ -1,7 +1,12 @@
 import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
 import { useImagePreviewWidget } from '@/renderer/extensions/vueNodes/widgets/composables/useImagePreviewWidget'
 
-const CANVAS_IMAGE_PREVIEW_WIDGET = '$$canvas-image-preview'
+export const CANVAS_IMAGE_PREVIEW_WIDGET = '$$canvas-image-preview'
+const CANVAS_IMAGE_PREVIEW_NODE_TYPES = new Set(['PreviewImage', 'SaveImage'])
+
+export function supportsVirtualCanvasImagePreview(node: LGraphNode): boolean {
+  return CANVAS_IMAGE_PREVIEW_NODE_TYPES.has(node.type)
+}
 
 /**
  * Composable for handling canvas image previews in nodes
@@ -15,6 +20,8 @@ export function useNodeCanvasImagePreview() {
   function showCanvasImagePreview(node: LGraphNode) {
     if (!node.imgs?.length) return
 
+    if (node.isSubgraphNode()) return
+
     if (!node.widgets?.find((w) => w.name === CANVAS_IMAGE_PREVIEW_WIDGET)) {
       imagePreviewWidget(node, {
         type: 'IMAGE_PREVIEW',

src/composables/node/usePromotedPreviews.test.ts

@@ -0,0 +1,262 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { reactive } from 'vue'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import {
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
+import { useNodeOutputStore } from '@/stores/imagePreviewStore'
+import { usePromotionStore } from '@/stores/promotionStore'
+import { createNodeLocatorId } from '@/types/nodeIdentification'
+
+import { usePromotedPreviews } from './usePromotedPreviews'
+
+type MockNodeOutputStore = Pick<
+  ReturnType<typeof useNodeOutputStore>,
+  'nodeOutputs' | 'getNodeImageUrls'
+>
+
+const getNodeImageUrls = vi.hoisted(() =>
+  vi.fn<MockNodeOutputStore['getNodeImageUrls']>()
+)
+const useNodeOutputStoreMock = vi.hoisted(() =>
+  vi.fn<() => MockNodeOutputStore>()
+)
+
+vi.mock('@/stores/imagePreviewStore', () => {
+  return {
+    useNodeOutputStore: useNodeOutputStoreMock
+  }
+})
+
+function createMockNodeOutputStore(): MockNodeOutputStore {
+  return {
+    nodeOutputs: reactive<MockNodeOutputStore['nodeOutputs']>({}),
+    getNodeImageUrls
+  }
+}
+
+function createSetup() {
+  const subgraph = createTestSubgraph()
+  const subgraphNode = createTestSubgraphNode(subgraph)
+  return { subgraph, subgraphNode }
+}
+
+function addInteriorNode(
+  setup: ReturnType<typeof createSetup>,
+  options: {
+    id: number
+    previewMediaType?: 'image' | 'video' | 'audio' | 'model'
+  } = { id: 10 }
+): LGraphNode {
+  const node = new LGraphNode('test')
+  node.id = options.id
+  if (options.previewMediaType) {
+    node.previewMediaType = options.previewMediaType
+  }
+  setup.subgraph.add(node)
+  return node
+}
+
+function seedOutputs(subgraphId: string, nodeIds: Array<number | string>) {
+  const store = useNodeOutputStore()
+  for (const nodeId of nodeIds) {
+    const locatorId = createNodeLocatorId(subgraphId, nodeId)
+    store.nodeOutputs[locatorId] = {
+      images: [{ filename: 'output.png' }]
+    }
+  }
+}
+
+describe(usePromotedPreviews, () => {
+  let nodeOutputStore: MockNodeOutputStore
+
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    vi.clearAllMocks()
+
+    nodeOutputStore = createMockNodeOutputStore()
+    useNodeOutputStoreMock.mockReturnValue(nodeOutputStore)
+  })
+
+  it('returns empty array for non-SubgraphNode', () => {
+    const node = new LGraphNode('test')
+    const { promotedPreviews } = usePromotedPreviews(() => node)
+    expect(promotedPreviews.value).toEqual([])
+  })
+
+  it('returns empty array for null node', () => {
+    const { promotedPreviews } = usePromotedPreviews(() => null)
+    expect(promotedPreviews.value).toEqual([])
+  })
+
+  it('returns empty array when no $$ promotions exist', () => {
+    const setup = createSetup()
+    addInteriorNode(setup, { id: 10 })
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      'seed'
+    )
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value).toEqual([])
+  })
+
+  it('returns image preview for promoted $$ widget with outputs', () => {
+    const setup = createSetup()
+    addInteriorNode(setup, { id: 10, previewMediaType: 'image' })
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      '$$canvas-image-preview'
+    )
+
+    const mockUrls = ['/view?filename=output.png']
+    seedOutputs(setup.subgraph.id, [10])
+    vi.mocked(useNodeOutputStore().getNodeImageUrls).mockReturnValue(mockUrls)
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value).toEqual([
+      {
+        interiorNodeId: '10',
+        widgetName: '$$canvas-image-preview',
+        type: 'image',
+        urls: mockUrls
+      }
+    ])
+  })
+
+  it('returns video type when interior node has video previewMediaType', () => {
+    const setup = createSetup()
+    addInteriorNode(setup, { id: 10, previewMediaType: 'video' })
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      '$$canvas-image-preview'
+    )
+
+    seedOutputs(setup.subgraph.id, [10])
+    vi.mocked(useNodeOutputStore().getNodeImageUrls).mockReturnValue([
+      '/view?filename=output.webm'
+    ])
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value[0].type).toBe('video')
+  })
+
+  it('returns audio type when interior node has audio previewMediaType', () => {
+    const setup = createSetup()
+    addInteriorNode(setup, { id: 10, previewMediaType: 'audio' })
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      '$$canvas-image-preview'
+    )
+
+    seedOutputs(setup.subgraph.id, [10])
+    vi.mocked(useNodeOutputStore().getNodeImageUrls).mockReturnValue([
+      '/view?filename=output.mp3'
+    ])
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value[0].type).toBe('audio')
+  })
+
+  it('returns separate entries for multiple promoted $$ widgets', () => {
+    const setup = createSetup()
+    const node10 = addInteriorNode(setup, {
+      id: 10,
+      previewMediaType: 'image'
+    })
+    const node20 = addInteriorNode(setup, {
+      id: 20,
+      previewMediaType: 'image'
+    })
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      '$$canvas-image-preview'
+    )
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '20',
+      '$$canvas-image-preview'
+    )
+
+    seedOutputs(setup.subgraph.id, [10, 20])
+    vi.mocked(useNodeOutputStore().getNodeImageUrls).mockImplementation(
+      (node: LGraphNode) => {
+        if (node === node10) return ['/view?a=1']
+        if (node === node20) return ['/view?b=2']
+        return undefined
+      }
+    )
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value).toHaveLength(2)
+    expect(promotedPreviews.value[0].urls).toEqual(['/view?a=1'])
+    expect(promotedPreviews.value[1].urls).toEqual(['/view?b=2'])
+  })
+
+  it('skips interior nodes with no image output', () => {
+    const setup = createSetup()
+    addInteriorNode(setup, { id: 10 })
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      '$$canvas-image-preview'
+    )
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value).toEqual([])
+  })
+
+  it('skips missing interior nodes', () => {
+    const setup = createSetup()
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '99',
+      '$$canvas-image-preview'
+    )
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value).toEqual([])
+  })
+
+  it('ignores non-$$ promoted widgets', () => {
+    const setup = createSetup()
+    addInteriorNode(setup, { id: 10 })
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      'seed'
+    )
+    usePromotionStore().promote(
+      setup.subgraphNode.rootGraph.id,
+      setup.subgraphNode.id,
+      '10',
+      '$$canvas-image-preview'
+    )
+
+    const mockUrls = ['/view?filename=img.png']
+    seedOutputs(setup.subgraph.id, [10])
+    vi.mocked(useNodeOutputStore().getNodeImageUrls).mockReturnValue(mockUrls)
+
+    const { promotedPreviews } = usePromotedPreviews(() => setup.subgraphNode)
+    expect(promotedPreviews.value).toHaveLength(1)
+    expect(promotedPreviews.value[0].urls).toEqual(mockUrls)
+  })
+})

src/composables/node/usePromotedPreviews.ts

@@ -0,0 +1,75 @@
+import type { MaybeRefOrGetter } from 'vue'
+import { computed, toValue } from 'vue'
+
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
+import { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
+import { useNodeOutputStore } from '@/stores/imagePreviewStore'
+import { usePromotionStore } from '@/stores/promotionStore'
+import { createNodeLocatorId } from '@/types/nodeIdentification'
+
+interface PromotedPreview {
+  interiorNodeId: string
+  widgetName: string
+  type: 'image' | 'video' | 'audio'
+  urls: string[]
+}
+
+/**
+ * Returns reactive preview media from promoted `$$` pseudo-widgets
+ * on a SubgraphNode. Each promoted preview interior node produces
+ * a separate entry so they render independently.
+ */
+export function usePromotedPreviews(
+  lgraphNode: MaybeRefOrGetter<LGraphNode | null | undefined>
+) {
+  const promotionStore = usePromotionStore()
+  const nodeOutputStore = useNodeOutputStore()
+
+  const promotedPreviews = computed((): PromotedPreview[] => {
+    const node = toValue(lgraphNode)
+    if (!(node instanceof SubgraphNode)) return []
+
+    const entries = promotionStore.getPromotions(node.rootGraph.id, node.id)
+    const pseudoEntries = entries.filter((e) => e.widgetName.startsWith('$$'))
+    if (!pseudoEntries.length) return []
+
+    const previews: PromotedPreview[] = []
+
+    for (const entry of pseudoEntries) {
+      const interiorNode = node.subgraph.getNodeById(entry.interiorNodeId)
+      if (!interiorNode) continue
+
+      // Read from the reactive nodeOutputs ref to establish Vue
+      // dependency tracking. getNodeImageUrls reads from the
+      // non-reactive app.nodeOutputs, so without this access the
+      // computed would never re-evaluate when outputs change.
+      const locatorId = createNodeLocatorId(
+        node.subgraph.id,
+        entry.interiorNodeId
+      )
+      const _reactiveOutputs = nodeOutputStore.nodeOutputs[locatorId]
+      if (!_reactiveOutputs?.images?.length) continue
+
+      const urls = nodeOutputStore.getNodeImageUrls(interiorNode)
+      if (!urls?.length) continue
+
+      const type =
+        interiorNode.previewMediaType === 'video'
+          ? 'video'
+          : interiorNode.previewMediaType === 'audio'
+            ? 'audio'
+            : 'image'
+
+      previews.push({
+        interiorNodeId: entry.interiorNodeId,
+        widgetName: entry.widgetName,
+        type,
+        urls
+      })
+    }
+
+    return previews
+  })
+
+  return { promotedPreviews }
+}

src/composables/useCoreCommands.ts

@@ -9,7 +9,7 @@ import {
   DEFAULT_LIGHT_COLOR_PALETTE
 } from '@/constants/coreColorPalettes'
 
-import { tryToggleWidgetPromotion } from '@/core/graph/subgraph/proxyWidgetUtils'
+import { tryToggleWidgetPromotion } from '@/core/graph/subgraph/promotionUtils'
 import { t } from '@/i18n'
 import {
   LGraphEventMode,

src/composables/useValueTransform.ts

@@ -1,32 +0,0 @@
-/**
- * Creates a getter/setter pair that transforms values on access if they have changed.
- * Does not observe deep changes.
- *
- * @example
- * const transformFunction = (items: string[]) => items.map(item => `root/${item}.ext`)
- * const { get, set } = useValueTransform(transformFunction, [])
- * Object.defineProperty(obj, 'value', { get, set })
- *
- * obj.value = ['filename1', 'filename2']
- * console.log(obj.value) // ["root/filename1.ext", "root/filename2.ext"]
- */
-export function useValueTransform<Internal, External>(
-  transform: (value: Internal) => External,
-  initialValue: Internal
-) {
-  let internalValue: Internal = initialValue
-  let cachedValue: External = transform(initialValue)
-  let isChanged = false
-
-  return {
-    get: () => {
-      if (!isChanged) return cachedValue
-      cachedValue = transform(internalValue)
-      return cachedValue
-    },
-    set: (value: Internal) => {
-      isChanged = true
-      internalValue = value
-    }
-  }
-}

src/core/graph/subgraph/promotedWidgetTypes.ts

@@ -0,0 +1,14 @@
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
+
+export interface PromotedWidgetView extends IBaseWidget {
+  readonly node: SubgraphNode
+  readonly sourceNodeId: string
+  readonly sourceWidgetName: string
+}
+
+export function isPromotedWidgetView(
+  widget: IBaseWidget
+): widget is PromotedWidgetView {
+  return 'sourceNodeId' in widget && 'sourceWidgetName' in widget
+}

src/core/graph/subgraph/promotedWidgetView.test.ts

@@ -0,0 +1,921 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+// Barrel import must come first to avoid circular dependency
+// (promotedWidgetView → widgetMap → BaseWidget → LegacyWidget → barrel)
+import {
+  CanvasPointer,
+  LGraphNode,
+  LiteGraph
+} from '@/lib/litegraph/src/litegraph'
+import type {
+  CanvasPointerEvent,
+  SubgraphNode
+} from '@/lib/litegraph/src/litegraph'
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+
+import { createPromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetView'
+import type { PromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetView'
+import { usePromotionStore } from '@/stores/promotionStore'
+import { useWidgetValueStore } from '@/stores/widgetValueStore'
+
+import {
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
+
+vi.mock('@/renderer/core/canvas/canvasStore', () => ({
+  useCanvasStore: () => ({})
+}))
+const mockDomWidgetStore = vi.hoisted(() => ({
+  widgetStates: new Map(),
+  setPositionOverride: vi.fn(),
+  clearPositionOverride: vi.fn()
+}))
+vi.mock('@/stores/domWidgetStore', () => ({
+  useDomWidgetStore: () => mockDomWidgetStore
+}))
+vi.mock('@/services/litegraphService', () => ({
+  useLitegraphService: () => ({ updatePreviews: () => ({}) })
+}))
+
+function setupSubgraph(
+  innerNodeCount: number = 0
+): [SubgraphNode, LGraphNode[]] {
+  const subgraph = createTestSubgraph()
+  const subgraphNode = createTestSubgraphNode(subgraph)
+  subgraphNode._internalConfigureAfterSlots()
+  const graph = subgraphNode.graph!
+  graph.add(subgraphNode)
+  const innerNodes: LGraphNode[] = []
+  for (let i = 0; i < innerNodeCount; i++) {
+    const innerNode = new LGraphNode(`InnerNode${i}`)
+    subgraph.add(innerNode)
+    innerNodes.push(innerNode)
+  }
+  return [subgraphNode, innerNodes]
+}
+
+function setPromotions(
+  subgraphNode: SubgraphNode,
+  entries: [string, string][]
+) {
+  usePromotionStore().setPromotions(
+    subgraphNode.rootGraph.id,
+    subgraphNode.id,
+    entries.map(([interiorNodeId, widgetName]) => ({
+      interiorNodeId,
+      widgetName
+    }))
+  )
+}
+
+function firstInnerNode(innerNodes: LGraphNode[]): LGraphNode {
+  const innerNode = innerNodes[0]
+  if (!innerNode) throw new Error('Expected at least one inner node')
+  return innerNode
+}
+
+describe(createPromotedWidgetView, () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    mockDomWidgetStore.widgetStates.clear()
+    vi.clearAllMocks()
+  })
+
+  test('exposes sourceNodeId and sourceWidgetName', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '42', 'myWidget')
+    expect(view.sourceNodeId).toBe('42')
+    expect(view.sourceWidgetName).toBe('myWidget')
+  })
+
+  test('name defaults to widgetName when no displayName given', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '1', 'myWidget')
+    expect(view.name).toBe('myWidget')
+  })
+
+  test('name uses displayName when provided', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      '1',
+      'myWidget',
+      'Custom Label'
+    )
+    expect(view.name).toBe('Custom Label')
+  })
+
+  test('node getter returns the subgraphNode', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '1', 'myWidget')
+    // node is defined via Object.defineProperty at runtime but not on the TS interface
+    expect((view as unknown as Record<string, unknown>).node).toBe(subgraphNode)
+  })
+
+  test('serialize is false', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '1', 'myWidget')
+    expect(view.serialize).toBe(false)
+  })
+
+  test('computedDisabled is false and setter is a no-op', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '1', 'myWidget')
+    expect(view.computedDisabled).toBe(false)
+    view.computedDisabled = true
+    expect(view.computedDisabled).toBe(false)
+  })
+
+  test('positional properties are writable and independent', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '1', 'myWidget')
+    expect(view.y).toBe(0)
+
+    view.y = 100
+    view.last_y = 90
+    view.computedHeight = 30
+
+    expect(view.y).toBe(100)
+    expect(view.last_y).toBe(90)
+    expect(view.computedHeight).toBe(30)
+  })
+
+  test('type delegates to interior widget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    innerNode.addWidget('combo', 'picker', 'a', () => {}, {
+      values: ['a', 'b']
+    })
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'picker'
+    )
+    expect(view.type).toBe('combo')
+  })
+
+  test('type falls back to button when interior widget is missing', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '999', 'missing')
+    expect(view.type).toBe('button')
+  })
+
+  test('options delegates to interior widget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    const opts = { values: ['a', 'b'] as string[] }
+    innerNode.addWidget('combo', 'picker', 'a', () => {}, opts)
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'picker'
+    )
+    expect(view.options).toBe(opts)
+  })
+
+  test('options falls back to empty object when interior widget is missing', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '999', 'missing')
+    expect(view.options).toEqual({})
+  })
+
+  test('linkedWidgets delegates to interior widget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    const seedWidget = innerNode.addWidget('number', 'seed', 1, () => {})
+    const controlWidget = innerNode.addWidget(
+      'combo',
+      'control_after_generate',
+      'randomize',
+      () => {},
+      {
+        values: ['fixed', 'increment', 'decrement', 'randomize']
+      }
+    )
+    seedWidget.linkedWidgets = [controlWidget]
+
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'seed'
+    )
+
+    expect(view.linkedWidgets).toBe(seedWidget.linkedWidgets)
+    expect(view.linkedWidgets?.[0].name).toBe('control_after_generate')
+  })
+
+  test('value is store-backed via widgetValueStore', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    innerNode.addWidget('text', 'myWidget', 'initial', () => {})
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'myWidget'
+    )
+
+    // Value should read from the store (which was populated by addWidget)
+    expect(view.value).toBe('initial')
+
+    // Setting value through the view updates the store
+    view.value = 'updated'
+    expect(view.value).toBe('updated')
+
+    // The interior widget reads from the same store
+    expect(innerNode.widgets![0].value).toBe('updated')
+  })
+
+  test('value falls back to interior widget when store entry is missing', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    const fallbackWidgetShape = {
+      name: 'myWidget',
+      type: 'text',
+      value: 'initial',
+      options: {}
+    } satisfies Pick<IBaseWidget, 'name' | 'type' | 'value' | 'options'>
+    const fallbackWidget = fallbackWidgetShape as unknown as IBaseWidget
+    innerNode.widgets = [fallbackWidget]
+
+    const widgetValueStore = useWidgetValueStore()
+    vi.spyOn(widgetValueStore, 'getWidget').mockReturnValue(undefined)
+
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'myWidget'
+    )
+
+    expect(view.value).toBe('initial')
+    view.value = 'updated'
+    expect(fallbackWidget.value).toBe('updated')
+  })
+
+  test('label falls back to displayName then widgetName', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    innerNode.addWidget('text', 'myWidget', 'val', () => {})
+    const store = useWidgetValueStore()
+    const bareId = String(innerNode.id)
+
+    // No displayName → falls back to widgetName
+    const view1 = createPromotedWidgetView(subgraphNode, bareId, 'myWidget')
+    // Store label is undefined → falls back to displayName/widgetName
+    const state = store.getWidget(
+      subgraphNode.rootGraph.id,
+      bareId as never,
+      'myWidget'
+    )
+    state!.label = undefined
+    expect(view1.label).toBe('myWidget')
+
+    // With displayName → falls back to displayName
+    const view2 = createPromotedWidgetView(
+      subgraphNode,
+      bareId,
+      'myWidget',
+      'Custom'
+    )
+    expect(view2.label).toBe('Custom')
+  })
+
+  test('callback forwards to interior widget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    const callbackSpy = vi.fn()
+    innerNode.addWidget('text', 'myWidget', 'val', callbackSpy)
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'myWidget'
+    )
+
+    view.callback!('newVal')
+    expect(callbackSpy).toHaveBeenCalled()
+    expect(callbackSpy.mock.calls[0][0]).toBe('newVal')
+  })
+
+  test('callback is safe when interior widget is missing', () => {
+    const [subgraphNode] = setupSubgraph()
+    const view = createPromotedWidgetView(subgraphNode, '999', 'missing')
+    expect(() => view.callback!('val')).not.toThrow()
+  })
+
+  test('computeSize delegates to interior widget computeSize', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    const widget = innerNode.addWidget('text', 'legacySize', 'val', () => {})
+    const computeSize = vi.fn<(width?: number) => [number, number]>(
+      (width?: number) => [width ?? 0, 37]
+    )
+    widget.computeSize = computeSize
+
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'legacySize'
+    )
+
+    expect(typeof view.computeSize).toBe('function')
+    expect(view.computeSize?.(210)).toEqual([210, 37])
+    expect(computeSize).toHaveBeenCalledWith(210)
+  })
+
+  test('onPointerDown falls back to legacy mouse callback', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    subgraphNode.pos = [10, 20]
+    const innerNode = firstInnerNode(innerNodes)
+    const mouse = vi.fn(() => true)
+    const legacyWidget = {
+      name: 'legacyMouse',
+      type: 'mystery-legacy',
+      value: 'val',
+      options: {},
+      mouse
+    } as unknown as IBaseWidget
+    innerNode.widgets = [legacyWidget]
+
+    const view = createPromotedWidgetView(
+      subgraphNode,
+      String(innerNode.id),
+      'legacyMouse'
+    )
+
+    const pointer = new CanvasPointer(document.createElement('div'))
+    pointer.eDown = {
+      canvasX: 110,
+      canvasY: 120,
+      deltaX: 0,
+      deltaY: 0,
+      safeOffsetX: 0,
+      safeOffsetY: 0
+    } as CanvasPointerEvent
+
+    const handled = view.onPointerDown?.(
+      pointer,
+      subgraphNode,
+      {} as Parameters<NonNullable<typeof view.onPointerDown>>[2]
+    )
+
+    expect(handled).toBe(true)
+    expect(mouse).toHaveBeenCalledWith(pointer.eDown, [100, 100], subgraphNode)
+
+    pointer.eUp = {
+      canvasX: 130,
+      canvasY: 140,
+      deltaX: 0,
+      deltaY: 0,
+      safeOffsetX: 0,
+      safeOffsetY: 0
+    } as CanvasPointerEvent
+    pointer.finally?.()
+
+    expect(mouse).toHaveBeenCalledWith(pointer.eUp, [120, 120], subgraphNode)
+  })
+})
+
+describe('SubgraphNode.widgets getter', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  test('returns empty array when no proxyWidgets', () => {
+    const [subgraphNode] = setupSubgraph()
+    expect(subgraphNode.widgets).toEqual([])
+  })
+
+  test('caches view objects across getter calls (stable references)', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+
+    const first = subgraphNode.widgets[0]
+    const second = subgraphNode.widgets[0]
+    expect(first).toBe(second)
+  })
+
+  test('memoizes promotion list by reference', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+
+    const views1 = subgraphNode.widgets
+    expect(views1).toHaveLength(1)
+
+    // Same reference → same result (memoized)
+    const views2 = subgraphNode.widgets
+    expect(views2[0]).toBe(views1[0])
+
+    // New store value with same content → same cached view object
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+    const views3 = subgraphNode.widgets
+    expect(views3[0]).toBe(views1[0])
+  })
+
+  test('cleans stale cache entries when promotions shrink', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+
+    setPromotions(subgraphNode, [
+      ['1', 'widgetA'],
+      ['1', 'widgetB']
+    ])
+    expect(subgraphNode.widgets).toHaveLength(2)
+    const viewA = subgraphNode.widgets[0]
+
+    // Remove widgetA from promotion list
+    setPromotions(subgraphNode, [['1', 'widgetB']])
+    expect(subgraphNode.widgets).toHaveLength(1)
+    expect(subgraphNode.widgets[0].name).toBe('widgetB')
+
+    // Re-adding widgetA creates a new view (old one was cleaned)
+    setPromotions(subgraphNode, [
+      ['1', 'widgetB'],
+      ['1', 'widgetA']
+    ])
+    const newViewA = subgraphNode.widgets[1]
+    expect(newViewA).not.toBe(viewA)
+  })
+
+  test('deduplicates entries with same nodeId:widgetName', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+
+    setPromotions(subgraphNode, [
+      ['1', 'widgetA'],
+      ['1', 'widgetA']
+    ])
+    expect(subgraphNode.widgets).toHaveLength(1)
+  })
+
+  test('setter is a no-op', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+
+    // Assigning to widgets does nothing
+    subgraphNode.widgets = []
+    expect(subgraphNode.widgets).toHaveLength(1)
+  })
+
+  test('migrates legacy -1 entries via _resolveLegacyEntry', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+
+    // Simulate a slot-connected widget so legacy resolution works
+    const subgraph = subgraphNode.subgraph
+    subgraph.addInput('stringWidget', '*')
+    subgraphNode._internalConfigureAfterSlots()
+
+    // The _internalConfigureAfterSlots would have set up the slot-connected
+    // widget via _setWidget if there's a link. For unit testing legacy
+    // migration, we need to set up the input._widget manually.
+    const input = subgraphNode.inputs.find((i) => i.name === 'stringWidget')
+    if (input) {
+      input._widget = createPromotedWidgetView(
+        subgraphNode,
+        String(innerNodes[0].id),
+        'stringWidget'
+      )
+    }
+
+    // Set legacy -1 format via properties and re-run hydration
+    subgraphNode.properties.proxyWidgets = [['-1', 'stringWidget']]
+    subgraphNode._internalConfigureAfterSlots()
+
+    // Migration should have rewritten the store with resolved IDs
+    const entries = usePromotionStore().getPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id
+    )
+    expect(entries).toStrictEqual([
+      {
+        interiorNodeId: String(innerNodes[0].id),
+        widgetName: 'stringWidget'
+      }
+    ])
+  })
+
+  test('hydrate promotions from serialize/configure round-trip', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    innerNode.addWidget('text', 'widgetA', 'a', () => {})
+
+    setPromotions(subgraphNode, [[String(innerNode.id), 'widgetA']])
+    const serialized = subgraphNode.serialize()
+
+    const restoredNode = createTestSubgraphNode(subgraphNode.subgraph, {
+      id: 99
+    })
+    restoredNode.configure({
+      ...serialized,
+      id: restoredNode.id,
+      type: subgraphNode.subgraph.id
+    })
+
+    const restoredEntries = usePromotionStore().getPromotions(
+      restoredNode.rootGraph.id,
+      restoredNode.id
+    )
+    expect(restoredEntries).toStrictEqual([
+      {
+        interiorNodeId: String(innerNode.id),
+        widgetName: 'widgetA'
+      }
+    ])
+  })
+
+  test('clone output preserves proxyWidgets for promotion hydration', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const innerNode = firstInnerNode(innerNodes)
+    innerNode.addWidget('text', 'widgetA', 'a', () => {})
+
+    setPromotions(subgraphNode, [[String(innerNode.id), 'widgetA']])
+
+    const createNodeSpy = vi
+      .spyOn(LiteGraph, 'createNode')
+      .mockImplementation(() =>
+        createTestSubgraphNode(subgraphNode.subgraph, { id: 999 })
+      )
+
+    const clonedNode = subgraphNode.clone()
+    expect(clonedNode).toBeTruthy()
+    createNodeSpy.mockRestore()
+    if (!clonedNode) throw new Error('Expected clone to return a node')
+
+    const clonedSerialized = clonedNode.serialize()
+    expect(clonedSerialized.properties?.proxyWidgets).toStrictEqual([
+      [String(innerNode.id), 'widgetA']
+    ])
+
+    const hydratedClone = createTestSubgraphNode(subgraphNode.subgraph, {
+      id: 100
+    })
+    hydratedClone.configure({
+      ...clonedSerialized,
+      id: hydratedClone.id,
+      type: subgraphNode.subgraph.id
+    })
+
+    const hydratedEntries = usePromotionStore().getPromotions(
+      hydratedClone.rootGraph.id,
+      hydratedClone.id
+    )
+    expect(hydratedEntries).toStrictEqual([
+      {
+        interiorNodeId: String(innerNode.id),
+        widgetName: 'widgetA'
+      }
+    ])
+  })
+})
+
+describe('widgets getter caching', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  test('preserves view identities when promotion order changes', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+    setPromotions(subgraphNode, [
+      ['1', 'widgetA'],
+      ['1', 'widgetB']
+    ])
+
+    const [viewA, viewB] = subgraphNode.widgets
+
+    setPromotions(subgraphNode, [
+      ['1', 'widgetB'],
+      ['1', 'widgetA']
+    ])
+
+    expect(subgraphNode.widgets[0]).toBe(viewB)
+    expect(subgraphNode.widgets[1]).toBe(viewA)
+  })
+
+  test('deduplicates by key while preserving first-occurrence order', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+
+    setPromotions(subgraphNode, [
+      ['1', 'widgetB'],
+      ['1', 'widgetA'],
+      ['1', 'widgetB'],
+      ['1', 'widgetA']
+    ])
+
+    expect(subgraphNode.widgets).toHaveLength(2)
+    expect(subgraphNode.widgets[0].name).toBe('widgetB')
+    expect(subgraphNode.widgets[1].name).toBe('widgetA')
+  })
+
+  test('returns same array reference when promotions unchanged', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+
+    const result1 = subgraphNode.widgets
+    const result2 = subgraphNode.widgets
+    expect(result1).toBe(result2)
+  })
+
+  test('returns new array after promotion change', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+
+    const result1 = subgraphNode.widgets
+
+    setPromotions(subgraphNode, [
+      ['1', 'widgetA'],
+      ['1', 'widgetB']
+    ])
+    const result2 = subgraphNode.widgets
+
+    expect(result1).not.toBe(result2)
+    expect(result2).toHaveLength(2)
+  })
+
+  test('invalidates cache on removeWidget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+    setPromotions(subgraphNode, [
+      ['1', 'widgetA'],
+      ['1', 'widgetB']
+    ])
+
+    const result1 = subgraphNode.widgets
+    expect(result1).toHaveLength(2)
+
+    subgraphNode.removeWidget(result1[0])
+    const result2 = subgraphNode.widgets
+    expect(result2).toHaveLength(1)
+    expect(result1).not.toBe(result2)
+  })
+})
+
+describe('promote/demote cycle', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  test('promoting adds to store and widgets reflects it', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+
+    expect(subgraphNode.widgets).toHaveLength(0)
+
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+    expect(subgraphNode.widgets).toHaveLength(1)
+    const view = subgraphNode.widgets[0] as PromotedWidgetView
+    expect(view.sourceNodeId).toBe('1')
+    expect(view.sourceWidgetName).toBe('widgetA')
+  })
+
+  test('demoting via removeWidget removes from store', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+    setPromotions(subgraphNode, [
+      ['1', 'widgetA'],
+      ['1', 'widgetB']
+    ])
+
+    const viewA = subgraphNode.widgets[0]
+    subgraphNode.removeWidget(viewA)
+
+    expect(subgraphNode.widgets).toHaveLength(1)
+    expect(subgraphNode.widgets[0].name).toBe('widgetB')
+    const entries = usePromotionStore().getPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id
+    )
+    expect(entries).toStrictEqual([
+      { interiorNodeId: '1', widgetName: 'widgetB' }
+    ])
+  })
+
+  test('full promote → demote → re-promote cycle', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+
+    // Promote
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+    expect(subgraphNode.widgets).toHaveLength(1)
+    const view1 = subgraphNode.widgets[0]
+
+    // Demote
+    subgraphNode.removeWidget(view1)
+    expect(subgraphNode.widgets).toHaveLength(0)
+
+    // Re-promote — creates a new view since the cache was cleared
+    setPromotions(subgraphNode, [['1', 'widgetA']])
+    expect(subgraphNode.widgets).toHaveLength(1)
+    expect(subgraphNode.widgets[0]).not.toBe(view1)
+    expect(
+      (subgraphNode.widgets[0] as PromotedWidgetView).sourceWidgetName
+    ).toBe('widgetA')
+  })
+})
+
+describe('disconnected state', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  test('view resolves type when interior widget exists', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('number', 'numWidget', 42, () => {})
+    setPromotions(subgraphNode, [['1', 'numWidget']])
+
+    expect(subgraphNode.widgets[0].type).toBe('number')
+  })
+
+  test('view falls back to button type when interior node is removed', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'myWidget', 'val', () => {})
+    setPromotions(subgraphNode, [['1', 'myWidget']])
+
+    expect(subgraphNode.widgets[0].type).toBe('text')
+
+    // Remove the interior node from the subgraph
+    subgraphNode.subgraph.remove(innerNodes[0])
+    expect(subgraphNode.widgets[0].type).toBe('button')
+  })
+
+  test('view recovers when interior widget is re-added', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'myWidget', 'val', () => {})
+    setPromotions(subgraphNode, [['1', 'myWidget']])
+
+    // Remove widget
+    innerNodes[0].widgets!.pop()
+    expect(subgraphNode.widgets[0].type).toBe('button')
+
+    // Re-add widget
+    innerNodes[0].addWidget('text', 'myWidget', 'val', () => {})
+    expect(subgraphNode.widgets[0].type).toBe('text')
+  })
+
+  test('options returns empty object when disconnected', () => {
+    const [subgraphNode] = setupSubgraph()
+    setPromotions(subgraphNode, [['999', 'ghost']])
+    expect(subgraphNode.widgets[0].options).toEqual({})
+  })
+
+  test('tooltip returns undefined when disconnected', () => {
+    const [subgraphNode] = setupSubgraph()
+    setPromotions(subgraphNode, [['999', 'ghost']])
+    expect(subgraphNode.widgets[0].tooltip).toBeUndefined()
+  })
+})
+
+function createFakeCanvasContext() {
+  return new Proxy({} as CanvasRenderingContext2D, {
+    get: () => vi.fn(() => ({ width: 10 }))
+  })
+}
+
+describe('DOM widget promotion', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    vi.clearAllMocks()
+  })
+
+  function createMockDOMWidget(node: LGraphNode, name: string) {
+    const widget = node.addWidget('text', name, 'val', () => {})
+    // Add 'element' and 'id' to make it a BaseDOMWidget
+    Object.defineProperties(widget, {
+      element: { value: document.createElement('div'), enumerable: true },
+      id: { value: `dom-widget-${name}`, enumerable: true }
+    })
+    return widget
+  }
+
+  function createMockComponentWidget(node: LGraphNode, name: string) {
+    const widget = node.addWidget('custom', name, 'val', () => {})
+    Object.defineProperties(widget, {
+      component: { value: {}, enumerable: true },
+      id: { value: `comp-widget-${name}`, enumerable: true }
+    })
+    return widget
+  }
+
+  test('draw registers position override for DOM widgets', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    createMockDOMWidget(innerNodes[0], 'textarea')
+    setPromotions(subgraphNode, [['1', 'textarea']])
+
+    const view = subgraphNode.widgets[0]
+    view.draw!(createFakeCanvasContext(), subgraphNode, 200, 0, 30)
+
+    expect(mockDomWidgetStore.setPositionOverride).toHaveBeenCalledWith(
+      'dom-widget-textarea',
+      { node: subgraphNode, widget: view }
+    )
+  })
+
+  test('draw registers position override for component widgets', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    createMockComponentWidget(innerNodes[0], 'compWidget')
+    setPromotions(subgraphNode, [['1', 'compWidget']])
+
+    const view = subgraphNode.widgets[0]
+    view.draw!(createFakeCanvasContext(), subgraphNode, 200, 0, 30)
+
+    expect(mockDomWidgetStore.setPositionOverride).toHaveBeenCalledWith(
+      'comp-widget-compWidget',
+      { node: subgraphNode, widget: view }
+    )
+  })
+
+  test('draw does not register override for non-DOM widgets', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'textWidget', 'val', () => {})
+    setPromotions(subgraphNode, [['1', 'textWidget']])
+
+    const view = subgraphNode.widgets[0]
+    view.draw!(createFakeCanvasContext(), subgraphNode, 200, 0, 30, true)
+
+    expect(mockDomWidgetStore.setPositionOverride).not.toHaveBeenCalled()
+  })
+
+  test('draw does not mutate interior node pos or size for non-DOM widgets', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const interiorNode = firstInnerNode(innerNodes)
+    interiorNode.pos = [10, 20]
+    interiorNode.size = [300, 120]
+    interiorNode.addWidget('text', 'textWidget', 'val', () => {})
+    setPromotions(subgraphNode, [[String(interiorNode.id), 'textWidget']])
+
+    const originalPos = [...interiorNode.pos]
+    const originalSize = [...interiorNode.size]
+    const view = subgraphNode.widgets[0]
+
+    view.draw!(createFakeCanvasContext(), subgraphNode, 200, 0, 30)
+
+    expect(Array.from(interiorNode.pos)).toEqual(originalPos)
+    expect(Array.from(interiorNode.size)).toEqual(originalSize)
+  })
+
+  test('computeLayoutSize delegates to interior DOM widget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const domWidget = createMockDOMWidget(innerNodes[0], 'textarea')
+    domWidget.computeLayoutSize = vi.fn(() => ({
+      minHeight: 100,
+      maxHeight: 300,
+      minWidth: 0
+    }))
+    setPromotions(subgraphNode, [['1', 'textarea']])
+
+    const view = subgraphNode.widgets[0]
+    const result = view.computeLayoutSize!(subgraphNode)
+
+    expect(result).toEqual({ minHeight: 100, maxHeight: 300, minWidth: 0 })
+  })
+
+  test('demoting clears position override for DOM widget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    createMockDOMWidget(innerNodes[0], 'textarea')
+    setPromotions(subgraphNode, [['1', 'textarea']])
+
+    const view = subgraphNode.widgets[0]
+    subgraphNode.removeWidget(view)
+
+    expect(mockDomWidgetStore.clearPositionOverride).toHaveBeenCalledWith(
+      'dom-widget-textarea'
+    )
+  })
+
+  test('onRemoved clears position overrides for all promoted DOM widgets', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    createMockDOMWidget(innerNodes[0], 'widgetA')
+    createMockDOMWidget(innerNodes[0], 'widgetB')
+    setPromotions(subgraphNode, [
+      ['1', 'widgetA'],
+      ['1', 'widgetB']
+    ])
+
+    // Access widgets to populate cache
+    expect(subgraphNode.widgets).toHaveLength(2)
+
+    subgraphNode.onRemoved()
+
+    expect(mockDomWidgetStore.clearPositionOverride).toHaveBeenCalledWith(
+      'dom-widget-widgetA'
+    )
+    expect(mockDomWidgetStore.clearPositionOverride).toHaveBeenCalledWith(
+      'dom-widget-widgetB'
+    )
+  })
+})

src/core/graph/subgraph/promotedWidgetView.ts

@@ -0,0 +1,367 @@
+import type { LGraphNode, NodeId } from '@/lib/litegraph/src/LGraphNode'
+import type { LGraphCanvas } from '@/lib/litegraph/src/LGraphCanvas'
+import type { CanvasPointer } from '@/lib/litegraph/src/CanvasPointer'
+import type { Point } from '@/lib/litegraph/src/interfaces'
+import type { CanvasPointerEvent } from '@/lib/litegraph/src/types/events'
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
+import type { BaseWidget } from '@/lib/litegraph/src/widgets/BaseWidget'
+import { toConcreteWidget } from '@/lib/litegraph/src/widgets/widgetMap'
+import { t } from '@/i18n'
+import { useDomWidgetStore } from '@/stores/domWidgetStore'
+import {
+  stripGraphPrefix,
+  useWidgetValueStore
+} from '@/stores/widgetValueStore'
+
+import type { PromotedWidgetView as IPromotedWidgetView } from './promotedWidgetTypes'
+
+export type { PromotedWidgetView } from './promotedWidgetTypes'
+export { isPromotedWidgetView } from './promotedWidgetTypes'
+
+function resolve(
+  subgraphNode: SubgraphNode,
+  nodeId: string,
+  widgetName: string
+): { node: LGraphNode; widget: IBaseWidget } | undefined {
+  const node = subgraphNode.subgraph.getNodeById(nodeId)
+  if (!node) return undefined
+  const widget = node.widgets?.find((w: IBaseWidget) => w.name === widgetName)
+  return widget ? { node, widget } : undefined
+}
+
+function isWidgetValue(value: unknown): value is IBaseWidget['value'] {
+  if (value === undefined) return true
+  if (typeof value === 'string') return true
+  if (typeof value === 'number') return true
+  if (typeof value === 'boolean') return true
+  return value !== null && typeof value === 'object'
+}
+
+type LegacyMouseWidget = IBaseWidget & {
+  mouse: (e: CanvasPointerEvent, pos: Point, node: LGraphNode) => unknown
+}
+
+function hasLegacyMouse(widget: IBaseWidget): widget is LegacyMouseWidget {
+  return 'mouse' in widget && typeof widget.mouse === 'function'
+}
+
+export function createPromotedWidgetView(
+  subgraphNode: SubgraphNode,
+  nodeId: string,
+  widgetName: string,
+  displayName?: string
+): IPromotedWidgetView {
+  return new PromotedWidgetView(subgraphNode, nodeId, widgetName, displayName)
+}
+
+class PromotedWidgetView implements IPromotedWidgetView {
+  [symbol: symbol]: boolean
+
+  readonly sourceNodeId: string
+  readonly sourceWidgetName: string
+
+  readonly serialize = false
+
+  last_y?: number
+  computedHeight?: number
+
+  private readonly graphId: string
+  private readonly bareNodeId: NodeId
+  private yValue = 0
+
+  private projectedSourceNode?: LGraphNode
+  private projectedSourceWidget?: IBaseWidget
+  private projectedWidget?: BaseWidget
+
+  constructor(
+    private readonly subgraphNode: SubgraphNode,
+    nodeId: string,
+    widgetName: string,
+    private readonly displayName?: string
+  ) {
+    this.sourceNodeId = nodeId
+    this.sourceWidgetName = widgetName
+    this.graphId = subgraphNode.rootGraph.id
+    this.bareNodeId = stripGraphPrefix(nodeId)
+  }
+
+  get node(): SubgraphNode {
+    return this.subgraphNode
+  }
+
+  get name(): string {
+    return this.displayName ?? this.sourceWidgetName
+  }
+
+  get y(): number {
+    return this.yValue
+  }
+
+  set y(value: number) {
+    this.yValue = value
+    this.syncDomOverride()
+  }
+
+  get computedDisabled(): false {
+    return false
+  }
+
+  set computedDisabled(_value: boolean | undefined) {}
+
+  get type(): IBaseWidget['type'] {
+    return this.resolve()?.widget.type ?? 'button'
+  }
+
+  get options(): IBaseWidget['options'] {
+    return this.resolve()?.widget.options ?? {}
+  }
+
+  get tooltip(): string | undefined {
+    return this.resolve()?.widget.tooltip
+  }
+
+  get linkedWidgets(): IBaseWidget[] | undefined {
+    return this.resolve()?.widget.linkedWidgets
+  }
+
+  get value(): IBaseWidget['value'] {
+    const state = this.getWidgetState()
+    if (state && isWidgetValue(state.value)) return state.value
+    return this.resolve()?.widget.value
+  }
+
+  set value(value: IBaseWidget['value']) {
+    const state = this.getWidgetState()
+    if (state) {
+      state.value = value
+      return
+    }
+
+    const resolved = this.resolve()
+    if (resolved && isWidgetValue(value)) {
+      resolved.widget.value = value
+    }
+  }
+
+  get label(): string | undefined {
+    const state = this.getWidgetState()
+    return state?.label ?? this.displayName ?? this.sourceWidgetName
+  }
+
+  set label(value: string | undefined) {
+    const state = this.getWidgetState()
+    if (state) state.label = value
+  }
+
+  get hidden(): boolean {
+    return this.resolve()?.widget.hidden ?? false
+  }
+
+  get computeLayoutSize(): IBaseWidget['computeLayoutSize'] {
+    const resolved = this.resolve()
+    const computeLayoutSize = resolved?.widget.computeLayoutSize
+    if (!computeLayoutSize) return undefined
+    return (node: LGraphNode) => computeLayoutSize.call(resolved.widget, node)
+  }
+
+  get computeSize(): IBaseWidget['computeSize'] {
+    const resolved = this.resolve()
+    const computeSize = resolved?.widget.computeSize
+    if (!computeSize) return undefined
+    return (width?: number) => computeSize.call(resolved.widget, width)
+  }
+
+  draw(
+    ctx: CanvasRenderingContext2D,
+    _node: LGraphNode,
+    widgetWidth: number,
+    y: number,
+    H: number,
+    lowQuality?: boolean
+  ): void {
+    const resolved = this.resolve()
+    if (!resolved) {
+      drawDisconnectedPlaceholder(ctx, widgetWidth, y, H)
+      return
+    }
+
+    if (isBaseDOMWidget(resolved.widget)) return this.syncDomOverride(resolved)
+
+    const projected = this.getProjectedWidget(resolved)
+    if (!projected || typeof projected.drawWidget !== 'function') return
+
+    const originalY = projected.y
+    const originalComputedHeight = projected.computedHeight
+
+    projected.y = this.y
+    projected.computedHeight = this.computedHeight
+    projected.value = this.value
+
+    projected.drawWidget(ctx, {
+      width: widgetWidth,
+      showText: !lowQuality,
+      suppressPromotedOutline: true
+    })
+
+    projected.y = originalY
+    projected.computedHeight = originalComputedHeight
+  }
+
+  onPointerDown(
+    pointer: CanvasPointer,
+    _node: LGraphNode,
+    canvas: LGraphCanvas
+  ): boolean {
+    const resolved = this.resolve()
+    if (!resolved) return false
+
+    const interior = resolved.widget
+    if (typeof interior.onPointerDown === 'function') {
+      const handled = interior.onPointerDown(pointer, this.subgraphNode, canvas)
+      if (handled) return true
+    }
+
+    const concrete = toConcreteWidget(interior, this.subgraphNode, false)
+    if (concrete)
+      return this.bindConcretePointerHandlers(pointer, canvas, concrete)
+
+    if (hasLegacyMouse(interior))
+      return this.handleLegacyMouse(pointer, interior)
+
+    return false
+  }
+
+  callback(
+    value: unknown,
+    canvas?: LGraphCanvas,
+    node?: LGraphNode,
+    pos?: Point,
+    e?: CanvasPointerEvent
+  ) {
+    this.resolve()?.widget.callback?.(value, canvas, node, pos, e)
+  }
+
+  private resolve(): { node: LGraphNode; widget: IBaseWidget } | undefined {
+    return resolve(this.subgraphNode, this.sourceNodeId, this.sourceWidgetName)
+  }
+
+  private getWidgetState() {
+    return useWidgetValueStore().getWidget(
+      this.graphId,
+      this.bareNodeId,
+      this.sourceWidgetName
+    )
+  }
+
+  private getProjectedWidget(resolved: {
+    node: LGraphNode
+    widget: IBaseWidget
+  }): BaseWidget | undefined {
+    const shouldRebuild =
+      !this.projectedWidget ||
+      this.projectedSourceNode !== resolved.node ||
+      this.projectedSourceWidget !== resolved.widget
+
+    if (!shouldRebuild) return this.projectedWidget
+
+    const concrete = toConcreteWidget(resolved.widget, resolved.node, false)
+    if (!concrete) {
+      this.projectedWidget = undefined
+      this.projectedSourceNode = undefined
+      this.projectedSourceWidget = undefined
+      return undefined
+    }
+
+    this.projectedWidget = concrete.createCopyForNode(this.subgraphNode)
+    this.projectedSourceNode = resolved.node
+    this.projectedSourceWidget = resolved.widget
+    return this.projectedWidget
+  }
+
+  private bindConcretePointerHandlers(
+    pointer: CanvasPointer,
+    canvas: LGraphCanvas,
+    concrete: BaseWidget
+  ): boolean {
+    const downEvent = pointer.eDown
+    if (!downEvent) return false
+
+    pointer.onClick = () =>
+      concrete.onClick({
+        e: downEvent,
+        node: this.subgraphNode,
+        canvas
+      })
+    pointer.onDrag = (eMove) =>
+      concrete.onDrag?.({
+        e: eMove,
+        node: this.subgraphNode,
+        canvas
+      })
+    return true
+  }
+
+  private handleLegacyMouse(
+    pointer: CanvasPointer,
+    interior: LegacyMouseWidget
+  ): boolean {
+    const downEvent = pointer.eDown
+    if (!downEvent) return false
+
+    const downPosition: Point = [
+      downEvent.canvasX - this.subgraphNode.pos[0],
+      downEvent.canvasY - this.subgraphNode.pos[1]
+    ]
+    interior.mouse(downEvent, downPosition, this.subgraphNode)
+
+    pointer.finally = () => {
+      const upEvent = pointer.eUp
+      if (!upEvent) return
+
+      const upPosition: Point = [
+        upEvent.canvasX - this.subgraphNode.pos[0],
+        upEvent.canvasY - this.subgraphNode.pos[1]
+      ]
+      interior.mouse(upEvent, upPosition, this.subgraphNode)
+    }
+
+    return true
+  }
+
+  private syncDomOverride(
+    resolved:
+      | { node: LGraphNode; widget: IBaseWidget }
+      | undefined = this.resolve()
+  ) {
+    if (!resolved || !isBaseDOMWidget(resolved.widget)) return
+    useDomWidgetStore().setPositionOverride(resolved.widget.id, {
+      node: this.subgraphNode,
+      widget: this
+    })
+  }
+}
+
+/** Checks if a widget is a BaseDOMWidget (DOMWidget or ComponentWidget). */
+function isBaseDOMWidget(
+  widget: IBaseWidget
+): widget is IBaseWidget & { id: string } {
+  return 'id' in widget && ('element' in widget || 'component' in widget)
+}
+
+function drawDisconnectedPlaceholder(
+  ctx: CanvasRenderingContext2D,
+  width: number,
+  y: number,
+  H: number
+) {
+  ctx.save()
+  ctx.fillStyle = '#333'
+  ctx.fillRect(15, y, width - 30, H)
+  ctx.fillStyle = '#999'
+  ctx.font = '11px monospace'
+  ctx.textAlign = 'center'
+  ctx.textBaseline = 'middle'
+  ctx.fillText(t('subgraphStore.disconnected'), width / 2, y + H / 2)
+  ctx.restore()
+}

src/core/graph/subgraph/promotionUtils.test.ts

@@ -0,0 +1,235 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+import { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import {
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
+import { usePromotionStore } from '@/stores/promotionStore'
+
+const updatePreviewsMock = vi.hoisted(() => vi.fn())
+vi.mock('@/services/litegraphService', () => ({
+  useLitegraphService: () => ({ updatePreviews: updatePreviewsMock })
+}))
+
+import {
+  CANVAS_IMAGE_PREVIEW_WIDGET,
+  getPromotableWidgets,
+  isPreviewPseudoWidget,
+  promoteRecommendedWidgets,
+  pruneDisconnected
+} from './promotionUtils'
+
+function widget(
+  overrides: Partial<
+    Pick<IBaseWidget, 'name' | 'serialize' | 'type' | 'options'>
+  >
+): IBaseWidget {
+  return { name: 'widget', ...overrides } as unknown as IBaseWidget
+}
+
+describe('isPreviewPseudoWidget', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    vi.restoreAllMocks()
+  })
+
+  it('returns true for $$-prefixed widget names', () => {
+    expect(
+      isPreviewPseudoWidget(widget({ name: '$$canvas-image-preview' }))
+    ).toBe(true)
+    expect(isPreviewPseudoWidget(widget({ name: '$$anything' }))).toBe(true)
+  })
+
+  it('returns true for serialize:false with type "preview"', () => {
+    expect(
+      isPreviewPseudoWidget(
+        widget({ name: 'videopreview', serialize: false, type: 'preview' })
+      )
+    ).toBe(true)
+  })
+
+  it('returns true for options.serialize:false with type "preview" (VHS pattern)', () => {
+    expect(
+      isPreviewPseudoWidget(
+        widget({
+          name: 'videopreview',
+          type: 'preview',
+          options: { serialize: false }
+        })
+      )
+    ).toBe(true)
+  })
+
+  it('returns true for serialize:false with type "video"', () => {
+    expect(
+      isPreviewPseudoWidget(
+        widget({ name: 'vid', serialize: false, type: 'video' })
+      )
+    ).toBe(true)
+  })
+
+  it('returns true for serialize:false with type "audioUI"', () => {
+    expect(
+      isPreviewPseudoWidget(
+        widget({ name: 'audio', serialize: false, type: 'audioUI' })
+      )
+    ).toBe(true)
+  })
+
+  it('returns false for type "preview" when serialize is not false', () => {
+    expect(
+      isPreviewPseudoWidget(
+        widget({ name: 'videopreview', serialize: true, type: 'preview' })
+      )
+    ).toBe(false)
+  })
+
+  it('returns false for regular widgets', () => {
+    expect(
+      isPreviewPseudoWidget(widget({ name: 'seed', type: 'number' }))
+    ).toBe(false)
+  })
+
+  it('returns false for serialize:false with unknown type', () => {
+    expect(
+      isPreviewPseudoWidget(
+        widget({ name: 'text', serialize: false, type: 'customtext' })
+      )
+    ).toBe(false)
+  })
+})
+
+describe('pruneDisconnected', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    vi.restoreAllMocks()
+  })
+
+  it('removes disconnected entries and emits a dev warning', () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const interiorNode = new LGraphNode('TestNode')
+    subgraphNode.subgraph.add(interiorNode)
+    interiorNode.addWidget('text', 'kept', 'value', () => {})
+
+    const store = usePromotionStore()
+    store.setPromotions(subgraphNode.rootGraph.id, subgraphNode.id, [
+      { interiorNodeId: String(interiorNode.id), widgetName: 'kept' },
+      { interiorNodeId: String(interiorNode.id), widgetName: 'missing-widget' },
+      { interiorNodeId: '9999', widgetName: 'missing-node' }
+    ])
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    pruneDisconnected(subgraphNode)
+
+    expect(
+      store.getPromotions(subgraphNode.rootGraph.id, subgraphNode.id)
+    ).toEqual([{ interiorNodeId: String(interiorNode.id), widgetName: 'kept' }])
+    expect(warnSpy).toHaveBeenCalledOnce()
+  })
+
+  it('keeps virtual canvas preview promotions for PreviewImage nodes', () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const interiorNode = new LGraphNode('PreviewImage')
+    interiorNode.type = 'PreviewImage'
+    subgraphNode.subgraph.add(interiorNode)
+
+    const store = usePromotionStore()
+    store.setPromotions(subgraphNode.rootGraph.id, subgraphNode.id, [
+      {
+        interiorNodeId: String(interiorNode.id),
+        widgetName: CANVAS_IMAGE_PREVIEW_WIDGET
+      }
+    ])
+
+    pruneDisconnected(subgraphNode)
+
+    expect(
+      store.getPromotions(subgraphNode.rootGraph.id, subgraphNode.id)
+    ).toEqual([
+      {
+        interiorNodeId: String(interiorNode.id),
+        widgetName: CANVAS_IMAGE_PREVIEW_WIDGET
+      }
+    ])
+  })
+})
+
+describe('getPromotableWidgets', () => {
+  it('adds virtual canvas preview widget for PreviewImage nodes', () => {
+    const node = new LGraphNode('PreviewImage')
+    node.type = 'PreviewImage'
+
+    const widgets = getPromotableWidgets(node)
+
+    expect(
+      widgets.some((widget) => widget.name === CANVAS_IMAGE_PREVIEW_WIDGET)
+    ).toBe(true)
+  })
+
+  it('adds virtual canvas preview widget for SaveImage nodes', () => {
+    const node = new LGraphNode('SaveImage')
+    node.type = 'SaveImage'
+
+    const widgets = getPromotableWidgets(node)
+
+    expect(
+      widgets.some((widget) => widget.name === CANVAS_IMAGE_PREVIEW_WIDGET)
+    ).toBe(true)
+  })
+
+  it('does not add virtual canvas preview widget for non-image nodes', () => {
+    const node = new LGraphNode('TextNode')
+    node.addOutput('TEXT', 'STRING')
+
+    const widgets = getPromotableWidgets(node)
+
+    expect(
+      widgets.some((widget) => widget.name === CANVAS_IMAGE_PREVIEW_WIDGET)
+    ).toBe(false)
+  })
+
+  it('does not add virtual canvas preview widget for ImageInvert nodes', () => {
+    const node = new LGraphNode('ImageInvert')
+    node.type = 'ImageInvert'
+
+    const widgets = getPromotableWidgets(node)
+
+    expect(
+      widgets.some((widget) => widget.name === CANVAS_IMAGE_PREVIEW_WIDGET)
+    ).toBe(false)
+  })
+})
+
+describe('promoteRecommendedWidgets', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+    updatePreviewsMock.mockReset()
+  })
+
+  it('skips deferred updatePreviews when a preview widget already exists', () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const interiorNode = new LGraphNode('TestNode')
+    subgraph.add(interiorNode)
+
+    const previewWidget = interiorNode.addWidget(
+      'custom',
+      'videopreview',
+      'value',
+      () => {}
+    )
+    previewWidget.type = 'preview'
+    previewWidget.serialize = false
+
+    promoteRecommendedWidgets(subgraphNode)
+
+    expect(updatePreviewsMock).not.toHaveBeenCalled()
+  })
+})

src/core/graph/subgraph/promotionUtils.ts

@@ -0,0 +1,285 @@
+import { isPromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetTypes'
+import { t } from '@/i18n'
+import type {
+  IContextMenuValue,
+  LGraphNode
+} from '@/lib/litegraph/src/litegraph'
+import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets.ts'
+import { useToastStore } from '@/platform/updates/common/toastStore'
+import {
+  CANVAS_IMAGE_PREVIEW_WIDGET,
+  supportsVirtualCanvasImagePreview
+} from '@/composables/node/useNodeCanvasImagePreview'
+import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
+import { useLitegraphService } from '@/services/litegraphService'
+import { usePromotionStore } from '@/stores/promotionStore'
+import { useSubgraphNavigationStore } from '@/stores/subgraphNavigationStore'
+
+type PartialNode = Pick<LGraphNode, 'title' | 'id' | 'type'>
+
+export type WidgetItem = [PartialNode, IBaseWidget]
+export { CANVAS_IMAGE_PREVIEW_WIDGET }
+
+export function getWidgetName(w: IBaseWidget): string {
+  return isPromotedWidgetView(w) ? w.sourceWidgetName : w.name
+}
+
+/** Known non-$$ preview widget types added by core or popular extensions. */
+const PREVIEW_WIDGET_TYPES = new Set(['preview', 'video', 'audioUI'])
+
+/**
+ * Returns true for pseudo-widgets that display media previews and should
+ * be auto-promoted when their node is inside a subgraph.
+ * Matches the core `$$` convention as well as custom-node patterns
+ * (e.g. VHS `videopreview` with type `"preview"`).
+ */
+export function isPreviewPseudoWidget(widget: IBaseWidget): boolean {
+  if (widget.name.startsWith('$$')) return true
+  // Custom nodes may set serialize on the widget or in options
+  if (widget.serialize !== false && widget.options?.serialize !== false)
+    return false
+  if (typeof widget.type === 'string' && PREVIEW_WIDGET_TYPES.has(widget.type))
+    return true
+  return false
+}
+
+export function promoteWidget(
+  node: PartialNode,
+  widget: IBaseWidget,
+  parents: SubgraphNode[]
+) {
+  const store = usePromotionStore()
+  const nodeId = String(
+    isPromotedWidgetView(widget) ? widget.sourceNodeId : node.id
+  )
+  const widgetName = getWidgetName(widget)
+  for (const parent of parents) {
+    store.promote(parent.rootGraph.id, parent.id, nodeId, widgetName)
+  }
+}
+
+export function demoteWidget(
+  node: PartialNode,
+  widget: IBaseWidget,
+  parents: SubgraphNode[]
+) {
+  const store = usePromotionStore()
+  const nodeId = String(
+    isPromotedWidgetView(widget) ? widget.sourceNodeId : node.id
+  )
+  const widgetName = getWidgetName(widget)
+  for (const parent of parents) {
+    store.demote(parent.rootGraph.id, parent.id, nodeId, widgetName)
+  }
+}
+
+function getParentNodes(): SubgraphNode[] {
+  const { navigationStack } = useSubgraphNavigationStore()
+  const subgraph = navigationStack.at(-1)
+  if (!subgraph) {
+    useToastStore().add({
+      severity: 'error',
+      summary: t('g.error'),
+      detail: t('subgraphStore.promoteOutsideSubgraph'),
+      life: 2000
+    })
+    return []
+  }
+  const parentGraph = navigationStack.at(-2) ?? subgraph.rootGraph
+  return parentGraph.nodes.filter(
+    (node): node is SubgraphNode =>
+      node.type === subgraph.id && node.isSubgraphNode()
+  )
+}
+
+export function addWidgetPromotionOptions(
+  options: (IContextMenuValue<unknown> | null)[],
+  widget: IBaseWidget,
+  node: LGraphNode
+) {
+  const store = usePromotionStore()
+  const parents = getParentNodes()
+  const nodeId = String(node.id)
+  const widgetName = getWidgetName(widget)
+  const promotableParents = parents.filter(
+    (s) => !store.isPromoted(s.rootGraph.id, s.id, nodeId, widgetName)
+  )
+  if (promotableParents.length > 0)
+    options.unshift({
+      content: t('subgraphStore.promoteWidget', {
+        name: widget.label ?? widget.name
+      }),
+      callback: () => {
+        promoteWidget(node, widget, promotableParents)
+        widget.callback?.(widget.value)
+      }
+    })
+  else {
+    options.unshift({
+      content: t('subgraphStore.unpromoteWidget', {
+        name: widget.label ?? widget.name
+      }),
+      callback: () => {
+        demoteWidget(node, widget, parents)
+        widget.callback?.(widget.value)
+      }
+    })
+  }
+}
+
+export function tryToggleWidgetPromotion() {
+  const canvas = useCanvasStore().getCanvas()
+  const [x, y] = canvas.graph_mouse
+  const node = canvas.graph?.getNodeOnPos(x, y, canvas.visible_nodes)
+  if (!node) return
+  const widget = node.getWidgetOnPos(x, y, true)
+  const parents = getParentNodes()
+  if (!parents.length || !widget) return
+  const store = usePromotionStore()
+  const nodeId = String(node.id)
+  const widgetName = getWidgetName(widget)
+  const promotableParents = parents.filter(
+    (s) => !store.isPromoted(s.rootGraph.id, s.id, nodeId, widgetName)
+  )
+  if (promotableParents.length > 0)
+    promoteWidget(node, widget, promotableParents)
+  else demoteWidget(node, widget, parents)
+}
+
+const recommendedNodes = [
+  'CLIPTextEncode',
+  'LoadImage',
+  'SaveImage',
+  'PreviewImage'
+]
+const recommendedWidgetNames = ['seed']
+export function isRecommendedWidget([node, widget]: WidgetItem) {
+  return (
+    !widget.computedDisabled &&
+    (recommendedNodes.includes(node.type) ||
+      recommendedWidgetNames.includes(widget.name))
+  )
+}
+
+function supportsVirtualPreviewWidget(node: LGraphNode): boolean {
+  return supportsVirtualCanvasImagePreview(node)
+}
+
+function createVirtualCanvasImagePreviewWidget(): IBaseWidget {
+  return {
+    name: CANVAS_IMAGE_PREVIEW_WIDGET,
+    type: 'IMAGE_PREVIEW',
+    options: { serialize: false },
+    serialize: false,
+    y: 0,
+    computedDisabled: false
+  }
+}
+
+export function getPromotableWidgets(node: LGraphNode): IBaseWidget[] {
+  const widgets = [...(node.widgets ?? [])]
+
+  const hasCanvasPreviewWidget = widgets.some(
+    (widget) => widget.name === CANVAS_IMAGE_PREVIEW_WIDGET
+  )
+  const supportsVirtualPreview = supportsVirtualPreviewWidget(node)
+  if (!hasCanvasPreviewWidget && supportsVirtualPreview) {
+    widgets.push(createVirtualCanvasImagePreviewWidget())
+  }
+
+  return widgets
+}
+
+function nodeWidgets(n: LGraphNode): WidgetItem[] {
+  return getPromotableWidgets(n).map((w: IBaseWidget) => [n, w])
+}
+
+export function promoteRecommendedWidgets(subgraphNode: SubgraphNode) {
+  const store = usePromotionStore()
+  const { updatePreviews } = useLitegraphService()
+  const interiorNodes = subgraphNode.subgraph.nodes
+  for (const node of interiorNodes) {
+    node.updateComputedDisabled()
+
+    const hasPreviewWidget = () =>
+      node.widgets?.some(isPreviewPseudoWidget) ?? false
+
+    function promotePreviewWidget() {
+      const widget = node.widgets?.find(isPreviewPseudoWidget)
+      if (!widget) return
+      if (
+        store.isPromoted(
+          subgraphNode.rootGraph.id,
+          subgraphNode.id,
+          String(node.id),
+          widget.name
+        )
+      )
+        return
+      promoteWidget(node, widget, [subgraphNode])
+    }
+    // Promote preview widgets that already exist (e.g. custom node DOM widgets
+    // like VHS videopreview that are created in onNodeCreated).
+    promotePreviewWidget()
+
+    // If a preview widget already exists in this frame, there's nothing to
+    // defer. Core $$ preview widgets are the lazy path that needs updatePreviews.
+    if (hasPreviewWidget()) continue
+
+    // Also schedule a deferred check: core $$ widgets are created lazily by
+    // updatePreviews when node outputs are first loaded.
+    requestAnimationFrame(() => updatePreviews(node, promotePreviewWidget))
+  }
+  const filteredWidgets: WidgetItem[] = interiorNodes
+    .flatMap(nodeWidgets)
+    .filter(isRecommendedWidget)
+  for (const [n, w] of filteredWidgets) {
+    store.promote(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      String(n.id),
+      getWidgetName(w)
+    )
+  }
+  subgraphNode.computeSize(subgraphNode.size)
+}
+
+export function pruneDisconnected(subgraphNode: SubgraphNode) {
+  const store = usePromotionStore()
+  const subgraph = subgraphNode.subgraph
+  const entries = store.getPromotions(
+    subgraphNode.rootGraph.id,
+    subgraphNode.id
+  )
+  const removedEntries: Array<{ interiorNodeId: string; widgetName: string }> =
+    []
+
+  const validEntries = entries.filter((entry) => {
+    const node = subgraph.getNodeById(entry.interiorNodeId)
+    if (!node) {
+      removedEntries.push(entry)
+      return false
+    }
+    const hasWidget = getPromotableWidgets(node).some(
+      (iw) => iw.name === entry.widgetName
+    )
+    if (!hasWidget) {
+      removedEntries.push(entry)
+    }
+    return hasWidget
+  })
+
+  if (removedEntries.length > 0 && import.meta.env.DEV) {
+    console.warn(
+      '[proxyWidgetUtils] Pruned disconnected promotions',
+      removedEntries,
+      {
+        graphId: subgraphNode.rootGraph.id,
+        subgraphNodeId: subgraphNode.id
+      }
+    )
+  }
+
+  store.setPromotions(subgraphNode.rootGraph.id, subgraphNode.id, validEntries)
+}

src/core/graph/subgraph/proxyWidget.test.ts

@@ -1,235 +0,0 @@
-import { createTestingPinia } from '@pinia/testing'
-import { setActivePinia } from 'pinia'
-import { beforeEach, describe, expect, test, vi } from 'vitest'
-
-import { registerProxyWidgets } from '@/core/graph/subgraph/proxyWidget'
-import { promoteWidget } from '@/core/graph/subgraph/proxyWidgetUtils'
-import { parseProxyWidgets } from '@/core/schemas/proxyWidget'
-import { LGraph, LGraphNode, SubgraphNode } from '@/lib/litegraph/src/litegraph'
-import type { LGraphCanvas } from '@/lib/litegraph/src/litegraph'
-
-import {
-  createTestSubgraph,
-  createTestSubgraphNode
-} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
-
-const canvasEl: Partial<HTMLCanvasElement> = { addEventListener() {} }
-const canvas: Partial<LGraphCanvas> = { canvas: canvasEl as HTMLCanvasElement }
-registerProxyWidgets(canvas as LGraphCanvas)
-
-vi.mock('@/renderer/core/canvas/canvasStore', () => ({
-  useCanvasStore: () => ({})
-}))
-vi.mock('@/stores/domWidgetStore', () => ({
-  useDomWidgetStore: () => ({ widgetStates: new Map() })
-}))
-vi.mock('@/services/litegraphService', () => ({
-  useLitegraphService: () => ({ updatePreviews: () => ({}) })
-}))
-
-function setupSubgraph(
-  innerNodeCount: number = 0
-): [SubgraphNode, LGraphNode[]] {
-  const subgraph = createTestSubgraph()
-  const subgraphNode = createTestSubgraphNode(subgraph)
-  subgraphNode._internalConfigureAfterSlots()
-  const graph = subgraphNode.graph!
-  graph.add(subgraphNode)
-  const innerNodes = []
-  for (let i = 0; i < innerNodeCount; i++) {
-    const innerNode = new LGraphNode(`InnerNode${i}`)
-    subgraph.add(innerNode)
-    innerNodes.push(innerNode)
-  }
-  return [subgraphNode, innerNodes]
-}
-
-describe('Subgraph proxyWidgets', () => {
-  beforeEach(() => {
-    setActivePinia(createTestingPinia({ stubActions: false }))
-  })
-
-  test('Can add simple widget', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'stringWidget']]
-    expect(subgraphNode.widgets.length).toBe(1)
-    expect(subgraphNode.properties.proxyWidgets).toStrictEqual([
-      ['1', 'stringWidget']
-    ])
-  })
-  test('Can add multiple widgets with same name', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(2)
-    for (const innerNode of innerNodes)
-      innerNode.addWidget('text', 'stringWidget', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [
-      ['1', 'stringWidget'],
-      ['2', 'stringWidget']
-    ]
-    expect(subgraphNode.widgets.length).toBe(2)
-    expect(subgraphNode.widgets[0].name).not.toEqual(
-      subgraphNode.widgets[1].name
-    )
-  })
-  test('Will serialize existing widgets', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'istringWidget', 'value', () => {})
-    subgraphNode.addWidget('text', 'stringWidget', 'value', () => {})
-
-    const proxyWidgets = parseProxyWidgets(subgraphNode.properties.proxyWidgets)
-    proxyWidgets.push(['1', 'istringWidget'])
-    subgraphNode.properties.proxyWidgets = proxyWidgets
-
-    expect(subgraphNode.widgets.length).toBe(2)
-    expect(subgraphNode.widgets[0].name).toBe('stringWidget')
-    subgraphNode.properties.proxyWidgets = [proxyWidgets[1], proxyWidgets[0]]
-    expect(subgraphNode.widgets[0].name).toBe('1: istringWidget')
-  })
-  test('Will mirror changes to value', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'stringWidget']]
-    expect(subgraphNode.widgets.length).toBe(1)
-    expect(subgraphNode.widgets[0].value).toBe('value')
-    innerNodes[0].widgets![0].value = 'test'
-    expect(subgraphNode.widgets[0].value).toBe('test')
-    subgraphNode.widgets[0].value = 'test2'
-    expect(innerNodes[0].widgets![0].value).toBe('test2')
-  })
-  test('Will not modify position or sizing of existing widgets', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'stringWidget']]
-    if (!innerNodes[0].widgets) throw new Error('node has no widgets')
-    innerNodes[0].widgets[0].y = 10
-    innerNodes[0].widgets[0].last_y = 11
-    innerNodes[0].widgets[0].computedHeight = 12
-    subgraphNode.widgets[0].y = 20
-    subgraphNode.widgets[0].last_y = 21
-    subgraphNode.widgets[0].computedHeight = 22
-    expect(innerNodes[0].widgets[0].y).toBe(10)
-    expect(innerNodes[0].widgets[0].last_y).toBe(11)
-    expect(innerNodes[0].widgets[0].computedHeight).toBe(12)
-  })
-  test('Can detach and re-attach widgets', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'stringWidget']]
-    if (!innerNodes[0].widgets) throw new Error('node has no widgets')
-    expect(subgraphNode.widgets[0].value).toBe('value')
-    const poppedWidget = innerNodes[0].widgets.pop()
-    //simulate new draw frame
-    subgraphNode.widgets[0].computedHeight = 10
-    expect(subgraphNode.widgets[0].value).toBe(undefined)
-    innerNodes[0].widgets.push(poppedWidget!)
-    subgraphNode.widgets[0].computedHeight = 10
-    expect(subgraphNode.widgets[0].value).toBe('value')
-  })
-  test('Proxy widget label shows widgetName, not "nodeId: widgetName"', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'seed', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'seed']]
-
-    const proxyWidget = subgraphNode.widgets[0]
-    expect(proxyWidget.label).toBe('seed')
-    expect(proxyWidget.name).toBe('1: seed')
-  })
-
-  test('Proxy widget label reflects linked widget label', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'seed', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'seed']]
-
-    const proxyWidget = subgraphNode.widgets[0]
-    expect(proxyWidget.label).toBe('seed')
-
-    innerNodes[0].widgets![0].label = 'My Inner Label'
-    // Trigger re-resolve of linked widget
-    proxyWidget.computedHeight = 10
-    expect(proxyWidget.label).toBe('My Inner Label')
-  })
-
-  test('Proxy widget user rename takes priority over linked widget label', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'seed', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'seed']]
-
-    const proxyWidget = subgraphNode.widgets[0]
-    proxyWidget.label = 'My Custom Seed'
-    expect(proxyWidget.label).toBe('My Custom Seed')
-
-    innerNodes[0].widgets![0].label = 'Inner Override'
-    proxyWidget.computedHeight = 10
-    expect(proxyWidget.label).toBe('My Custom Seed')
-  })
-
-  test('Proxy widget label resets to linked widget on undefined', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'seed', 'value', () => {})
-    subgraphNode.properties.proxyWidgets = [['1', 'seed']]
-
-    const proxyWidget = subgraphNode.widgets[0]
-    proxyWidget.label = 'Custom'
-    expect(proxyWidget.label).toBe('Custom')
-
-    proxyWidget.label = undefined
-    innerNodes[0].widgets![0].label = 'Inner Label'
-    proxyWidget.computedHeight = 10
-    expect(proxyWidget.label).toBe('Inner Label')
-  })
-
-  test('Proxy widget labels are correct when loaded from serialized data', () => {
-    // Intentionally constructs SubgraphNode via constructor (not setupSubgraph)
-    // to exercise the deserialization/onConfigure path from blueprint JSON.
-    const subgraph = createTestSubgraph()
-    const innerNode = new LGraphNode('InnerNode')
-    subgraph.add(innerNode)
-    innerNode.addWidget('text', 'seed', 'value', () => {})
-    innerNode.addWidget('text', 'steps', 'value', () => {})
-
-    const parentGraph = new LGraph()
-    const subgraphNode = new SubgraphNode(parentGraph, subgraph, {
-      id: 1,
-      type: subgraph.id,
-      pos: [100, 100],
-      size: [200, 100],
-      inputs: [],
-      outputs: [],
-      properties: {
-        proxyWidgets: [
-          ['1', 'seed'],
-          ['1', 'steps']
-        ]
-      },
-      flags: {},
-      mode: 0,
-      order: 0
-    })
-
-    expect(subgraphNode.widgets).toHaveLength(2)
-    expect(subgraphNode.widgets[0].label).toBe('seed')
-    expect(subgraphNode.widgets[0].name).toBe('1: seed')
-    expect(subgraphNode.widgets[1].label).toBe('steps')
-    expect(subgraphNode.widgets[1].name).toBe('1: steps')
-  })
-
-  test('Prevents duplicate promotion', () => {
-    const [subgraphNode, innerNodes] = setupSubgraph(1)
-    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
-
-    const widget = innerNodes[0].widgets![0]
-
-    // Promote once
-    promoteWidget(innerNodes[0], widget, [subgraphNode])
-    expect(subgraphNode.widgets.length).toBe(1)
-    expect(subgraphNode.properties.proxyWidgets).toHaveLength(1)
-
-    // Try to promote again - should not create duplicate
-    promoteWidget(innerNodes[0], widget, [subgraphNode])
-    expect(subgraphNode.widgets.length).toBe(1)
-    expect(subgraphNode.properties.proxyWidgets).toHaveLength(1)
-    expect(subgraphNode.properties.proxyWidgets).toStrictEqual([
-      ['1', 'stringWidget']
-    ])
-  })
-})

src/core/graph/subgraph/proxyWidget.ts

@@ -1,257 +0,0 @@
-import {
-  demoteWidget,
-  promoteRecommendedWidgets
-} from '@/core/graph/subgraph/proxyWidgetUtils'
-import { parseProxyWidgets } from '@/core/schemas/proxyWidget'
-import type { NodeProperty } from '@/lib/litegraph/src/LGraphNode'
-import type {
-  LGraph,
-  LGraphCanvas,
-  LGraphNode
-} from '@/lib/litegraph/src/litegraph'
-import { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
-import type { ISerialisedNode } from '@/lib/litegraph/src/types/serialisation'
-import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets.ts'
-import { disconnectedWidget } from '@/lib/litegraph/src/widgets/DisconnectedWidget'
-import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
-import { DOMWidgetImpl } from '@/scripts/domWidget'
-import { useLitegraphService } from '@/services/litegraphService'
-import { useDomWidgetStore } from '@/stores/domWidgetStore'
-import { getNodeByExecutionId } from '@/utils/graphTraversalUtil'
-
-/**
- * @typedef {object} Overlay - Each proxy Widget has an associated overlay object
- * Accessing a property which exists in the overlay object will
- * instead result in the action being performed on the overlay object
- * 3 properties are added for locating the proxied widget
- * @property {LGraph} graph - The graph the widget resides in. Used for widget lookup
- * @property {string} nodeId - The NodeId the proxy Widget is located on
- * @property {string} widgetName - The name of the linked widget
- *
- * @property {boolean} isProxyWidget - Always true, used as type guard
- * @property {LGraphNode} node - not included on IBaseWidget, but required for overlay
- */
-type Overlay = Partial<IBaseWidget> & {
-  graph: LGraph
-  nodeId: string
-  widgetName: string
-  isProxyWidget: boolean
-  node?: LGraphNode
-}
-// A ProxyWidget can be treated like a normal widget.
-// the _overlay property can be used to directly access the Overlay object
-/**
- * @typedef {object} ProxyWidget - a reference to a widget that can
- * be displayed and owned by a separate node
- * @property {Overlay} _overlay - a special property to access the overlay of the widget
- * Any property that exists in the overlay will be accessed instead of the property
- * on the linked widget
- */
-type ProxyWidget = IBaseWidget & { _overlay: Overlay }
-export function isProxyWidget(w: IBaseWidget): w is ProxyWidget {
-  return (w as { _overlay?: Overlay })?._overlay?.isProxyWidget ?? false
-}
-export function isDisconnectedWidget(w: ProxyWidget) {
-  return w instanceof disconnectedWidget.constructor
-}
-
-export function registerProxyWidgets(canvas: LGraphCanvas) {
-  //NOTE: canvasStore hasn't been initialized yet
-  canvas.canvas.addEventListener<'subgraph-opened'>('subgraph-opened', (e) => {
-    const { subgraph, fromNode } = e.detail
-    const proxyWidgets = parseProxyWidgets(fromNode.properties.proxyWidgets)
-    for (const node of subgraph.nodes) {
-      for (const widget of node.widgets ?? []) {
-        widget.promoted = proxyWidgets.some(
-          ([n, w]) => node.id == n && widget.name == w
-        )
-      }
-    }
-  })
-  canvas.canvas.addEventListener<'subgraph-converted'>(
-    'subgraph-converted',
-    (e) => promoteRecommendedWidgets(e.detail.subgraphNode)
-  )
-  SubgraphNode.prototype.onConfigure = onConfigure
-}
-
-const originalOnConfigure = SubgraphNode.prototype.onConfigure
-const onConfigure = function (
-  this: LGraphNode,
-  serialisedNode: ISerialisedNode
-) {
-  if (!this.isSubgraphNode())
-    throw new Error("Can't add proxyWidgets to non-subgraphNode")
-
-  const canvasStore = useCanvasStore()
-  //Must give value to proxyWidgets prior to defining or it won't serialize
-  this.properties.proxyWidgets ??= []
-
-  originalOnConfigure?.call(this, serialisedNode)
-
-  Object.defineProperty(this.properties, 'proxyWidgets', {
-    get: () =>
-      this.widgets.map((w) =>
-        isProxyWidget(w)
-          ? [w._overlay.nodeId, w._overlay.widgetName]
-          : ['-1', w.name]
-      ),
-    set: (property: NodeProperty) => {
-      const parsed = parseProxyWidgets(property)
-      const { deactivateWidget, setWidget } = useDomWidgetStore()
-      const isActiveGraph = useCanvasStore().canvas?.graph === this.graph
-      if (isActiveGraph) {
-        for (const w of this.widgets.filter((w) => isProxyWidget(w))) {
-          if (w instanceof DOMWidgetImpl) deactivateWidget(w.id)
-        }
-      }
-
-      const newWidgets = parsed.flatMap(([nodeId, widgetName]) => {
-        if (nodeId === '-1') {
-          const widget = this.widgets.find((w) => w.name === widgetName)
-          return widget ? [widget] : []
-        }
-        const w = newProxyWidget(this, nodeId, widgetName)
-        if (isActiveGraph && w instanceof DOMWidgetImpl) setWidget(w)
-        return [w]
-      })
-      this.widgets = this.widgets.filter((w) => {
-        if (isProxyWidget(w)) return false
-        const widgetName = w.name
-        return !parsed.some(([, name]) => widgetName === name)
-      })
-      this.widgets.push(...newWidgets)
-
-      canvasStore.canvas?.setDirty(true, true)
-      this._setConcreteSlots()
-      this.arrange()
-    }
-  })
-  if (serialisedNode.properties?.proxyWidgets) {
-    this.properties.proxyWidgets = serialisedNode.properties.proxyWidgets
-    const parsed = parseProxyWidgets(serialisedNode.properties.proxyWidgets)
-    serialisedNode.widgets_values?.forEach((v, index) => {
-      if (parsed[index]?.[0] !== '-1') return
-      const widget = this.widgets.find((w) => w.name == parsed[index][1])
-      if (v !== null && widget) widget.value = v
-    })
-  }
-}
-
-function newProxyWidget(
-  subgraphNode: SubgraphNode,
-  nodeId: string,
-  widgetName: string
-) {
-  const name = `${nodeId}: ${widgetName}`
-  const overlay = {
-    //items specific for proxy management
-    nodeId,
-    graph: subgraphNode.subgraph,
-    widgetName,
-    //Items which normally exist on widgets
-    afterQueued: undefined,
-    computedHeight: undefined,
-    isProxyWidget: true,
-    last_y: undefined,
-    name,
-    node: subgraphNode,
-    onRemove: undefined,
-    promoted: undefined,
-    serialize: false,
-    width: undefined,
-    y: 0
-  }
-  return newProxyFromOverlay(subgraphNode, overlay)
-}
-function resolveLinkedWidget(
-  overlay: Overlay
-): [LGraphNode | undefined, IBaseWidget | undefined] {
-  const { graph, nodeId, widgetName } = overlay
-  const n = getNodeByExecutionId(graph, nodeId)
-  if (!n) return [undefined, undefined]
-  const widget = n.widgets?.find((w: IBaseWidget) => w.name === widgetName)
-  //Slightly hacky. Force recursive resolution of nested widgets
-  if (widget && isProxyWidget(widget) && isDisconnectedWidget(widget))
-    widget.computedHeight = 20
-  return [n, widget]
-}
-
-function newProxyFromOverlay(subgraphNode: SubgraphNode, overlay: Overlay) {
-  const { updatePreviews } = useLitegraphService()
-  let [linkedNode, linkedWidget] = resolveLinkedWidget(overlay)
-  let backingWidget = linkedWidget ?? disconnectedWidget
-  if (overlay.widgetName.startsWith('$$')) {
-    overlay.node = new Proxy(subgraphNode, {
-      get(_t, p) {
-        if (p !== 'imgs') return Reflect.get(subgraphNode, p)
-        if (!linkedNode) return []
-        return linkedNode.imgs
-      }
-    })
-  }
-  /**
-   * A set of handlers which define widget interaction
-   * Many arguments are shared between function calls
-   * @param {IBaseWidget} _t - The "target" the call is originally made on.
-   *   This argument is never used, but must be defined for typechecking
-   * @param {string} property - The name of the accessed value.
-   *   Checked for conditional logic, but never changed
-   * @param {object} receiver - The object the result is set to
-   *   and the value used as 'this' if property is a get/set method
-   * @param {unknown} value - only used on set calls. The thing being assigned
-   */
-  let userLabel: string | undefined
-  const handler = {
-    get(_t: IBaseWidget, property: string, receiver: object) {
-      let redirectedTarget: object = backingWidget
-      let redirectedReceiver = receiver
-      if (property == '_overlay') return overlay
-      else if (property == 'value') redirectedReceiver = backingWidget
-      else if (property == 'label')
-        return userLabel ?? linkedWidget?.label ?? overlay.widgetName
-      if (Object.prototype.hasOwnProperty.call(overlay, property)) {
-        redirectedTarget = overlay
-        redirectedReceiver = overlay
-      }
-      return Reflect.get(redirectedTarget, property, redirectedReceiver)
-    },
-    set(_t: IBaseWidget, property: string, value: unknown) {
-      if (property == 'label') {
-        userLabel = value as string | undefined
-        return true
-      }
-      let redirectedTarget: object = backingWidget
-      if (property == 'computedHeight') {
-        if (overlay.widgetName.startsWith('$$') && linkedNode) {
-          updatePreviews(linkedNode)
-        }
-        if (linkedNode && linkedWidget?.computedDisabled) {
-          demoteWidget(linkedNode, linkedWidget, [subgraphNode])
-        }
-        //update linkage regularly, but no more than once per frame
-        ;[linkedNode, linkedWidget] = resolveLinkedWidget(overlay)
-        backingWidget = linkedWidget ?? disconnectedWidget
-      }
-      if (Object.prototype.hasOwnProperty.call(overlay, property)) {
-        redirectedTarget = overlay
-      }
-      return Reflect.set(redirectedTarget, property, value, redirectedTarget)
-    },
-    getPrototypeOf() {
-      return Reflect.getPrototypeOf(backingWidget)
-    },
-    ownKeys() {
-      return Reflect.ownKeys(backingWidget)
-    },
-    has(_t: IBaseWidget, property: string) {
-      let redirectedTarget: object = backingWidget
-      if (Object.prototype.hasOwnProperty.call(overlay, property)) {
-        redirectedTarget = overlay
-      }
-      return Reflect.has(redirectedTarget, property)
-    }
-  }
-  const w = new Proxy(disconnectedWidget, handler)
-  return w
-}

src/core/graph/subgraph/proxyWidgetUtils.ts

@@ -1,188 +0,0 @@
-import { parseProxyWidgets } from '@/core/schemas/proxyWidget'
-import type { ProxyWidgetsProperty } from '@/core/schemas/proxyWidget'
-import {
-  isProxyWidget,
-  isDisconnectedWidget
-} from '@/core/graph/subgraph/proxyWidget'
-import { t } from '@/i18n'
-import type {
-  IContextMenuValue,
-  LGraphNode
-} from '@/lib/litegraph/src/litegraph'
-import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
-import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets.ts'
-import { useToastStore } from '@/platform/updates/common/toastStore'
-import { useCanvasStore } from '@/renderer/core/canvas/canvasStore'
-import { useLitegraphService } from '@/services/litegraphService'
-import { useSubgraphNavigationStore } from '@/stores/subgraphNavigationStore'
-
-type PartialNode = Pick<LGraphNode, 'title' | 'id' | 'type'>
-
-export type WidgetItem = [PartialNode, IBaseWidget]
-
-function getProxyWidgets(node: SubgraphNode) {
-  return parseProxyWidgets(node.properties.proxyWidgets)
-}
-export function promoteWidget(
-  node: PartialNode,
-  widget: IBaseWidget,
-  parents: SubgraphNode[]
-) {
-  for (const parent of parents) {
-    const existingProxyWidgets = getProxyWidgets(parent)
-    // Prevent duplicate promotion
-    if (existingProxyWidgets.some(matchesPropertyItem([node, widget]))) {
-      continue
-    }
-    const proxyWidgets = [
-      ...existingProxyWidgets,
-      widgetItemToProperty([node, widget])
-    ]
-    parent.properties.proxyWidgets = proxyWidgets
-  }
-  widget.promoted = true
-}
-
-export function demoteWidget(
-  node: PartialNode,
-  widget: IBaseWidget,
-  parents: SubgraphNode[]
-) {
-  for (const parent of parents) {
-    const proxyWidgets = getProxyWidgets(parent).filter(
-      (widgetItem) => !matchesPropertyItem([node, widget])(widgetItem)
-    )
-    parent.properties.proxyWidgets = proxyWidgets
-  }
-  widget.promoted = false
-}
-
-function getWidgetName(w: IBaseWidget): string {
-  return isProxyWidget(w) ? w._overlay.widgetName : w.name
-}
-
-export function matchesWidgetItem([nodeId, widgetName]: [string, string]) {
-  return ([n, w]: WidgetItem) =>
-    n.id == nodeId && getWidgetName(w) === widgetName
-}
-export function matchesPropertyItem([n, w]: WidgetItem) {
-  return ([nodeId, widgetName]: [string, string]) =>
-    n.id == nodeId && getWidgetName(w) === widgetName
-}
-export function widgetItemToProperty([n, w]: WidgetItem): [string, string] {
-  return [`${n.id}`, getWidgetName(w)]
-}
-
-function getParentNodes(): SubgraphNode[] {
-  //NOTE: support for determining parents of a subgraph is limited
-  //This function will require rework to properly support linked subgraphs
-  //Either by including actual parents in the navigation stack,
-  //or by adding a new event for parent listeners to collect from
-  const { navigationStack } = useSubgraphNavigationStore()
-  const subgraph = navigationStack.at(-1)
-  if (!subgraph) {
-    useToastStore().add({
-      severity: 'error',
-      summary: t('g.error'),
-      detail: t('subgraphStore.promoteOutsideSubgraph'),
-      life: 2000
-    })
-    return []
-  }
-  const parentGraph = navigationStack.at(-2) ?? subgraph.rootGraph
-  return parentGraph.nodes.filter(
-    (node): node is SubgraphNode =>
-      node.type === subgraph.id && node.isSubgraphNode()
-  )
-}
-
-export function addWidgetPromotionOptions(
-  options: (IContextMenuValue<unknown> | null)[],
-  widget: IBaseWidget,
-  node: LGraphNode
-) {
-  const parents = getParentNodes()
-  const promotableParents = parents.filter(
-    (s) => !getProxyWidgets(s).some(matchesPropertyItem([node, widget]))
-  )
-  if (promotableParents.length > 0)
-    options.unshift({
-      content: `Promote Widget: ${widget.label ?? widget.name}`,
-      callback: () => {
-        promoteWidget(node, widget, promotableParents)
-        widget.callback?.(widget.value)
-      }
-    })
-  else {
-    options.unshift({
-      content: `Un-Promote Widget: ${widget.label ?? widget.name}`,
-      callback: () => {
-        demoteWidget(node, widget, parents)
-        widget.callback?.(widget.value)
-      }
-    })
-  }
-}
-export function tryToggleWidgetPromotion() {
-  const canvas = useCanvasStore().getCanvas()
-  const [x, y] = canvas.graph_mouse
-  const node = canvas.graph?.getNodeOnPos(x, y, canvas.visible_nodes)
-  if (!node) return
-  const widget = node.getWidgetOnPos(x, y, true)
-  const parents = getParentNodes()
-  if (!parents.length || !widget) return
-  const promotableParents = parents.filter(
-    (s) => !getProxyWidgets(s).some(matchesPropertyItem([node, widget]))
-  )
-  if (promotableParents.length > 0)
-    promoteWidget(node, widget, promotableParents)
-  else demoteWidget(node, widget, parents)
-}
-const recommendedNodes = [
-  'CLIPTextEncode',
-  'LoadImage',
-  'SaveImage',
-  'PreviewImage'
-]
-const recommendedWidgetNames = ['seed']
-export function isRecommendedWidget([node, widget]: WidgetItem) {
-  return (
-    !widget.computedDisabled &&
-    (recommendedNodes.includes(node.type) ||
-      recommendedWidgetNames.includes(widget.name))
-  )
-}
-
-function nodeWidgets(n: LGraphNode): WidgetItem[] {
-  return n.widgets?.map((w: IBaseWidget) => [n, w]) ?? []
-}
-export function promoteRecommendedWidgets(subgraphNode: SubgraphNode) {
-  const { updatePreviews } = useLitegraphService()
-  const interiorNodes = subgraphNode.subgraph.nodes
-  for (const node of interiorNodes) {
-    node.updateComputedDisabled()
-    function checkWidgets() {
-      updatePreviews(node)
-      const widget = node.widgets?.find((w) => w.name.startsWith('$$'))
-      if (!widget) return
-      const pw = getProxyWidgets(subgraphNode)
-      if (pw.some(matchesPropertyItem([node, widget]))) return
-      promoteWidget(node, widget, [subgraphNode])
-    }
-    requestAnimationFrame(() => updatePreviews(node, checkWidgets))
-  }
-  const filteredWidgets: WidgetItem[] = interiorNodes
-    .flatMap(nodeWidgets)
-    .filter(isRecommendedWidget)
-  const proxyWidgets: ProxyWidgetsProperty =
-    filteredWidgets.map(widgetItemToProperty)
-  subgraphNode.properties.proxyWidgets = proxyWidgets
-  subgraphNode.computeSize(subgraphNode.size)
-}
-
-export function pruneDisconnected(subgraphNode: SubgraphNode) {
-  subgraphNode.properties.proxyWidgets = subgraphNode.widgets
-    .filter(isProxyWidget)
-    .filter((w) => !isDisconnectedWidget(w))
-    .map((w) => [w._overlay.nodeId, w._overlay.widgetName])
-}

src/core/graph/subgraph/resolvePromotedWidgetSource.ts

@@ -0,0 +1,29 @@
+import { isPromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetTypes'
+import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
+
+interface ResolvedPromotedWidgetSource {
+  node: LGraphNode
+  widget: IBaseWidget
+}
+
+export function resolvePromotedWidgetSource(
+  hostNode: LGraphNode,
+  widget: IBaseWidget
+): ResolvedPromotedWidgetSource | undefined {
+  if (!isPromotedWidgetView(widget)) return undefined
+  if (!hostNode.isSubgraphNode()) return undefined
+
+  const sourceNode = hostNode.subgraph.getNodeById(widget.sourceNodeId)
+  if (!sourceNode) return undefined
+
+  const sourceWidget = sourceNode.widgets?.find(
+    (entry) => entry.name === widget.sourceWidgetName
+  )
+  if (!sourceWidget) return undefined
+
+  return {
+    node: sourceNode,
+    widget: sourceWidget
+  }
+}

src/core/graph/subgraph/subgraphNodePromotion.test.ts

@@ -0,0 +1,287 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { SubgraphNode } from '@/lib/litegraph/src/litegraph'
+import { usePromotionStore } from '@/stores/promotionStore'
+
+import {
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
+
+vi.mock('@/renderer/core/canvas/canvasStore', () => ({
+  useCanvasStore: () => ({})
+}))
+vi.mock('@/stores/domWidgetStore', () => ({
+  useDomWidgetStore: () => ({ widgetStates: new Map() })
+}))
+vi.mock('@/services/litegraphService', () => ({
+  useLitegraphService: () => ({ updatePreviews: () => ({}) })
+}))
+
+function setupSubgraph(
+  innerNodeCount: number = 0
+): [SubgraphNode, LGraphNode[]] {
+  const subgraph = createTestSubgraph()
+  const subgraphNode = createTestSubgraphNode(subgraph)
+  subgraphNode._internalConfigureAfterSlots()
+  const graph = subgraphNode.graph!
+  graph.add(subgraphNode)
+  const innerNodes = []
+  for (let i = 0; i < innerNodeCount; i++) {
+    const innerNode = new LGraphNode(`InnerNode${i}`)
+    subgraph.add(innerNode)
+    innerNodes.push(innerNode)
+  }
+  return [subgraphNode, innerNodes]
+}
+
+describe('Subgraph proxyWidgets', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  test('Can add simple widget', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [{ interiorNodeId: '1', widgetName: 'stringWidget' }]
+    )
+    expect(subgraphNode.widgets.length).toBe(1)
+    expect(
+      usePromotionStore().getPromotions(
+        subgraphNode.rootGraph.id,
+        subgraphNode.id
+      )
+    ).toStrictEqual([{ interiorNodeId: '1', widgetName: 'stringWidget' }])
+  })
+  test('Can add multiple widgets with same name', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(2)
+    for (const innerNode of innerNodes)
+      innerNode.addWidget('text', 'stringWidget', 'value', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [
+        { interiorNodeId: '1', widgetName: 'stringWidget' },
+        { interiorNodeId: '2', widgetName: 'stringWidget' }
+      ]
+    )
+    expect(subgraphNode.widgets.length).toBe(2)
+    // Both views share the widget name; they're distinguished by sourceNodeId
+    expect(subgraphNode.widgets[0].name).toBe('stringWidget')
+    expect(subgraphNode.widgets[1].name).toBe('stringWidget')
+  })
+  test('Will reflect proxyWidgets order changes', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const store = usePromotionStore()
+    innerNodes[0].addWidget('text', 'widgetA', 'value', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'value', () => {})
+
+    store.setPromotions(subgraphNode.rootGraph.id, subgraphNode.id, [
+      { interiorNodeId: '1', widgetName: 'widgetA' },
+      { interiorNodeId: '1', widgetName: 'widgetB' }
+    ])
+    expect(subgraphNode.widgets.length).toBe(2)
+    expect(subgraphNode.widgets[0].name).toBe('widgetA')
+    expect(subgraphNode.widgets[1].name).toBe('widgetB')
+
+    // Reorder
+    store.setPromotions(subgraphNode.rootGraph.id, subgraphNode.id, [
+      { interiorNodeId: '1', widgetName: 'widgetB' },
+      { interiorNodeId: '1', widgetName: 'widgetA' }
+    ])
+    expect(subgraphNode.widgets[0].name).toBe('widgetB')
+    expect(subgraphNode.widgets[1].name).toBe('widgetA')
+  })
+  test('Will mirror changes to value', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [{ interiorNodeId: '1', widgetName: 'stringWidget' }]
+    )
+    expect(subgraphNode.widgets.length).toBe(1)
+    expect(subgraphNode.widgets[0].value).toBe('value')
+    innerNodes[0].widgets![0].value = 'test'
+    expect(subgraphNode.widgets[0].value).toBe('test')
+    subgraphNode.widgets[0].value = 'test2'
+    expect(innerNodes[0].widgets![0].value).toBe('test2')
+  })
+  test('Will not modify position or sizing of existing widgets', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [{ interiorNodeId: '1', widgetName: 'stringWidget' }]
+    )
+    if (!innerNodes[0].widgets) throw new Error('node has no widgets')
+    innerNodes[0].widgets[0].y = 10
+    innerNodes[0].widgets[0].last_y = 11
+    innerNodes[0].widgets[0].computedHeight = 12
+    subgraphNode.widgets[0].y = 20
+    subgraphNode.widgets[0].last_y = 21
+    subgraphNode.widgets[0].computedHeight = 22
+    expect(innerNodes[0].widgets[0].y).toBe(10)
+    expect(innerNodes[0].widgets[0].last_y).toBe(11)
+    expect(innerNodes[0].widgets[0].computedHeight).toBe(12)
+  })
+  test('Renders placeholder when interior widget is detached', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [{ interiorNodeId: '1', widgetName: 'stringWidget' }]
+    )
+    if (!innerNodes[0].widgets) throw new Error('node has no widgets')
+
+    // View resolves the interior widget's type
+    expect(subgraphNode.widgets[0].type).toBe('text')
+
+    // Remove interior widget — view falls back to disconnected state
+    innerNodes[0].widgets.pop()
+    expect(subgraphNode.widgets[0].type).toBe('button')
+
+    // Re-add — view resolves again
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+    expect(subgraphNode.widgets[0].type).toBe('text')
+  })
+  test('Prevents duplicate promotion', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const store = usePromotionStore()
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+
+    // Promote once
+    store.promote(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      String(innerNodes[0].id),
+      'stringWidget'
+    )
+    expect(subgraphNode.widgets.length).toBe(1)
+    expect(
+      store.getPromotions(subgraphNode.rootGraph.id, subgraphNode.id)
+    ).toHaveLength(1)
+
+    // Try to promote again - should not create duplicate
+    store.promote(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      String(innerNodes[0].id),
+      'stringWidget'
+    )
+    expect(subgraphNode.widgets.length).toBe(1)
+    expect(
+      store.getPromotions(subgraphNode.rootGraph.id, subgraphNode.id)
+    ).toHaveLength(1)
+    expect(
+      store.getPromotions(subgraphNode.rootGraph.id, subgraphNode.id)
+    ).toStrictEqual([{ interiorNodeId: '1', widgetName: 'stringWidget' }])
+  })
+
+  test('removeWidget removes from promotion list and view cache', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    const store = usePromotionStore()
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+    store.setPromotions(subgraphNode.rootGraph.id, subgraphNode.id, [
+      { interiorNodeId: '1', widgetName: 'widgetA' },
+      { interiorNodeId: '1', widgetName: 'widgetB' }
+    ])
+    expect(subgraphNode.widgets).toHaveLength(2)
+
+    const widgetToRemove = subgraphNode.widgets[0]
+    subgraphNode.removeWidget(widgetToRemove)
+
+    expect(subgraphNode.widgets).toHaveLength(1)
+    expect(subgraphNode.widgets[0].name).toBe('widgetB')
+    expect(
+      store.getPromotions(subgraphNode.rootGraph.id, subgraphNode.id)
+    ).toStrictEqual([{ interiorNodeId: '1', widgetName: 'widgetB' }])
+  })
+
+  test('removeWidgetByName removes from promotion list', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [
+        { interiorNodeId: '1', widgetName: 'widgetA' },
+        { interiorNodeId: '1', widgetName: 'widgetB' }
+      ]
+    )
+
+    subgraphNode.removeWidgetByName('widgetA')
+
+    expect(subgraphNode.widgets).toHaveLength(1)
+    expect(subgraphNode.widgets[0].name).toBe('widgetB')
+  })
+
+  test('removeWidget cleans up input references', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [{ interiorNodeId: '1', widgetName: 'stringWidget' }]
+    )
+
+    const view = subgraphNode.widgets[0]
+    // Simulate an input referencing the widget
+    subgraphNode.addInput('stringWidget', '*')
+    const input = subgraphNode.inputs[subgraphNode.inputs.length - 1]
+    input._widget = view
+
+    subgraphNode.removeWidget(view)
+
+    expect(input._widget).toBeUndefined()
+    expect(subgraphNode.widgets).toHaveLength(0)
+  })
+
+  test('serialize does not produce widgets_values for promoted views', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'stringWidget', 'value', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [{ interiorNodeId: '1', widgetName: 'stringWidget' }]
+    )
+    expect(subgraphNode.widgets).toHaveLength(1)
+
+    const serialized = subgraphNode.serialize()
+
+    // SubgraphNode doesn't set serialize_widgets, so widgets_values is absent.
+    // Even if it were set, views have serialize: false and would be skipped.
+    expect(serialized.widgets_values).toBeUndefined()
+  })
+
+  test('serialize preserves proxyWidgets in properties', () => {
+    const [subgraphNode, innerNodes] = setupSubgraph(1)
+    innerNodes[0].addWidget('text', 'widgetA', 'a', () => {})
+    innerNodes[0].addWidget('text', 'widgetB', 'b', () => {})
+    usePromotionStore().setPromotions(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      [
+        { interiorNodeId: '1', widgetName: 'widgetA' },
+        { interiorNodeId: '1', widgetName: 'widgetB' }
+      ]
+    )
+
+    const serialized = subgraphNode.serialize()
+
+    expect(serialized.properties?.proxyWidgets).toStrictEqual([
+      ['1', 'widgetA'],
+      ['1', 'widgetB']
+    ])
+  })
+})

src/core/graph/subgraph/unpromotedWidgetUtils.test.ts

@@ -0,0 +1,56 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import {
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
+import { usePromotionStore } from '@/stores/promotionStore'
+
+import { hasUnpromotedWidgets } from './unpromotedWidgetUtils'
+
+describe('hasUnpromotedWidgets', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  it('returns true when subgraph has at least one enabled unpromoted widget', () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const interiorNode = new LGraphNode('InnerNode')
+    subgraph.add(interiorNode)
+    interiorNode.addWidget('text', 'seed', '123', () => {})
+
+    expect(hasUnpromotedWidgets(subgraphNode)).toBe(true)
+  })
+
+  it('returns false when all enabled widgets are already promoted', () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const interiorNode = new LGraphNode('InnerNode')
+    subgraph.add(interiorNode)
+    interiorNode.addWidget('text', 'seed', '123', () => {})
+
+    usePromotionStore().promote(
+      subgraphNode.rootGraph.id,
+      subgraphNode.id,
+      String(interiorNode.id),
+      'seed'
+    )
+
+    expect(hasUnpromotedWidgets(subgraphNode)).toBe(false)
+  })
+
+  it('ignores computed-disabled widgets', () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const interiorNode = new LGraphNode('InnerNode')
+    subgraph.add(interiorNode)
+    const widget = interiorNode.addWidget('text', 'seed', '123', () => {})
+    widget.computedDisabled = true
+
+    expect(hasUnpromotedWidgets(subgraphNode)).toBe(false)
+  })
+})

src/core/graph/subgraph/unpromotedWidgetUtils.ts

@@ -0,0 +1,20 @@
+import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
+import { usePromotionStore } from '@/stores/promotionStore'
+
+export function hasUnpromotedWidgets(subgraphNode: SubgraphNode): boolean {
+  const promotionStore = usePromotionStore()
+  const { id: subgraphNodeId, rootGraph, subgraph } = subgraphNode
+
+  return subgraph.nodes.some((interiorNode) =>
+    (interiorNode.widgets ?? []).some(
+      (widget) =>
+        !widget.computedDisabled &&
+        !promotionStore.isPromoted(
+          rootGraph.id,
+          subgraphNodeId,
+          String(interiorNode.id),
+          widget.name
+        )
+    )
+  )
+}

src/core/schemas/promotionSchema.ts

@@ -4,7 +4,7 @@ import { fromZodError } from 'zod-validation-error'
 import type { NodeProperty } from '@/lib/litegraph/src/LGraphNode'
 
 const proxyWidgetsPropertySchema = z.array(z.tuple([z.string(), z.string()]))
-export type ProxyWidgetsProperty = z.infer<typeof proxyWidgetsPropertySchema>
+type ProxyWidgetsProperty = z.infer<typeof proxyWidgetsPropertySchema>
 
 export function parseProxyWidgets(
   property: NodeProperty | undefined

src/extensions/core/uploadAudio.ts

@@ -5,6 +5,7 @@ import { useNodeFileInput } from '@/composables/node/useNodeFileInput'
 import { useNodePaste } from '@/composables/node/useNodePaste'
 import { t } from '@/i18n'
 import type { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import { resolveNodeRootGraphId } from '@/lib/litegraph/src/litegraph'
 import type {
   IBaseWidget,
   IStringWidget
@@ -143,10 +144,15 @@ app.registerExtension({
         }
 
         audioUIWidget.options.getValue = () =>
-          (useWidgetValueStore().getWidget(node.id, inputName)
-            ?.value as string) ?? ''
+          (useWidgetValueStore().getWidget(
+            resolveNodeRootGraphId(node, app.rootGraph.id),
+            node.id,
+            inputName
+          )?.value as string) ?? ''
         audioUIWidget.options.setValue = (v) => {
+          const graphId = resolveNodeRootGraphId(node, app.rootGraph.id)
           const widgetState = useWidgetValueStore().getWidget(
+            graphId,
             node.id,
             inputName
           )

src/lib/litegraph/src/LGraph.test.ts

@@ -1,12 +1,17 @@
-import { describe, expect, it } from 'vitest'
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it } from 'vitest'
 
-import type { Subgraph } from '@/lib/litegraph/src/litegraph'
+import type { NodeId, Subgraph } from '@/lib/litegraph/src/litegraph'
 import {
   LGraph,
   LGraphNode,
   LiteGraph,
   LLink
 } from '@/lib/litegraph/src/litegraph'
+import type { UUID } from '@/lib/litegraph/src/utils/uuid'
+import { usePromotionStore } from '@/stores/promotionStore'
+import { useWidgetValueStore } from '@/stores/widgetValueStore'
 import {
   createTestSubgraphData,
   createTestSubgraphNode
@@ -225,9 +230,48 @@ describe('Graph Clearing and Callbacks', () => {
     // Verify nodes were actually removed
     expect(graph.nodes.length).toBe(0)
   })
+
+  test('clear() removes graph-scoped promotion and widget-value state', () => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+
+    const graph = new LGraph()
+    const graphId = 'graph-clear-cleanup' as UUID
+    graph.id = graphId
+
+    const promotionStore = usePromotionStore()
+    promotionStore.promote(graphId, 1 as NodeId, '10', 'seed')
+
+    const widgetValueStore = useWidgetValueStore()
+    widgetValueStore.registerWidget(graphId, {
+      nodeId: '10' as NodeId,
+      name: 'seed',
+      type: 'number',
+      value: 1,
+      options: {},
+      label: undefined,
+      serialize: undefined,
+      disabled: undefined
+    })
+
+    expect(promotionStore.isPromotedByAny(graphId, '10', 'seed')).toBe(true)
+    expect(widgetValueStore.getWidget(graphId, '10' as NodeId, 'seed')).toEqual(
+      expect.objectContaining({ value: 1 })
+    )
+
+    graph.clear()
+
+    expect(promotionStore.isPromotedByAny(graphId, '10', 'seed')).toBe(false)
+    expect(
+      widgetValueStore.getWidget(graphId, '10' as NodeId, 'seed')
+    ).toBeUndefined()
+  })
 })
 
 describe('Subgraph Definition Garbage Collection', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
   function createSubgraphWithNodes(rootGraph: LGraph, nodeCount: number) {
     const subgraph = rootGraph.createSubgraph(createTestSubgraphData())
 

src/lib/litegraph/src/LGraph.ts

@@ -9,6 +9,8 @@ import type { UUID } from '@/lib/litegraph/src/utils/uuid'
 import { createUuidv4, zeroUuid } from '@/lib/litegraph/src/utils/uuid'
 import { useLayoutMutations } from '@/renderer/core/layout/operations/layoutMutations'
 import { LayoutSource } from '@/renderer/core/layout/types'
+import { usePromotionStore } from '@/stores/promotionStore'
+import { useWidgetValueStore } from '@/stores/widgetValueStore'
 import { forEachNode } from '@/utils/graphTraversalUtil'
 
 import type { DragAndScaleState } from './DragAndScale'
@@ -352,6 +354,12 @@ export class LGraph
     this.stop()
     this.status = LGraph.STATUS_STOPPED
 
+    const graphId = this.id
+    if (this.isRootGraph && graphId !== zeroUuid) {
+      usePromotionStore().clearGraph(graphId)
+      useWidgetValueStore().clearGraph(graphId)
+    }
+
     this.id = zeroUuid
     this.revision = 0
 
@@ -965,17 +973,17 @@ export class LGraph
       node.flags.ghost = true
     }
 
-    // Register all widgets with the WidgetValueStore now that node has a valid ID.
-    // Widgets added before the node was in the graph deferred their setNodeId call.
+    node.graph = this
+    this._version++
+
+    // Register all widgets with the WidgetValueStore now that node has a
+    // valid ID and graph reference.
     if (node.widgets) {
       for (const widget of node.widgets) {
         if (isNodeBindable(widget)) widget.setNodeId(node.id)
       }
     }
 
-    node.graph = this
-    this._version++
-
     this._nodes.push(node)
     this._nodes_by_id[node.id] = node
 

src/lib/litegraph/src/LGraphCanvas.clipboard.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest'
+
+import { LGraph, LGraphNode, createUuidv4 } from '@/lib/litegraph/src/litegraph'
+import { remapClipboardSubgraphNodeIds } from '@/lib/litegraph/src/LGraphCanvas'
+import type {
+  ClipboardItems,
+  ExportedSubgraph,
+  ISerialisedNode
+} from '@/lib/litegraph/src/types/serialisation'
+
+function createSerialisedNode(
+  id: number,
+  type: string,
+  proxyWidgets?: Array<[string, string]>
+): ISerialisedNode {
+  return {
+    id,
+    type,
+    pos: [0, 0],
+    size: [140, 80],
+    flags: {},
+    order: 0,
+    mode: 0,
+    inputs: [],
+    outputs: [],
+    properties: proxyWidgets ? { proxyWidgets } : {}
+  }
+}
+
+describe('remapClipboardSubgraphNodeIds', () => {
+  it('remaps pasted subgraph interior IDs and proxyWidgets references', () => {
+    const rootGraph = new LGraph()
+    const existingNode = new LGraphNode('existing')
+    existingNode.id = 1
+    rootGraph.add(existingNode)
+
+    const subgraphId = createUuidv4()
+    const pastedSubgraph: ExportedSubgraph = {
+      id: subgraphId,
+      version: 1,
+      revision: 0,
+      state: {
+        lastNodeId: 0,
+        lastLinkId: 0,
+        lastGroupId: 0,
+        lastRerouteId: 0
+      },
+      config: {},
+      name: 'Pasted Subgraph',
+      inputNode: {
+        id: -10,
+        bounding: [0, 0, 10, 10]
+      },
+      outputNode: {
+        id: -20,
+        bounding: [0, 0, 10, 10]
+      },
+      inputs: [],
+      outputs: [],
+      widgets: [],
+      nodes: [createSerialisedNode(1, 'test/node')],
+      links: [
+        {
+          id: 1,
+          type: '*',
+          origin_id: 1,
+          origin_slot: 0,
+          target_id: 1,
+          target_slot: 0
+        }
+      ],
+      groups: []
+    }
+
+    const parsed: ClipboardItems = {
+      nodes: [createSerialisedNode(99, subgraphId, [['1', 'seed']])],
+      groups: [],
+      reroutes: [],
+      links: [],
+      subgraphs: [pastedSubgraph]
+    }
+
+    remapClipboardSubgraphNodeIds(parsed, rootGraph)
+
+    const remappedSubgraph = parsed.subgraphs?.[0]
+    expect(remappedSubgraph).toBeDefined()
+
+    const remappedLink = remappedSubgraph?.links?.[0]
+    expect(remappedLink).toBeDefined()
+
+    const remappedInteriorId = remappedSubgraph?.nodes?.[0]?.id
+    expect(remappedInteriorId).not.toBe(1)
+    expect(remappedLink?.origin_id).toBe(remappedInteriorId)
+    expect(remappedLink?.target_id).toBe(remappedInteriorId)
+
+    const remappedNode = parsed.nodes?.[0]
+    expect(remappedNode).toBeDefined()
+    expect(remappedNode?.properties?.proxyWidgets).toStrictEqual([
+      [String(remappedInteriorId), 'seed']
+    ])
+  })
+})

src/lib/litegraph/src/LGraphCanvas.ts

@@ -4065,6 +4065,7 @@ export class LGraphCanvas implements CustomEventDispatcher<LGraphCanvasEventMap>
     for (const nodeInfo of allNodeInfo)
       if (nodeInfo.type in subgraphIdMap)
         nodeInfo.type = subgraphIdMap[nodeInfo.type]
+    remapClipboardSubgraphNodeIds(parsed, graph.rootGraph)
 
     // Subgraphs
     for (const info of parsed.subgraphs) {
@@ -4095,8 +4096,8 @@ export class LGraphCanvas implements CustomEventDispatcher<LGraphCanvasEventMap>
       nodes.set(info.id, node)
       info.id = -1
 
-      node.configure(info)
       graph.add(node)
+      node.configure(info)
 
       created.push(node)
     }
@@ -8797,3 +8798,115 @@ export class LGraphCanvas implements CustomEventDispatcher<LGraphCanvasEventMap>
     }
   }
 }
+
+function patchLinkNodeIds(
+  links: { origin_id: NodeId; target_id: NodeId }[] | undefined,
+  remappedIds: Map<NodeId, NodeId>
+) {
+  if (!links?.length) return
+
+  for (const link of links) {
+    const newOriginId = remappedIds.get(link.origin_id)
+    if (newOriginId !== undefined) link.origin_id = newOriginId
+
+    const newTargetId = remappedIds.get(link.target_id)
+    if (newTargetId !== undefined) link.target_id = newTargetId
+  }
+}
+
+function remapNodeId(
+  nodeId: string,
+  remappedIds: Map<NodeId, NodeId>
+): NodeId | undefined {
+  const directMatch = remappedIds.get(nodeId)
+  if (directMatch !== undefined) return directMatch
+  if (!/^-?\d+$/.test(nodeId)) return undefined
+
+  const numericId = Number(nodeId)
+  if (!Number.isSafeInteger(numericId)) return undefined
+
+  return remappedIds.get(numericId)
+}
+
+function remapProxyWidgets(
+  info: ISerialisedNode,
+  remappedIds: Map<NodeId, NodeId> | undefined
+) {
+  if (!remappedIds || remappedIds.size === 0) return
+
+  const proxyWidgets = info.properties?.proxyWidgets
+  if (!Array.isArray(proxyWidgets)) return
+
+  for (const entry of proxyWidgets) {
+    if (!Array.isArray(entry)) continue
+
+    const [nodeId] = entry
+    if (typeof nodeId !== 'string' || nodeId === '-1') continue
+
+    const remappedNodeId = remapNodeId(nodeId, remappedIds)
+    if (remappedNodeId !== undefined) entry[0] = String(remappedNodeId)
+  }
+}
+
+/**
+ * Remaps pasted subgraph interior node IDs that would collide with existing
+ * node IDs in the root graph. Also patches subgraph link node IDs and
+ * SubgraphNode `properties.proxyWidgets` references so promoted widget
+ * associations stay aligned with remapped interior IDs.
+ */
+export function remapClipboardSubgraphNodeIds(
+  parsed: ClipboardItems,
+  rootGraph: LGraph
+): void {
+  const usedNodeIds = new Set<number>()
+  forEachNode(rootGraph, (node) => {
+    if (typeof node.id !== 'number') return
+    usedNodeIds.add(node.id)
+    if (rootGraph.state.lastNodeId < node.id)
+      rootGraph.state.lastNodeId = node.id
+  })
+
+  function nextUniqueNodeId() {
+    while (usedNodeIds.has(++rootGraph.state.lastNodeId));
+    const nextId = rootGraph.state.lastNodeId
+    usedNodeIds.add(nextId)
+    return nextId
+  }
+
+  const subgraphNodeIdMap = new Map<UUID, Map<NodeId, NodeId>>()
+  for (const subgraphInfo of parsed.subgraphs ?? []) {
+    const remappedIds = new Map<NodeId, NodeId>()
+    const interiorNodes = subgraphInfo.nodes ?? []
+
+    for (const nodeInfo of interiorNodes) {
+      if (typeof nodeInfo.id !== 'number') continue
+
+      if (usedNodeIds.has(nodeInfo.id)) {
+        const oldId = nodeInfo.id
+        const newId = nextUniqueNodeId()
+        remappedIds.set(oldId, newId)
+        nodeInfo.id = newId
+        continue
+      }
+
+      usedNodeIds.add(nodeInfo.id)
+      if (rootGraph.state.lastNodeId < nodeInfo.id)
+        rootGraph.state.lastNodeId = nodeInfo.id
+    }
+
+    if (remappedIds.size > 0) {
+      patchLinkNodeIds(subgraphInfo.links, remappedIds)
+      subgraphNodeIdMap.set(subgraphInfo.id, remappedIds)
+    }
+  }
+
+  const allNodeInfo: ISerialisedNode[] = [
+    parsed.nodes ? [parsed.nodes] : [],
+    parsed.subgraphs ? parsed.subgraphs.map((s) => s.nodes ?? []) : []
+  ].flat(2)
+
+  for (const nodeInfo of allNodeInfo) {
+    if (typeof nodeInfo.type !== 'string') continue
+    remapProxyWidgets(nodeInfo, subgraphNodeIdMap.get(nodeInfo.type))
+  }
+}

src/lib/litegraph/src/infrastructure/SubgraphInputEventMap.ts

@@ -1,3 +1,4 @@
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
 import type { INodeInputSlot } from '@/lib/litegraph/src/litegraph'
 import type { SubgraphInput } from '@/lib/litegraph/src/subgraph/SubgraphInput'
 import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
@@ -8,6 +9,7 @@ export interface SubgraphInputEventMap extends LGraphEventMap {
   'input-connected': {
     input: INodeInputSlot
     widget: IBaseWidget
+    node: LGraphNode
   }
 
   'input-disconnected': {

src/lib/litegraph/src/litegraph.ts

@@ -144,7 +144,7 @@ export { isColorable } from './utils/type'
 export { createUuidv4 } from './utils/uuid'
 export type { UUID } from './utils/uuid'
 export { truncateText } from './utils/textUtils'
-export { getWidgetStep } from './utils/widget'
+export { getWidgetStep, resolveNodeRootGraphId } from './utils/widget'
 export { distributeSpace, type SpaceRequest } from './utils/spaceDistribution'
 
 export { BaseWidget } from './widgets/BaseWidget'

src/lib/litegraph/src/subgraph/PromotedWidgetViewManager.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'vitest'
+
+import { PromotedWidgetViewManager } from '@/lib/litegraph/src/subgraph/PromotedWidgetViewManager'
+import type { SubgraphPromotionEntry } from '@/services/subgraphPseudoWidgetCache'
+
+function makeView(entry: SubgraphPromotionEntry) {
+  return {
+    key: `${entry.interiorNodeId}:${entry.widgetName}`
+  }
+}
+
+describe('PromotedWidgetViewManager', () => {
+  test('returns memoized array when entries reference is unchanged', () => {
+    const manager = new PromotedWidgetViewManager<{ key: string }>()
+    const entries = [{ interiorNodeId: '1', widgetName: 'widgetA' }]
+
+    const first = manager.reconcile(entries, makeView)
+    const second = manager.reconcile(entries, makeView)
+
+    expect(second).toBe(first)
+    expect(second[0]).toBe(first[0])
+  })
+
+  test('preserves view identity while reflecting order changes', () => {
+    const manager = new PromotedWidgetViewManager<{ key: string }>()
+
+    const firstPass = manager.reconcile(
+      [
+        { interiorNodeId: '1', widgetName: 'widgetA' },
+        { interiorNodeId: '1', widgetName: 'widgetB' }
+      ],
+      makeView
+    )
+
+    const reordered = manager.reconcile(
+      [
+        { interiorNodeId: '1', widgetName: 'widgetB' },
+        { interiorNodeId: '1', widgetName: 'widgetA' }
+      ],
+      makeView
+    )
+
+    expect(reordered[0]).toBe(firstPass[1])
+    expect(reordered[1]).toBe(firstPass[0])
+  })
+
+  test('deduplicates by first occurrence and clears stale cache entries', () => {
+    const manager = new PromotedWidgetViewManager<{ key: string }>()
+
+    const first = manager.reconcile(
+      [
+        { interiorNodeId: '1', widgetName: 'widgetA' },
+        { interiorNodeId: '1', widgetName: 'widgetB' },
+        { interiorNodeId: '1', widgetName: 'widgetA' }
+      ],
+      makeView
+    )
+    expect(first.map((view) => view.key)).toStrictEqual([
+      '1:widgetA',
+      '1:widgetB'
+    ])
+
+    manager.reconcile(
+      [{ interiorNodeId: '1', widgetName: 'widgetB' }],
+      makeView
+    )
+
+    const restored = manager.reconcile(
+      [
+        { interiorNodeId: '1', widgetName: 'widgetB' },
+        { interiorNodeId: '1', widgetName: 'widgetA' }
+      ],
+      makeView
+    )
+
+    expect(restored[0]).toBe(first[1])
+    expect(restored[1]).not.toBe(first[0])
+  })
+})

src/lib/litegraph/src/subgraph/PromotedWidgetViewManager.ts

@@ -0,0 +1,86 @@
+type PromotionEntry = {
+  interiorNodeId: string
+  widgetName: string
+}
+
+type CreateView<TView> = (entry: PromotionEntry) => TView
+
+/**
+ * Reconciles promoted widget entries to stable view instances.
+ *
+ * Keeps object identity stable by key while preserving the current
+ * promotion order and deduplicating duplicate entries by first occurrence.
+ */
+export class PromotedWidgetViewManager<TView> {
+  private viewCache = new Map<string, TView>()
+  private cachedViews: TView[] | null = null
+  private cachedEntriesRef: readonly PromotionEntry[] | null = null
+
+  reconcile(
+    entries: readonly PromotionEntry[],
+    createView: CreateView<TView>
+  ): TView[] {
+    if (this.cachedViews && entries === this.cachedEntriesRef)
+      return this.cachedViews
+
+    const views: TView[] = []
+    const seenKeys = new Set<string>()
+
+    for (const entry of entries) {
+      const key = this.makeKey(entry.interiorNodeId, entry.widgetName)
+      if (seenKeys.has(key)) continue
+      seenKeys.add(key)
+
+      const existing = this.viewCache.get(key)
+      if (existing) {
+        views.push(existing)
+        continue
+      }
+
+      const nextView = createView(entry)
+      this.viewCache.set(key, nextView)
+      views.push(nextView)
+    }
+
+    for (const key of this.viewCache.keys()) {
+      if (!seenKeys.has(key)) this.viewCache.delete(key)
+    }
+
+    this.cachedViews = views
+    this.cachedEntriesRef = entries
+    return views
+  }
+
+  getOrCreate(
+    interiorNodeId: string,
+    widgetName: string,
+    createView: () => TView
+  ): TView {
+    const key = this.makeKey(interiorNodeId, widgetName)
+    const cached = this.viewCache.get(key)
+    if (cached) return cached
+
+    const view = createView()
+    this.viewCache.set(key, view)
+    return view
+  }
+
+  remove(interiorNodeId: string, widgetName: string): void {
+    this.viewCache.delete(this.makeKey(interiorNodeId, widgetName))
+    this.invalidateMemoizedList()
+  }
+
+  clear(): void {
+    this.viewCache.clear()
+    this.invalidateMemoizedList()
+  }
+
+  invalidateMemoizedList(): void {
+    this.cachedViews = null
+    this.cachedEntriesRef = null
+  }
+
+  private makeKey(interiorNodeId: string, widgetName: string): string {
+    return `${interiorNodeId}:${widgetName}`
+  }
+}

src/lib/litegraph/src/subgraph/SubgraphInput.ts

@@ -90,7 +90,8 @@ export class SubgraphInput extends SubgraphSlot {
       this._widget ??= inputWidget
       this.events.dispatch('input-connected', {
         input: slot,
-        widget: inputWidget
+        widget: inputWidget,
+        node
       })
     }
 

src/lib/litegraph/src/subgraph/SubgraphNode.ts

@@ -29,11 +29,18 @@ import type {
 } from '@/lib/litegraph/src/types/serialisation'
 import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets'
 import type { UUID } from '@/lib/litegraph/src/utils/uuid'
-import { BaseWidget } from '@/lib/litegraph/src/widgets/BaseWidget'
-import { AssetWidget } from '@/lib/litegraph/src/widgets/AssetWidget'
+import {
+  createPromotedWidgetView,
+  isPromotedWidgetView
+} from '@/core/graph/subgraph/promotedWidgetView'
+import type { PromotedWidgetView } from '@/core/graph/subgraph/promotedWidgetView'
+import { parseProxyWidgets } from '@/core/schemas/promotionSchema'
+import { useDomWidgetStore } from '@/stores/domWidgetStore'
+import { usePromotionStore } from '@/stores/promotionStore'
 
 import { ExecutableNodeDTO } from './ExecutableNodeDTO'
 import type { ExecutableLGraphNode, ExecutionId } from './ExecutableNodeDTO'
+import { PromotedWidgetViewManager } from './PromotedWidgetViewManager'
 import type { SubgraphInput } from './SubgraphInput'
 
 const workflowSvg = new Image()
@@ -64,7 +71,55 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
     return true
   }
 
-  override widgets: IBaseWidget[] = []
+  private _promotedViewManager =
+    new PromotedWidgetViewManager<PromotedWidgetView>()
+
+  // Declared as accessor via Object.defineProperty in constructor.
+  // TypeScript doesn't allow overriding a property with get/set syntax,
+  // so we use declare + defineProperty instead.
+  declare widgets: IBaseWidget[]
+
+  private _getPromotedViews(): PromotedWidgetView[] {
+    const store = usePromotionStore()
+    const entries = store.getPromotionsRef(this.rootGraph.id, this.id)
+
+    return this._promotedViewManager.reconcile(entries, (entry) =>
+      createPromotedWidgetView(this, entry.interiorNodeId, entry.widgetName)
+    )
+  }
+
+  private _resolveLegacyEntry(
+    widgetName: string
+  ): [string, string] | undefined {
+    // Legacy -1 entries use the slot name as the widget name.
+    // Find the input with that name, then trace to the connected interior widget.
+    const input = this.inputs.find((i) => i.name === widgetName)
+    if (!input?._widget) return undefined
+
+    const widget = input._widget
+    if (isPromotedWidgetView(widget)) {
+      return [widget.sourceNodeId, widget.sourceWidgetName]
+    }
+
+    // Fallback: find via subgraph input slot connection
+    const subgraphInput = this.subgraph.inputNode.slots.find(
+      (slot) => slot.name === widgetName
+    )
+    if (!subgraphInput) return undefined
+
+    for (const linkId of subgraphInput.linkIds) {
+      const link = this.subgraph.getLink(linkId)
+      if (!link) continue
+      const { inputNode } = link.resolve(this.subgraph)
+      if (!inputNode) continue
+      const targetInput = inputNode.inputs.find((inp) => inp.link === linkId)
+      if (!targetInput) continue
+      const w = inputNode.getWidgetFromSlot(targetInput)
+      if (w) return [String(inputNode.id), w.name]
+    }
+
+    return undefined
+  }
 
   /** Manages lifecycle of all subgraph event listeners */
   private _eventAbortController = new AbortController()
@@ -79,6 +134,19 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
     super(subgraph.name, subgraph.id)
     this.graph = graph
 
+    // Synthetic widgets getter — SubgraphNodes have no native widgets.
+    Object.defineProperty(this, 'widgets', {
+      get: () => this._getPromotedViews(),
+      set: () => {
+        if (import.meta.env.DEV)
+          console.warn(
+            'Cannot manually set widgets on SubgraphNode; use the promotion system.'
+          )
+      },
+      configurable: true,
+      enumerable: true
+    })
+
     // Update this node when the subgraph input / output slots are changed
     const subgraphEvents = this.subgraph.events
     const { signal } = this._eventAbortController
@@ -88,13 +156,19 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
       (e) => {
         const subgraphInput = e.detail.input
         const { name, type } = subgraphInput
-        const existingInput = this.inputs.find((i) => i.name == name)
+        const existingInput = this.inputs.find((i) => i.name === name)
         if (existingInput) {
           const linkId = subgraphInput.linkIds[0]
           const { inputNode, input } = subgraph.links[linkId].resolve(subgraph)
-          const widget = inputNode?.widgets?.find?.((w) => w.name == name)
-          if (widget)
-            this._setWidget(subgraphInput, existingInput, widget, input?.widget)
+          const widget = inputNode?.widgets?.find?.((w) => w.name === name)
+          if (widget && inputNode)
+            this._setWidget(
+              subgraphInput,
+              existingInput,
+              widget,
+              input?.widget,
+              inputNode
+            )
           return
         }
         const input = this.addInput(name, type)
@@ -200,13 +274,36 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
     subgraphInput.events.addEventListener(
       'input-connected',
       (e) => {
-        if (input._widget) return
-
         const widget = subgraphInput._widget
         if (!widget) return
 
+        // If this widget is already promoted, demote it first
+        // so it transitions cleanly to being linked via SubgraphInput.
+        const nodeId = String(e.detail.node.id)
+        if (
+          usePromotionStore().isPromoted(
+            this.rootGraph.id,
+            this.id,
+            nodeId,
+            widget.name
+          )
+        ) {
+          usePromotionStore().demote(
+            this.rootGraph.id,
+            this.id,
+            nodeId,
+            widget.name
+          )
+        }
+
         const widgetLocator = e.detail.input.widget
-        this._setWidget(subgraphInput, input, widget, widgetLocator)
+        this._setWidget(
+          subgraphInput,
+          input,
+          widget,
+          widgetLocator,
+          e.detail.node
+        )
       },
       { signal }
     )
@@ -218,7 +315,7 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
         const connectedWidgets = subgraphInput.getConnectedWidgets()
         if (connectedWidgets.length > 0) return
 
-        this.removeWidgetByName(input.name)
+        if (input._widget) this.ensureWidgetRemoved(input._widget)
 
         delete input.pos
         delete input.widget
@@ -276,8 +373,42 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
   }
 
   override _internalConfigureAfterSlots() {
-    // Reset widgets
-    this.widgets.length = 0
+    // Ensure proxyWidgets is initialized so it serializes
+    this.properties.proxyWidgets ??= []
+
+    // Clear view cache — forces re-creation on next getter access.
+    // Do NOT clear properties.proxyWidgets — it was already populated
+    // from serialized data by super.configure(info) before this runs.
+    this._promotedViewManager.clear()
+
+    // Hydrate the store from serialized properties.proxyWidgets
+    const raw = parseProxyWidgets(this.properties.proxyWidgets)
+    const store = usePromotionStore()
+    const entries = raw
+      .map(([nodeId, widgetName]) => {
+        if (nodeId === '-1') {
+          const resolved = this._resolveLegacyEntry(widgetName)
+          if (resolved)
+            return { interiorNodeId: resolved[0], widgetName: resolved[1] }
+          if (import.meta.env.DEV) {
+            console.warn(
+              `[SubgraphNode] Failed to resolve legacy -1 entry for widget "${widgetName}"`
+            )
+          }
+          return null
+        }
+        return { interiorNodeId: nodeId, widgetName }
+      })
+      .filter((e): e is NonNullable<typeof e> => e !== null)
+    store.setPromotions(this.rootGraph.id, this.id, entries)
+
+    // Write back resolved entries so legacy -1 format doesn't persist
+    if (raw.some(([id]) => id === '-1')) {
+      this.properties.proxyWidgets = entries.map((e) => [
+        e.interiorNodeId,
+        e.widgetName
+      ])
+    }
 
     // Check all inputs for connected widgets
     for (const input of this.inputs) {
@@ -323,7 +454,13 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
         const widget = inputNode.getWidgetFromSlot(targetInput)
         if (!widget) continue
 
-        this._setWidget(subgraphInput, input, widget, targetInput.widget)
+        this._setWidget(
+          subgraphInput,
+          input,
+          widget,
+          targetInput.widget,
+          inputNode
+        )
         break
       }
     }
@@ -332,69 +469,20 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
   private _setWidget(
     subgraphInput: Readonly<SubgraphInput>,
     input: INodeInputSlot,
-    widget: Readonly<IBaseWidget>,
-    inputWidget: IWidgetLocator | undefined
+    _widget: Readonly<IBaseWidget>,
+    inputWidget: IWidgetLocator | undefined,
+    interiorNode: LGraphNode
   ) {
-    // Use the first matching widget
-    const promotedWidget =
-      widget instanceof BaseWidget
-        ? widget.createCopyForNode(this)
-        : { ...widget, node: this }
-    if (widget instanceof AssetWidget)
-      promotedWidget.options.nodeType ??= widget.node.type
+    const nodeId = String(interiorNode.id)
+    const widgetName = _widget.name
 
-    Object.assign(promotedWidget, {
-      get name() {
-        return subgraphInput.name
-      },
-      set name(value) {
-        console.warn(
-          'Promoted widget: setting name is not allowed',
-          this,
-          value
-        )
-      },
-      get localized_name() {
-        return subgraphInput.localized_name
-      },
-      set localized_name(value) {
-        console.warn(
-          'Promoted widget: setting localized_name is not allowed',
-          this,
-          value
-        )
-      },
-      get label() {
-        return subgraphInput.label
-      },
-      set label(value) {
-        console.warn(
-          'Promoted widget: setting label is not allowed',
-          this,
-          value
-        )
-      },
-      get tooltip() {
-        // Preserve the original widget's tooltip for promoted widgets
-        return widget.tooltip
-      },
-      set tooltip(value) {
-        console.warn(
-          'Promoted widget: setting tooltip is not allowed',
-          this,
-          value
-        )
-      }
-    })
+    // Add to promotion store
+    usePromotionStore().promote(this.rootGraph.id, this.id, nodeId, widgetName)
 
-    const widgetCount = this.inputs.filter((i) => i.widget).length
-    this.widgets.splice(widgetCount, 0, promotedWidget)
-
-    // Dispatch widget-promoted event
-    this.subgraph.events.dispatch('widget-promoted', {
-      widget: promotedWidget,
-      subgraphNode: this
-    })
+    // Create/retrieve the view from cache
+    const view = this._promotedViewManager.getOrCreate(nodeId, widgetName, () =>
+      createPromotedWidgetView(this, nodeId, widgetName, subgraphInput.name)
+    )
 
     // NOTE: This code creates linked chains of prototypes for passing across
     // multiple levels of subgraphs. As part of this, it intentionally avoids
@@ -403,7 +491,13 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
     input.widget.name = subgraphInput.name
     if (inputWidget) Object.setPrototypeOf(input.widget, inputWidget)
 
-    input._widget = promotedWidget
+    input._widget = view
+
+    // Dispatch widget-promoted event
+    this.subgraph.events.dispatch('widget-promoted', {
+      widget: view,
+      subgraphNode: this
+    })
   }
 
   /**
@@ -535,40 +629,73 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
     return nodes
   }
 
+  /** Clear the DOM position override for a promoted view's interior widget. */
+  private _clearDomOverrideForView(view: PromotedWidgetView): void {
+    const node = this.subgraph.getNodeById(view.sourceNodeId)
+    if (!node) return
+    const interiorWidget = node.widgets?.find(
+      (w: IBaseWidget) => w.name === view.sourceWidgetName
+    )
+    if (
+      interiorWidget &&
+      'id' in interiorWidget &&
+      ('element' in interiorWidget || 'component' in interiorWidget)
+    ) {
+      useDomWidgetStore().clearPositionOverride(String(interiorWidget.id))
+    }
+  }
+
+  override removeWidget(widget: IBaseWidget): void {
+    this.ensureWidgetRemoved(widget)
+  }
+
   override removeWidgetByName(name: string): void {
     const widget = this.widgets.find((w) => w.name === name)
-    if (widget) {
-      this.subgraph.events.dispatch('widget-demoted', {
-        widget,
-        subgraphNode: this
-      })
-    }
-    super.removeWidgetByName(name)
+    if (widget) this.ensureWidgetRemoved(widget)
   }
 
   override ensureWidgetRemoved(widget: IBaseWidget): void {
-    if (this.widgets.includes(widget)) {
-      this.subgraph.events.dispatch('widget-demoted', {
-        widget,
-        subgraphNode: this
-      })
+    if (isPromotedWidgetView(widget)) {
+      this._clearDomOverrideForView(widget)
+      usePromotionStore().demote(
+        this.rootGraph.id,
+        this.id,
+        widget.sourceNodeId,
+        widget.sourceWidgetName
+      )
+      this._promotedViewManager.remove(
+        widget.sourceNodeId,
+        widget.sourceWidgetName
+      )
     }
-    super.ensureWidgetRemoved(widget)
+    for (const input of this.inputs) {
+      if (input._widget === widget) {
+        input._widget = undefined
+        input.widget = undefined
+      }
+    }
+    this.subgraph.events.dispatch('widget-demoted', {
+      widget,
+      subgraphNode: this
+    })
   }
 
   override onRemoved(): void {
-    // Clean up all subgraph event listeners
     this._eventAbortController.abort()
 
-    // Clean up all promoted widgets
     for (const widget of this.widgets) {
-      if ('isProxyWidget' in widget && widget.isProxyWidget) continue
+      if (isPromotedWidgetView(widget)) {
+        this._clearDomOverrideForView(widget)
+      }
       this.subgraph.events.dispatch('widget-demoted', {
         widget,
         subgraphNode: this
       })
     }
 
+    usePromotionStore().setPromotions(this.rootGraph.id, this.id, [])
+    this._promotedViewManager.clear()
+
     for (const input of this.inputs) {
       if (
         input._listenerController &&
@@ -610,36 +737,36 @@ export class SubgraphNode extends LGraphNode implements BaseLGraph {
    * This ensures nested subgraph widget values are preserved when saving.
    */
   override serialize(): ISerialisedNode {
-    // Sync widget values to subgraph definition before serialization
-    for (let i = 0; i < this.widgets.length; i++) {
-      const widget = this.widgets[i]
-      const input = this.inputs.find((inp) => inp.name === widget.name)
+    // Sync widget values to subgraph definition before serialization.
+    // Only sync for inputs that are linked to a promoted widget via _widget.
+    for (const input of this.inputs) {
+      if (!input._widget) continue
 
-      if (input) {
-        const subgraphInput = this.subgraph.inputNode.slots.find(
-          (slot) => slot.name === input.name
-        )
+      const subgraphInput = this.subgraph.inputNode.slots.find(
+        (slot) => slot.name === input.name
+      )
+      if (!subgraphInput) continue
 
-        if (subgraphInput) {
-          // Find all widgets connected to this subgraph input
-          const connectedWidgets = subgraphInput.getConnectedWidgets()
-
-          // Update the value of all connected widgets
-          for (const connectedWidget of connectedWidgets) {
-            connectedWidget.value = widget.value
-          }
-        }
+      const connectedWidgets = subgraphInput.getConnectedWidgets()
+      for (const connectedWidget of connectedWidgets) {
+        connectedWidget.value = input._widget.value
       }
     }
 
-    // Call parent serialize method
+    // Write promotion store state back to properties for serialization
+    const entries = usePromotionStore().getPromotions(
+      this.rootGraph.id,
+      this.id
+    )
+    this.properties.proxyWidgets = entries.map((e) => [
+      e.interiorNodeId,
+      e.widgetName
+    ])
+
     return super.serialize()
   }
   override clone() {
     const clone = super.clone()
-    // force reasign so domWidgets reset ownership
-
-    this.properties.proxyWidgets = this.properties.proxyWidgets
 
     //TODO: Consider deep cloning subgraphs here.
     //It's the safest place to prevent creation of linked subgraphs

src/lib/litegraph/src/subgraph/__fixtures__/subgraphFixtures.ts

@@ -6,12 +6,25 @@
  * in their test files. Each fixture provides a clean, pre-configured subgraph
  * setup for different testing scenarios.
  */
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+
 import type { Subgraph } from '@/lib/litegraph/src/litegraph'
 import { LGraph } from '@/lib/litegraph/src/litegraph'
 import type { SubgraphEventMap } from '@/lib/litegraph/src/infrastructure/SubgraphEventMap'
 import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode'
 
-import { test } from '../../__fixtures__/testExtensions'
+import { test as baseTest } from '../../__fixtures__/testExtensions'
+
+const test = baseTest.extend({
+  pinia: [
+    async ({}, use) => {
+      setActivePinia(createTestingPinia({ stubActions: false }))
+      await use(undefined)
+    },
+    { auto: true }
+  ]
+})
 import {
   createEventCapture,
   createNestedSubgraphs,

src/lib/litegraph/src/types/widgets.ts

@@ -411,14 +411,6 @@ export interface IBaseWidget<
 
   hidden?: boolean
   advanced?: boolean
-  /**
-   * This property is automatically computed on graph change
-   * and should not be changed.
-   * Promoted widgets have a colored border
-   * @see /core/graph/subgraph/proxyWidget.registerProxyWidgets
-   */
-  promoted?: boolean
-
   tooltip?: string
 
   // TODO: Confirm this format

src/lib/litegraph/src/utils/widget.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, test } from 'vitest'
 
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
 import type { IWidgetOptions } from '@/lib/litegraph/src/litegraph'
-import { getWidgetStep } from '@/lib/litegraph/src/litegraph'
+import {
+  getWidgetStep,
+  resolveNodeRootGraphId
+} from '@/lib/litegraph/src/litegraph'
 
 describe('getWidgetStep', () => {
   test('should return step2 when available', () => {
@@ -42,3 +46,27 @@ describe('getWidgetStep', () => {
     expect(getWidgetStep(optionsWithZeroStep)).toBe(1)
   })
 })
+
+type GraphIdNode = Pick<LGraphNode, 'graph'>
+
+describe('resolveNodeRootGraphId', () => {
+  test('returns node rootGraph id when node belongs to a graph', () => {
+    const node = {
+      graph: {
+        rootGraph: {
+          id: 'subgraph-root-id'
+        }
+      }
+    } as GraphIdNode
+
+    expect(resolveNodeRootGraphId(node)).toBe('subgraph-root-id')
+  })
+
+  test('returns fallback graph id when node graph is missing', () => {
+    const node = {
+      graph: null
+    } as GraphIdNode
+
+    expect(resolveNodeRootGraphId(node, 'app-root-id')).toBe('app-root-id')
+  })
+})

src/lib/litegraph/src/utils/widget.ts

@@ -1,4 +1,6 @@
+import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
 import type { IWidgetOptions } from '@/lib/litegraph/src/types/widgets'
+import type { UUID } from '@/lib/litegraph/src/utils/uuid'
 
 /**
  * The step value for numeric widgets.
@@ -23,3 +25,17 @@ export function evaluateInput(input: string): number | undefined {
   if (isNaN(newValue)) return undefined
   return newValue
 }
+
+export function resolveNodeRootGraphId(
+  node: Pick<LGraphNode, 'graph'>
+): UUID | undefined
+export function resolveNodeRootGraphId(
+  node: Pick<LGraphNode, 'graph'>,
+  fallbackGraphId: UUID
+): UUID
+export function resolveNodeRootGraphId(
+  node: Pick<LGraphNode, 'graph'>,
+  fallbackGraphId?: UUID
+): UUID | undefined {
+  return node.graph?.rootGraph.id ?? fallbackGraphId
+}

src/lib/litegraph/src/widgets/AssetWidget.ts

@@ -36,12 +36,13 @@ export class AssetWidget
 
   override drawWidget(
     ctx: CanvasRenderingContext2D,
-    { width, showText = true }: DrawWidgetOptions
+    options: DrawWidgetOptions
   ) {
+    const { width, showText = true } = options
     // Store original context attributes
     const { fillStyle, strokeStyle, textAlign } = ctx
 
-    this.drawWidgetShape(ctx, { width, showText })
+    this.drawWidgetShape(ctx, options)
 
     if (showText) {
       this.drawTruncatingText({ ctx, width, leftPadding: 0, rightPadding: 0 })

src/lib/litegraph/src/widgets/BaseWidget.test.ts

@@ -2,7 +2,7 @@ import { createTestingPinia } from '@pinia/testing'
 import { setActivePinia } from 'pinia'
 import { beforeEach, describe, expect, it } from 'vitest'
 
-import { LGraphNode } from '@/lib/litegraph/src/litegraph'
+import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph'
 import type { INumericWidget } from '@/lib/litegraph/src/types/widgets'
 import { NumberWidget } from '@/lib/litegraph/src/widgets/NumberWidget'
 import { useWidgetValueStore } from '@/stores/widgetValueStore'
@@ -25,14 +25,17 @@ function createTestWidget(
 }
 
 describe('BaseWidget store integration', () => {
+  let graph: LGraph
   let node: LGraphNode
   let store: ReturnType<typeof useWidgetValueStore>
 
   beforeEach(() => {
     setActivePinia(createTestingPinia({ stubActions: false }))
     store = useWidgetValueStore()
+    graph = new LGraph()
     node = new LGraphNode('TestNode')
     node.id = 1
+    graph.add(node)
   })
 
   describe('metadata properties before registration', () => {
@@ -41,15 +44,13 @@ describe('BaseWidget store integration', () => {
         label: 'My Label',
         hidden: true,
         disabled: true,
-        advanced: true,
-        promoted: true
+        advanced: true
       })
 
       expect(widget.label).toBe('My Label')
       expect(widget.hidden).toBe(true)
       expect(widget.disabled).toBe(true)
       expect(widget.advanced).toBe(true)
-      expect(widget.promoted).toBe(true)
     })
 
     it('allows setting properties without store', () => {
@@ -59,13 +60,11 @@ describe('BaseWidget store integration', () => {
       widget.hidden = true
       widget.disabled = true
       widget.advanced = true
-      widget.promoted = true
 
       expect(widget.label).toBe('New Label')
       expect(widget.hidden).toBe(true)
       expect(widget.disabled).toBe(true)
       expect(widget.advanced).toBe(true)
-      expect(widget.promoted).toBe(true)
     })
   })
 
@@ -76,8 +75,7 @@ describe('BaseWidget store integration', () => {
         label: 'Store Label',
         hidden: true,
         disabled: true,
-        advanced: true,
-        promoted: true
+        advanced: true
       })
       widget.setNodeId(1)
 
@@ -85,7 +83,6 @@ describe('BaseWidget store integration', () => {
       expect(widget.hidden).toBe(true)
       expect(widget.disabled).toBe(true)
       expect(widget.advanced).toBe(true)
-      expect(widget.promoted).toBe(true)
     })
 
     it('writes to store when registered', () => {
@@ -96,12 +93,10 @@ describe('BaseWidget store integration', () => {
       widget.hidden = true
       widget.disabled = true
       widget.advanced = true
-      widget.promoted = true
 
-      const state = store.getWidget(1, 'writeWidget')
+      const state = store.getWidget(graph.id, 1, 'writeWidget')
       expect(state?.label).toBe('Updated Label')
       expect(state?.disabled).toBe(true)
-      expect(state?.promoted).toBe(true)
 
       expect(widget.hidden).toBe(true)
       expect(widget.advanced).toBe(true)
@@ -112,9 +107,9 @@ describe('BaseWidget store integration', () => {
       widget.setNodeId(1)
 
       widget.value = 99
-      expect(store.getWidget(1, 'valueWidget')?.value).toBe(99)
+      expect(store.getWidget(graph.id, 1, 'valueWidget')?.value).toBe(99)
 
-      const state = store.getWidget(1, 'valueWidget')!
+      const state = store.getWidget(graph.id, 1, 'valueWidget')!
       state.value = 55
       expect(widget.value).toBe(55)
     })
@@ -128,12 +123,11 @@ describe('BaseWidget store integration', () => {
         label: 'Auto Label',
         hidden: true,
         disabled: true,
-        advanced: true,
-        promoted: true
+        advanced: true
       })
       widget.setNodeId(1)
 
-      const state = store.getWidget(1, 'autoRegWidget')
+      const state = store.getWidget(graph.id, 1, 'autoRegWidget')
       expect(state).toBeDefined()
       expect(state?.nodeId).toBe(1)
       expect(state?.name).toBe('autoRegWidget')
@@ -141,7 +135,6 @@ describe('BaseWidget store integration', () => {
       expect(state?.value).toBe(100)
       expect(state?.label).toBe('Auto Label')
       expect(state?.disabled).toBe(true)
-      expect(state?.promoted).toBe(true)
       expect(state?.options).toEqual({ min: 0, max: 100 })
 
       expect(widget.hidden).toBe(true)
@@ -152,10 +145,9 @@ describe('BaseWidget store integration', () => {
       const widget = createTestWidget(node, { name: 'defaultsWidget' })
       widget.setNodeId(1)
 
-      const state = store.getWidget(1, 'defaultsWidget')
+      const state = store.getWidget(graph.id, 1, 'defaultsWidget')
       expect(state).toBeDefined()
       expect(state?.disabled).toBe(false)
-      expect(state?.promoted).toBe(false)
       expect(state?.label).toBeUndefined()
 
       expect(widget.hidden).toBeUndefined()
@@ -166,7 +158,7 @@ describe('BaseWidget store integration', () => {
       const widget = createTestWidget(node, { name: 'valuesWidget', value: 77 })
       widget.setNodeId(1)
 
-      expect(store.getWidget(1, 'valuesWidget')?.value).toBe(77)
+      expect(store.getWidget(graph.id, 1, 'valuesWidget')?.value).toBe(77)
     })
   })
 
@@ -186,7 +178,7 @@ describe('BaseWidget store integration', () => {
 
       widget.disabled = undefined
 
-      const state = store.getWidget(1, 'testWidget')
+      const state = store.getWidget(graph.id, 1, 'testWidget')
       expect(state?.disabled).toBe(false)
     })
   })

src/lib/litegraph/src/widgets/BaseWidget.ts

@@ -16,6 +16,7 @@ import type {
   NodeBindable,
   TWidgetType
 } from '@/lib/litegraph/src/types/widgets'
+import { usePromotionStore } from '@/stores/promotionStore'
 import type { WidgetState } from '@/stores/widgetValueStore'
 import { useWidgetValueStore } from '@/stores/widgetValueStore'
 
@@ -24,6 +25,8 @@ export interface DrawWidgetOptions {
   width: number
   /** Synonym for "low quality". */
   showText?: boolean
+  /** When true, suppresses the promoted outline color (e.g. for projected copies on SubgraphNode). */
+  suppressPromotedOutline?: boolean
 }
 
 interface DrawTruncatingTextOptions extends DrawWidgetOptions {
@@ -100,12 +103,6 @@ export abstract class BaseWidget<TWidget extends IBaseWidget = IBaseWidget>
     this._state.disabled = value ?? false
   }
 
-  get promoted(): boolean | undefined {
-    return this._state.promoted
-  }
-  set promoted(value: boolean | undefined) {
-    this._state.promoted = value ?? false
-  }
   element?: HTMLElement
   callback?(
     value: TWidget['value'],
@@ -138,7 +135,10 @@ export abstract class BaseWidget<TWidget extends IBaseWidget = IBaseWidget>
    * Once set, value reads/writes will be delegated to the store.
    */
   setNodeId(nodeId: NodeId): void {
-    this._state = useWidgetValueStore().registerWidget({
+    const graphId = this.node.graph?.rootGraph.id
+    if (!graphId) return
+
+    this._state = useWidgetValueStore().registerWidget(graphId, {
       ...this._state,
       nodeId
     })
@@ -181,7 +181,6 @@ export abstract class BaseWidget<TWidget extends IBaseWidget = IBaseWidget>
       labelBaseline,
       label,
       disabled,
-      promoted,
       value,
       linkedWidgets,
       ...safeValues
@@ -195,19 +194,32 @@ export abstract class BaseWidget<TWidget extends IBaseWidget = IBaseWidget>
       value,
       label,
       disabled: disabled ?? false,
-      promoted: promoted ?? false,
       serialize: this.serialize,
       options: this.options
     }
   }
 
-  get outline_color() {
-    if (this.promoted) return LiteGraph.WIDGET_PROMOTED_OUTLINE_COLOR
+  getOutlineColor(suppressPromotedOutline = false) {
+    const graphId = this.node.graph?.rootGraph.id
+    if (
+      graphId &&
+      !suppressPromotedOutline &&
+      usePromotionStore().isPromotedByAny(
+        graphId,
+        String(this.node.id),
+        this.name
+      )
+    )
+      return LiteGraph.WIDGET_PROMOTED_OUTLINE_COLOR
     return this.advanced
       ? LiteGraph.WIDGET_ADVANCED_OUTLINE_COLOR
       : LiteGraph.WIDGET_OUTLINE_COLOR
   }
 
+  get outline_color() {
+    return this.getOutlineColor()
+  }
+
   get background_color() {
     return LiteGraph.WIDGET_BGCOLOR
   }
@@ -262,13 +274,13 @@ export abstract class BaseWidget<TWidget extends IBaseWidget = IBaseWidget>
    */
   protected drawWidgetShape(
     ctx: CanvasRenderingContext2D,
-    { width, showText }: DrawWidgetOptions
+    { width, showText, suppressPromotedOutline }: DrawWidgetOptions
   ): void {
     const { height, y } = this
     const { margin } = BaseWidget
 
     ctx.textAlign = 'left'
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(suppressPromotedOutline)
     ctx.fillStyle = this.background_color
     ctx.beginPath()
 
@@ -289,7 +301,7 @@ export abstract class BaseWidget<TWidget extends IBaseWidget = IBaseWidget>
    */
   protected drawVueOnlyWarning(
     ctx: CanvasRenderingContext2D,
-    { width }: DrawWidgetOptions,
+    { width, suppressPromotedOutline }: DrawWidgetOptions,
     label: string
   ): void {
     const { y, height } = this
@@ -299,7 +311,7 @@ export abstract class BaseWidget<TWidget extends IBaseWidget = IBaseWidget>
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/BooleanWidget.ts

@@ -11,12 +11,13 @@ export class BooleanWidget
 
   override drawWidget(
     ctx: CanvasRenderingContext2D,
-    { width, showText = true }: DrawWidgetOptions
+    options: DrawWidgetOptions
   ) {
+    const { width, showText = true } = options
     const { height, y } = this
     const { margin } = BaseWidget
 
-    this.drawWidgetShape(ctx, { width, showText })
+    this.drawWidgetShape(ctx, options)
 
     ctx.fillStyle = this.value ? '#89A' : '#333'
     ctx.beginPath()

src/lib/litegraph/src/widgets/ButtonWidget.ts

@@ -23,7 +23,7 @@ export class ButtonWidget
    */
   override drawWidget(
     ctx: CanvasRenderingContext2D,
-    { width, showText = true }: DrawWidgetOptions
+    { width, showText = true, suppressPromotedOutline }: DrawWidgetOptions
   ) {
     // Store original context attributes
     const { fillStyle, strokeStyle, textAlign } = ctx
@@ -41,7 +41,7 @@ export class ButtonWidget
 
     // Draw button outline if not disabled
     if (showText && !this.computedDisabled) {
-      ctx.strokeStyle = this.outline_color
+      ctx.strokeStyle = this.getOutlineColor(suppressPromotedOutline)
       ctx.strokeRect(margin, y, width - margin * 2, height)
     }
 

src/lib/litegraph/src/widgets/ChartWidget.ts

@@ -23,7 +23,7 @@ export class ChartWidget
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(options.suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/DisconnectedWidget.ts

@@ -1,39 +0,0 @@
-import { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
-import type { IButtonWidget } from '@/lib/litegraph/src/types/widgets'
-
-import { BaseWidget } from './BaseWidget'
-import type { DrawWidgetOptions } from './BaseWidget'
-
-class DisconnectedWidget extends BaseWidget<IButtonWidget> {
-  constructor(widget: IButtonWidget) {
-    super(widget, new LGraphNode('DisconnectedPlaceholder'))
-    this.disabled = true
-  }
-
-  override drawWidget(
-    ctx: CanvasRenderingContext2D,
-    { width, showText = true }: DrawWidgetOptions
-  ) {
-    ctx.save()
-    this.drawWidgetShape(ctx, { width, showText })
-    if (showText) {
-      this.drawTruncatingText({ ctx, width, leftPadding: 0, rightPadding: 0 })
-    }
-    ctx.restore()
-  }
-
-  override onClick() {}
-
-  override get _displayValue() {
-    return 'Disconnected'
-  }
-}
-const conf: IButtonWidget = {
-  type: 'button',
-  value: undefined,
-  name: 'Disconnected',
-  options: {},
-  y: 0,
-  clicked: false
-}
-export const disconnectedWidget = new DisconnectedWidget(conf)

src/lib/litegraph/src/widgets/FileUploadWidget.ts

@@ -23,7 +23,7 @@ export class FileUploadWidget
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(options.suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/GalleriaWidget.ts

@@ -23,7 +23,7 @@ export class GalleriaWidget
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(options.suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/ImageCompareWidget.ts

@@ -23,7 +23,7 @@ export class ImageCompareWidget
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(options.suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/KnobWidget.ts

@@ -33,7 +33,7 @@ export class KnobWidget extends BaseWidget<IKnobWidget> implements IKnobWidget {
 
   drawWidget(
     ctx: CanvasRenderingContext2D,
-    { width, showText = true }: DrawWidgetOptions
+    { width, showText = true, suppressPromotedOutline }: DrawWidgetOptions
   ): void {
     // Store original context attributes
     const { fillStyle, strokeStyle, textAlign } = ctx
@@ -145,10 +145,10 @@ export class KnobWidget extends BaseWidget<IKnobWidget> implements IKnobWidget {
 
     // Draw outline if not disabled
     if (showText && !this.computedDisabled) {
-      ctx.strokeStyle = this.outline_color
+      ctx.strokeStyle = this.getOutlineColor(suppressPromotedOutline)
       // Draw value
       ctx.beginPath()
-      ctx.strokeStyle = this.outline_color
+      ctx.strokeStyle = this.getOutlineColor(suppressPromotedOutline)
       ctx.arc(
         arc_center.x,
         arc_center.y,

src/lib/litegraph/src/widgets/MarkdownWidget.ts

@@ -23,7 +23,7 @@ export class MarkdownWidget
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(options.suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/MultiSelectWidget.ts

@@ -23,7 +23,7 @@ export class MultiSelectWidget
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(options.suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/SelectButtonWidget.ts

@@ -23,7 +23,7 @@ export class SelectButtonWidget
     ctx.fillStyle = this.background_color
     ctx.fillRect(15, y, width - 30, height)
 
-    ctx.strokeStyle = this.outline_color
+    ctx.strokeStyle = this.getOutlineColor(options.suppressPromotedOutline)
     ctx.strokeRect(15, y, width - 30, height)
 
     ctx.fillStyle = this.text_color

src/lib/litegraph/src/widgets/SliderWidget.ts

@@ -20,7 +20,7 @@ export class SliderWidget
    */
   override drawWidget(
     ctx: CanvasRenderingContext2D,
-    { width, showText = true }: DrawWidgetOptions
+    { width, showText = true, suppressPromotedOutline }: DrawWidgetOptions
   ) {
     // Store original context attributes
     const { fillStyle, strokeStyle, textAlign } = ctx
@@ -43,7 +43,7 @@ export class SliderWidget
 
     // Draw outline if not disabled
     if (showText && !this.computedDisabled) {
-      ctx.strokeStyle = this.outline_color
+      ctx.strokeStyle = this.getOutlineColor(suppressPromotedOutline)
       ctx.strokeRect(margin, y, width - margin * 2, height)
     }
 

src/lib/litegraph/src/widgets/TextWidget.ts

@@ -21,12 +21,13 @@ export class TextWidget
    */
   override drawWidget(
     ctx: CanvasRenderingContext2D,
-    { width, showText = true }: DrawWidgetOptions
+    options: DrawWidgetOptions
   ) {
+    const { width, showText = true } = options
     // Store original context attributes
     const { fillStyle, strokeStyle, textAlign } = ctx
 
-    this.drawWidgetShape(ctx, { width, showText })
+    this.drawWidgetShape(ctx, options)
 
     if (showText) {
       this.drawTruncatingText({ ctx, width, leftPadding: 0, rightPadding: 0 })

src/locales/en/main.json

@@ -1075,7 +1075,11 @@
     "cannotDeleteGlobal": "Cannot delete installed blueprints",
     "enterDescription": "Enter a description",
     "searchAliases": "Search Aliases",
-    "enterSearchAliases": "Enter search aliases (comma separated)"
+    "enterSearchAliases": "Enter search aliases (comma separated)",
+    "disconnected": "Disconnected",
+    "linked": "(Linked)",
+    "promoteWidget": "Promote Widget: {name}",
+    "unpromoteWidget": "Un-Promote Widget: {name}"
   },
   "electronFileDownload": {
     "inProgress": "In Progress",

src/renderer/core/canvas/canvasStore.ts

@@ -10,8 +10,10 @@ import type {
   LGraph,
   LGraphCanvas,
   LGraphGroup,
-  LGraphNode
+  LGraphNode,
+  SubgraphNode
 } from '@/lib/litegraph/src/litegraph'
+import { promoteRecommendedWidgets } from '@/core/graph/subgraph/promotionUtils'
 import { app } from '@/scripts/app'
 import { isLGraphGroup, isLGraphNode, isReroute } from '@/utils/litegraphUtil'
 
@@ -135,6 +137,13 @@ export const useCanvasStore = defineStore('canvas', () => {
       useEventListener(newCanvas.canvas, 'subgraph-opened', () => {
         isInSubgraph.value = true
       })
+
+      useEventListener(
+        newCanvas.canvas,
+        'subgraph-converted',
+        (e: CustomEvent<{ subgraphNode: SubgraphNode }>) =>
+          promoteRecommendedWidgets(e.detail.subgraphNode)
+      )
     },
     { immediate: true }
   )

src/renderer/extensions/vueNodes/VideoPreview.vue

@@ -7,7 +7,7 @@
     <!-- Video Wrapper -->
     <div
       ref="videoWrapperEl"
-      class="relative h-full w-full grow overflow-hidden rounded-[5px] bg-node-component-surface"
+      class="relative flex flex-1 overflow-hidden rounded-[5px] bg-node-component-surface"
       tabindex="0"
       role="region"
       :aria-label="$t('g.videoPreview')"
@@ -21,7 +21,7 @@
       <div
         v-if="videoError"
         role="alert"
-        class="flex size-full flex-col items-center justify-center bg-muted-background text-center text-base-foreground py-8"
+        class="flex flex-auto flex-col items-center justify-center bg-muted-background text-center text-base-foreground py-8"
       >
         <i
           class="mb-2 icon-[lucide--video-off] h-12 w-12 text-base-foreground"