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>

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
-    }
-  }
-}