refactor: bake LayoutSource at instantiation, retire ambient source

Retargeted squash of the layout-source stack onto the pruned attachment
rework: useLayoutMutations(source) bakes the source when instantiated,
operations carry their source explicitly, the store stamps the session
actor on operations that do not carry one, and the ambient
setSource/setActor/getCurrentSource/getCurrentActor knobs are removed.
DOM height convention is passed explicitly through batchUpdateNodeBounds
options instead of sniffed from an ambient DOM source.

Author: DrJKL

docs/adr/0003-crdt-based-layout-system.md

@@ -156,9 +156,9 @@ serializable command shape every mutation goes through.
 
 Entity geometry registers and unregisters with the entity that owns it
 (`LGraph.add` / `LGraph.remove`) rather than being seeded per graph on renderer
-entry. All three entity types key by `makeScopedLayoutKey(rootGraphId, id)`, so
-a root graph's teardown is one `clearGraph`; graphs sharing that bucket drop
-their entries individually through `unregisterAllGraphLayout`.
+entry. All three entity types key by `makeScopedLayoutKey(rootGraphId, id)`, and
+every graph — root or nested — drops its entries individually through
+`unregisterAllGraphLayout`.
 
 ## Notes
 

docs/architecture/node-data-store.md

@@ -169,13 +169,11 @@ it as `configure()` applies the real values. This follows the precedent
 already set by `LGraph.createReroute`.
 
 Geometry now leaves the store the same way: `LGraph.remove` unregisters one
-entry, and bulk teardown goes through one of two paths. A root graph's `clear`
-calls `layoutStore.clearGraph(graphId)`, beside the five peer stores cleared
-there, because layout is keyed by `rootGraphId` and so has a bucket to wipe.
-Graphs that share the root's bucket — subgraphs, unconfigured graphs, and the
-orphaned subgraph release — call `unregisterAllGraphLayout` to drop entries
-individually, mirroring `unregisterAllNodeStates` exactly. Both live in a
-dedicated module so no teardown path re-derives the store writes by hand.
+entry, and every bulk teardown — a root graph's `clear`, subgraphs,
+unconfigured graphs, and the orphaned subgraph release — calls
+`unregisterAllGraphLayout` to drop entries individually, mirroring
+`unregisterAllNodeStates` exactly. It lives in a dedicated module so no
+teardown path re-derives the store writes by hand.
 
 `useVueNodeLifecycle` is gone; `GraphCanvas` owns only the Layout↔LiteGraph
 sync lifecycle, and while the Vue renderer is on it drops view-scoped slot and

src/composables/graph/useArrangeNodes.ts

@@ -165,7 +165,7 @@ interface ArrangeOptions {
 
 export function useArrangeNodes() {
   const { selectedNodes, hasMultipleSelection } = useSelectionState()
-  const mutations = useLayoutMutations()
+  const mutations = useLayoutMutations(LayoutSource.Canvas)
   const workflowStore = useWorkflowStore()
   const canvasStore = useCanvasStore()
 
@@ -180,7 +180,6 @@ export function useArrangeNodes() {
     const updates = computeArrangement(selectedNodes.value, layout, gap)
     if (updates.length === 0) return
 
-    mutations.setSource(LayoutSource.Canvas)
     mutations.batchMoveNodes(rootGraphId, updates)
     app.canvas?.setDirty(true, true)
     if (captureUndo) {

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

@@ -9,6 +9,7 @@ import type { LGraphCanvas } from '@/lib/litegraph/src/LGraphCanvas'
 import type { Subgraph } from '@/lib/litegraph/src/litegraph'
 import { useLayoutMutations } from '@/renderer/core/layout/operations/layoutMutations'
 import { layoutStore } from '@/renderer/core/layout/store/layoutStore'
+import { LayoutSource } from '@/renderer/core/layout/types'
 import {
   LGraph,
   LGraphGroup,
@@ -1730,12 +1731,16 @@ describe('node layout registration', () => {
     node.id = toNodeId(42)
     node.pos = [10, 20]
     node.size = [100, 80]
-    useLayoutMutations().createNode(graph.rootGraph.id, node.id, {
-      position: { x: 300, y: 400 },
-      size: { width: 220, height: 160 },
-      zIndex: 1,
-      visible: true
-    })
+    useLayoutMutations(LayoutSource.Canvas).createNode(
+      graph.rootGraph.id,
+      node.id,
+      {
+        position: { x: 300, y: 400 },
+        size: { width: 220, height: 160 },
+        zIndex: 1,
+        visible: true
+      }
+    )
 
     graph.add(node)
 

src/lib/litegraph/src/LGraphCanvas.ts

@@ -4348,11 +4348,12 @@ export class LGraphCanvas implements CustomEventDispatcher<LGraphCanvasEventMap>
       }))
 
     const rootGraphId = graph.rootGraph.id
-    if (newPositions.length) layoutStore.setSource(LayoutSource.Canvas)
-    layoutStore.batchUpdateNodeBounds(rootGraphId, newPositions)
+    layoutStore.batchUpdateNodeBounds(rootGraphId, newPositions, {
+      source: LayoutSource.Canvas
+    })
 
     // Bring cloned/pasted nodes to front so they render above the originals
-    const { setNodeZIndex } = useLayoutMutations()
+    const { setNodeZIndex } = useLayoutMutations(LayoutSource.Canvas)
     for (const { nodeId } of newPositions) {
       setNodeZIndex(rootGraphId, nodeId, layoutStore.allocateZIndex())
     }
@@ -4987,7 +4988,7 @@ export class LGraphCanvas implements CustomEventDispatcher<LGraphCanvasEventMap>
     const i = graph._nodes.indexOf(node)
     if (i == -1) return
 
-    canvasLayoutMutations().bringNodeToFront(graph.rootGraph.id, node.id)
+    canvasLayoutMutations.bringNodeToFront(graph.rootGraph.id, node.id)
 
     graph._nodes.splice(i, 1)
     graph._nodes.push(node)

src/lib/litegraph/src/LGraphGroup.test.ts

@@ -6,6 +6,7 @@ import type { LGraphCanvas } from '@/lib/litegraph/src/litegraph'
 import { LGraph, LGraphGroup, LGraphNode } from '@/lib/litegraph/src/litegraph'
 import { useLayoutMutations } from '@/renderer/core/layout/operations/layoutMutations'
 import { layoutStore } from '@/renderer/core/layout/store/layoutStore'
+import { LayoutSource } from '@/renderer/core/layout/types'
 import type { GroupId } from '@/types/groupId'
 import { toGroupId } from '@/types/groupId'
 import * as colorUtil from '@/utils/colorUtil'
@@ -285,7 +286,10 @@ describe('group layout in layoutStore', () => {
   test('keeps geometry locally when the store entry is gone', () => {
     const graph = new LGraph()
     const group = addedGroup(graph, toGroupId(809))
-    useLayoutMutations().deleteGroup(graph.rootGraph.id, group.id)
+    useLayoutMutations(LayoutSource.Canvas).deleteGroup(
+      graph.rootGraph.id,
+      group.id
+    )
 
     group.pos = [11, 22]
 
@@ -379,7 +383,7 @@ describe('group layout in layoutStore', () => {
       type: 'setGroupBounds',
       actor: 'test',
       timestamp: 1,
-      source: layoutStore.getCurrentSource(),
+      source: LayoutSource.Canvas,
       entity: 'group',
       graphId: graph.rootGraph.id,
       groupId: group.id,

src/lib/litegraph/src/LGraphNode.test.ts

@@ -10,6 +10,7 @@ import type {
 } from '@/lib/litegraph/src/litegraph'
 import type { Rect } from '@/lib/litegraph/src/interfaces'
 import { layoutStore } from '@/renderer/core/layout/store/layoutStore'
+import { LayoutSource } from '@/renderer/core/layout/types'
 import type { LGraphCanvas } from '@/lib/litegraph/src/LGraphCanvas'
 import type { CanvasPointerEvent } from '@/lib/litegraph/src/types/events'
 import { BaseWidget } from '@/lib/litegraph/src/widgets/BaseWidget'
@@ -880,12 +881,16 @@ describe('layout geometry projection', () => {
     const graph = new LGraph()
     const node = new LGraphNode('test')
     graph.add(node)
-    layoutStore.batchUpdateNodeBounds(graph.rootGraph.id, [
-      {
-        nodeId: node.id,
-        bounds: { x: 30, y: 40, width: 200, height: 80 }
-      }
-    ])
+    layoutStore.batchUpdateNodeBounds(
+      graph.rootGraph.id,
+      [
+        {
+          nodeId: node.id,
+          bounds: { x: 30, y: 40, width: 200, height: 80 }
+        }
+      ],
+      { source: LayoutSource.Canvas }
+    )
 
     node.move(5, 10)
 
@@ -898,12 +903,16 @@ describe('layout geometry projection', () => {
     const graph = new LGraph()
     const node = new LGraphNode('test')
     graph.add(node)
-    layoutStore.batchUpdateNodeBounds(graph.rootGraph.id, [
-      {
-        nodeId: node.id,
-        bounds: { x: 103, y: 97, width: 200, height: 80 }
-      }
-    ])
+    layoutStore.batchUpdateNodeBounds(
+      graph.rootGraph.id,
+      [
+        {
+          nodeId: node.id,
+          bounds: { x: 103, y: 97, width: 200, height: 80 }
+        }
+      ],
+      { source: LayoutSource.Canvas }
+    )
 
     node.snapToGrid(20)
 
@@ -916,12 +925,16 @@ describe('layout geometry projection', () => {
     const graph = new LGraph()
     const node = new LGraphNode('test')
     graph.add(node)
-    layoutStore.batchUpdateNodeBounds(graph.rootGraph.id, [
-      {
-        nodeId: node.id,
-        bounds: { x: 30, y: 40, width: 200, height: 80 }
-      }
-    ])
+    layoutStore.batchUpdateNodeBounds(
+      graph.rootGraph.id,
+      [
+        {
+          nodeId: node.id,
+          bounds: { x: 30, y: 40, width: 200, height: 80 }
+        }
+      ],
+      { source: LayoutSource.Canvas }
+    )
 
     graph.remove(node)
     graph.add(node)
@@ -943,12 +956,16 @@ describe('layout geometry projection', () => {
     const pos = node.pos
     const size = node.size
 
-    layoutStore.batchUpdateNodeBounds(graph.rootGraph.id, [
-      {
-        nodeId: node.id,
-        bounds: { x: 30, y: 40, width: 200, height: 80 }
-      }
-    ])
+    layoutStore.batchUpdateNodeBounds(
+      graph.rootGraph.id,
+      [
+        {
+          nodeId: node.id,
+          bounds: { x: 30, y: 40, width: 200, height: 80 }
+        }
+      ],
+      { source: LayoutSource.Canvas }
+    )
     pos[0] = 50
     size[1] = 90
 
@@ -970,12 +987,16 @@ describe('layout geometry projection', () => {
     node.pos = [10, 20]
     node.size = [100, 50]
     graph.add(node)
-    layoutStore.batchUpdateNodeBounds(graph.rootGraph.id, [
-      {
-        nodeId: node.id,
-        bounds: { x: 30, y: 40, width: 200, height: 80 }
-      }
-    ])
+    layoutStore.batchUpdateNodeBounds(
+      graph.rootGraph.id,
+      [
+        {
+          nodeId: node.id,
+          bounds: { x: 30, y: 40, width: 200, height: 80 }
+        }
+      ],
+      { source: LayoutSource.Canvas }
+    )
 
     node.pos = [50, 60]
 
@@ -988,12 +1009,16 @@ describe('layout geometry projection', () => {
     node.pos = [10, 20]
     node.size = [100, 50]
     graph.add(node)
-    layoutStore.batchUpdateNodeBounds(graph.rootGraph.id, [
-      {
-        nodeId: node.id,
-        bounds: { x: 30, y: 40, width: 200, height: 80 }
-      }
-    ])
+    layoutStore.batchUpdateNodeBounds(
+      graph.rootGraph.id,
+      [
+        {
+          nodeId: node.id,
+          bounds: { x: 30, y: 40, width: 200, height: 80 }
+        }
+      ],
+      { source: LayoutSource.Canvas }
+    )
 
     node.size = [300, 90]
 
@@ -1006,12 +1031,16 @@ describe('layout geometry projection', () => {
     node.pos = [10, 20]
     node.size = [100, 50]
     graph.add(node)
-    layoutStore.batchUpdateNodeBounds(graph.rootGraph.id, [
-      {
-        nodeId: node.id,
-        bounds: { x: 30, y: 40, width: 200, height: 80 }
-      }
-    ])
+    layoutStore.batchUpdateNodeBounds(
+      graph.rootGraph.id,
+      [
+        {
+          nodeId: node.id,
+          bounds: { x: 30, y: 40, width: 200, height: 80 }
+        }
+      ],
+      { source: LayoutSource.Canvas }
+    )
 
     node.pos = [50, 60]
     node.setSize([node.size[0], 120])

src/lib/litegraph/src/Reroute.store.test.ts

@@ -21,6 +21,7 @@ import { enableSubgraphNodeCreation } from '@/lib/litegraph/src/subgraph/__fixtu
 import type { SerialisableGraph } from '@/lib/litegraph/src/types/serialisation'
 import { useLayoutMutations } from '@/renderer/core/layout/operations/layoutMutations'
 import { layoutStore } from '@/renderer/core/layout/store/layoutStore'
+import { LayoutSource } from '@/renderer/core/layout/types'
 import { useRerouteStore } from '@/stores/rerouteStore'
 import { graphScopeOf } from '@/types/graphScopeId'
 import { toRerouteId } from '@/types/rerouteId'
@@ -62,10 +63,14 @@ describe('Reroute ↔ rerouteStore integration', () => {
     const incumbent = new Reroute(toRerouteId(1), graph, [0, 0])
     vi.spyOn(console, 'error').mockImplementation(() => {})
     useRerouteStore().registerReroute(graphScopeOf(graph), incumbent._chain)
-    useLayoutMutations().createReroute(graph.rootGraph.id, incumbent.id, {
-      x: 0,
-      y: 0
-    })
+    useLayoutMutations(LayoutSource.Canvas).createReroute(
+      graph.rootGraph.id,
+      incumbent.id,
+      {
+        x: 0,
+        y: 0
+      }
+    )
 
     const collision = new Reroute(incumbent.id, graph, [10, 10])
 
@@ -421,10 +426,14 @@ describe('Reroute position lives only in layoutStore', () => {
 
     // Move it in the store only. A mirrored copy on the class could not see
     // this without a synchronisation step.
-    useLayoutMutations().moveReroute(graph.rootGraph.id, reroute.id, {
-      x: 300,
-      y: 400
-    })
+    useLayoutMutations(LayoutSource.Canvas).moveReroute(
+      graph.rootGraph.id,
+      reroute.id,
+      {
+        x: 300,
+        y: 400
+      }
+    )
 
     expect([...reroute.pos]).toEqual([300, 400])
     expect(reroute.pos).toBe(pos)

src/renderer/core/canvas/canvasStore.ts

@@ -15,6 +15,7 @@ import type {
 } from '@/lib/litegraph/src/litegraph'
 import { promoteRecommendedWidgets } from '@/core/graph/subgraph/promotionUtils'
 import { useLayoutMutations } from '@/renderer/core/layout/operations/layoutMutations'
+import { LayoutSource } from '@/renderer/core/layout/types'
 import { app } from '@/scripts/app'
 import type { NodeId } from '@/types/nodeId'
 import { isLGraphGroup, isLGraphNode, isReroute } from '@/utils/litegraphUtil'
@@ -179,7 +180,7 @@ export const useCanvasStore = defineStore('canvas', () => {
           isGhostPlacing.value = e.detail.active
           const graphId = rootGraphId.value
           if (e.detail.active && graphId) {
-            const mutations = useLayoutMutations()
+            const mutations = useLayoutMutations(LayoutSource.Canvas)
             mutations.bringNodeToFront(graphId, e.detail.nodeId)
           }
         }

src/renderer/core/canvas/litegraph/arrangeForLegacyRender.test.ts

@@ -51,7 +51,7 @@ describe('arrangeForLegacyRender', () => {
     const graph = new LGraph()
     const first = addedNode(graph)
     const second = addedNode(graph)
-    const mutations = canvasLayoutMutations()
+    const mutations = canvasLayoutMutations
     mutations.setNodeZIndex(graph.id, first.id, 2)
     mutations.setNodeZIndex(graph.id, second.id, 1)