fix: clear widget-order and preview-exposure entries on node teardown (#14276)

**STACKED — merging lands on `matt/be-5050-node-shell-state` (owned by
@mattmillerai), NOT `main`.** That branch is itself based on
`feature/ecs-migration`, where `src/core/graph/nodeShell/` lives. Do not
merge before its parent lands; GitHub retargets this PR as the stack
unwinds.

## ELI-5

When a node joins a graph we write it into three places: its shell
state, its widget bindings, and its widget ordering (plus preview
exposures accumulate against the same bucket). When a node left, we only
erased the first one. The leftovers piled up in a bucket shared by the
whole workflow and stayed there until the entire graph was thrown away.
This adds the missing "undo" for the other two and points every teardown
path at it.

## Summary

`attachNodeToStores` registers three things; every teardown path only
undid one, so widget-order and preview-exposure entries orphaned in the
shared root-graph bucket. This adds `detachNodeFromStores` as its exact
inverse and routes the teardown paths through it.

## Changes

- **What**: New `detachNodeFromStores(graph, node, mode)` in
`nodeShellLifecycle.ts` — unregisters the shell state, removes each
`getWidgetIds(node.widgets)` entry from the widget order, and clears the
node's preview exposures (`String(node.id)` host locator, the same key
`promotionUtils`/`SubgraphNode` write under). `unregisterAllNodeStates`
moves out of `nodeShellState.ts` and becomes `detachAllNodesFromStores`
in the same module — it needs the root graph to reach those buckets, so
it now takes the graph (which carries `rootGraph`) rather than just
`_nodes`/`_subgraphs`. Call sites: `LGraph.remove` (both the per-node
teardown and the released-subgraph-definition walk) and
`releaseGraphStores`'s non-root branch.
- **Breaking**: none — `unregisterAllNodeStates` had exactly one
external caller (`LGraph.ts`), and no behavior the extension surface can
observe changes.

## Reachability the leak had (all three are load-bearing, not
theoretical)

- Subgraphs always take the non-root `else` branch of
`releaseGraphStores`, and `LGraph.configure` calls `clear()` first — so
re-configuring a subgraph orphaned its nodes' entries.
- `clear()` sets `id = zeroUuid` on exit, so a root graph whose
serialized data carries no id keeps taking the `else` branch for the
rest of the session.
- Plain `LGraph.remove(node)` leaked per-node on every branch, since it
never removed the widget order it added.

## Review Focus

**The judgment call the ticket left open — `deleteWidget` vs
`removeNodeWidgetOrder` — is decided per call site, and both are covered
by tests.** `LGraph.remove(node)` drops only the ordering and **keeps**
the stored widget values: a single node removal feeds undo/redo and a
node moved between graphs (`remove` then `add`) must not lose its
values. Graph and subgraph-definition teardown
(`detachAllNodesFromStores`) **discards** them, which is what the root
branch already does one line up — `clearGraph` on `widgetValueStore`
wipes that graph's widget states wholesale, so the non-root path was the
inconsistent one.

**Riskiest line: `deleteWidget` in the discard path**, because it is the
one edit that removes data rather than an index. It is safe because
`deleteWidget` only drops the store's map entry — the widget instance's
`_state` object is untouched, so a widget that survives the clear still
reads its own value, and re-registration (`setNodeId` →
`registerWidget`) writes it back from the widget/serialized data rather
than from store leftovers. Without this, a re-configure would silently
reuse the *stale* store value: `registerWidget` returns the existing
state when the type matches and ignores the incoming `init.value`.

**Deliberately not routed through the new helper:**
`useNodeReplacement.replaceWithMapping`. It calls
`unregisterNodeState`/`registerNodeState` for an in-place swap where the
new node inherits the same id and re-registers the same widgets —
clearing exposures there would drop a replaced host node's promoted
previews. It is a replacement, not a teardown.

**Deviation from the ticket's sketch:** preview exposures are cleared
with `setExposures(rootGraphId, locator, [])` (guarded by a
`getExposures(...).length` read) rather than a `removeExposure` per
name. Same result, one write instead of N, and the guard keeps the
reactive `exposures` ref from being touched on every ordinary node
deletion.

## Verification

New `src/core/graph/nodeShell/nodeShellLifecycle.test.ts` covers all
three: widget order dropped and values kept on `subgraph.remove(node)`;
exposures dropped when a host `SubgraphNode` is removed; order, values
and exposures all released when a zero-uuid root graph is cleared. **All
three fail on the base branch** (verified by stashing the source change
and re-running — `expected [ Array(1) ] to deeply equal []`).

`vitest run src/lib/litegraph src/core/graph
src/platform/nodeReplacement src/stores/widgetValueStore.test.ts
src/composables/node` — 1591 passed. `pnpm typecheck`, `pnpm knip`,
eslint and oxfmt on the changed files: clean.

Amp-Thread-ID: https://ampcode.com/threads/T-01a027af-1c32-7532-84f9-b94aa90620fa

Author: mattmillerai

src/core/graph/nodeShell/nodeShellLifecycle.test.ts

@@ -0,0 +1,102 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph'
+import type { Subgraph } from '@/lib/litegraph/src/litegraph'
+import {
+  createTestRootGraph,
+  createTestSubgraph,
+  createTestSubgraphNode
+} from '@/lib/litegraph/src/subgraph/__fixtures__/subgraphHelpers'
+import { getWidgetIds } from '@/lib/litegraph/src/utils/widget'
+import { usePreviewExposureStore } from '@/stores/previewExposureStore'
+import { useWidgetValueStore } from '@/stores/widgetValueStore'
+
+describe('node shell teardown', () => {
+  beforeEach(() => {
+    setActivePinia(createTestingPinia({ stubActions: false }))
+  })
+
+  function addWidgetedNode(graph: LGraph | Subgraph): LGraphNode {
+    const node = new LGraphNode('Node')
+    node.addWidget('text', 'prompt', 'a value', () => {})
+    graph.add(node)
+    return node
+  }
+
+  function widgetIdsOf(node: LGraphNode) {
+    return getWidgetIds(node.widgets ?? [])
+  }
+
+  it('drops the widget order a removed node registered, keeping its values', () => {
+    const subgraph = createTestSubgraph()
+    const rootGraphId = subgraph.rootGraph.id
+    const node = addWidgetedNode(subgraph)
+    const [widgetId] = widgetIdsOf(node)
+    const widgetValueStore = useWidgetValueStore()
+
+    expect(widgetValueStore.getNodeWidgetIds(rootGraphId, node.id)).toEqual([
+      widgetId
+    ])
+
+    subgraph.remove(node)
+
+    expect(widgetValueStore.getNodeWidgetIds(rootGraphId, node.id)).toEqual([])
+    expect(widgetValueStore.getWidget(widgetId)?.value).toBe('a value')
+  })
+
+  it('drops the preview exposures a removed host node owned', () => {
+    const rootGraph = createTestRootGraph()
+    const subgraph = createTestSubgraph({ rootGraph })
+    const hostNode = createTestSubgraphNode(subgraph)
+    rootGraph.add(hostNode)
+    const hostLocator = String(hostNode.id)
+    const previewExposureStore = usePreviewExposureStore()
+    previewExposureStore.addExposure(rootGraph.id, hostLocator, {
+      sourceNodeId: 1,
+      sourcePreviewName: 'images'
+    })
+
+    rootGraph.remove(hostNode)
+
+    expect(
+      previewExposureStore.getExposures(rootGraph.id, hostLocator)
+    ).toEqual([])
+  })
+
+  it('releases widget and exposure entries when a root graph is cleared', () => {
+    const graph = new LGraph()
+    const graphId = graph.id
+
+    const node = addWidgetedNode(graph)
+    const [widgetId] = widgetIdsOf(node)
+    const hostLocator = String(node.id)
+    const previewExposureStore = usePreviewExposureStore()
+    previewExposureStore.addExposure(graphId, hostLocator, {
+      sourceNodeId: 1,
+      sourcePreviewName: 'images'
+    })
+    const widgetValueStore = useWidgetValueStore()
+
+    graph.clear()
+
+    expect(widgetValueStore.getNodeWidgetIds(graphId, node.id)).toEqual([])
+    expect(widgetValueStore.getWidget(widgetId)).toBeUndefined()
+    expect(previewExposureStore.getExposures(graphId, hostLocator)).toEqual([])
+  })
+
+  it('releases entries of a widget the node dropped without unregistering', () => {
+    const graph = new LGraph()
+    const graphId = graph.id
+    const node = addWidgetedNode(graph)
+    const [widgetId] = widgetIdsOf(node)
+    const widgetValueStore = useWidgetValueStore()
+    node.widgets = []
+
+    graph.clear()
+
+    expect(widgetValueStore.getNodeWidgetIds(graphId, node.id)).toEqual([])
+    expect(widgetValueStore.getWidget(widgetId)).toBeUndefined()
+  })
+})

src/core/graph/nodeShell/nodeShellLifecycle.ts

@@ -1,13 +1,15 @@
 import { isNodeBindable } from '@/lib/litegraph/src/utils/type'
 import { getWidgetIds } from '@/lib/litegraph/src/utils/widget'
+import { usePreviewExposureStore } from '@/stores/previewExposureStore'
 import { useWidgetValueStore } from '@/stores/widgetValueStore'
 
-import { registerNodeState } from './nodeShellState'
+import { registerNodeState, unregisterNodeState } from './nodeShellState'
 
 import type { LGraph } from '@/lib/litegraph/src/LGraph'
 import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
 import type { NodeId } from '@/types/nodeId'
 import type { Subgraph } from '@/lib/litegraph/src/subgraph/Subgraph'
+import type { UUID } from '@/utils/uuid'
 
 /**
  * Registers a node's shell state and its widget bindings with the app
@@ -31,3 +33,57 @@ export function attachNodeToStores(
     getWidgetIds(node.widgets)
   )
 }
+
+/**
+ * Whether a detached node's widget values leave the store with it. A node that
+ * may come back — undo of a deletion — keeps its values and drops only its
+ * ordering; a node whose whole graph is going away takes its values along.
+ */
+type WidgetDetachMode = 'keep-values' | 'discard-values'
+
+function releaseNodePreviewExposures(
+  rootGraphId: UUID,
+  node: LGraphNode
+): void {
+  const previewExposureStore = usePreviewExposureStore()
+  const hostNodeLocator = String(node.id)
+  if (!previewExposureStore.getExposures(rootGraphId, hostNodeLocator).length) {
+    return
+  }
+  previewExposureStore.setExposures(rootGraphId, hostNodeLocator, [])
+}
+
+/**
+ * The inverse of {@link attachNodeToStores}: drops the node's shell state, the
+ * widget order it registered, and the preview exposures it hosts.
+ */
+export function detachNodeFromStores(
+  graph: Pick<LGraph, 'rootGraph'>,
+  node: LGraphNode,
+  mode: WidgetDetachMode = 'keep-values'
+): void {
+  const rootGraphId = graph.rootGraph.id
+  unregisterNodeState(node)
+  useWidgetValueStore().releaseNodeWidgets(rootGraphId, node.id, {
+    discardValues: mode === 'discard-values'
+  })
+  releaseNodePreviewExposures(rootGraphId, node)
+}
+
+/**
+ * Detaches every node a graph owns, including those inside the subgraph
+ * definitions it holds. Used when a graph's nodes leave the stores without a
+ * whole-bucket wipe: subgraph-definition removal, and clearing a graph that
+ * shares its bucket with other graphs. The graph is going away, so its nodes'
+ * widget values go with it — the same reach as the wipe a root graph performs.
+ */
+export function detachAllNodesFromStores(
+  graph: Pick<LGraph, '_nodes' | '_subgraphs' | 'rootGraph'>
+): void {
+  for (const node of graph._nodes) {
+    detachNodeFromStores(graph, node, 'discard-values')
+  }
+  for (const subgraph of graph._subgraphs.values()) {
+    detachAllNodesFromStores(subgraph)
+  }
+}

src/core/graph/nodeShell/nodeShellState.ts

@@ -110,22 +110,6 @@ export function unregisterNodeState(node: LGraphNode): void {
   )
 }
 
-/**
- * Unregisters every node a graph owns, including those inside the subgraph
- * definitions it holds. Used when a graph's nodes leave the store without a
- * whole-bucket wipe: subgraph-definition removal, and clearing a graph that
- * shares its bucket with other graphs.
- * @param graph The graph whose nodes should be unregistered
- */
-export function unregisterAllNodeStates(
-  graph: Pick<LGraph, '_nodes' | '_subgraphs'>
-): void {
-  for (const node of graph._nodes) unregisterNodeState(node)
-  for (const subgraph of graph._subgraphs.values()) {
-    unregisterAllNodeStates(subgraph)
-  }
-}
-
 function canTransferNodeState(
   node: LGraphNode,
   replacement: LGraphNode

src/lib/litegraph/src/LGraph.ts

@@ -5,11 +5,11 @@ import {
   SUBGRAPH_INPUT_ID,
   SUBGRAPH_OUTPUT_ID
 } from '@/lib/litegraph/src/constants'
-import { attachNodeToStores } from '@/core/graph/nodeShell/nodeShellLifecycle'
 import {
-  unregisterAllNodeStates,
-  unregisterNodeState
-} from '@/core/graph/nodeShell/nodeShellState'
+  attachNodeToStores,
+  detachAllNodesFromStores,
+  detachNodeFromStores
+} from '@/core/graph/nodeShell/nodeShellLifecycle'
 import type { UUID } from '@/utils/uuid'
 import { createUuidv4, zeroUuid } from '@/utils/uuid'
 import {
@@ -24,7 +24,9 @@ import {
 import { layoutStore } from '@/renderer/core/layout/store/layoutStore'
 import { useLinkStore } from '@/stores/linkStore'
 import { useNodeDataStore } from '@/stores/nodeDataStore'
+import { usePreviewExposureStore } from '@/stores/previewExposureStore'
 import { useRerouteStore } from '@/stores/rerouteStore'
+import { useWidgetValueStore } from '@/stores/widgetValueStore'
 import { toLinkId } from '@/types/linkId'
 import { isFloatingTopology } from '@/types/linkTopology'
 import { toRerouteId } from '@/types/rerouteId'
@@ -48,8 +50,6 @@ import {
   outputLinks
 } from './node/slotLinks'
 import { normalizeWidgetsView } from './node/widgetsView'
-import { usePreviewExposureStore } from '@/stores/previewExposureStore'
-import { useWidgetValueStore } from '@/stores/widgetValueStore'
 import { UNASSIGNED_NODE_ID, parseNodeId, toNodeId } from '@/types/nodeId'
 import type { NodeId, SerializedNodeId } from '@/types/nodeId'
 import { forEachNode, visitGraphNodes } from '@/utils/graphTraversalUtil'
@@ -251,7 +251,7 @@ function teardownOwnedGraphs(owner: LGraph): void {
       for (const node of graph._nodes) nodes.add(node)
     }
     for (const node of nodes) {
-      unregisterNodeState(node)
+      detachNodeFromStores(owner, node, 'discard-values')
       node.graph = null
     }
     detachGraphLayouts([owner], { removeLayouts: !owner.isRootGraph })
@@ -1284,7 +1284,7 @@ export class LGraph
       for (const subgraph of releasedSubgraphs) {
         unregisterAllLinkTopologies(subgraph)
         unregisterAllRerouteChains(subgraph)
-        unregisterAllNodeStates(subgraph)
+        detachAllNodesFromStores(subgraph)
         this.rootGraph.subgraphs.delete(subgraph.id)
       }
       detachGraphLayouts(releasedSubgraphs)
@@ -1293,7 +1293,7 @@ export class LGraph
     // callback
     node.onRemoved?.()
 
-    unregisterNodeState(node)
+    detachNodeFromStores(this, node)
     detachNodeLayout(node)
 
     node.graph = null

src/stores/widgetValueStore.ts

@@ -240,6 +240,32 @@ export const useWidgetValueStore = defineStore('widgetValue', () => {
     }
   }
 
+  /**
+   * Releases the widget ids tracked for a node, from the store's own record
+   * rather than the node's live widget list — the two diverge once a node drops
+   * widgets without unregistering them. `discardValues` also drops the widget
+   * states; retaining them lets a node that comes back keep what the user set.
+   */
+  function releaseNodeWidgets(
+    graphId: UUID,
+    localNodeId: NodeId,
+    { discardValues }: { discardValues: boolean }
+  ): void {
+    const graphOrders = graphNodeWidgetOrders.value.get(graphId)
+    if (!graphOrders) return
+
+    const order = graphOrders.get(localNodeId)
+    if (!order) return
+
+    if (discardValues) {
+      for (const widgetId of order) {
+        graphWidgetStates.value.get(graphId)?.delete(widgetId)
+        graphWidgetRenderStates.value.get(graphId)?.delete(widgetId)
+      }
+    }
+    graphOrders.delete(localNodeId)
+  }
+
   function clearGraph(graphId: UUID): void {
     graphWidgetStates.value.delete(graphId)
     graphWidgetRenderStates.value.delete(graphId)
@@ -258,6 +284,7 @@ export const useWidgetValueStore = defineStore('widgetValue', () => {
     setNodeWidgetOrder,
     replaceNodeWidgetOrder,
     removeNodeWidgetOrder,
+    releaseNodeWidgets,
     clearGraph
   }
 })