Add 'src/lib/litegraph/' from commit '1b58bf4966e9cdaa04bfaa40f5650b6c6680ab97'

git-subtree-dir: src/lib/litegraph
git-subtree-mainline: 1eadf80fec
git-subtree-split: 1b58bf4966

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

@@ -0,0 +1,460 @@
+import { describe, expect, it, vi } from "vitest"
+
+import { LGraph, LGraphNode } from "@/litegraph"
+import { ExecutableNodeDTO } from "@/subgraph/ExecutableNodeDTO"
+
+import {
+  createNestedSubgraphs,
+  createTestSubgraph,
+  createTestSubgraphNode,
+} from "./fixtures/subgraphHelpers"
+
+describe("ExecutableNodeDTO Creation", () => {
+  it("should create DTO from regular node", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    node.addInput("in", "number")
+    node.addOutput("out", "string")
+    graph.add(node)
+
+    const executableNodes = new Map()
+    const dto = new ExecutableNodeDTO(node, [], executableNodes, undefined)
+
+    expect(dto.node).toBe(node)
+    expect(dto.subgraphNodePath).toEqual([])
+    expect(dto.subgraphNode).toBeUndefined()
+    expect(dto.id).toBe(node.id.toString())
+  })
+
+  it("should create DTO with subgraph path", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Inner Node")
+    node.id = 42
+    graph.add(node)
+    const subgraphPath = ["10", "20"] as const
+
+    const dto = new ExecutableNodeDTO(node, subgraphPath, new Map(), undefined)
+
+    expect(dto.subgraphNodePath).toBe(subgraphPath)
+    expect(dto.id).toBe("10:20:42")
+  })
+
+  it("should clone input slot data", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    node.addInput("input1", "number")
+    node.addInput("input2", "string")
+    node.inputs[0].link = 123 // Simulate connected input
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    expect(dto.inputs).toHaveLength(2)
+    expect(dto.inputs[0].name).toBe("input1")
+    expect(dto.inputs[0].type).toBe("number")
+    expect(dto.inputs[0].linkId).toBe(123)
+    expect(dto.inputs[1].name).toBe("input2")
+    expect(dto.inputs[1].type).toBe("string")
+    expect(dto.inputs[1].linkId).toBeNull()
+
+    // Should be a copy, not reference
+    expect(dto.inputs).not.toBe(node.inputs)
+  })
+
+  it("should inherit graph reference", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    expect(dto.graph).toBe(graph)
+  })
+
+  it("should wrap applyToGraph method if present", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    const mockApplyToGraph = vi.fn()
+    Object.assign(node, { applyToGraph: mockApplyToGraph })
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    expect(dto.applyToGraph).toBeDefined()
+
+    // Test that wrapper calls original method
+    const args = ["arg1", "arg2"]
+    dto.applyToGraph!(args[0], args[1])
+
+    expect(mockApplyToGraph).toHaveBeenCalledWith(args[0], args[1])
+  })
+
+  it("should not create applyToGraph wrapper if method doesn't exist", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    expect(dto.applyToGraph).toBeUndefined()
+  })
+})
+
+describe("ExecutableNodeDTO Path-Based IDs", () => {
+  it("should generate simple ID for root node", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Root Node")
+    node.id = 5
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    expect(dto.id).toBe("5")
+  })
+
+  it("should generate path-based ID for nested node", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Nested Node")
+    node.id = 3
+    graph.add(node)
+    const path = ["1", "2"] as const
+
+    const dto = new ExecutableNodeDTO(node, path, new Map(), undefined)
+
+    expect(dto.id).toBe("1:2:3")
+  })
+
+  it("should handle deep nesting paths", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Deep Node")
+    node.id = 99
+    graph.add(node)
+    const path = ["1", "2", "3", "4", "5"] as const
+
+    const dto = new ExecutableNodeDTO(node, path, new Map(), undefined)
+
+    expect(dto.id).toBe("1:2:3:4:5:99")
+  })
+
+  it("should handle string and number IDs consistently", () => {
+    const graph = new LGraph()
+    const node1 = new LGraphNode("Node 1")
+    node1.id = 10
+    graph.add(node1)
+
+    const node2 = new LGraphNode("Node 2")
+    node2.id = 20
+    graph.add(node2)
+
+    const dto1 = new ExecutableNodeDTO(node1, ["5"], new Map(), undefined)
+    const dto2 = new ExecutableNodeDTO(node2, ["5"], new Map(), undefined)
+
+    expect(dto1.id).toBe("5:10")
+    expect(dto2.id).toBe("5:20")
+  })
+})
+
+describe("ExecutableNodeDTO Input Resolution", () => {
+  it("should return undefined for unconnected inputs", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    node.addInput("in", "number")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    // Unconnected input should return undefined
+    const resolved = dto.resolveInput(0)
+    expect(resolved).toBeUndefined()
+  })
+
+  it("should throw for non-existent input slots", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("No Input Node")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    // Should throw SlotIndexError for non-existent input
+    expect(() => dto.resolveInput(0)).toThrow("No input found for flattened id")
+  })
+
+  it("should handle subgraph boundary inputs", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "input1", type: "number" }],
+      nodeCount: 1,
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Get the inner node and create DTO
+    const innerNode = subgraph.nodes[0]
+    const dto = new ExecutableNodeDTO(innerNode, ["1"], new Map(), subgraphNode)
+
+    // Should return undefined for unconnected input
+    const resolved = dto.resolveInput(0)
+    expect(resolved).toBeUndefined()
+  })
+})
+
+describe("ExecutableNodeDTO Output Resolution", () => {
+  it("should resolve outputs for simple nodes", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    node.addOutput("out", "string")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    // resolveOutput requires type and visited parameters
+    const resolved = dto.resolveOutput(0, "string", new Set())
+
+    expect(resolved).toBeDefined()
+    expect(resolved?.node).toBe(dto)
+    expect(resolved?.origin_id).toBe(dto.id)
+    expect(resolved?.origin_slot).toBe(0)
+  })
+
+  it("should resolve cross-boundary outputs in subgraphs", () => {
+    const subgraph = createTestSubgraph({
+      outputs: [{ name: "output1", type: "string" }],
+      nodeCount: 1,
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Get the inner node and create DTO
+    const innerNode = subgraph.nodes[0]
+    const dto = new ExecutableNodeDTO(innerNode, ["1"], new Map(), subgraphNode)
+
+    const resolved = dto.resolveOutput(0, "string", new Set())
+
+    expect(resolved).toBeDefined()
+  })
+
+  it("should handle nodes with no outputs", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("No Output Node")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    // For regular nodes, resolveOutput returns the node itself even if no outputs
+    // This tests the current implementation behavior
+    const resolved = dto.resolveOutput(0, "string", new Set())
+    expect(resolved).toBeDefined()
+    expect(resolved?.node).toBe(dto)
+    expect(resolved?.origin_slot).toBe(0)
+  })
+})
+
+describe("ExecutableNodeDTO Properties", () => {
+  it("should provide access to basic properties", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    node.id = 42
+    node.addInput("input", "number")
+    node.addOutput("output", "string")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, ["1", "2"], new Map(), undefined)
+
+    expect(dto.id).toBe("1:2:42")
+    expect(dto.type).toBe(node.type)
+    expect(dto.title).toBe(node.title)
+    expect(dto.mode).toBe(node.mode)
+    expect(dto.isVirtualNode).toBe(node.isVirtualNode)
+  })
+
+  it("should provide access to input information", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    node.addInput("testInput", "number")
+    node.inputs[0].link = 999 // Simulate connection
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, [], new Map(), undefined)
+
+    expect(dto.inputs).toBeDefined()
+    expect(dto.inputs).toHaveLength(1)
+    expect(dto.inputs[0].name).toBe("testInput")
+    expect(dto.inputs[0].type).toBe("number")
+    expect(dto.inputs[0].linkId).toBe(999)
+  })
+})
+
+describe("ExecutableNodeDTO Memory Efficiency", () => {
+  it("should create lightweight objects", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Test Node")
+    node.addInput("in1", "number")
+    node.addInput("in2", "string")
+    node.addOutput("out1", "number")
+    node.addOutput("out2", "string")
+    graph.add(node)
+
+    const dto = new ExecutableNodeDTO(node, ["1"], new Map(), undefined)
+
+    // DTO should be lightweight - only essential properties
+    expect(dto.node).toBe(node) // Reference, not copy
+    expect(dto.subgraphNodePath).toEqual(["1"]) // Reference to path
+    expect(dto.inputs).toHaveLength(2) // Copied input data only
+
+    // Should not duplicate heavy node data
+    expect(dto.hasOwnProperty("outputs")).toBe(false) // Outputs not copied
+    expect(dto.hasOwnProperty("widgets")).toBe(false) // Widgets not copied
+  })
+
+  it("should handle disposal without memory leaks", () => {
+    const graph = new LGraph()
+    const nodes: ExecutableNodeDTO[] = []
+
+    // Create DTOs
+    for (let i = 0; i < 100; i++) {
+      const node = new LGraphNode(`Node ${i}`)
+      node.id = i
+      graph.add(node)
+      const dto = new ExecutableNodeDTO(node, ["parent"], new Map(), undefined)
+      nodes.push(dto)
+    }
+
+    expect(nodes).toHaveLength(100)
+
+    // Clear references
+    nodes.length = 0
+
+    // DTOs should be eligible for garbage collection
+    // (No explicit disposal needed - they're lightweight wrappers)
+    expect(nodes).toHaveLength(0)
+  })
+
+  it("should not retain unnecessary references", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const innerNode = subgraph.nodes[0]
+
+    const dto = new ExecutableNodeDTO(innerNode, ["1"], new Map(), subgraphNode)
+
+    // Should hold necessary references
+    expect(dto.node).toBe(innerNode)
+    expect(dto.subgraphNode).toBe(subgraphNode)
+    expect(dto.graph).toBe(innerNode.graph)
+
+    // Should not hold heavy references that prevent GC
+    expect(dto.hasOwnProperty("parentGraph")).toBe(false)
+    expect(dto.hasOwnProperty("rootGraph")).toBe(false)
+  })
+})
+
+describe("ExecutableNodeDTO Integration", () => {
+  it("should work with SubgraphNode flattening", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 3 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    const flattened = subgraphNode.getInnerNodes(new Map())
+
+    expect(flattened).toHaveLength(3)
+    expect(flattened[0]).toBeInstanceOf(ExecutableNodeDTO)
+    expect(flattened[0].id).toMatch(/^1:\d+$/)
+  })
+
+  it.skip("should handle nested subgraph flattening", () => {
+    // FIXME: Complex nested structure requires proper parent graph setup
+    // This test needs investigation of how resolveSubgraphIdPath works
+    // Skip for now - will implement in edge cases test file
+    const nested = createNestedSubgraphs({
+      depth: 2,
+      nodesPerLevel: 1,
+    })
+
+    const rootSubgraphNode = nested.subgraphNodes[0]
+    const executableNodes = new Map()
+    const flattened = rootSubgraphNode.getInnerNodes(executableNodes)
+
+    expect(flattened.length).toBeGreaterThan(0)
+    const hierarchicalIds = flattened.filter(dto => dto.id.includes(":"))
+    expect(hierarchicalIds.length).toBeGreaterThan(0)
+  })
+
+  it("should preserve original node properties through DTO", () => {
+    const graph = new LGraph()
+    const originalNode = new LGraphNode("Original")
+    originalNode.id = 123
+    originalNode.addInput("test", "number")
+    originalNode.properties = { value: 42 }
+    graph.add(originalNode)
+
+    const dto = new ExecutableNodeDTO(originalNode, ["parent"], new Map(), undefined)
+
+    // DTO should provide access to original node properties
+    expect(dto.node.id).toBe(123)
+    expect(dto.node.inputs).toHaveLength(1)
+    expect(dto.node.properties.value).toBe(42)
+
+    // But DTO ID should be path-based
+    expect(dto.id).toBe("parent:123")
+  })
+
+  it("should handle execution context correctly", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+    const subgraphNode = createTestSubgraphNode(subgraph, { id: 99 })
+    const innerNode = subgraph.nodes[0]
+    innerNode.id = 55
+
+    const dto = new ExecutableNodeDTO(innerNode, ["99"], new Map(), subgraphNode)
+
+    // DTO provides execution context
+    expect(dto.id).toBe("99:55") // Path-based execution ID
+    expect(dto.node.id).toBe(55) // Original node ID preserved
+    expect(dto.subgraphNode?.id).toBe(99) // Subgraph context
+  })
+})
+
+describe("ExecutableNodeDTO Scale Testing", () => {
+  it("should create DTOs at scale", () => {
+    const graph = new LGraph()
+    const startTime = performance.now()
+    const dtos: ExecutableNodeDTO[] = []
+
+    // Create DTOs to test performance
+    for (let i = 0; i < 1000; i++) {
+      const node = new LGraphNode(`Node ${i}`)
+      node.id = i
+      node.addInput("in", "number")
+      graph.add(node)
+
+      const dto = new ExecutableNodeDTO(node, ["parent"], new Map(), undefined)
+      dtos.push(dto)
+    }
+
+    const endTime = performance.now()
+    const duration = endTime - startTime
+
+    expect(dtos).toHaveLength(1000)
+    // Test deterministic properties instead of flaky timing
+    expect(dtos[0].id).toBe("parent:0")
+    expect(dtos[999].id).toBe("parent:999")
+    expect(dtos.every((dto, i) => dto.id === `parent:${i}`)).toBe(true)
+
+    console.log(`Created 1000 DTOs in ${duration.toFixed(2)}ms`)
+  })
+
+  it("should handle complex path generation correctly", () => {
+    const graph = new LGraph()
+    const node = new LGraphNode("Deep Node")
+    node.id = 999
+    graph.add(node)
+
+    // Test deterministic path generation behavior
+    const testCases = [
+      { depth: 1, expectedId: "1:999" },
+      { depth: 3, expectedId: "1:2:3:999" },
+      { depth: 5, expectedId: "1:2:3:4:5:999" },
+      { depth: 10, expectedId: "1:2:3:4:5:6:7:8:9:10:999" },
+    ]
+
+    for (const testCase of testCases) {
+      const path = Array.from({ length: testCase.depth }, (_, i) => (i + 1).toString())
+      const dto = new ExecutableNodeDTO(node, path, new Map(), undefined)
+      expect(dto.id).toBe(testCase.expectedId)
+    }
+  })
+})

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

@@ -0,0 +1,303 @@
+/**
+ * Core Subgraph Tests
+ *
+ * This file implements fundamental tests for the Subgraph class that establish
+ * patterns for the rest of the testing team. These tests cover construction,
+ * basic I/O management, and known issues.
+ */
+
+import { describe, expect, it } from "vitest"
+
+import { RecursionError } from "@/infrastructure/RecursionError"
+import { LGraph, Subgraph } from "@/litegraph"
+import { createUuidv4 } from "@/utils/uuid"
+
+import { subgraphTest } from "./fixtures/subgraphFixtures"
+import {
+  assertSubgraphStructure,
+  createTestSubgraph,
+  createTestSubgraphData,
+} from "./fixtures/subgraphHelpers"
+
+describe("Subgraph Construction", () => {
+  it("should create a subgraph with minimal data", () => {
+    const subgraph = createTestSubgraph()
+
+    assertSubgraphStructure(subgraph, {
+      inputCount: 0,
+      outputCount: 0,
+      nodeCount: 0,
+      name: "Test Subgraph",
+    })
+
+    expect(subgraph.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i)
+    expect(subgraph.inputNode).toBeDefined()
+    expect(subgraph.outputNode).toBeDefined()
+    expect(subgraph.inputNode.id).toBe(-10)
+    expect(subgraph.outputNode.id).toBe(-20)
+  })
+
+  it("should require a root graph", () => {
+    const subgraphData = createTestSubgraphData()
+
+    expect(() => {
+      // @ts-expect-error Testing invalid null parameter
+      new Subgraph(null, subgraphData)
+    }).toThrow("Root graph is required")
+  })
+
+  it("should accept custom name and ID", () => {
+    const customId = createUuidv4()
+    const customName = "My Custom Subgraph"
+
+    const subgraph = createTestSubgraph({
+      id: customId,
+      name: customName,
+    })
+
+    expect(subgraph.id).toBe(customId)
+    expect(subgraph.name).toBe(customName)
+  })
+
+  it("should initialize with empty inputs and outputs", () => {
+    const subgraph = createTestSubgraph()
+
+    expect(subgraph.inputs).toHaveLength(0)
+    expect(subgraph.outputs).toHaveLength(0)
+    expect(subgraph.widgets).toHaveLength(0)
+  })
+
+  it("should have properly configured input and output nodes", () => {
+    const subgraph = createTestSubgraph()
+
+    // Input node should be positioned on the left
+    expect(subgraph.inputNode.pos[0]).toBeLessThan(100)
+
+    // Output node should be positioned on the right
+    expect(subgraph.outputNode.pos[0]).toBeGreaterThan(300)
+
+    // Both should reference the subgraph
+    expect(subgraph.inputNode.subgraph).toBe(subgraph)
+    expect(subgraph.outputNode.subgraph).toBe(subgraph)
+  })
+})
+
+describe("Subgraph Input/Output Management", () => {
+  subgraphTest("should add a single input", ({ emptySubgraph }) => {
+    const input = emptySubgraph.addInput("test_input", "number")
+
+    expect(emptySubgraph.inputs).toHaveLength(1)
+    expect(input.name).toBe("test_input")
+    expect(input.type).toBe("number")
+    expect(emptySubgraph.inputs.indexOf(input)).toBe(0)
+  })
+
+  subgraphTest("should add a single output", ({ emptySubgraph }) => {
+    const output = emptySubgraph.addOutput("test_output", "string")
+
+    expect(emptySubgraph.outputs).toHaveLength(1)
+    expect(output.name).toBe("test_output")
+    expect(output.type).toBe("string")
+    expect(emptySubgraph.outputs.indexOf(output)).toBe(0)
+  })
+
+  subgraphTest("should maintain correct indices when adding multiple inputs", ({ emptySubgraph }) => {
+    const input1 = emptySubgraph.addInput("input_1", "number")
+    const input2 = emptySubgraph.addInput("input_2", "string")
+    const input3 = emptySubgraph.addInput("input_3", "boolean")
+
+    expect(emptySubgraph.inputs.indexOf(input1)).toBe(0)
+    expect(emptySubgraph.inputs.indexOf(input2)).toBe(1)
+    expect(emptySubgraph.inputs.indexOf(input3)).toBe(2)
+    expect(emptySubgraph.inputs).toHaveLength(3)
+  })
+
+  subgraphTest("should maintain correct indices when adding multiple outputs", ({ emptySubgraph }) => {
+    const output1 = emptySubgraph.addOutput("output_1", "number")
+    const output2 = emptySubgraph.addOutput("output_2", "string")
+    const output3 = emptySubgraph.addOutput("output_3", "boolean")
+
+    expect(emptySubgraph.outputs.indexOf(output1)).toBe(0)
+    expect(emptySubgraph.outputs.indexOf(output2)).toBe(1)
+    expect(emptySubgraph.outputs.indexOf(output3)).toBe(2)
+    expect(emptySubgraph.outputs).toHaveLength(3)
+  })
+
+  subgraphTest("should remove inputs correctly", ({ simpleSubgraph }) => {
+    // Add a second input first
+    simpleSubgraph.addInput("second_input", "string")
+    expect(simpleSubgraph.inputs).toHaveLength(2)
+
+    // Remove the first input
+    const firstInput = simpleSubgraph.inputs[0]
+    simpleSubgraph.removeInput(firstInput)
+
+    expect(simpleSubgraph.inputs).toHaveLength(1)
+    expect(simpleSubgraph.inputs[0].name).toBe("second_input")
+    // Verify it's at index 0 in the array
+    expect(simpleSubgraph.inputs.indexOf(simpleSubgraph.inputs[0])).toBe(0)
+  })
+
+  subgraphTest("should remove outputs correctly", ({ simpleSubgraph }) => {
+    // Add a second output first
+    simpleSubgraph.addOutput("second_output", "string")
+    expect(simpleSubgraph.outputs).toHaveLength(2)
+
+    // Remove the first output
+    const firstOutput = simpleSubgraph.outputs[0]
+    simpleSubgraph.removeOutput(firstOutput)
+
+    expect(simpleSubgraph.outputs).toHaveLength(1)
+    expect(simpleSubgraph.outputs[0].name).toBe("second_output")
+    // Verify it's at index 0 in the array
+    expect(simpleSubgraph.outputs.indexOf(simpleSubgraph.outputs[0])).toBe(0)
+  })
+})
+
+describe("Subgraph Serialization", () => {
+  subgraphTest("should serialize empty subgraph", ({ emptySubgraph }) => {
+    const serialized = emptySubgraph.asSerialisable()
+
+    expect(serialized.version).toBe(1)
+    expect(serialized.id).toBeTruthy()
+    expect(serialized.name).toBe("Empty Test Subgraph")
+    expect(serialized.inputs).toHaveLength(0)
+    expect(serialized.outputs).toHaveLength(0)
+    expect(serialized.nodes).toHaveLength(0)
+    expect(typeof serialized.links).toBe("object")
+  })
+
+  subgraphTest("should serialize subgraph with inputs and outputs", ({ simpleSubgraph }) => {
+    const serialized = simpleSubgraph.asSerialisable()
+
+    expect(serialized.inputs).toHaveLength(1)
+    expect(serialized.outputs).toHaveLength(1)
+    expect(serialized.inputs[0].name).toBe("input")
+    expect(serialized.inputs[0].type).toBe("number")
+    expect(serialized.outputs[0].name).toBe("output")
+    expect(serialized.outputs[0].type).toBe("number")
+  })
+
+  subgraphTest("should include input and output nodes in serialization", ({ emptySubgraph }) => {
+    const serialized = emptySubgraph.asSerialisable()
+
+    expect(serialized.inputNode).toBeDefined()
+    expect(serialized.outputNode).toBeDefined()
+    expect(serialized.inputNode.id).toBe(-10)
+    expect(serialized.outputNode.id).toBe(-20)
+  })
+})
+
+describe("Subgraph Known Issues", () => {
+  it.todo("should enforce MAX_NESTED_SUBGRAPHS limit", () => {
+    // This test documents that MAX_NESTED_SUBGRAPHS = 1000 is defined
+    // but not actually enforced anywhere in the code.
+    //
+    // Expected behavior: Should throw error when nesting exceeds limit
+    // Actual behavior: No validation is performed
+    //
+    // This safety limit should be implemented to prevent runaway recursion.
+  })
+
+  it("should provide MAX_NESTED_SUBGRAPHS constant", () => {
+    expect(Subgraph.MAX_NESTED_SUBGRAPHS).toBe(1000)
+  })
+
+  it("should have recursion detection in place", () => {
+    // Verify that RecursionError is available and can be thrown
+    expect(() => {
+      throw new RecursionError("test recursion")
+    }).toThrow(RecursionError)
+
+    expect(() => {
+      throw new RecursionError("test recursion")
+    }).toThrow("test recursion")
+  })
+})
+
+describe("Subgraph Root Graph Relationship", () => {
+  it("should maintain reference to root graph", () => {
+    const rootGraph = new LGraph()
+    const subgraphData = createTestSubgraphData()
+    const subgraph = new Subgraph(rootGraph, subgraphData)
+
+    expect(subgraph.rootGraph).toBe(rootGraph)
+  })
+
+  it("should inherit root graph in nested subgraphs", () => {
+    const rootGraph = new LGraph()
+    const parentData = createTestSubgraphData({
+      name: "Parent Subgraph",
+    })
+    const parentSubgraph = new Subgraph(rootGraph, parentData)
+
+    // Create a nested subgraph
+    const nestedData = createTestSubgraphData({
+      name: "Nested Subgraph",
+    })
+    const nestedSubgraph = new Subgraph(rootGraph, nestedData)
+
+    expect(nestedSubgraph.rootGraph).toBe(rootGraph)
+    expect(parentSubgraph.rootGraph).toBe(rootGraph)
+  })
+})
+
+describe("Subgraph Error Handling", () => {
+  subgraphTest("should handle removing non-existent input gracefully", ({ emptySubgraph }) => {
+    // Create a fake input that doesn't belong to this subgraph
+    const fakeInput = emptySubgraph.addInput("temp", "number")
+    emptySubgraph.removeInput(fakeInput) // Remove it first
+
+    // Now try to remove it again
+    expect(() => {
+      emptySubgraph.removeInput(fakeInput)
+    }).toThrow("Input not found")
+  })
+
+  subgraphTest("should handle removing non-existent output gracefully", ({ emptySubgraph }) => {
+    // Create a fake output that doesn't belong to this subgraph
+    const fakeOutput = emptySubgraph.addOutput("temp", "number")
+    emptySubgraph.removeOutput(fakeOutput) // Remove it first
+
+    // Now try to remove it again
+    expect(() => {
+      emptySubgraph.removeOutput(fakeOutput)
+    }).toThrow("Output not found")
+  })
+})
+
+describe("Subgraph Integration", () => {
+  it("should work with LGraph's node management", () => {
+    const subgraph = createTestSubgraph({
+      nodeCount: 3,
+    })
+
+    // Verify nodes were added to the subgraph
+    expect(subgraph.nodes).toHaveLength(3)
+
+    // Verify we can access nodes by ID
+    const firstNode = subgraph.getNodeById(1)
+    expect(firstNode).toBeDefined()
+    expect(firstNode?.title).toContain("Test Node")
+  })
+
+  it("should maintain link integrity", () => {
+    const subgraph = createTestSubgraph({
+      nodeCount: 2,
+    })
+
+    const node1 = subgraph.nodes[0]
+    const node2 = subgraph.nodes[1]
+
+    // Connect the nodes
+    node1.connect(0, node2, 0)
+
+    // Verify link was created
+    expect(subgraph.links.size).toBe(1)
+
+    // Verify link integrity
+    const link = Array.from(subgraph.links.values())[0]
+    expect(link.origin_id).toBe(node1.id)
+    expect(link.target_id).toBe(node2.id)
+  })
+})

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

@@ -0,0 +1,364 @@
+/**
+ * SubgraphEdgeCases Tests
+ *
+ * Tests for edge cases, error handling, and boundary conditions in the subgraph system.
+ * This covers unusual scenarios, invalid states, and stress testing.
+ */
+
+import { describe, expect, it } from "vitest"
+
+import { LGraph, LGraphNode, Subgraph } from "@/litegraph"
+
+import {
+  createNestedSubgraphs,
+  createTestSubgraph,
+  createTestSubgraphNode,
+} from "./fixtures/subgraphHelpers"
+
+describe("SubgraphEdgeCases - Recursion Detection", () => {
+  it("should handle circular subgraph references without crashing", () => {
+    const sub1 = createTestSubgraph({ name: "Sub1" })
+    const sub2 = createTestSubgraph({ name: "Sub2" })
+
+    // Create circular reference
+    const node1 = createTestSubgraphNode(sub1, { id: 1 })
+    const node2 = createTestSubgraphNode(sub2, { id: 2 })
+
+    sub1.add(node2)
+    sub2.add(node1)
+
+    // Should not crash or hang - currently throws path resolution error due to circular structure
+    expect(() => {
+      const executableNodes = new Map()
+      node1.getInnerNodes(executableNodes)
+    }).toThrow(/Node \[\d+\] not found/) // Current behavior: path resolution fails
+  })
+
+  it("should handle deep nesting scenarios", () => {
+    // Test with reasonable depth to avoid timeout
+    const nested = createNestedSubgraphs({ depth: 10, nodesPerLevel: 1 })
+
+    // Should create nested structure without errors
+    expect(nested.subgraphs).toHaveLength(10)
+    expect(nested.subgraphNodes).toHaveLength(10)
+
+    // First level should exist and be accessible
+    const firstLevel = nested.rootGraph.nodes[0]
+    expect(firstLevel).toBeDefined()
+    expect(firstLevel.isSubgraphNode()).toBe(true)
+  })
+
+  it.todo("should use WeakSet for cycle detection", () => {
+    // TODO: This test is currently skipped because cycle detection has a bug
+    // The fix is to pass 'visited' directly instead of 'new Set(visited)' in SubgraphNode.ts:299
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Add to own subgraph to create cycle
+    subgraph.add(subgraphNode)
+
+    // Should throw due to cycle detection
+    const executableNodes = new Map()
+    expect(() => {
+      subgraphNode.getInnerNodes(executableNodes)
+    }).toThrow(/while flattening subgraph/i)
+  })
+
+  it("should respect MAX_NESTED_SUBGRAPHS constant", () => {
+    // Verify the constant exists and is a reasonable positive number
+    expect(Subgraph.MAX_NESTED_SUBGRAPHS).toBeDefined()
+    expect(typeof Subgraph.MAX_NESTED_SUBGRAPHS).toBe("number")
+    expect(Subgraph.MAX_NESTED_SUBGRAPHS).toBeGreaterThan(0)
+    expect(Subgraph.MAX_NESTED_SUBGRAPHS).toBeLessThanOrEqual(10_000) // Reasonable upper bound
+
+    // Note: Currently not enforced in implementation
+    // This test documents the intended behavior
+  })
+})
+
+describe("SubgraphEdgeCases - Invalid States", () => {
+  it("should handle removing non-existent inputs gracefully", () => {
+    const subgraph = createTestSubgraph()
+    const fakeInput = { name: "fake", type: "number", disconnect: () => {} } as any
+
+    // Should throw appropriate error for non-existent input
+    expect(() => {
+      subgraph.removeInput(fakeInput)
+    }).toThrow(/Input not found/) // Expected error
+  })
+
+  it("should handle removing non-existent outputs gracefully", () => {
+    const subgraph = createTestSubgraph()
+    const fakeOutput = { name: "fake", type: "number", disconnect: () => {} } as any
+
+    expect(() => {
+      subgraph.removeOutput(fakeOutput)
+    }).toThrow(/Output not found/) // Expected error
+  })
+
+  it("should handle null/undefined input names", () => {
+    const subgraph = createTestSubgraph()
+
+    // ISSUE: Current implementation allows null/undefined names which may cause runtime errors
+    // TODO: Consider adding validation to prevent null/undefined names
+    // This test documents the current permissive behavior
+    expect(() => {
+      subgraph.addInput(null as any, "number")
+    }).not.toThrow() // Current behavior: allows null
+
+    expect(() => {
+      subgraph.addInput(undefined as any, "number")
+    }).not.toThrow() // Current behavior: allows undefined
+  })
+
+  it("should handle null/undefined output names", () => {
+    const subgraph = createTestSubgraph()
+
+    // ISSUE: Current implementation allows null/undefined names which may cause runtime errors
+    // TODO: Consider adding validation to prevent null/undefined names
+    // This test documents the current permissive behavior
+    expect(() => {
+      subgraph.addOutput(null as any, "number")
+    }).not.toThrow() // Current behavior: allows null
+
+    expect(() => {
+      subgraph.addOutput(undefined as any, "number")
+    }).not.toThrow() // Current behavior: allows undefined
+  })
+
+  it("should handle empty string names", () => {
+    const subgraph = createTestSubgraph()
+
+    // Current implementation may allow empty strings
+    // Document the actual behavior
+    expect(() => {
+      subgraph.addInput("", "number")
+    }).not.toThrow() // Current behavior: allows empty strings
+
+    expect(() => {
+      subgraph.addOutput("", "number")
+    }).not.toThrow() // Current behavior: allows empty strings
+  })
+
+  it("should handle undefined types gracefully", () => {
+    const subgraph = createTestSubgraph()
+
+    // Undefined type should not crash but may have default behavior
+    expect(() => {
+      subgraph.addInput("test", undefined as any)
+    }).not.toThrow()
+
+    expect(() => {
+      subgraph.addOutput("test", undefined as any)
+    }).not.toThrow()
+  })
+
+  it("should handle duplicate slot names", () => {
+    const subgraph = createTestSubgraph()
+
+    // Add first input
+    subgraph.addInput("duplicate", "number")
+
+    // Adding duplicate should not crash (current behavior allows it)
+    expect(() => {
+      subgraph.addInput("duplicate", "string")
+    }).not.toThrow()
+
+    // Should now have 2 inputs with same name
+    expect(subgraph.inputs.length).toBe(2)
+    expect(subgraph.inputs[0].name).toBe("duplicate")
+    expect(subgraph.inputs[1].name).toBe("duplicate")
+  })
+})
+
+describe("SubgraphEdgeCases - Boundary Conditions", () => {
+  it("should handle empty subgraphs (no nodes, no IO)", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 0 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Should handle empty subgraph without errors
+    const executableNodes = new Map()
+    const flattened = subgraphNode.getInnerNodes(executableNodes)
+
+    expect(flattened).toHaveLength(0)
+    expect(subgraph.inputs).toHaveLength(0)
+    expect(subgraph.outputs).toHaveLength(0)
+  })
+
+  it("should handle single input/output subgraphs", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "single_in", type: "number" }],
+      outputs: [{ name: "single_out", type: "number" }],
+      nodeCount: 1,
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.inputs).toHaveLength(1)
+    expect(subgraphNode.outputs).toHaveLength(1)
+    expect(subgraphNode.inputs[0].name).toBe("single_in")
+    expect(subgraphNode.outputs[0].name).toBe("single_out")
+  })
+
+  it("should handle subgraphs with many slots", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+
+    // Add many inputs (test with 20 to keep test fast)
+    for (let i = 0; i < 20; i++) {
+      subgraph.addInput(`input_${i}`, "number")
+    }
+
+    // Add many outputs
+    for (let i = 0; i < 20; i++) {
+      subgraph.addOutput(`output_${i}`, "number")
+    }
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraph.inputs).toHaveLength(20)
+    expect(subgraph.outputs).toHaveLength(20)
+    expect(subgraphNode.inputs).toHaveLength(20)
+    expect(subgraphNode.outputs).toHaveLength(20)
+
+    // Should still flatten correctly
+    const executableNodes = new Map()
+    const flattened = subgraphNode.getInnerNodes(executableNodes)
+    expect(flattened).toHaveLength(1) // Original node count
+  })
+
+  it("should handle very long slot names", () => {
+    const subgraph = createTestSubgraph()
+    const longName = "a".repeat(1000) // 1000 character name
+
+    expect(() => {
+      subgraph.addInput(longName, "number")
+      subgraph.addOutput(longName, "string")
+    }).not.toThrow()
+
+    expect(subgraph.inputs[0].name).toBe(longName)
+    expect(subgraph.outputs[0].name).toBe(longName)
+  })
+
+  it("should handle Unicode characters in names", () => {
+    const subgraph = createTestSubgraph()
+    const unicodeName = "测试_🚀_تست_тест"
+
+    expect(() => {
+      subgraph.addInput(unicodeName, "number")
+      subgraph.addOutput(unicodeName, "string")
+    }).not.toThrow()
+
+    expect(subgraph.inputs[0].name).toBe(unicodeName)
+    expect(subgraph.outputs[0].name).toBe(unicodeName)
+  })
+})
+
+describe("SubgraphEdgeCases - Type Validation", () => {
+  it("should allow connecting mismatched types (no validation currently)", () => {
+    const rootGraph = new LGraph()
+    const subgraph = createTestSubgraph()
+
+    subgraph.addInput("num", "number")
+    subgraph.addOutput("str", "string")
+
+    // Create a basic node manually since createNode is not available
+    const numberNode = new LGraphNode("basic/const")
+    numberNode.addOutput("value", "number")
+    rootGraph.add(numberNode)
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    rootGraph.add(subgraphNode)
+
+    // Currently allows mismatched connections (no type validation)
+    expect(() => {
+      numberNode.connect(0, subgraphNode, 0)
+    }).not.toThrow()
+  })
+
+  it("should handle invalid type strings", () => {
+    const subgraph = createTestSubgraph()
+
+    // These should not crash (current behavior)
+    expect(() => {
+      subgraph.addInput("test1", "invalid_type")
+      subgraph.addInput("test2", "")
+      subgraph.addInput("test3", "123")
+      subgraph.addInput("test4", "special!@#$%")
+    }).not.toThrow()
+  })
+
+  it("should handle complex type strings", () => {
+    const subgraph = createTestSubgraph()
+
+    expect(() => {
+      subgraph.addInput("array", "array<number>")
+      subgraph.addInput("object", "object<{x: number, y: string}>")
+      subgraph.addInput("union", "number|string")
+    }).not.toThrow()
+
+    expect(subgraph.inputs).toHaveLength(3)
+    expect(subgraph.inputs[0].type).toBe("array<number>")
+    expect(subgraph.inputs[1].type).toBe("object<{x: number, y: string}>")
+    expect(subgraph.inputs[2].type).toBe("number|string")
+  })
+})
+
+describe("SubgraphEdgeCases - Performance and Scale", () => {
+  it("should handle large numbers of nodes in subgraph", () => {
+    // Create subgraph with many nodes (keep reasonable for test speed)
+    const subgraph = createTestSubgraph({ nodeCount: 50 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    const executableNodes = new Map()
+    const flattened = subgraphNode.getInnerNodes(executableNodes)
+
+    expect(flattened).toHaveLength(50)
+
+    // Performance is acceptable for 50 nodes (typically < 1ms)
+  })
+
+  it("should handle rapid IO changes", () => {
+    const subgraph = createTestSubgraph()
+
+    // Rapidly add and remove inputs/outputs
+    for (let i = 0; i < 10; i++) {
+      const input = subgraph.addInput(`rapid_${i}`, "number")
+      const output = subgraph.addOutput(`rapid_${i}`, "number")
+
+      // Remove them immediately
+      subgraph.removeInput(input)
+      subgraph.removeOutput(output)
+    }
+
+    // Should end up with no inputs/outputs
+    expect(subgraph.inputs).toHaveLength(0)
+    expect(subgraph.outputs).toHaveLength(0)
+  })
+
+  it("should handle concurrent modifications safely", () => {
+    // This test ensures the system doesn't crash under concurrent access
+    // Note: JavaScript is single-threaded, so this tests rapid sequential access
+    const subgraph = createTestSubgraph({ nodeCount: 5 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Simulate concurrent operations
+    const operations = []
+    for (let i = 0; i < 20; i++) {
+      operations.push(() => {
+        const executableNodes = new Map()
+        subgraphNode.getInnerNodes(executableNodes)
+      }, () => {
+        subgraph.addInput(`concurrent_${i}`, "number")
+      }, () => {
+        if (subgraph.inputs.length > 0) {
+          subgraph.removeInput(subgraph.inputs[0])
+        }
+      })
+    }
+
+    // Execute all operations - should not crash
+    expect(() => {
+      for (const op of operations) op()
+    }).not.toThrow()
+  })
+})

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

@@ -0,0 +1,458 @@
+import { describe, expect, vi } from "vitest"
+
+import { subgraphTest } from "./fixtures/subgraphFixtures"
+import { verifyEventSequence } from "./fixtures/subgraphHelpers"
+
+describe("SubgraphEvents - Event Payload Verification", () => {
+  subgraphTest("dispatches input-added with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const input = subgraph.addInput("test_input", "number")
+
+    const addedEvents = capture.getEventsByType("input-added")
+    expect(addedEvents).toHaveLength(1)
+
+    expect(addedEvents[0].detail).toEqual({
+      input: expect.objectContaining({
+        name: "test_input",
+        type: "number",
+      }),
+    })
+
+    expect(addedEvents[0].detail.input).toBe(input)
+  })
+
+  subgraphTest("dispatches output-added with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const output = subgraph.addOutput("test_output", "string")
+
+    const addedEvents = capture.getEventsByType("output-added")
+    expect(addedEvents).toHaveLength(1)
+
+    expect(addedEvents[0].detail).toEqual({
+      output: expect.objectContaining({
+        name: "test_output",
+        type: "string",
+      }),
+    })
+
+    expect(addedEvents[0].detail.output).toBe(output)
+  })
+
+  subgraphTest("dispatches removing-input with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const input = subgraph.addInput("to_remove", "boolean")
+
+    capture.clear()
+
+    subgraph.removeInput(input)
+
+    const removingEvents = capture.getEventsByType("removing-input")
+    expect(removingEvents).toHaveLength(1)
+
+    expect(removingEvents[0].detail).toEqual({
+      input: expect.objectContaining({
+        name: "to_remove",
+        type: "boolean",
+      }),
+      index: 0,
+    })
+
+    expect(removingEvents[0].detail.input).toBe(input)
+  })
+
+  subgraphTest("dispatches removing-output with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const output = subgraph.addOutput("to_remove", "number")
+
+    capture.clear()
+
+    subgraph.removeOutput(output)
+
+    const removingEvents = capture.getEventsByType("removing-output")
+    expect(removingEvents).toHaveLength(1)
+
+    expect(removingEvents[0].detail).toEqual({
+      output: expect.objectContaining({
+        name: "to_remove",
+        type: "number",
+      }),
+      index: 0,
+    })
+
+    expect(removingEvents[0].detail.output).toBe(output)
+  })
+
+  subgraphTest("dispatches renaming-input with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const input = subgraph.addInput("old_name", "string")
+
+    capture.clear()
+
+    subgraph.renameInput(input, "new_name")
+
+    const renamingEvents = capture.getEventsByType("renaming-input")
+    expect(renamingEvents).toHaveLength(1)
+
+    expect(renamingEvents[0].detail).toEqual({
+      input: expect.objectContaining({
+        type: "string",
+      }),
+      index: 0,
+      oldName: "old_name",
+      newName: "new_name",
+    })
+
+    expect(renamingEvents[0].detail.input).toBe(input)
+
+    // Verify the label was updated after the event (renameInput sets label, not name)
+    expect(input.label).toBe("new_name")
+    expect(input.displayName).toBe("new_name")
+    expect(input.name).toBe("old_name")
+  })
+
+  subgraphTest("dispatches renaming-output with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const output = subgraph.addOutput("old_name", "number")
+
+    capture.clear()
+
+    subgraph.renameOutput(output, "new_name")
+
+    const renamingEvents = capture.getEventsByType("renaming-output")
+    expect(renamingEvents).toHaveLength(1)
+
+    expect(renamingEvents[0].detail).toEqual({
+      output: expect.objectContaining({
+        name: "old_name", // Should still have the old name when event is dispatched
+        type: "number",
+      }),
+      index: 0,
+      oldName: "old_name",
+      newName: "new_name",
+    })
+
+    expect(renamingEvents[0].detail.output).toBe(output)
+
+    // Verify the label was updated after the event
+    expect(output.label).toBe("new_name")
+    expect(output.displayName).toBe("new_name")
+    expect(output.name).toBe("old_name")
+  })
+
+  subgraphTest("dispatches adding-input with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    subgraph.addInput("test_input", "number")
+
+    const addingEvents = capture.getEventsByType("adding-input")
+    expect(addingEvents).toHaveLength(1)
+
+    expect(addingEvents[0].detail).toEqual({
+      name: "test_input",
+      type: "number",
+    })
+  })
+
+  subgraphTest("dispatches adding-output with correct payload", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    subgraph.addOutput("test_output", "string")
+
+    const addingEvents = capture.getEventsByType("adding-output")
+    expect(addingEvents).toHaveLength(1)
+
+    expect(addingEvents[0].detail).toEqual({
+      name: "test_output",
+      type: "string",
+    })
+  })
+})
+
+describe("SubgraphEvents - Event Handler Isolation", () => {
+  subgraphTest("continues dispatching if handler throws", ({ emptySubgraph }) => {
+    const handler1 = vi.fn(() => {
+      throw new Error("Handler 1 error")
+    })
+    const handler2 = vi.fn()
+    const handler3 = vi.fn()
+
+    emptySubgraph.events.addEventListener("input-added", handler1)
+    emptySubgraph.events.addEventListener("input-added", handler2)
+    emptySubgraph.events.addEventListener("input-added", handler3)
+
+    // The operation itself should not throw (error is isolated)
+    expect(() => {
+      emptySubgraph.addInput("test", "number")
+    }).not.toThrow()
+
+    // Verify all handlers were called despite the first one throwing
+    expect(handler1).toHaveBeenCalled()
+    expect(handler2).toHaveBeenCalled()
+    expect(handler3).toHaveBeenCalled()
+
+    // Verify the throwing handler actually received the event
+    expect(handler1).toHaveBeenCalledWith(expect.objectContaining({
+      type: "input-added",
+    }))
+
+    // Verify other handlers received correct event data
+    expect(handler2).toHaveBeenCalledWith(expect.objectContaining({
+      type: "input-added",
+      detail: expect.objectContaining({
+        input: expect.objectContaining({
+          name: "test",
+          type: "number",
+        }),
+      }),
+    }))
+    expect(handler3).toHaveBeenCalledWith(expect.objectContaining({
+      type: "input-added",
+    }))
+  })
+
+  subgraphTest("maintains handler execution order", ({ emptySubgraph }) => {
+    const executionOrder: number[] = []
+
+    const handler1 = vi.fn(() => executionOrder.push(1))
+    const handler2 = vi.fn(() => executionOrder.push(2))
+    const handler3 = vi.fn(() => executionOrder.push(3))
+
+    emptySubgraph.events.addEventListener("input-added", handler1)
+    emptySubgraph.events.addEventListener("input-added", handler2)
+    emptySubgraph.events.addEventListener("input-added", handler3)
+
+    emptySubgraph.addInput("test", "number")
+
+    expect(executionOrder).toEqual([1, 2, 3])
+  })
+
+  subgraphTest("prevents handler accumulation with proper cleanup", ({ emptySubgraph }) => {
+    const handler = vi.fn()
+
+    for (let i = 0; i < 5; i++) {
+      emptySubgraph.events.addEventListener("input-added", handler)
+      emptySubgraph.events.removeEventListener("input-added", handler)
+    }
+
+    emptySubgraph.events.addEventListener("input-added", handler)
+
+    emptySubgraph.addInput("test", "number")
+
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  subgraphTest("supports AbortController cleanup patterns", ({ emptySubgraph }) => {
+    const abortController = new AbortController()
+    const { signal } = abortController
+
+    const handler = vi.fn()
+
+    emptySubgraph.events.addEventListener("input-added", handler, { signal })
+
+    emptySubgraph.addInput("test1", "number")
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    abortController.abort()
+
+    emptySubgraph.addInput("test2", "number")
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe("SubgraphEvents - Event Sequence Testing", () => {
+  subgraphTest("maintains correct event sequence for inputs", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    subgraph.addInput("input1", "number")
+
+    verifyEventSequence(capture.events, [
+      "adding-input",
+      "input-added",
+    ])
+  })
+
+  subgraphTest("maintains correct event sequence for outputs", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    subgraph.addOutput("output1", "string")
+
+    verifyEventSequence(capture.events, [
+      "adding-output",
+      "output-added",
+    ])
+  })
+
+  subgraphTest("maintains correct event sequence for rapid operations", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    subgraph.addInput("input1", "number")
+    subgraph.addInput("input2", "string")
+    subgraph.addOutput("output1", "boolean")
+    subgraph.addOutput("output2", "number")
+
+    verifyEventSequence(capture.events, [
+      "adding-input",
+      "input-added",
+      "adding-input",
+      "input-added",
+      "adding-output",
+      "output-added",
+      "adding-output",
+      "output-added",
+    ])
+  })
+
+  subgraphTest("handles concurrent event handling", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const handler1 = vi.fn(() => {
+      return new Promise(resolve => setTimeout(resolve, 1))
+    })
+
+    const handler2 = vi.fn()
+    const handler3 = vi.fn()
+
+    subgraph.events.addEventListener("input-added", handler1)
+    subgraph.events.addEventListener("input-added", handler2)
+    subgraph.events.addEventListener("input-added", handler3)
+
+    subgraph.addInput("test", "number")
+
+    expect(handler1).toHaveBeenCalled()
+    expect(handler2).toHaveBeenCalled()
+    expect(handler3).toHaveBeenCalled()
+
+    const addedEvents = capture.getEventsByType("input-added")
+    expect(addedEvents).toHaveLength(1)
+  })
+
+  subgraphTest("validates event timestamps are properly ordered", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    subgraph.addInput("input1", "number")
+    subgraph.addInput("input2", "string")
+    subgraph.addOutput("output1", "boolean")
+
+    for (let i = 1; i < capture.events.length; i++) {
+      expect(capture.events[i].timestamp).toBeGreaterThanOrEqual(
+        capture.events[i - 1].timestamp,
+      )
+    }
+  })
+})
+
+describe("SubgraphEvents - Event Cancellation", () => {
+  subgraphTest("supports preventDefault() for cancellable events", ({ emptySubgraph }) => {
+    const preventHandler = vi.fn((event: Event) => {
+      event.preventDefault()
+    })
+
+    emptySubgraph.events.addEventListener("removing-input", preventHandler)
+
+    const input = emptySubgraph.addInput("test", "number")
+
+    emptySubgraph.removeInput(input)
+
+    expect(emptySubgraph.inputs).toContain(input)
+    expect(preventHandler).toHaveBeenCalled()
+  })
+
+  subgraphTest("supports preventDefault() for output removal", ({ emptySubgraph }) => {
+    const preventHandler = vi.fn((event: Event) => {
+      event.preventDefault()
+    })
+
+    emptySubgraph.events.addEventListener("removing-output", preventHandler)
+
+    const output = emptySubgraph.addOutput("test", "number")
+
+    emptySubgraph.removeOutput(output)
+
+    expect(emptySubgraph.outputs).toContain(output)
+    expect(preventHandler).toHaveBeenCalled()
+  })
+
+  subgraphTest("allows removal when not prevented", ({ emptySubgraph }) => {
+    const allowHandler = vi.fn()
+
+    emptySubgraph.events.addEventListener("removing-input", allowHandler)
+
+    const input = emptySubgraph.addInput("test", "number")
+
+    emptySubgraph.removeInput(input)
+
+    expect(emptySubgraph.inputs).not.toContain(input)
+    expect(emptySubgraph.inputs).toHaveLength(0)
+    expect(allowHandler).toHaveBeenCalled()
+  })
+})
+
+describe("SubgraphEvents - Event Detail Structure Validation", () => {
+  subgraphTest("validates all event detail structures match TypeScript types", ({ eventCapture }) => {
+    const { subgraph, capture } = eventCapture
+
+    const input = subgraph.addInput("test_input", "number")
+    subgraph.renameInput(input, "renamed_input")
+    subgraph.removeInput(input)
+
+    const output = subgraph.addOutput("test_output", "string")
+    subgraph.renameOutput(output, "renamed_output")
+    subgraph.removeOutput(output)
+
+    const addingInputEvent = capture.getEventsByType("adding-input")[0]
+    expect(addingInputEvent.detail).toEqual({
+      name: expect.any(String),
+      type: expect.any(String),
+    })
+
+    const inputAddedEvent = capture.getEventsByType("input-added")[0]
+    expect(inputAddedEvent.detail).toEqual({
+      input: expect.any(Object),
+    })
+
+    const renamingInputEvent = capture.getEventsByType("renaming-input")[0]
+    expect(renamingInputEvent.detail).toEqual({
+      input: expect.any(Object),
+      index: expect.any(Number),
+      oldName: expect.any(String),
+      newName: expect.any(String),
+    })
+
+    const removingInputEvent = capture.getEventsByType("removing-input")[0]
+    expect(removingInputEvent.detail).toEqual({
+      input: expect.any(Object),
+      index: expect.any(Number),
+    })
+
+    const addingOutputEvent = capture.getEventsByType("adding-output")[0]
+    expect(addingOutputEvent.detail).toEqual({
+      name: expect.any(String),
+      type: expect.any(String),
+    })
+
+    const outputAddedEvent = capture.getEventsByType("output-added")[0]
+    expect(outputAddedEvent.detail).toEqual({
+      output: expect.any(Object),
+    })
+
+    const renamingOutputEvent = capture.getEventsByType("renaming-output")[0]
+    expect(renamingOutputEvent.detail).toEqual({
+      output: expect.any(Object),
+      index: expect.any(Number),
+      oldName: expect.any(String),
+      newName: expect.any(String),
+    })
+
+    const removingOutputEvent = capture.getEventsByType("removing-output")[0]
+    expect(removingOutputEvent.detail).toEqual({
+      output: expect.any(Object),
+      index: expect.any(Number),
+    })
+  })
+})

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

@@ -0,0 +1,386 @@
+import { describe, expect, it } from "vitest"
+
+import { LGraphNode } from "@/litegraph"
+
+import { subgraphTest } from "./fixtures/subgraphFixtures"
+import {
+  createTestSubgraph,
+  createTestSubgraphNode,
+} from "./fixtures/subgraphHelpers"
+
+describe("SubgraphIO - Input Slot Dual-Nature Behavior", () => {
+  subgraphTest("input accepts external connections from parent graph", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+
+    subgraph.addInput("test_input", "number")
+
+    const externalNode = new LGraphNode("External Source")
+    externalNode.addOutput("out", "number")
+    parentGraph.add(externalNode)
+
+    expect(() => {
+      externalNode.connect(0, subgraphNode, 0)
+    }).not.toThrow()
+
+    expect(externalNode.outputs[0].links?.includes(subgraphNode.inputs[0].link)).toBe(true)
+    expect(subgraphNode.inputs[0].link).not.toBe(null)
+  })
+
+  subgraphTest("empty input slot creation enables dynamic IO", ({ simpleSubgraph }) => {
+    const initialInputCount = simpleSubgraph.inputs.length
+
+    // Create empty input slot
+    simpleSubgraph.addInput("", "*")
+
+    // Should create new input
+    expect(simpleSubgraph.inputs.length).toBe(initialInputCount + 1)
+
+    // The empty slot should be configurable
+    const emptyInput = simpleSubgraph.inputs.at(-1)
+    expect(emptyInput.name).toBe("")
+    expect(emptyInput.type).toBe("*")
+  })
+
+  subgraphTest("handles slot removal with active connections", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+
+    const externalNode = new LGraphNode("External Source")
+    externalNode.addOutput("out", "*")
+    parentGraph.add(externalNode)
+
+    externalNode.connect(0, subgraphNode, 0)
+
+    // Verify connection exists
+    expect(subgraphNode.inputs[0].link).not.toBe(null)
+
+    // Remove the existing input (fixture creates one input)
+    const inputToRemove = subgraph.inputs[0]
+    subgraph.removeInput(inputToRemove)
+
+    // Connection should be cleaned up
+    expect(subgraphNode.inputs.length).toBe(0)
+    expect(externalNode.outputs[0].links).toHaveLength(0)
+  })
+
+  subgraphTest("handles slot renaming with active connections", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+
+    const externalNode = new LGraphNode("External Source")
+    externalNode.addOutput("out", "*")
+    parentGraph.add(externalNode)
+
+    externalNode.connect(0, subgraphNode, 0)
+
+    // Verify connection exists
+    expect(subgraphNode.inputs[0].link).not.toBe(null)
+
+    // Rename the existing input (fixture creates input named "input")
+    const inputToRename = subgraph.inputs[0]
+    subgraph.renameInput(inputToRename, "new_name")
+
+    // Connection should persist and subgraph definition should be updated
+    expect(subgraphNode.inputs[0].link).not.toBe(null)
+    expect(subgraph.inputs[0].label).toBe("new_name")
+    expect(subgraph.inputs[0].displayName).toBe("new_name")
+  })
+})
+
+describe("SubgraphIO - Output Slot Dual-Nature Behavior", () => {
+  subgraphTest("output provides connections to parent graph", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+
+    // Add an output to the subgraph
+    subgraph.addOutput("test_output", "number")
+
+    const externalNode = new LGraphNode("External Target")
+    externalNode.addInput("in", "number")
+    parentGraph.add(externalNode)
+
+    // External connection from subgraph output should work
+    expect(() => {
+      subgraphNode.connect(0, externalNode, 0)
+    }).not.toThrow()
+
+    expect(subgraphNode.outputs[0].links?.includes(externalNode.inputs[0].link)).toBe(true)
+    expect(externalNode.inputs[0].link).not.toBe(null)
+  })
+
+  subgraphTest("empty output slot creation enables dynamic IO", ({ simpleSubgraph }) => {
+    const initialOutputCount = simpleSubgraph.outputs.length
+
+    // Create empty output slot
+    simpleSubgraph.addOutput("", "*")
+
+    // Should create new output
+    expect(simpleSubgraph.outputs.length).toBe(initialOutputCount + 1)
+
+    // The empty slot should be configurable
+    const emptyOutput = simpleSubgraph.outputs.at(-1)
+    expect(emptyOutput.name).toBe("")
+    expect(emptyOutput.type).toBe("*")
+  })
+
+  subgraphTest("handles slot removal with active connections", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+
+    const externalNode = new LGraphNode("External Target")
+    externalNode.addInput("in", "*")
+    parentGraph.add(externalNode)
+
+    subgraphNode.connect(0, externalNode, 0)
+
+    // Verify connection exists
+    expect(externalNode.inputs[0].link).not.toBe(null)
+
+    // Remove the existing output (fixture creates one output)
+    const outputToRemove = subgraph.outputs[0]
+    subgraph.removeOutput(outputToRemove)
+
+    // Connection should be cleaned up
+    expect(subgraphNode.outputs.length).toBe(0)
+    expect(externalNode.inputs[0].link).toBe(null)
+  })
+
+  subgraphTest("handles slot renaming updates all references", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+
+    const externalNode = new LGraphNode("External Target")
+    externalNode.addInput("in", "*")
+    parentGraph.add(externalNode)
+
+    subgraphNode.connect(0, externalNode, 0)
+
+    // Verify connection exists
+    expect(externalNode.inputs[0].link).not.toBe(null)
+
+    // Rename the existing output (fixture creates output named "output")
+    const outputToRename = subgraph.outputs[0]
+    subgraph.renameOutput(outputToRename, "new_name")
+
+    // Connection should persist and subgraph definition should be updated
+    expect(externalNode.inputs[0].link).not.toBe(null)
+    expect(subgraph.outputs[0].label).toBe("new_name")
+    expect(subgraph.outputs[0].displayName).toBe("new_name")
+  })
+})
+
+describe("SubgraphIO - Boundary Connection Management", () => {
+  subgraphTest("verifies cross-boundary link resolution", ({ complexSubgraph }) => {
+    const subgraphNode = createTestSubgraphNode(complexSubgraph)
+    const parentGraph = subgraphNode.graph!
+
+    const externalSource = new LGraphNode("External Source")
+    externalSource.addOutput("out", "number")
+    parentGraph.add(externalSource)
+
+    const externalTarget = new LGraphNode("External Target")
+    externalTarget.addInput("in", "number")
+    parentGraph.add(externalTarget)
+
+    externalSource.connect(0, subgraphNode, 0)
+    subgraphNode.connect(0, externalTarget, 0)
+
+    expect(subgraphNode.inputs[0].link).not.toBe(null)
+    expect(externalTarget.inputs[0].link).not.toBe(null)
+  })
+
+  subgraphTest("handles bypass nodes that pass through data", ({ simpleSubgraph }) => {
+    const subgraphNode = createTestSubgraphNode(simpleSubgraph)
+    const parentGraph = subgraphNode.graph!
+
+    const externalSource = new LGraphNode("External Source")
+    externalSource.addOutput("out", "number")
+    parentGraph.add(externalSource)
+
+    const externalTarget = new LGraphNode("External Target")
+    externalTarget.addInput("in", "number")
+    parentGraph.add(externalTarget)
+
+    externalSource.connect(0, subgraphNode, 0)
+    subgraphNode.connect(0, externalTarget, 0)
+
+    expect(subgraphNode.inputs[0].link).not.toBe(null)
+    expect(externalTarget.inputs[0].link).not.toBe(null)
+  })
+
+  subgraphTest("tests link integrity across subgraph boundaries", ({ subgraphWithNode }) => {
+    const { subgraphNode, parentGraph } = subgraphWithNode
+
+    const externalSource = new LGraphNode("External Source")
+    externalSource.addOutput("out", "*")
+    parentGraph.add(externalSource)
+
+    const externalTarget = new LGraphNode("External Target")
+    externalTarget.addInput("in", "*")
+    parentGraph.add(externalTarget)
+
+    externalSource.connect(0, subgraphNode, 0)
+    subgraphNode.connect(0, externalTarget, 0)
+
+    const inputBoundaryLink = subgraphNode.inputs[0].link
+    const outputBoundaryLink = externalTarget.inputs[0].link
+
+    expect(inputBoundaryLink).toBeTruthy()
+    expect(outputBoundaryLink).toBeTruthy()
+
+    // Links should exist in parent graph
+    expect(inputBoundaryLink).toBeTruthy()
+    expect(outputBoundaryLink).toBeTruthy()
+  })
+
+  subgraphTest("verifies proper link cleanup on slot removal", ({ complexSubgraph }) => {
+    const subgraphNode = createTestSubgraphNode(complexSubgraph)
+    const parentGraph = subgraphNode.graph!
+
+    const externalSource = new LGraphNode("External Source")
+    externalSource.addOutput("out", "number")
+    parentGraph.add(externalSource)
+
+    const externalTarget = new LGraphNode("External Target")
+    externalTarget.addInput("in", "number")
+    parentGraph.add(externalTarget)
+
+    externalSource.connect(0, subgraphNode, 0)
+    subgraphNode.connect(0, externalTarget, 0)
+
+    expect(subgraphNode.inputs[0].link).not.toBe(null)
+    expect(externalTarget.inputs[0].link).not.toBe(null)
+
+    const inputToRemove = complexSubgraph.inputs[0]
+    complexSubgraph.removeInput(inputToRemove)
+
+    expect(subgraphNode.inputs.findIndex(i => i.name === "data")).toBe(-1)
+    expect(externalSource.outputs[0].links).toHaveLength(0)
+
+    const outputToRemove = complexSubgraph.outputs[0]
+    complexSubgraph.removeOutput(outputToRemove)
+
+    expect(subgraphNode.outputs.findIndex(o => o.name === "result")).toBe(-1)
+    expect(externalTarget.inputs[0].link).toBe(null)
+  })
+})
+
+describe("SubgraphIO - Advanced Scenarios", () => {
+  it("handles multiple inputs and outputs with complex connections", () => {
+    const subgraph = createTestSubgraph({
+      name: "Complex IO Test",
+      inputs: [
+        { name: "input1", type: "number" },
+        { name: "input2", type: "string" },
+        { name: "input3", type: "boolean" },
+      ],
+      outputs: [
+        { name: "output1", type: "number" },
+        { name: "output2", type: "string" },
+      ],
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Should have correct number of slots
+    expect(subgraphNode.inputs.length).toBe(3)
+    expect(subgraphNode.outputs.length).toBe(2)
+
+    // Each slot should have correct type
+    expect(subgraphNode.inputs[0].type).toBe("number")
+    expect(subgraphNode.inputs[1].type).toBe("string")
+    expect(subgraphNode.inputs[2].type).toBe("boolean")
+    expect(subgraphNode.outputs[0].type).toBe("number")
+    expect(subgraphNode.outputs[1].type).toBe("string")
+  })
+
+  it("handles dynamic slot creation and removal", () => {
+    const subgraph = createTestSubgraph({
+      name: "Dynamic IO Test",
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Start with no slots
+    expect(subgraphNode.inputs.length).toBe(0)
+    expect(subgraphNode.outputs.length).toBe(0)
+
+    // Add slots dynamically
+    subgraph.addInput("dynamic_input", "number")
+    subgraph.addOutput("dynamic_output", "string")
+
+    // SubgraphNode should automatically update
+    expect(subgraphNode.inputs.length).toBe(1)
+    expect(subgraphNode.outputs.length).toBe(1)
+    expect(subgraphNode.inputs[0].name).toBe("dynamic_input")
+    expect(subgraphNode.outputs[0].name).toBe("dynamic_output")
+
+    // Remove slots
+    subgraph.removeInput(subgraph.inputs[0])
+    subgraph.removeOutput(subgraph.outputs[0])
+
+    // SubgraphNode should automatically update
+    expect(subgraphNode.inputs.length).toBe(0)
+    expect(subgraphNode.outputs.length).toBe(0)
+  })
+
+  it("maintains slot synchronization across multiple instances", () => {
+    const subgraph = createTestSubgraph({
+      name: "Multi-Instance Test",
+      inputs: [{ name: "shared_input", type: "number" }],
+      outputs: [{ name: "shared_output", type: "number" }],
+    })
+
+    // Create multiple instances
+    const instance1 = createTestSubgraphNode(subgraph)
+    const instance2 = createTestSubgraphNode(subgraph)
+    const instance3 = createTestSubgraphNode(subgraph)
+
+    // All instances should have same slots
+    expect(instance1.inputs.length).toBe(1)
+    expect(instance2.inputs.length).toBe(1)
+    expect(instance3.inputs.length).toBe(1)
+
+    // Modify the subgraph definition
+    subgraph.addInput("new_input", "string")
+    subgraph.addOutput("new_output", "boolean")
+
+    // All instances should automatically update
+    expect(instance1.inputs.length).toBe(2)
+    expect(instance2.inputs.length).toBe(2)
+    expect(instance3.inputs.length).toBe(2)
+    expect(instance1.outputs.length).toBe(2)
+    expect(instance2.outputs.length).toBe(2)
+    expect(instance3.outputs.length).toBe(2)
+  })
+})
+
+describe("SubgraphIO - Empty Slot Connection", () => {
+  subgraphTest("creates new input and connects when dragging from empty slot inside subgraph", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode } = subgraphWithNode
+
+    // Create a node inside the subgraph that will receive the connection
+    const internalNode = new LGraphNode("Internal Node")
+    internalNode.addInput("in", "string")
+    subgraph.add(internalNode)
+
+    // Simulate the connection process from the empty slot to an internal node
+    // The -1 indicates a connection from the "empty" slot
+    subgraph.inputNode.connectByType(-1, internalNode, "string")
+
+    // 1. A new input should have been created on the subgraph
+    expect(subgraph.inputs.length).toBe(2) // Fixture adds one input already
+    const newInput = subgraph.inputs[1]
+    expect(newInput.name).toBe("in")
+    expect(newInput.type).toBe("string")
+
+    // 2. The subgraph node should now have a corresponding real input slot
+    expect(subgraphNode.inputs.length).toBe(2)
+    const subgraphInputSlot = subgraphNode.inputs[1]
+    expect(subgraphInputSlot.name).toBe("in")
+
+    // 3. A link should be established inside the subgraph
+    expect(internalNode.inputs[0].link).not.toBe(null)
+    const link = subgraph.links.get(internalNode.inputs[0].link!)
+    expect(link).toBeDefined()
+    expect(link.target_id).toBe(internalNode.id)
+    expect(link.target_slot).toBe(0)
+    expect(link.origin_id).toBe(subgraph.inputNode.id)
+    expect(link.origin_slot).toBe(1) // Should be the second slot
+  })
+})

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

@@ -0,0 +1,428 @@
+import { describe, expect, it, vi } from "vitest"
+
+import { LGraph } from "@/litegraph"
+
+import { subgraphTest } from "./fixtures/subgraphFixtures"
+import {
+  createTestSubgraph,
+  createTestSubgraphNode,
+} from "./fixtures/subgraphHelpers"
+
+describe("SubgraphNode Memory Management", () => {
+  describe("Event Listener Cleanup", () => {
+    it("should register event listeners on construction", () => {
+      const subgraph = createTestSubgraph()
+
+      // Spy on addEventListener to track listener registration
+      const addEventSpy = vi.spyOn(subgraph.events, "addEventListener")
+      const initialCalls = addEventSpy.mock.calls.length
+
+      createTestSubgraphNode(subgraph)
+
+      // Should have registered listeners for subgraph events
+      expect(addEventSpy.mock.calls.length).toBeGreaterThan(initialCalls)
+
+      // Should have registered listeners for all major events
+      const eventTypes = addEventSpy.mock.calls.map(call => call[0])
+      expect(eventTypes).toContain("input-added")
+      expect(eventTypes).toContain("removing-input")
+      expect(eventTypes).toContain("output-added")
+      expect(eventTypes).toContain("removing-output")
+      expect(eventTypes).toContain("renaming-input")
+      expect(eventTypes).toContain("renaming-output")
+    })
+
+    it("should clean up input listeners on removal", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input1", type: "number" }],
+      })
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // Add input should have created listeners
+      expect(subgraphNode.inputs[0]._listenerController).toBeDefined()
+      expect(subgraphNode.inputs[0]._listenerController?.signal.aborted).toBe(false)
+
+      // Call onRemoved to simulate node removal
+      subgraphNode.onRemoved()
+
+      // Input listeners should be aborted
+      expect(subgraphNode.inputs[0]._listenerController?.signal.aborted).toBe(true)
+    })
+
+    it("should not accumulate listeners during reconfiguration", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input1", type: "number" }],
+      })
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      const addEventSpy = vi.spyOn(subgraph.events, "addEventListener")
+      const initialCalls = addEventSpy.mock.calls.length
+
+      // Reconfigure multiple times
+      for (let i = 0; i < 5; i++) {
+        subgraphNode.configure({
+          id: subgraphNode.id,
+          type: subgraph.id,
+          pos: [100 * i, 100 * i],
+          size: [200, 100],
+          inputs: [],
+          outputs: [],
+          properties: {},
+          flags: {},
+          mode: 0,
+        })
+      }
+
+      // Should not add new main subgraph listeners
+      // (Only input-specific listeners might be reconfigured)
+      const finalCalls = addEventSpy.mock.calls.length
+      expect(finalCalls).toBe(initialCalls) // Main listeners not re-added
+    })
+  })
+
+  describe("Widget Promotion Memory Management", () => {
+    it("should clean up promoted widget references", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "testInput", type: "number" }],
+      })
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // Simulate widget promotion scenario
+      const input = subgraphNode.inputs[0]
+      const mockWidget = {
+        type: "number",
+        name: "promoted_widget",
+        value: 123,
+        draw: vi.fn(),
+        mouse: vi.fn(),
+        computeSize: vi.fn(),
+        createCopyForNode: vi.fn().mockReturnValue({
+          type: "number",
+          name: "promoted_widget",
+          value: 123,
+        }),
+      }
+
+      // Simulate widget promotion
+      input._widget = mockWidget
+      input.widget = { name: "promoted_widget" }
+      subgraphNode.widgets.push(mockWidget)
+
+      expect(input._widget).toBe(mockWidget)
+      expect(input.widget).toBeDefined()
+      expect(subgraphNode.widgets).toContain(mockWidget)
+
+      // Remove widget (this should clean up references)
+      subgraphNode.removeWidget(mockWidget)
+
+      // Widget should be removed from array
+      expect(subgraphNode.widgets).not.toContain(mockWidget)
+    })
+
+    it("should not leak widgets during reconfiguration", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input1", type: "number" }],
+      })
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // Track widget count before and after reconfigurations
+      const initialWidgetCount = subgraphNode.widgets.length
+
+      // Reconfigure multiple times
+      for (let i = 0; i < 3; i++) {
+        subgraphNode.configure({
+          id: subgraphNode.id,
+          type: subgraph.id,
+          pos: [100, 100],
+          size: [200, 100],
+          inputs: [],
+          outputs: [],
+          properties: {},
+          flags: {},
+          mode: 0,
+        })
+      }
+
+      // Widget count should not accumulate
+      expect(subgraphNode.widgets.length).toBe(initialWidgetCount)
+    })
+  })
+})
+
+describe("SubgraphMemory - Event Listener Management", () => {
+  subgraphTest("event handlers still work after node creation", ({ emptySubgraph }) => {
+    const rootGraph = new LGraph()
+    const subgraphNode = createTestSubgraphNode(emptySubgraph)
+    rootGraph.add(subgraphNode)
+
+    const handler = vi.fn()
+    emptySubgraph.events.addEventListener("input-added", handler)
+
+    emptySubgraph.addInput("test", "number")
+
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(handler).toHaveBeenCalledWith(expect.objectContaining({
+      type: "input-added",
+    }))
+  })
+
+  subgraphTest("can add and remove multiple nodes without errors", ({ emptySubgraph }) => {
+    const rootGraph = new LGraph()
+    const nodes: ReturnType<typeof createTestSubgraphNode>[] = []
+
+    // Should be able to create multiple nodes without issues
+    for (let i = 0; i < 5; i++) {
+      const subgraphNode = createTestSubgraphNode(emptySubgraph)
+      rootGraph.add(subgraphNode)
+      nodes.push(subgraphNode)
+    }
+
+    expect(rootGraph.nodes.length).toBe(5)
+
+    // Should be able to remove them all without issues
+    for (const node of nodes) {
+      rootGraph.remove(node)
+    }
+
+    expect(rootGraph.nodes.length).toBe(0)
+  })
+
+  subgraphTest("supports AbortController cleanup patterns", ({ emptySubgraph }) => {
+    const abortController = new AbortController()
+    const { signal } = abortController
+
+    const handler = vi.fn()
+
+    emptySubgraph.events.addEventListener("input-added", handler, { signal })
+
+    emptySubgraph.addInput("test1", "number")
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    abortController.abort()
+
+    emptySubgraph.addInput("test2", "number")
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  subgraphTest("handles multiple creation/deletion cycles", ({ emptySubgraph }) => {
+    const rootGraph = new LGraph()
+
+    for (let cycle = 0; cycle < 3; cycle++) {
+      const nodes = []
+
+      for (let i = 0; i < 5; i++) {
+        const subgraphNode = createTestSubgraphNode(emptySubgraph)
+        rootGraph.add(subgraphNode)
+        nodes.push(subgraphNode)
+      }
+
+      expect(rootGraph.nodes.length).toBe(5)
+
+      for (const node of nodes) {
+        rootGraph.remove(node)
+      }
+
+      expect(rootGraph.nodes.length).toBe(0)
+    }
+  })
+})
+
+describe("SubgraphMemory - Reference Management", () => {
+  it("properly manages subgraph references in root graph", () => {
+    const rootGraph = new LGraph()
+    const subgraph = createTestSubgraph()
+    const subgraphId = subgraph.id
+
+    // Add subgraph to root graph registry
+    rootGraph.subgraphs.set(subgraphId, subgraph)
+    expect(rootGraph.subgraphs.has(subgraphId)).toBe(true)
+    expect(rootGraph.subgraphs.get(subgraphId)).toBe(subgraph)
+
+    // Remove subgraph from registry
+    rootGraph.subgraphs.delete(subgraphId)
+    expect(rootGraph.subgraphs.has(subgraphId)).toBe(false)
+  })
+
+  it("maintains proper parent-child references", () => {
+    const rootGraph = new LGraph()
+    const subgraph = createTestSubgraph({ nodeCount: 2 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Add to graph
+    rootGraph.add(subgraphNode)
+    expect(subgraphNode.graph).toBe(rootGraph)
+    expect(rootGraph.nodes).toContain(subgraphNode)
+
+    // Remove from graph
+    rootGraph.remove(subgraphNode)
+    expect(rootGraph.nodes).not.toContain(subgraphNode)
+  })
+
+  it("prevents circular reference creation", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Subgraph should not contain its own instance node
+    expect(subgraph.nodes).not.toContain(subgraphNode)
+
+    // If circular references were attempted, they should be detected
+    expect(subgraphNode.subgraph).toBe(subgraph)
+    expect(subgraph.nodes.includes(subgraphNode)).toBe(false)
+  })
+})
+
+describe("SubgraphMemory - Widget Reference Management", () => {
+  subgraphTest("properly sets and clears widget references", ({ simpleSubgraph }) => {
+    const subgraphNode = createTestSubgraphNode(simpleSubgraph)
+    const input = subgraphNode.inputs[0]
+
+    // Mock widget for testing
+    const mockWidget = {
+      type: "number",
+      value: 42,
+      name: "test_widget",
+    }
+
+    // Set widget reference
+    if (input && "_widget" in input) {
+      ;(input as any)._widget = mockWidget
+      expect((input as any)._widget).toBe(mockWidget)
+    }
+
+    // Clear widget reference
+    if (input && "_widget" in input) {
+      ;(input as any)._widget = undefined
+      expect((input as any)._widget).toBeUndefined()
+    }
+  })
+
+  subgraphTest("maintains widget count consistency", ({ simpleSubgraph }) => {
+    const subgraphNode = createTestSubgraphNode(simpleSubgraph)
+
+    const initialWidgetCount = subgraphNode.widgets?.length || 0
+
+    // Add mock widgets
+    const widget1 = { type: "number", value: 1, name: "widget1" }
+    const widget2 = { type: "string", value: "test", name: "widget2" }
+
+    if (subgraphNode.widgets) {
+      subgraphNode.widgets.push(widget1, widget2)
+      expect(subgraphNode.widgets.length).toBe(initialWidgetCount + 2)
+    }
+
+    // Remove widgets
+    if (subgraphNode.widgets) {
+      subgraphNode.widgets.length = initialWidgetCount
+      expect(subgraphNode.widgets.length).toBe(initialWidgetCount)
+    }
+  })
+
+  subgraphTest("cleans up references during node removal", ({ simpleSubgraph }) => {
+    const subgraphNode = createTestSubgraphNode(simpleSubgraph)
+    const input = subgraphNode.inputs[0]
+    const output = subgraphNode.outputs[0]
+
+    // Set up references that should be cleaned up
+    const mockReferences = {
+      widget: { type: "number", value: 42 },
+      connection: { id: 1, type: "number" },
+      listener: vi.fn(),
+    }
+
+    // Set references
+    if (input) {
+      ;(input as any)._widget = mockReferences.widget
+      ;(input as any)._connection = mockReferences.connection
+    }
+    if (output) {
+      ;(input as any)._connection = mockReferences.connection
+    }
+
+    // Verify references are set
+    expect((input as any)?._widget).toBe(mockReferences.widget)
+    expect((input as any)?._connection).toBe(mockReferences.connection)
+
+    // Simulate proper cleanup (what onRemoved should do)
+    subgraphNode.onRemoved()
+
+    // Input-specific listeners should be cleaned up (this works)
+    if (input && "_listenerController" in input) {
+      expect((input as any)._listenerController?.signal.aborted).toBe(true)
+    }
+  })
+})
+
+describe("SubgraphMemory - Performance and Scale", () => {
+  subgraphTest("handles multiple subgraphs in same graph", ({ subgraphWithNode }) => {
+    const { parentGraph } = subgraphWithNode
+    const subgraphA = createTestSubgraph({ name: "Subgraph A" })
+    const subgraphB = createTestSubgraph({ name: "Subgraph B" })
+
+    const nodeA = createTestSubgraphNode(subgraphA)
+    const nodeB = createTestSubgraphNode(subgraphB)
+
+    parentGraph.add(nodeA)
+    parentGraph.add(nodeB)
+
+    expect(nodeA.graph).toBe(parentGraph)
+    expect(nodeB.graph).toBe(parentGraph)
+    expect(parentGraph.nodes.length).toBe(3) // Original + nodeA + nodeB
+
+    parentGraph.remove(nodeA)
+    parentGraph.remove(nodeB)
+
+    expect(parentGraph.nodes.length).toBe(1) // Only the original subgraphNode remains
+  })
+
+  it("handles many instances without issues", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "stress_input", type: "number" }],
+      outputs: [{ name: "stress_output", type: "number" }],
+    })
+
+    const rootGraph = new LGraph()
+    const instances = []
+
+    // Create instances
+    for (let i = 0; i < 25; i++) {
+      const instance = createTestSubgraphNode(subgraph)
+      rootGraph.add(instance)
+      instances.push(instance)
+    }
+
+    expect(instances.length).toBe(25)
+    expect(rootGraph.nodes.length).toBe(25)
+
+    // Remove all instances (proper cleanup)
+    for (const instance of instances) {
+      rootGraph.remove(instance)
+    }
+
+    expect(rootGraph.nodes.length).toBe(0)
+  })
+
+  it("maintains consistent behavior across multiple cycles", () => {
+    const subgraph = createTestSubgraph()
+    const rootGraph = new LGraph()
+
+    for (let cycle = 0; cycle < 10; cycle++) {
+      const instances = []
+
+      // Create instances
+      for (let i = 0; i < 10; i++) {
+        const instance = createTestSubgraphNode(subgraph)
+        rootGraph.add(instance)
+        instances.push(instance)
+      }
+
+      expect(rootGraph.nodes.length).toBe(10)
+
+      // Remove instances
+      for (const instance of instances) {
+        rootGraph.remove(instance)
+      }
+
+      expect(rootGraph.nodes.length).toBe(0)
+    }
+  })
+})

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

@@ -0,0 +1,578 @@
+/**
+ * SubgraphNode Tests
+ *
+ * Tests for SubgraphNode instances including construction,
+ * IO synchronization, and edge cases.
+ */
+
+import { describe, expect, it, vi } from "vitest"
+
+import { LGraph, Subgraph } from "@/litegraph"
+
+import { subgraphTest } from "./fixtures/subgraphFixtures"
+import {
+  createTestSubgraph,
+  createTestSubgraphNode,
+} from "./fixtures/subgraphHelpers"
+
+describe("SubgraphNode Construction", () => {
+  it("should create a SubgraphNode from a subgraph definition", () => {
+    const subgraph = createTestSubgraph({
+      name: "Test Definition",
+      inputs: [{ name: "input", type: "number" }],
+      outputs: [{ name: "output", type: "number" }],
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode).toBeDefined()
+    expect(subgraphNode.subgraph).toBe(subgraph)
+    expect(subgraphNode.type).toBe(subgraph.id)
+    expect(subgraphNode.isVirtualNode).toBe(true)
+    expect(subgraphNode.displayType).toBe("Subgraph node")
+  })
+
+  it("should configure from instance data", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "value", type: "number" }],
+      outputs: [{ name: "result", type: "number" }],
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph, {
+      id: 42,
+      pos: [300, 150],
+      size: [180, 80],
+    })
+
+    expect(subgraphNode.id).toBe(42)
+    expect(Array.from(subgraphNode.pos)).toEqual([300, 150])
+    expect(Array.from(subgraphNode.size)).toEqual([180, 80])
+  })
+
+  it("should maintain reference to root graph", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const parentGraph = subgraphNode.graph
+
+    expect(subgraphNode.rootGraph).toBe(parentGraph.rootGraph)
+  })
+
+  subgraphTest("should synchronize slots with subgraph definition", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode } = subgraphWithNode
+
+    // SubgraphNode should have same number of inputs/outputs as definition
+    expect(subgraphNode.inputs).toHaveLength(subgraph.inputs.length)
+    expect(subgraphNode.outputs).toHaveLength(subgraph.outputs.length)
+  })
+
+  subgraphTest("should update slots when subgraph definition changes", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode } = subgraphWithNode
+
+    const initialInputCount = subgraphNode.inputs.length
+
+    // Add an input to the subgraph definition
+    subgraph.addInput("new_input", "string")
+
+    // SubgraphNode should automatically update (this tests the event system)
+    expect(subgraphNode.inputs).toHaveLength(initialInputCount + 1)
+    expect(subgraphNode.inputs.at(-1)?.name).toBe("new_input")
+    expect(subgraphNode.inputs.at(-1)?.type).toBe("string")
+  })
+})
+
+describe("SubgraphNode Synchronization", () => {
+  it("should sync input addition", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.inputs).toHaveLength(0)
+
+    subgraph.addInput("value", "number")
+
+    expect(subgraphNode.inputs).toHaveLength(1)
+    expect(subgraphNode.inputs[0].name).toBe("value")
+    expect(subgraphNode.inputs[0].type).toBe("number")
+  })
+
+  it("should sync output addition", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.outputs).toHaveLength(0)
+
+    subgraph.addOutput("result", "string")
+
+    expect(subgraphNode.outputs).toHaveLength(1)
+    expect(subgraphNode.outputs[0].name).toBe("result")
+    expect(subgraphNode.outputs[0].type).toBe("string")
+  })
+
+  it("should sync input removal", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [
+        { name: "input1", type: "number" },
+        { name: "input2", type: "string" },
+      ],
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.inputs).toHaveLength(2)
+
+    subgraph.removeInput(subgraph.inputs[0])
+
+    expect(subgraphNode.inputs).toHaveLength(1)
+    expect(subgraphNode.inputs[0].name).toBe("input2")
+  })
+
+  it("should sync output removal", () => {
+    const subgraph = createTestSubgraph({
+      outputs: [
+        { name: "output1", type: "number" },
+        { name: "output2", type: "string" },
+      ],
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.outputs).toHaveLength(2)
+
+    subgraph.removeOutput(subgraph.outputs[0])
+
+    expect(subgraphNode.outputs).toHaveLength(1)
+    expect(subgraphNode.outputs[0].name).toBe("output2")
+  })
+
+  it("should sync slot renaming", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "oldName", type: "number" }],
+      outputs: [{ name: "oldOutput", type: "string" }],
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Rename input
+    subgraph.inputs[0].label = "newName"
+    subgraph.events.dispatch("renaming-input", {
+      input: subgraph.inputs[0],
+      index: 0,
+      oldName: "oldName",
+      newName: "newName",
+    })
+
+    expect(subgraphNode.inputs[0].label).toBe("newName")
+
+    // Rename output
+    subgraph.outputs[0].label = "newOutput"
+    subgraph.events.dispatch("renaming-output", {
+      output: subgraph.outputs[0],
+      index: 0,
+      oldName: "oldOutput",
+      newName: "newOutput",
+    })
+
+    expect(subgraphNode.outputs[0].label).toBe("newOutput")
+  })
+})
+
+describe("SubgraphNode Lifecycle", () => {
+  it("should initialize with empty widgets array", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.widgets).toBeDefined()
+    expect(subgraphNode.widgets).toHaveLength(0)
+  })
+
+  it("should handle reconfiguration", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "input1", type: "number" }],
+      outputs: [{ name: "output1", type: "string" }],
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Initial state
+    expect(subgraphNode.inputs).toHaveLength(1)
+    expect(subgraphNode.outputs).toHaveLength(1)
+
+    // Add more slots to subgraph
+    subgraph.addInput("input2", "string")
+    subgraph.addOutput("output2", "number")
+
+    // Reconfigure
+    subgraphNode.configure({
+      id: subgraphNode.id,
+      type: subgraph.id,
+      pos: [200, 200],
+      size: [180, 100],
+      inputs: [],
+      outputs: [],
+      properties: {},
+      flags: {},
+      mode: 0,
+    })
+
+    // Should reflect updated subgraph structure
+    expect(subgraphNode.inputs).toHaveLength(2)
+    expect(subgraphNode.outputs).toHaveLength(2)
+  })
+
+  it("should handle removal lifecycle", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const parentGraph = new LGraph()
+
+    parentGraph.add(subgraphNode)
+    expect(parentGraph.nodes).toContain(subgraphNode)
+
+    // Test onRemoved method
+    subgraphNode.onRemoved()
+
+    // Note: onRemoved doesn't automatically remove from graph
+    // but it should clean up internal state
+    expect(subgraphNode.inputs).toBeDefined()
+  })
+})
+
+describe("SubgraphNode Basic Functionality", () => {
+  it("should identify as subgraph node", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.isSubgraphNode()).toBe(true)
+    expect(subgraphNode.isVirtualNode).toBe(true)
+  })
+
+  it("should inherit input types correctly", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [
+        { name: "numberInput", type: "number" },
+        { name: "stringInput", type: "string" },
+        { name: "anyInput", type: "*" },
+      ],
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.inputs[0].type).toBe("number")
+    expect(subgraphNode.inputs[1].type).toBe("string")
+    expect(subgraphNode.inputs[2].type).toBe("*")
+  })
+
+  it("should inherit output types correctly", () => {
+    const subgraph = createTestSubgraph({
+      outputs: [
+        { name: "numberOutput", type: "number" },
+        { name: "stringOutput", type: "string" },
+        { name: "anyOutput", type: "*" },
+      ],
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    expect(subgraphNode.outputs[0].type).toBe("number")
+    expect(subgraphNode.outputs[1].type).toBe("string")
+    expect(subgraphNode.outputs[2].type).toBe("*")
+  })
+})
+
+describe("SubgraphNode Execution", () => {
+  it("should flatten to ExecutableNodeDTOs", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 3 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    const executableNodes = new Map()
+    const flattened = subgraphNode.getInnerNodes(executableNodes)
+
+    expect(flattened).toHaveLength(3)
+    expect(flattened[0].id).toMatch(/^1:\d+$/) // Should have path-based ID like "1:1"
+    expect(flattened[1].id).toMatch(/^1:\d+$/)
+    expect(flattened[2].id).toMatch(/^1:\d+$/)
+  })
+
+  it.skip("should handle nested subgraph execution", () => {
+    // FIXME: Complex nested structure requires proper parent graph setup
+    // Skip for now - similar issue to ExecutableNodeDTO nested test
+    // Will implement proper nested execution test in edge cases file
+    const childSubgraph = createTestSubgraph({
+      name: "Child",
+      nodeCount: 1,
+    })
+
+    const parentSubgraph = createTestSubgraph({
+      name: "Parent",
+      nodeCount: 1,
+    })
+
+    const childSubgraphNode = createTestSubgraphNode(childSubgraph, { id: 42 })
+    parentSubgraph.add(childSubgraphNode)
+
+    const parentSubgraphNode = createTestSubgraphNode(parentSubgraph, { id: 10 })
+
+    const executableNodes = new Map()
+    const flattened = parentSubgraphNode.getInnerNodes(executableNodes)
+
+    expect(flattened.length).toBeGreaterThan(0)
+  })
+
+  it("should resolve cross-boundary input links", () => {
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "input1", type: "number" }],
+      nodeCount: 1,
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    const resolved = subgraphNode.resolveSubgraphInputLinks(0)
+
+    expect(resolved).toBeDefined()
+    expect(Array.isArray(resolved)).toBe(true)
+  })
+
+  it("should resolve cross-boundary output links", () => {
+    const subgraph = createTestSubgraph({
+      outputs: [{ name: "output1", type: "number" }],
+      nodeCount: 1,
+    })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    const resolved = subgraphNode.resolveSubgraphOutputLink(0)
+
+    // May be undefined if no internal connection exists
+    expect(resolved === undefined || typeof resolved === "object").toBe(true)
+  })
+
+  it("should prevent infinite recursion", () => {
+    // Cycle detection properly prevents infinite recursion when a subgraph contains itself
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Add subgraph node to its own subgraph (circular reference)
+    subgraph.add(subgraphNode)
+
+    const executableNodes = new Map()
+    expect(() => {
+      subgraphNode.getInnerNodes(executableNodes)
+    }).toThrow(/Circular reference detected.*infinite loop in the subgraph hierarchy/i)
+  })
+
+  it("should handle nested subgraph execution", () => {
+    // This test verifies that subgraph nodes can be properly executed
+    // when they contain other nodes and produce correct output
+    const subgraph = createTestSubgraph({
+      name: "Nested Execution Test",
+      nodeCount: 3,
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Verify that we can get executable DTOs for all nested nodes
+    const executableNodes = new Map()
+    const flattened = subgraphNode.getInnerNodes(executableNodes)
+
+    expect(flattened).toHaveLength(3)
+
+    // Each DTO should have proper execution context
+    for (const dto of flattened) {
+      expect(dto).toHaveProperty("id")
+      expect(dto).toHaveProperty("graph")
+      expect(dto).toHaveProperty("inputs")
+      expect(dto.id).toMatch(/^\d+:\d+$/) // Path-based ID format
+    }
+  })
+
+  it("should resolve cross-boundary links", () => {
+    // This test verifies that links can cross subgraph boundaries
+    // Currently this is a basic test - full cross-boundary linking
+    // requires more complex setup with actual connected nodes
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "external_input", type: "number" }],
+      outputs: [{ name: "external_output", type: "number" }],
+      nodeCount: 2,
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Verify the subgraph node has the expected I/O structure for cross-boundary links
+    expect(subgraphNode.inputs).toHaveLength(1)
+    expect(subgraphNode.outputs).toHaveLength(1)
+    expect(subgraphNode.inputs[0].name).toBe("external_input")
+    expect(subgraphNode.outputs[0].name).toBe("external_output")
+
+    // Internal nodes should be flattened correctly
+    const executableNodes = new Map()
+    const flattened = subgraphNode.getInnerNodes(executableNodes)
+    expect(flattened).toHaveLength(2)
+  })
+})
+
+describe("SubgraphNode Edge Cases", () => {
+  it("should handle deep nesting", () => {
+    // Create a simpler deep nesting test that works with current implementation
+    const subgraph = createTestSubgraph({
+      name: "Deep Test",
+      nodeCount: 5, // Multiple nodes to test flattening at depth
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+
+    // Should be able to flatten without errors even with multiple nodes
+    const executableNodes = new Map()
+    expect(() => {
+      subgraphNode.getInnerNodes(executableNodes)
+    }).not.toThrow()
+
+    const flattened = subgraphNode.getInnerNodes(executableNodes)
+    expect(flattened.length).toBe(5)
+
+    // All flattened nodes should have proper path-based IDs
+    for (const dto of flattened) {
+      expect(dto.id).toMatch(/^\d+:\d+$/)
+    }
+  })
+
+  it("should validate against MAX_NESTED_SUBGRAPHS", () => {
+    // Test that the MAX_NESTED_SUBGRAPHS constant exists
+    // Note: Currently not enforced in the implementation
+    expect(Subgraph.MAX_NESTED_SUBGRAPHS).toBe(1000)
+
+    // This test documents the current behavior - limit is not enforced
+    // TODO: Implement actual limit enforcement when business requirements clarify
+  })
+})
+
+describe("SubgraphNode Integration", () => {
+  it("should be addable to a parent graph", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const parentGraph = new LGraph()
+
+    parentGraph.add(subgraphNode)
+
+    expect(parentGraph.nodes).toContain(subgraphNode)
+    expect(subgraphNode.graph).toBe(parentGraph)
+  })
+
+  subgraphTest("should maintain reference to root graph", ({ subgraphWithNode }) => {
+    const { subgraphNode } = subgraphWithNode
+
+    // For this test, parentGraph should be the root, but in nested scenarios
+    // it would traverse up to find the actual root
+    expect(subgraphNode.rootGraph).toBeDefined()
+  })
+
+  it("should handle graph removal properly", () => {
+    const subgraph = createTestSubgraph()
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    const parentGraph = new LGraph()
+
+    parentGraph.add(subgraphNode)
+    expect(parentGraph.nodes).toContain(subgraphNode)
+
+    parentGraph.remove(subgraphNode)
+    expect(parentGraph.nodes).not.toContain(subgraphNode)
+  })
+})
+
+describe("Foundation Test Utilities", () => {
+  it("should create test SubgraphNodes with custom options", () => {
+    const subgraph = createTestSubgraph()
+    const customPos: [number, number] = [500, 300]
+    const customSize: [number, number] = [250, 120]
+
+    const subgraphNode = createTestSubgraphNode(subgraph, {
+      pos: customPos,
+      size: customSize,
+    })
+
+    expect(Array.from(subgraphNode.pos)).toEqual(customPos)
+    expect(Array.from(subgraphNode.size)).toEqual(customSize)
+  })
+
+  subgraphTest("fixtures should provide properly configured SubgraphNode", ({ subgraphWithNode }) => {
+    const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+
+    expect(subgraph).toBeDefined()
+    expect(subgraphNode).toBeDefined()
+    expect(parentGraph).toBeDefined()
+    expect(parentGraph.nodes).toContain(subgraphNode)
+  })
+})
+
+describe("SubgraphNode Cleanup", () => {
+  it("should clean up event listeners when removed", () => {
+    const rootGraph = new LGraph()
+    const subgraph = createTestSubgraph()
+
+    // Create and add two nodes
+    const node1 = createTestSubgraphNode(subgraph)
+    const node2 = createTestSubgraphNode(subgraph)
+    rootGraph.add(node1)
+    rootGraph.add(node2)
+
+    // Verify both nodes start with no inputs
+    expect(node1.inputs.length).toBe(0)
+    expect(node2.inputs.length).toBe(0)
+
+    // Remove node2
+    rootGraph.remove(node2)
+
+    // Now trigger an event - only node1 should respond
+    subgraph.events.dispatch("input-added", {
+      input: { name: "test", type: "number", id: "test-id" } as any,
+    })
+
+    // Only node1 should have added an input
+    expect(node1.inputs.length).toBe(1) // node1 responds
+    expect(node2.inputs.length).toBe(0) // node2 should NOT respond (but currently does)
+  })
+
+  it("should not accumulate handlers over multiple add/remove cycles", () => {
+    const rootGraph = new LGraph()
+    const subgraph = createTestSubgraph()
+
+    // Add and remove nodes multiple times
+    const removedNodes: SubgraphNode[] = []
+    for (let i = 0; i < 3; i++) {
+      const node = createTestSubgraphNode(subgraph)
+      rootGraph.add(node)
+      rootGraph.remove(node)
+      removedNodes.push(node)
+    }
+
+    // All nodes should have 0 inputs
+    for (const node of removedNodes) {
+      expect(node.inputs.length).toBe(0)
+    }
+
+    // Trigger an event - no nodes should respond
+    subgraph.events.dispatch("input-added", {
+      input: { name: "test", type: "number", id: "test-id" } as any,
+    })
+
+    // Without cleanup: all 3 removed nodes would have added an input
+    // With cleanup: no nodes should have added an input
+    for (const node of removedNodes) {
+      expect(node.inputs.length).toBe(0) // Should stay 0 after cleanup
+    }
+  })
+
+  it("should clean up input listener controllers on removal", () => {
+    const rootGraph = new LGraph()
+    const subgraph = createTestSubgraph({
+      inputs: [{ name: "in1", type: "number" }, { name: "in2", type: "string" }],
+    })
+
+    const subgraphNode = createTestSubgraphNode(subgraph)
+    rootGraph.add(subgraphNode)
+
+    // Verify listener controllers exist
+    expect(subgraphNode.inputs[0]._listenerController).toBeDefined()
+    expect(subgraphNode.inputs[1]._listenerController).toBeDefined()
+
+    // Track abort calls
+    const abortSpy1 = vi.spyOn(subgraphNode.inputs[0]._listenerController!, "abort")
+    const abortSpy2 = vi.spyOn(subgraphNode.inputs[1]._listenerController!, "abort")
+
+    // Remove node
+    rootGraph.remove(subgraphNode)
+
+    // Verify abort was called on each controller
+    expect(abortSpy1).toHaveBeenCalledTimes(1)
+    expect(abortSpy2).toHaveBeenCalledTimes(1)
+  })
+})

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

@@ -0,0 +1,231 @@
+import { describe, expect, it, vi } from "vitest"
+
+import { LGraphButton } from "@/LGraphButton"
+import { LGraphCanvas } from "@/LGraphCanvas"
+
+import { createTestSubgraph, createTestSubgraphNode } from "./fixtures/subgraphHelpers"
+
+describe("SubgraphNode Title Button", () => {
+  describe("Constructor", () => {
+    it("should automatically add enter_subgraph button", () => {
+      const subgraph = createTestSubgraph({
+        name: "Test Subgraph",
+        inputs: [{ name: "input", type: "number" }],
+      })
+
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      expect(subgraphNode.title_buttons).toHaveLength(1)
+
+      const button = subgraphNode.title_buttons[0]
+      expect(button).toBeInstanceOf(LGraphButton)
+      expect(button.name).toBe("enter_subgraph")
+      expect(button.text).toBe("\uE93B") // pi-window-maximize
+      expect(button.xOffset).toBe(-10)
+      expect(button.yOffset).toBe(0)
+      expect(button.fontSize).toBe(16)
+    })
+
+    it("should preserve enter_subgraph button when adding more buttons", () => {
+      const subgraph = createTestSubgraph()
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // Add another button
+      const customButton = subgraphNode.addTitleButton({
+        name: "custom_button",
+        text: "C",
+      })
+
+      expect(subgraphNode.title_buttons).toHaveLength(2)
+      expect(subgraphNode.title_buttons[0].name).toBe("enter_subgraph")
+      expect(subgraphNode.title_buttons[1]).toBe(customButton)
+    })
+  })
+
+  describe("onTitleButtonClick", () => {
+    it("should open subgraph when enter_subgraph button is clicked", () => {
+      const subgraph = createTestSubgraph({
+        name: "Test Subgraph",
+      })
+
+      const subgraphNode = createTestSubgraphNode(subgraph)
+      const enterButton = subgraphNode.title_buttons[0]
+
+      const canvas = {
+        openSubgraph: vi.fn(),
+        dispatch: vi.fn(),
+      } as unknown as LGraphCanvas
+
+      subgraphNode.onTitleButtonClick(enterButton, canvas)
+
+      expect(canvas.openSubgraph).toHaveBeenCalledWith(subgraph)
+      expect(canvas.dispatch).not.toHaveBeenCalled() // Should not call parent implementation
+    })
+
+    it("should call parent implementation for other buttons", () => {
+      const subgraph = createTestSubgraph()
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      const customButton = subgraphNode.addTitleButton({
+        name: "custom_button",
+        text: "X",
+      })
+
+      const canvas = {
+        openSubgraph: vi.fn(),
+        dispatch: vi.fn(),
+      } as unknown as LGraphCanvas
+
+      subgraphNode.onTitleButtonClick(customButton, canvas)
+
+      expect(canvas.openSubgraph).not.toHaveBeenCalled()
+      expect(canvas.dispatch).toHaveBeenCalledWith("litegraph:node-title-button-clicked", {
+        node: subgraphNode,
+        button: customButton,
+      })
+    })
+  })
+
+  describe("Integration with node click handling", () => {
+    it("should handle clicks on enter_subgraph button", () => {
+      const subgraph = createTestSubgraph({
+        name: "Nested Subgraph",
+        nodeCount: 3,
+      })
+
+      const subgraphNode = createTestSubgraphNode(subgraph)
+      subgraphNode.pos = [100, 100]
+      subgraphNode.size = [200, 100]
+
+      const enterButton = subgraphNode.title_buttons[0]
+      enterButton.getWidth = vi.fn().mockReturnValue(25)
+      enterButton.height = 20
+
+      // Simulate button being drawn at node-relative coordinates
+      // Button x: 200 - 5 - 25 = 170
+      // Button y: -30 (title height)
+      enterButton._last_area[0] = 170
+      enterButton._last_area[1] = -30
+      enterButton._last_area[2] = 25
+      enterButton._last_area[3] = 20
+
+      const canvas = {
+        ctx: {
+          measureText: vi.fn().mockReturnValue({ width: 25 }),
+        } as unknown as CanvasRenderingContext2D,
+        openSubgraph: vi.fn(),
+        dispatch: vi.fn(),
+      } as unknown as LGraphCanvas
+
+      // Simulate click on the enter button
+      const event = {
+        canvasX: 275, // Near right edge where button should be
+        canvasY: 80, // In title area
+      } as any
+
+      // Calculate node-relative position
+      const clickPosRelativeToNode: [number, number] = [
+        275 - subgraphNode.pos[0], // 275 - 100 = 175
+        80 - subgraphNode.pos[1], // 80 - 100 = -20
+      ]
+
+      const handled = subgraphNode.onMouseDown(event, clickPosRelativeToNode, canvas)
+
+      expect(handled).toBe(true)
+      expect(canvas.openSubgraph).toHaveBeenCalledWith(subgraph)
+    })
+
+    it("should not interfere with normal node operations", () => {
+      const subgraph = createTestSubgraph()
+      const subgraphNode = createTestSubgraphNode(subgraph)
+      subgraphNode.pos = [100, 100]
+      subgraphNode.size = [200, 100]
+
+      const canvas = {
+        ctx: {
+          measureText: vi.fn().mockReturnValue({ width: 25 }),
+        } as unknown as CanvasRenderingContext2D,
+        openSubgraph: vi.fn(),
+        dispatch: vi.fn(),
+      } as unknown as LGraphCanvas
+
+      // Click in the body of the node, not on button
+      const event = {
+        canvasX: 200, // Middle of node
+        canvasY: 150, // Body area
+      } as any
+
+      // Calculate node-relative position
+      const clickPosRelativeToNode: [number, number] = [
+        200 - subgraphNode.pos[0], // 200 - 100 = 100
+        150 - subgraphNode.pos[1], // 150 - 100 = 50
+      ]
+
+      const handled = subgraphNode.onMouseDown(event, clickPosRelativeToNode, canvas)
+
+      expect(handled).toBe(false)
+      expect(canvas.openSubgraph).not.toHaveBeenCalled()
+    })
+
+    it("should not process button clicks when node is collapsed", () => {
+      const subgraph = createTestSubgraph()
+      const subgraphNode = createTestSubgraphNode(subgraph)
+      subgraphNode.pos = [100, 100]
+      subgraphNode.size = [200, 100]
+      subgraphNode.flags.collapsed = true
+
+      const enterButton = subgraphNode.title_buttons[0]
+      enterButton.getWidth = vi.fn().mockReturnValue(25)
+      enterButton.height = 20
+
+      // Set button area as if it was drawn
+      enterButton._last_area[0] = 170
+      enterButton._last_area[1] = -30
+      enterButton._last_area[2] = 25
+      enterButton._last_area[3] = 20
+
+      const canvas = {
+        ctx: {
+          measureText: vi.fn().mockReturnValue({ width: 25 }),
+        } as unknown as CanvasRenderingContext2D,
+        openSubgraph: vi.fn(),
+        dispatch: vi.fn(),
+      } as unknown as LGraphCanvas
+
+      // Try to click on where the button would be
+      const event = {
+        canvasX: 275,
+        canvasY: 80,
+      } as any
+
+      const clickPosRelativeToNode: [number, number] = [
+        275 - subgraphNode.pos[0], // 175
+        80 - subgraphNode.pos[1], // -20
+      ]
+
+      const handled = subgraphNode.onMouseDown(event, clickPosRelativeToNode, canvas)
+
+      // Should not handle the click when collapsed
+      expect(handled).toBe(false)
+      expect(canvas.openSubgraph).not.toHaveBeenCalled()
+    })
+  })
+
+  describe("Visual properties", () => {
+    it("should have appropriate visual properties for enter button", () => {
+      const subgraph = createTestSubgraph()
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      const enterButton = subgraphNode.title_buttons[0]
+
+      // Check visual properties
+      expect(enterButton.text).toBe("\uE93B") // pi-window-maximize
+      expect(enterButton.fontSize).toBe(16) // Icon size
+      expect(enterButton.xOffset).toBe(-10) // Positioned from right edge
+      expect(enterButton.yOffset).toBe(0) // Centered vertically
+
+      // Should be visible by default
+      expect(enterButton.visible).toBe(true)
+    })
+  })
+})

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

@@ -0,0 +1,432 @@
+/**
+ * SubgraphSerialization Tests
+ *
+ * Tests for saving, loading, and version compatibility of subgraphs.
+ * This covers serialization, deserialization, data integrity, and migration scenarios.
+ */
+
+import { describe, expect, it } from "vitest"
+
+import { LGraph, Subgraph } from "@/litegraph"
+
+import {
+  createTestSubgraph,
+  createTestSubgraphNode,
+} from "./fixtures/subgraphHelpers"
+
+describe("SubgraphSerialization - Basic Serialization", () => {
+  it("should save and load simple subgraphs", () => {
+    const original = createTestSubgraph({
+      name: "Simple Test",
+      nodeCount: 2,
+    })
+    original.addInput("in1", "number")
+    original.addInput("in2", "string")
+    original.addOutput("out", "boolean")
+
+    // Serialize
+    const exported = original.asSerialisable()
+
+    // Verify exported structure
+    expect(exported).toHaveProperty("id", original.id)
+    expect(exported).toHaveProperty("name", "Simple Test")
+    expect(exported).toHaveProperty("nodes")
+    expect(exported).toHaveProperty("links")
+    expect(exported).toHaveProperty("inputs")
+    expect(exported).toHaveProperty("outputs")
+    expect(exported).toHaveProperty("version")
+
+    // Create new instance from serialized data
+    const restored = new Subgraph(new LGraph(), exported)
+
+    // Verify structure is preserved
+    expect(restored.id).toBe(original.id)
+    expect(restored.name).toBe(original.name)
+    expect(restored.inputs.length).toBe(2) // Only added inputs, not original nodeCount
+    expect(restored.outputs.length).toBe(1)
+    // Note: nodes may not be restored if they're not registered types
+    // This is expected behavior - serialization preserves I/O but nodes need valid types
+
+    // Verify input details
+    expect(restored.inputs[0].name).toBe("in1")
+    expect(restored.inputs[0].type).toBe("number")
+    expect(restored.inputs[1].name).toBe("in2")
+    expect(restored.inputs[1].type).toBe("string")
+    expect(restored.outputs[0].name).toBe("out")
+    expect(restored.outputs[0].type).toBe("boolean")
+  })
+
+  it("should verify all properties are preserved", () => {
+    const original = createTestSubgraph({
+      name: "Property Test",
+      nodeCount: 3,
+      inputs: [
+        { name: "input1", type: "number" },
+        { name: "input2", type: "string" },
+      ],
+      outputs: [
+        { name: "output1", type: "boolean" },
+        { name: "output2", type: "array" },
+      ],
+    })
+
+    const exported = original.asSerialisable()
+    const restored = new Subgraph(new LGraph(), exported)
+
+    // Verify core properties
+    expect(restored.id).toBe(original.id)
+    expect(restored.name).toBe(original.name)
+    expect(restored.description).toBe(original.description)
+
+    // Verify I/O structure
+    expect(restored.inputs.length).toBe(original.inputs.length)
+    expect(restored.outputs.length).toBe(original.outputs.length)
+    // Nodes may not be restored if they don't have registered types
+
+    // Verify I/O details match
+    for (let i = 0; i < original.inputs.length; i++) {
+      expect(restored.inputs[i].name).toBe(original.inputs[i].name)
+      expect(restored.inputs[i].type).toBe(original.inputs[i].type)
+    }
+
+    for (let i = 0; i < original.outputs.length; i++) {
+      expect(restored.outputs[i].name).toBe(original.outputs[i].name)
+      expect(restored.outputs[i].type).toBe(original.outputs[i].type)
+    }
+  })
+
+  it("should test export() and configure() methods", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+    subgraph.addInput("test_input", "number")
+    subgraph.addOutput("test_output", "string")
+
+    // Test export
+    const exported = subgraph.asSerialisable()
+    expect(exported).toHaveProperty("id")
+    expect(exported).toHaveProperty("nodes")
+    expect(exported).toHaveProperty("links")
+    expect(exported).toHaveProperty("inputs")
+    expect(exported).toHaveProperty("outputs")
+
+    // Test configure with partial data
+    const newSubgraph = createTestSubgraph({ nodeCount: 0 })
+    expect(() => {
+      newSubgraph.configure(exported)
+    }).not.toThrow()
+
+    // Verify configuration applied
+    expect(newSubgraph.inputs.length).toBe(1)
+    expect(newSubgraph.outputs.length).toBe(1)
+    expect(newSubgraph.inputs[0].name).toBe("test_input")
+    expect(newSubgraph.outputs[0].name).toBe("test_output")
+  })
+})
+
+describe("SubgraphSerialization - Complex Serialization", () => {
+  it("should serialize nested subgraphs with multiple levels", () => {
+    // Create a nested structure
+    const childSubgraph = createTestSubgraph({
+      name: "Child",
+      nodeCount: 2,
+      inputs: [{ name: "child_in", type: "number" }],
+      outputs: [{ name: "child_out", type: "string" }],
+    })
+
+    const parentSubgraph = createTestSubgraph({
+      name: "Parent",
+      nodeCount: 1,
+      inputs: [{ name: "parent_in", type: "boolean" }],
+      outputs: [{ name: "parent_out", type: "array" }],
+    })
+
+    // Add child to parent
+    const childInstance = createTestSubgraphNode(childSubgraph, { id: 100 })
+    parentSubgraph.add(childInstance)
+
+    // Serialize both
+    const childExported = childSubgraph.asSerialisable()
+    const parentExported = parentSubgraph.asSerialisable()
+
+    // Verify both can be serialized
+    expect(childExported).toHaveProperty("name", "Child")
+    expect(parentExported).toHaveProperty("name", "Parent")
+    expect(parentExported.nodes.length).toBe(2) // 1 original + 1 child subgraph
+
+    // Restore and verify
+    const restoredChild = new Subgraph(new LGraph(), childExported)
+    const restoredParent = new Subgraph(new LGraph(), parentExported)
+
+    expect(restoredChild.name).toBe("Child")
+    expect(restoredParent.name).toBe("Parent")
+    expect(restoredChild.inputs.length).toBe(1)
+    expect(restoredParent.inputs.length).toBe(1)
+  })
+
+  it("should serialize subgraphs with many nodes and connections", () => {
+    const largeSubgraph = createTestSubgraph({
+      name: "Large Subgraph",
+      nodeCount: 10, // Many nodes
+    })
+
+    // Add many I/O slots
+    for (let i = 0; i < 5; i++) {
+      largeSubgraph.addInput(`input_${i}`, "number")
+      largeSubgraph.addOutput(`output_${i}`, "string")
+    }
+
+    const exported = largeSubgraph.asSerialisable()
+    const restored = new Subgraph(new LGraph(), exported)
+
+    // Verify I/O data preserved
+    expect(restored.inputs.length).toBe(5)
+    expect(restored.outputs.length).toBe(5)
+    // Nodes may not be restored if they don't have registered types
+
+    // Verify I/O naming preserved
+    for (let i = 0; i < 5; i++) {
+      expect(restored.inputs[i].name).toBe(`input_${i}`)
+      expect(restored.outputs[i].name).toBe(`output_${i}`)
+    }
+  })
+
+  it("should preserve custom node data", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 2 })
+
+    // Add custom properties to nodes (if supported)
+    const nodes = subgraph.nodes
+    if (nodes.length > 0) {
+      const firstNode = nodes[0]
+      if (firstNode.properties) {
+        firstNode.properties.customValue = 42
+        firstNode.properties.customString = "test"
+      }
+    }
+
+    const exported = subgraph.asSerialisable()
+    const restored = new Subgraph(new LGraph(), exported)
+
+    // Test nodes may not be restored if they don't have registered types
+    // This is expected behavior
+
+    // Custom properties preservation depends on node implementation
+    // This test documents the expected behavior
+    if (restored.nodes.length > 0 && restored.nodes[0].properties) {
+      // Properties should be preserved if the node supports them
+      expect(restored.nodes[0].properties).toBeDefined()
+    }
+  })
+})
+
+describe("SubgraphSerialization - Version Compatibility", () => {
+  it("should handle version field in exports", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 1 })
+    const exported = subgraph.asSerialisable()
+
+    // Should have version field
+    expect(exported).toHaveProperty("version")
+    expect(typeof exported.version).toBe("number")
+  })
+
+  it("should load version 1.0+ format", () => {
+    const modernFormat = {
+      version: 1, // Number as expected by current implementation
+      id: "test-modern-id",
+      name: "Modern Subgraph",
+      nodes: [],
+      links: {},
+      groups: [],
+      config: {},
+      definitions: { subgraphs: [] },
+      inputs: [{ id: "input-id", name: "modern_input", type: "number" }],
+      outputs: [{ id: "output-id", name: "modern_output", type: "string" }],
+      inputNode: {
+        id: -10,
+        bounding: [0, 0, 120, 60],
+      },
+      outputNode: {
+        id: -20,
+        bounding: [300, 0, 120, 60],
+      },
+      widgets: [],
+    }
+
+    expect(() => {
+      const subgraph = new Subgraph(new LGraph(), modernFormat)
+      expect(subgraph.name).toBe("Modern Subgraph")
+      expect(subgraph.inputs.length).toBe(1)
+      expect(subgraph.outputs.length).toBe(1)
+    }).not.toThrow()
+  })
+
+  it("should handle missing fields gracefully", () => {
+    const incompleteFormat = {
+      version: 1,
+      id: "incomplete-id",
+      name: "Incomplete Subgraph",
+      nodes: [],
+      links: {},
+      groups: [],
+      config: {},
+      definitions: { subgraphs: [] },
+      inputNode: {
+        id: -10,
+        bounding: [0, 0, 120, 60],
+      },
+      outputNode: {
+        id: -20,
+        bounding: [300, 0, 120, 60],
+      },
+      // Missing optional: inputs, outputs, widgets
+    }
+
+    expect(() => {
+      const subgraph = new Subgraph(new LGraph(), incompleteFormat)
+      expect(subgraph.name).toBe("Incomplete Subgraph")
+      // Should have default empty arrays
+      expect(Array.isArray(subgraph.inputs)).toBe(true)
+      expect(Array.isArray(subgraph.outputs)).toBe(true)
+    }).not.toThrow()
+  })
+
+  it("should consider future-proofing", () => {
+    const futureFormat = {
+      version: 2, // Future version (number)
+      id: "future-id",
+      name: "Future Subgraph",
+      nodes: [],
+      links: {},
+      groups: [],
+      config: {},
+      definitions: { subgraphs: [] },
+      inputs: [],
+      outputs: [],
+      inputNode: {
+        id: -10,
+        bounding: [0, 0, 120, 60],
+      },
+      outputNode: {
+        id: -20,
+        bounding: [300, 0, 120, 60],
+      },
+      widgets: [],
+      futureFeature: "unknown_data", // Unknown future field
+    }
+
+    // Should handle future format gracefully
+    expect(() => {
+      const subgraph = new Subgraph(new LGraph(), futureFormat)
+      expect(subgraph.name).toBe("Future Subgraph")
+    }).not.toThrow()
+  })
+})
+
+describe("SubgraphSerialization - Data Integrity", () => {
+  it("should pass round-trip testing (save → load → save → compare)", () => {
+    const original = createTestSubgraph({
+      name: "Round Trip Test",
+      nodeCount: 3,
+      inputs: [
+        { name: "rt_input1", type: "number" },
+        { name: "rt_input2", type: "string" },
+      ],
+      outputs: [{ name: "rt_output1", type: "boolean" }],
+    })
+
+    // First round trip
+    const exported1 = original.asSerialisable()
+    const restored1 = new Subgraph(new LGraph(), exported1)
+
+    // Second round trip
+    const exported2 = restored1.asSerialisable()
+    const restored2 = new Subgraph(new LGraph(), exported2)
+
+    // Compare key properties
+    expect(restored2.id).toBe(original.id)
+    expect(restored2.name).toBe(original.name)
+    expect(restored2.inputs.length).toBe(original.inputs.length)
+    expect(restored2.outputs.length).toBe(original.outputs.length)
+    // Nodes may not be restored if they don't have registered types
+
+    // Compare I/O details
+    for (let i = 0; i < original.inputs.length; i++) {
+      expect(restored2.inputs[i].name).toBe(original.inputs[i].name)
+      expect(restored2.inputs[i].type).toBe(original.inputs[i].type)
+    }
+
+    for (let i = 0; i < original.outputs.length; i++) {
+      expect(restored2.outputs[i].name).toBe(original.outputs[i].name)
+      expect(restored2.outputs[i].type).toBe(original.outputs[i].type)
+    }
+  })
+
+  it("should verify IDs remain unique", () => {
+    const subgraph1 = createTestSubgraph({ name: "Unique1", nodeCount: 2 })
+    const subgraph2 = createTestSubgraph({ name: "Unique2", nodeCount: 2 })
+
+    const exported1 = subgraph1.asSerialisable()
+    const exported2 = subgraph2.asSerialisable()
+
+    // IDs should be unique
+    expect(exported1.id).not.toBe(exported2.id)
+
+    const restored1 = new Subgraph(new LGraph(), exported1)
+    const restored2 = new Subgraph(new LGraph(), exported2)
+
+    expect(restored1.id).not.toBe(restored2.id)
+    expect(restored1.id).toBe(subgraph1.id)
+    expect(restored2.id).toBe(subgraph2.id)
+  })
+
+  it("should maintain connection integrity after load", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 2 })
+    subgraph.addInput("connection_test", "number")
+    subgraph.addOutput("connection_result", "string")
+
+    const exported = subgraph.asSerialisable()
+    const restored = new Subgraph(new LGraph(), exported)
+
+    // Verify I/O connections can be established
+    expect(restored.inputs.length).toBe(1)
+    expect(restored.outputs.length).toBe(1)
+    expect(restored.inputs[0].name).toBe("connection_test")
+    expect(restored.outputs[0].name).toBe("connection_result")
+
+    // Verify subgraph can be instantiated
+    const instance = createTestSubgraphNode(restored)
+    expect(instance.inputs.length).toBe(1)
+    expect(instance.outputs.length).toBe(1)
+  })
+
+  it("should preserve node positions and properties", () => {
+    const subgraph = createTestSubgraph({ nodeCount: 2 })
+
+    // Modify node positions if possible
+    if (subgraph.nodes.length > 0) {
+      const node = subgraph.nodes[0]
+      if ("pos" in node) {
+        node.pos = [100, 200]
+      }
+      if ("size" in node) {
+        node.size = [150, 80]
+      }
+    }
+
+    const exported = subgraph.asSerialisable()
+    const restored = new Subgraph(new LGraph(), exported)
+
+    // Test nodes may not be restored if they don't have registered types
+    // This is expected behavior
+
+    // Position/size preservation depends on node implementation
+    // This test documents the expected behavior
+    if (restored.nodes.length > 0) {
+      const restoredNode = restored.nodes[0]
+      expect(restoredNode).toBeDefined()
+
+      // Properties should be preserved if supported
+      if ("pos" in restoredNode && restoredNode.pos) {
+        expect(Array.isArray(restoredNode.pos)).toBe(true)
+      }
+    }
+  })
+})

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

@@ -0,0 +1,332 @@
+import { describe, expect, it, vi } from "vitest"
+
+import { LinkConnector } from "@/canvas/LinkConnector"
+import { ToInputFromIoNodeLink } from "@/canvas/ToInputFromIoNodeLink"
+import { SUBGRAPH_INPUT_ID } from "@/constants"
+import { LGraphNode, type LinkNetwork } from "@/litegraph"
+import { NodeInputSlot } from "@/node/NodeInputSlot"
+import { NodeOutputSlot } from "@/node/NodeOutputSlot"
+import { isSubgraphInput, isSubgraphOutput } from "@/subgraph/subgraphUtils"
+
+import { createTestSubgraph, createTestSubgraphNode } from "./fixtures/subgraphHelpers"
+
+describe("Subgraph slot connections", () => {
+  describe("SubgraphInput connections", () => {
+    it("should connect to compatible regular input slots", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "test_input", type: "number" }],
+      })
+
+      const subgraphInput = subgraph.inputs[0]
+
+      const node = new LGraphNode("TestNode")
+      node.addInput("compatible_input", "number")
+      node.addInput("incompatible_input", "string")
+      subgraph.add(node)
+
+      const compatibleSlot = node.inputs[0] as NodeInputSlot
+      const incompatibleSlot = node.inputs[1] as NodeInputSlot
+
+      expect(compatibleSlot.isValidTarget(subgraphInput)).toBe(true)
+      expect(incompatibleSlot.isValidTarget(subgraphInput)).toBe(false)
+    })
+
+    // "not implemented" yet, but the test passes in terms of type checking
+    // it("should connect to compatible SubgraphOutput", () => {
+    //   const subgraph = createTestSubgraph({
+    //     inputs: [{ name: "test_input", type: "number" }],
+    //     outputs: [{ name: "test_output", type: "number" }],
+    //   })
+
+    //   const subgraphInput = subgraph.inputs[0]
+    //   const subgraphOutput = subgraph.outputs[0]
+
+    //   expect(subgraphOutput.isValidTarget(subgraphInput)).toBe(true)
+    // })
+
+    it("should not connect to another SubgraphInput", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [
+          { name: "input1", type: "number" },
+          { name: "input2", type: "number" },
+        ],
+      })
+
+      const subgraphInput1 = subgraph.inputs[0]
+      const subgraphInput2 = subgraph.inputs[1]
+
+      expect(subgraphInput2.isValidTarget(subgraphInput1)).toBe(false)
+    })
+
+    it("should not connect to output slots", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "test_input", type: "number" }],
+      })
+
+      const subgraphInput = subgraph.inputs[0]
+
+      const node = new LGraphNode("TestNode")
+      node.addOutput("test_output", "number")
+      subgraph.add(node)
+      const outputSlot = node.outputs[0] as NodeOutputSlot
+
+      expect(outputSlot.isValidTarget(subgraphInput)).toBe(false)
+    })
+  })
+
+  describe("SubgraphOutput connections", () => {
+    it("should connect from compatible regular output slots", () => {
+      const subgraph = createTestSubgraph()
+      const node = new LGraphNode("TestNode")
+      node.addOutput("out", "number")
+      subgraph.add(node)
+
+      const subgraphOutput = subgraph.addOutput("result", "number")
+      const nodeOutput = node.outputs[0]
+
+      expect(subgraphOutput.isValidTarget(nodeOutput)).toBe(true)
+    })
+
+    it("should connect from SubgraphInput", () => {
+      const subgraph = createTestSubgraph()
+
+      const subgraphInput = subgraph.addInput("value", "number")
+      const subgraphOutput = subgraph.addOutput("result", "number")
+
+      expect(subgraphOutput.isValidTarget(subgraphInput)).toBe(true)
+    })
+
+    it("should not connect to another SubgraphOutput", () => {
+      const subgraph = createTestSubgraph()
+
+      const subgraphOutput1 = subgraph.addOutput("result1", "number")
+      const subgraphOutput2 = subgraph.addOutput("result2", "number")
+
+      expect(subgraphOutput1.isValidTarget(subgraphOutput2)).toBe(false)
+    })
+  })
+
+  describe("LinkConnector dragging behavior", () => {
+    it("should drag existing link when dragging from input slot connected to subgraph input node", () => {
+      // Create a subgraph with one input
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input1", type: "number" }],
+      })
+
+      // Create a node inside the subgraph
+      const internalNode = new LGraphNode("InternalNode")
+      internalNode.id = 100
+      internalNode.addInput("in", "number")
+      subgraph.add(internalNode)
+
+      // Connect the subgraph input to the internal node's input
+      const link = subgraph.inputNode.slots[0].connect(internalNode.inputs[0], internalNode)
+      expect(link).toBeDefined()
+      expect(link!.origin_id).toBe(SUBGRAPH_INPUT_ID)
+      expect(link!.target_id).toBe(internalNode.id)
+
+      // Verify the input slot has the link
+      expect(internalNode.inputs[0].link).toBe(link!.id)
+
+      // Create a LinkConnector
+      const setConnectingLinks = vi.fn()
+      const connector = new LinkConnector(setConnectingLinks)
+
+      // Now try to drag from the input slot
+      connector.moveInputLink(subgraph as LinkNetwork, internalNode.inputs[0])
+
+      // Verify that we're dragging the existing link
+      expect(connector.isConnecting).toBe(true)
+      expect(connector.state.connectingTo).toBe("input")
+      expect(connector.state.draggingExistingLinks).toBe(true)
+
+      // Check that we have exactly one render link
+      expect(connector.renderLinks).toHaveLength(1)
+
+      // The render link should be a ToInputFromIoNodeLink, not MovingInputLink
+      expect(connector.renderLinks[0]).toBeInstanceOf(ToInputFromIoNodeLink)
+
+      // The input links collection should contain our link
+      expect(connector.inputLinks).toHaveLength(1)
+      expect(connector.inputLinks[0]).toBe(link)
+
+      // Verify the link is marked as dragging
+      expect(link!._dragging).toBe(true)
+    })
+  })
+
+  describe("Type compatibility", () => {
+    it("should respect type compatibility for SubgraphInput connections", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "number_input", type: "number" }],
+      })
+
+      const subgraphInput = subgraph.inputs[0]
+
+      const node = new LGraphNode("TestNode")
+      node.addInput("number_slot", "number")
+      node.addInput("string_slot", "string")
+      node.addInput("any_slot", "*")
+      node.addInput("boolean_slot", "boolean")
+      subgraph.add(node)
+
+      const numberSlot = node.inputs[0] as NodeInputSlot
+      const stringSlot = node.inputs[1] as NodeInputSlot
+      const anySlot = node.inputs[2] as NodeInputSlot
+      const booleanSlot = node.inputs[3] as NodeInputSlot
+
+      expect(numberSlot.isValidTarget(subgraphInput)).toBe(true)
+      expect(stringSlot.isValidTarget(subgraphInput)).toBe(false)
+      expect(anySlot.isValidTarget(subgraphInput)).toBe(true)
+      expect(booleanSlot.isValidTarget(subgraphInput)).toBe(false)
+    })
+
+    it("should respect type compatibility for SubgraphOutput connections", () => {
+      const subgraph = createTestSubgraph()
+      const node = new LGraphNode("TestNode")
+      node.addOutput("out", "string")
+      subgraph.add(node)
+
+      const subgraphOutput = subgraph.addOutput("result", "number")
+      const nodeOutput = node.outputs[0]
+
+      expect(subgraphOutput.isValidTarget(nodeOutput)).toBe(false)
+    })
+
+    it("should handle wildcard SubgraphInput", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "any_input", type: "*" }],
+      })
+
+      const subgraphInput = subgraph.inputs[0]
+
+      const node = new LGraphNode("TestNode")
+      node.addInput("number_slot", "number")
+      subgraph.add(node)
+
+      const numberSlot = node.inputs[0] as NodeInputSlot
+
+      expect(numberSlot.isValidTarget(subgraphInput)).toBe(true)
+    })
+  })
+
+  describe("Type guards", () => {
+    it("should correctly identify SubgraphInput", () => {
+      const subgraph = createTestSubgraph()
+      const subgraphInput = subgraph.addInput("value", "number")
+      const node = new LGraphNode("TestNode")
+      node.addInput("in", "number")
+
+      expect(isSubgraphInput(subgraphInput)).toBe(true)
+      expect(isSubgraphInput(node.inputs[0])).toBe(false)
+      expect(isSubgraphInput(null)).toBe(false)
+      // eslint-disable-next-line unicorn/no-useless-undefined
+      expect(isSubgraphInput(undefined)).toBe(false)
+      expect(isSubgraphInput({})).toBe(false)
+    })
+
+    it("should correctly identify SubgraphOutput", () => {
+      const subgraph = createTestSubgraph()
+      const subgraphOutput = subgraph.addOutput("result", "number")
+      const node = new LGraphNode("TestNode")
+      node.addOutput("out", "number")
+
+      expect(isSubgraphOutput(subgraphOutput)).toBe(true)
+      expect(isSubgraphOutput(node.outputs[0])).toBe(false)
+      expect(isSubgraphOutput(null)).toBe(false)
+      // eslint-disable-next-line unicorn/no-useless-undefined
+      expect(isSubgraphOutput(undefined)).toBe(false)
+      expect(isSubgraphOutput({})).toBe(false)
+    })
+  })
+
+  describe("Nested subgraphs", () => {
+    it("should handle dragging from SubgraphInput in nested subgraphs", () => {
+      const parentSubgraph = createTestSubgraph({
+        inputs: [{ name: "parent_input", type: "number" }],
+        outputs: [{ name: "parent_output", type: "number" }],
+      })
+
+      const nestedSubgraph = createTestSubgraph({
+        inputs: [{ name: "nested_input", type: "number" }],
+        outputs: [{ name: "nested_output", type: "number" }],
+      })
+
+      const nestedSubgraphNode = createTestSubgraphNode(nestedSubgraph)
+      parentSubgraph.add(nestedSubgraphNode)
+
+      const regularNode = new LGraphNode("TestNode")
+      regularNode.addInput("test_input", "number")
+      nestedSubgraph.add(regularNode)
+
+      const nestedSubgraphInput = nestedSubgraph.inputs[0]
+      const regularNodeSlot = regularNode.inputs[0] as NodeInputSlot
+
+      expect(regularNodeSlot.isValidTarget(nestedSubgraphInput)).toBe(true)
+    })
+
+    it("should handle multiple levels of nesting", () => {
+      const level1 = createTestSubgraph({
+        inputs: [{ name: "level1_input", type: "string" }],
+      })
+
+      const level2 = createTestSubgraph({
+        inputs: [{ name: "level2_input", type: "string" }],
+      })
+
+      const level3 = createTestSubgraph({
+        inputs: [{ name: "level3_input", type: "string" }],
+        outputs: [{ name: "level3_output", type: "string" }],
+      })
+
+      const level2Node = createTestSubgraphNode(level2)
+      level1.add(level2Node)
+
+      const level3Node = createTestSubgraphNode(level3)
+      level2.add(level3Node)
+
+      const deepNode = new LGraphNode("DeepNode")
+      deepNode.addInput("deep_input", "string")
+      level3.add(deepNode)
+
+      const level3Input = level3.inputs[0]
+      const deepNodeSlot = deepNode.inputs[0] as NodeInputSlot
+
+      expect(deepNodeSlot.isValidTarget(level3Input)).toBe(true)
+
+      const level3Output = level3.outputs[0]
+      expect(level3Output.isValidTarget(level3Input)).toBe(true)
+    })
+
+    it("should maintain type checking across nesting levels", () => {
+      const outer = createTestSubgraph({
+        inputs: [{ name: "outer_number", type: "number" }],
+      })
+
+      const inner = createTestSubgraph({
+        inputs: [
+          { name: "inner_number", type: "number" },
+          { name: "inner_string", type: "string" },
+        ],
+      })
+
+      const innerNode = createTestSubgraphNode(inner)
+      outer.add(innerNode)
+
+      const node = new LGraphNode("TestNode")
+      node.addInput("number_slot", "number")
+      node.addInput("string_slot", "string")
+      inner.add(node)
+
+      const innerNumberInput = inner.inputs[0]
+      const innerStringInput = inner.inputs[1]
+      const numberSlot = node.inputs[0] as NodeInputSlot
+      const stringSlot = node.inputs[1] as NodeInputSlot
+
+      expect(numberSlot.isValidTarget(innerNumberInput)).toBe(true)
+      expect(numberSlot.isValidTarget(innerStringInput)).toBe(false)
+      expect(stringSlot.isValidTarget(innerNumberInput)).toBe(false)
+      expect(stringSlot.isValidTarget(innerStringInput)).toBe(true)
+    })
+  })
+})

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

@@ -0,0 +1,181 @@
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+import { LGraphNode } from "@/litegraph"
+
+import { createTestSubgraph } from "./fixtures/subgraphHelpers"
+
+describe("SubgraphSlot visual feedback", () => {
+  let mockCtx: CanvasRenderingContext2D
+  let mockColorContext: any
+  let globalAlphaValues: number[]
+
+  beforeEach(() => {
+    // Clear the array before each test
+    globalAlphaValues = []
+
+    // Create a mock canvas context that tracks all globalAlpha values
+    const mockContext = {
+      _globalAlpha: 1,
+      get globalAlpha() {
+        return this._globalAlpha
+      },
+      set globalAlpha(value: number) {
+        this._globalAlpha = value
+        globalAlphaValues.push(value)
+      },
+      fillStyle: "",
+      strokeStyle: "",
+      lineWidth: 1,
+      beginPath: vi.fn(),
+      arc: vi.fn(),
+      fill: vi.fn(),
+      stroke: vi.fn(),
+      rect: vi.fn(),
+      fillText: vi.fn(),
+    }
+    mockCtx = mockContext as unknown as CanvasRenderingContext2D
+
+    // Create a mock color context
+    mockColorContext = {
+      defaultInputColor: "#FF0000",
+      defaultOutputColor: "#00FF00",
+      getConnectedColor: vi.fn().mockReturnValue("#0000FF"),
+      getDisconnectedColor: vi.fn().mockReturnValue("#AAAAAA"),
+    }
+  })
+
+  it("should render SubgraphInput slots with full opacity when dragging from compatible slot", () => {
+    const subgraph = createTestSubgraph()
+    const node = new LGraphNode("TestNode")
+    node.addInput("in", "number")
+    subgraph.add(node)
+
+    // Add a subgraph input
+    const subgraphInput = subgraph.addInput("value", "number")
+
+    // Simulate dragging from the subgraph input (which acts as output inside subgraph)
+    const nodeInput = node.inputs[0]
+
+    // Draw the slot with a compatible fromSlot
+    subgraphInput.draw({
+      ctx: mockCtx,
+      colorContext: mockColorContext,
+      fromSlot: nodeInput,
+      editorAlpha: 1,
+    })
+
+    // Should render with full opacity (not 0.4)
+    // Check that 0.4 was NOT set during drawing
+    expect(globalAlphaValues).not.toContain(0.4)
+  })
+
+  it("should render SubgraphInput slots with 40% opacity when dragging from another SubgraphInput", () => {
+    const subgraph = createTestSubgraph()
+
+    // Add two subgraph inputs
+    const subgraphInput1 = subgraph.addInput("value1", "number")
+    const subgraphInput2 = subgraph.addInput("value2", "number")
+
+    // Draw subgraphInput2 while dragging from subgraphInput1 (incompatible - both are outputs inside subgraph)
+    subgraphInput2.draw({
+      ctx: mockCtx,
+      colorContext: mockColorContext,
+      fromSlot: subgraphInput1,
+      editorAlpha: 1,
+    })
+
+    // Should render with 40% opacity
+    // Check that 0.4 was set during drawing
+    expect(globalAlphaValues).toContain(0.4)
+  })
+
+  it("should render SubgraphOutput slots with full opacity when dragging from compatible slot", () => {
+    const subgraph = createTestSubgraph()
+    const node = new LGraphNode("TestNode")
+    node.addOutput("out", "number")
+    subgraph.add(node)
+
+    // Add a subgraph output
+    const subgraphOutput = subgraph.addOutput("result", "number")
+
+    // Simulate dragging from a node output
+    const nodeOutput = node.outputs[0]
+
+    // Draw the slot with a compatible fromSlot
+    subgraphOutput.draw({
+      ctx: mockCtx,
+      colorContext: mockColorContext,
+      fromSlot: nodeOutput,
+      editorAlpha: 1,
+    })
+
+    // Should render with full opacity (not 0.4)
+    // Check that 0.4 was NOT set during drawing
+    expect(globalAlphaValues).not.toContain(0.4)
+  })
+
+  it("should render SubgraphOutput slots with 40% opacity when dragging from another SubgraphOutput", () => {
+    const subgraph = createTestSubgraph()
+
+    // Add two subgraph outputs
+    const subgraphOutput1 = subgraph.addOutput("result1", "number")
+    const subgraphOutput2 = subgraph.addOutput("result2", "number")
+
+    // Draw subgraphOutput2 while dragging from subgraphOutput1 (incompatible - both are inputs inside subgraph)
+    subgraphOutput2.draw({
+      ctx: mockCtx,
+      colorContext: mockColorContext,
+      fromSlot: subgraphOutput1,
+      editorAlpha: 1,
+    })
+
+    // Should render with 40% opacity
+    // Check that 0.4 was set during drawing
+    expect(globalAlphaValues).toContain(0.4)
+  })
+
+  // "not implmeneted yet"
+  // it("should render slots with full opacity when dragging between compatible SubgraphInput and SubgraphOutput", () => {
+  //   const subgraph = createTestSubgraph()
+
+  //   // Add subgraph input and output with matching types
+  //   const subgraphInput = subgraph.addInput("value", "number")
+  //   const subgraphOutput = subgraph.addOutput("result", "number")
+
+  //   // Draw SubgraphOutput slot while dragging from SubgraphInput
+  //   subgraphOutput.draw({
+  //     ctx: mockCtx,
+  //     colorContext: mockColorContext,
+  //     fromSlot: subgraphInput,
+  //     editorAlpha: 1,
+  //   })
+
+  //   // Should render with full opacity
+  //   expect(mockCtx.globalAlpha).toBe(1)
+  // })
+
+  it("should render slots with 40% opacity when dragging between incompatible types", () => {
+    const subgraph = createTestSubgraph()
+    const node = new LGraphNode("TestNode")
+    node.addOutput("string_output", "string")
+    subgraph.add(node)
+
+    // Add subgraph output with incompatible type
+    const subgraphOutput = subgraph.addOutput("result", "number")
+
+    // Get the string output slot from the node
+    const nodeStringOutput = node.outputs[0]
+
+    // Draw the SubgraphOutput slot while dragging from a node output with incompatible type
+    subgraphOutput.draw({
+      ctx: mockCtx,
+      colorContext: mockColorContext,
+      fromSlot: nodeStringOutput,
+      editorAlpha: 1,
+    })
+
+    // Should render with 40% opacity due to type mismatch
+    // Check that 0.4 was set during drawing
+    expect(globalAlphaValues).toContain(0.4)
+  })
+})

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

@@ -0,0 +1,349 @@
+import type { ISlotType } from "@/interfaces"
+import type { TWidgetType } from "@/types/widgets"
+
+import { describe, expect, it } from "vitest"
+
+import { LGraphNode, Subgraph } from "@/litegraph"
+import { BaseWidget } from "@/widgets/BaseWidget"
+
+import { createEventCapture, createTestSubgraph, createTestSubgraphNode } from "./fixtures/subgraphHelpers"
+
+// Helper to create a node with a widget
+function createNodeWithWidget(
+  title: string,
+  widgetType: TWidgetType = "number",
+  widgetValue: any = 42,
+  slotType: ISlotType = "number",
+  tooltip?: string,
+) {
+  const node = new LGraphNode(title)
+  const input = node.addInput("value", slotType)
+  node.addOutput("out", slotType)
+
+  const widget = new BaseWidget({
+    name: "widget",
+    type: widgetType,
+    value: widgetValue,
+    y: 0,
+    options: widgetType === "number" ? { min: 0, max: 100, step: 1 } : {},
+    node,
+    tooltip,
+  })
+  node.widgets = [widget]
+  input.widget = { name: widget.name }
+
+  return { node, widget, input }
+}
+
+// Helper to connect subgraph input to node and create SubgraphNode
+function setupPromotedWidget(subgraph: Subgraph, node: LGraphNode, slotIndex = 0) {
+  subgraph.add(node)
+  subgraph.inputNode.slots[slotIndex].connect(node.inputs[slotIndex], node)
+  return createTestSubgraphNode(subgraph)
+}
+
+describe("SubgraphWidgetPromotion", () => {
+  describe("Widget Promotion Functionality", () => {
+    it("should promote widgets when connecting node to subgraph input", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "value", type: "number" }],
+      })
+
+      const { node } = createNodeWithWidget("Test Node")
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+
+      // The widget should be promoted to the subgraph node
+      expect(subgraphNode.widgets).toHaveLength(1)
+      expect(subgraphNode.widgets[0].name).toBe("value") // Uses subgraph input name
+      expect(subgraphNode.widgets[0].type).toBe("number")
+      expect(subgraphNode.widgets[0].value).toBe(42)
+    })
+
+    it("should promote all widget types", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [
+          { name: "numberInput", type: "number" },
+          { name: "stringInput", type: "string" },
+          { name: "toggleInput", type: "boolean" },
+        ],
+      })
+
+      // Create nodes with different widget types
+      const { node: numberNode } = createNodeWithWidget("Number Node", "number", 100)
+      const { node: stringNode } = createNodeWithWidget("String Node", "string", "test", "string")
+      const { node: toggleNode } = createNodeWithWidget("Toggle Node", "toggle", true, "boolean")
+
+      // Setup all nodes
+      subgraph.add(numberNode)
+      subgraph.add(stringNode)
+      subgraph.add(toggleNode)
+
+      subgraph.inputNode.slots[0].connect(numberNode.inputs[0], numberNode)
+      subgraph.inputNode.slots[1].connect(stringNode.inputs[0], stringNode)
+      subgraph.inputNode.slots[2].connect(toggleNode.inputs[0], toggleNode)
+
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // All widgets should be promoted
+      expect(subgraphNode.widgets).toHaveLength(3)
+
+      // Check specific widget values
+      expect(subgraphNode.widgets[0].value).toBe(100)
+      expect(subgraphNode.widgets[1].value).toBe("test")
+      expect(subgraphNode.widgets[2].value).toBe(true)
+    })
+
+    it("should fire widget-promoted event when widget is promoted", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input", type: "number" }],
+      })
+
+      const eventCapture = createEventCapture(subgraph.events, [
+        "widget-promoted",
+        "widget-demoted",
+      ])
+
+      const { node } = createNodeWithWidget("Test Node")
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+
+      // Check event was fired
+      const promotedEvents = eventCapture.getEventsByType("widget-promoted")
+      expect(promotedEvents).toHaveLength(1)
+      expect(promotedEvents[0].detail.widget).toBeDefined()
+      expect(promotedEvents[0].detail.subgraphNode).toBe(subgraphNode)
+
+      eventCapture.cleanup()
+    })
+
+    it("should fire widget-demoted event when removing promoted widget", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input", type: "number" }],
+      })
+
+      const { node } = createNodeWithWidget("Test Node")
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+      expect(subgraphNode.widgets).toHaveLength(1)
+
+      const eventCapture = createEventCapture(subgraph.events, ["widget-demoted"])
+
+      // Remove the widget
+      subgraphNode.removeWidgetByName("input")
+
+      // Check event was fired
+      const demotedEvents = eventCapture.getEventsByType("widget-demoted")
+      expect(demotedEvents).toHaveLength(1)
+      expect(demotedEvents[0].detail.widget).toBeDefined()
+      expect(demotedEvents[0].detail.subgraphNode).toBe(subgraphNode)
+
+      // Widget should be removed
+      expect(subgraphNode.widgets).toHaveLength(0)
+
+      eventCapture.cleanup()
+    })
+
+    it("should handle multiple widgets on same node", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [
+          { name: "input1", type: "number" },
+          { name: "input2", type: "string" },
+        ],
+      })
+
+      // Create node with multiple widgets
+      const multiWidgetNode = new LGraphNode("Multi Widget Node")
+      const numInput = multiWidgetNode.addInput("num", "number")
+      const strInput = multiWidgetNode.addInput("str", "string")
+
+      const widget1 = new BaseWidget({
+        name: "widget1",
+        type: "number",
+        value: 10,
+        y: 0,
+        options: {},
+        node: multiWidgetNode,
+      })
+
+      const widget2 = new BaseWidget({
+        name: "widget2",
+        type: "string",
+        value: "hello",
+        y: 40,
+        options: {},
+        node: multiWidgetNode,
+      })
+
+      multiWidgetNode.widgets = [widget1, widget2]
+      numInput.widget = { name: widget1.name }
+      strInput.widget = { name: widget2.name }
+      subgraph.add(multiWidgetNode)
+
+      // Connect both inputs
+      subgraph.inputNode.slots[0].connect(multiWidgetNode.inputs[0], multiWidgetNode)
+      subgraph.inputNode.slots[1].connect(multiWidgetNode.inputs[1], multiWidgetNode)
+
+      // Create SubgraphNode
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // Both widgets should be promoted
+      expect(subgraphNode.widgets).toHaveLength(2)
+      expect(subgraphNode.widgets[0].name).toBe("input1")
+      expect(subgraphNode.widgets[0].value).toBe(10)
+
+      expect(subgraphNode.widgets[1].name).toBe("input2")
+      expect(subgraphNode.widgets[1].value).toBe("hello")
+    })
+
+    it("should fire widget-demoted events when node is removed", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input", type: "number" }],
+      })
+
+      const { node } = createNodeWithWidget("Test Node")
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+
+      expect(subgraphNode.widgets).toHaveLength(1)
+
+      const eventCapture = createEventCapture(subgraph.events, ["widget-demoted"])
+
+      // Remove the subgraph node
+      subgraphNode.onRemoved()
+
+      // Should fire demoted events for all widgets
+      const demotedEvents = eventCapture.getEventsByType("widget-demoted")
+      expect(demotedEvents).toHaveLength(1)
+
+      eventCapture.cleanup()
+    })
+
+    it("should not promote widget if input is not connected", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input", type: "number" }],
+      })
+
+      const { node } = createNodeWithWidget("Test Node")
+      subgraph.add(node)
+
+      // Don't connect - just create SubgraphNode
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // No widgets should be promoted
+      expect(subgraphNode.widgets).toHaveLength(0)
+    })
+
+    it("should handle disconnection of promoted widget", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "input", type: "number" }],
+      })
+
+      const { node } = createNodeWithWidget("Test Node")
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+      expect(subgraphNode.widgets).toHaveLength(1)
+
+      // Disconnect the link
+      subgraph.inputNode.slots[0].disconnect()
+
+      // Widget should be removed (through event listeners)
+      expect(subgraphNode.widgets).toHaveLength(0)
+    })
+  })
+
+  describe("Tooltip Promotion", () => {
+    it("should preserve widget tooltip when promoting", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "value", type: "number" }],
+      })
+
+      const originalTooltip = "This is a test tooltip"
+      const { node } = createNodeWithWidget("Test Node", "number", 42, "number", originalTooltip)
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+
+      // The promoted widget should preserve the original tooltip
+      expect(subgraphNode.widgets).toHaveLength(1)
+      expect(subgraphNode.widgets[0].tooltip).toBe(originalTooltip)
+    })
+
+    it("should handle widgets with no tooltip", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "value", type: "number" }],
+      })
+
+      const { node } = createNodeWithWidget("Test Node", "number", 42, "number")
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+
+      // The promoted widget should have undefined tooltip
+      expect(subgraphNode.widgets).toHaveLength(1)
+      expect(subgraphNode.widgets[0].tooltip).toBeUndefined()
+    })
+
+    it("should preserve tooltips for multiple promoted widgets", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [
+          { name: "input1", type: "number" },
+          { name: "input2", type: "string" },
+        ],
+      })
+
+      // Create node with multiple widgets with different tooltips
+      const multiWidgetNode = new LGraphNode("Multi Widget Node")
+      const numInput = multiWidgetNode.addInput("num", "number")
+      const strInput = multiWidgetNode.addInput("str", "string")
+
+      const widget1 = new BaseWidget({
+        name: "widget1",
+        type: "number",
+        value: 10,
+        y: 0,
+        options: {},
+        node: multiWidgetNode,
+        tooltip: "Number widget tooltip",
+      })
+
+      const widget2 = new BaseWidget({
+        name: "widget2",
+        type: "string",
+        value: "hello",
+        y: 40,
+        options: {},
+        node: multiWidgetNode,
+        tooltip: "String widget tooltip",
+      })
+
+      multiWidgetNode.widgets = [widget1, widget2]
+      numInput.widget = { name: widget1.name }
+      strInput.widget = { name: widget2.name }
+      subgraph.add(multiWidgetNode)
+
+      // Connect both inputs
+      subgraph.inputNode.slots[0].connect(multiWidgetNode.inputs[0], multiWidgetNode)
+      subgraph.inputNode.slots[1].connect(multiWidgetNode.inputs[1], multiWidgetNode)
+
+      // Create SubgraphNode
+      const subgraphNode = createTestSubgraphNode(subgraph)
+
+      // Both widgets should preserve their tooltips
+      expect(subgraphNode.widgets).toHaveLength(2)
+      expect(subgraphNode.widgets[0].tooltip).toBe("Number widget tooltip")
+      expect(subgraphNode.widgets[1].tooltip).toBe("String widget tooltip")
+    })
+
+    it("should preserve original tooltip after promotion", () => {
+      const subgraph = createTestSubgraph({
+        inputs: [{ name: "value", type: "number" }],
+      })
+
+      const originalTooltip = "Original tooltip"
+      const { node } = createNodeWithWidget("Test Node", "number", 42, "number", originalTooltip)
+      const subgraphNode = setupPromotedWidget(subgraph, node)
+
+      const promotedWidget = subgraphNode.widgets[0]
+
+      // The promoted widget should preserve the original tooltip
+      expect(promotedWidget.tooltip).toBe(originalTooltip)
+
+      // The promoted widget should still function normally
+      expect(promotedWidget.name).toBe("value") // Uses subgraph input name
+      expect(promotedWidget.type).toBe("number")
+      expect(promotedWidget.value).toBe(42)
+    })
+  })
+})

src/lib/litegraph/test/subgraph/fixtures/README.md

@@ -0,0 +1,311 @@
+# Subgraph Testing Fixtures and Utilities
+
+This directory contains the testing infrastructure for LiteGraph's subgraph functionality. These utilities provide a consistent, easy-to-use API for writing subgraph tests.
+
+## What is a Subgraph?
+
+A subgraph in LiteGraph is a graph-within-a-graph that can be reused as a single node. It has:
+- Input slots that map to an internal input node
+- Output slots that map to an internal output node
+- Internal nodes and connections
+- The ability to be instantiated multiple times as SubgraphNode instances
+
+## Quick Start
+
+```typescript
+// Import what you need
+import { createTestSubgraph, assertSubgraphStructure } from "./fixtures/subgraphHelpers"
+import { subgraphTest } from "./fixtures/subgraphFixtures"
+
+// Option 1: Create a subgraph manually
+it("should do something", () => {
+  const subgraph = createTestSubgraph({
+    name: "My Test Subgraph",
+    inputCount: 2,
+    outputCount: 1
+  })
+  
+  // Test your functionality
+  expect(subgraph.inputs).toHaveLength(2)
+})
+
+// Option 2: Use pre-configured fixtures
+subgraphTest("should handle events", ({ simpleSubgraph, eventCapture }) => {
+  // simpleSubgraph comes pre-configured with 1 input, 1 output, and 2 nodes
+  expect(simpleSubgraph.inputs).toHaveLength(1)
+  // Your test logic here
+})
+```
+
+## Files Overview
+
+### `subgraphHelpers.ts` - Core Helper Functions
+
+**Main Factory Functions:**
+- `createTestSubgraph(options?)` - Creates a fully configured Subgraph instance with root graph
+- `createTestSubgraphNode(subgraph, options?)` - Creates a SubgraphNode (instance of a subgraph)
+- `createNestedSubgraphs(options?)` - Creates nested subgraph hierarchies for testing deep structures
+
+**Assertion & Validation:**
+- `assertSubgraphStructure(subgraph, expected)` - Validates subgraph has expected inputs/outputs/nodes
+- `verifyEventSequence(events, expectedSequence)` - Ensures events fired in correct order
+- `logSubgraphStructure(subgraph, label?)` - Debug helper to print subgraph structure
+
+**Test Data & Events:**
+- `createTestSubgraphData(overrides?)` - Creates raw ExportedSubgraph data for serialization tests
+- `createComplexSubgraphData(nodeCount?)` - Generates complex subgraph with internal connections
+- `createEventCapture(eventTarget, eventTypes)` - Sets up event monitoring with automatic cleanup
+
+### `subgraphFixtures.ts` - Vitest Fixtures
+
+Pre-configured test scenarios that automatically set up and tear down:
+
+**Basic Fixtures (`subgraphTest`):**
+- `emptySubgraph` - Minimal subgraph with no inputs/outputs/nodes
+- `simpleSubgraph` - 1 input ("input": number), 1 output ("output": number), 2 internal nodes
+- `complexSubgraph` - 3 inputs (data, control, text), 2 outputs (result, status), 5 nodes
+- `nestedSubgraph` - 3-level deep hierarchy with 2 nodes per level
+- `subgraphWithNode` - Complete setup: subgraph definition + SubgraphNode instance + parent graph
+- `eventCapture` - Subgraph with event monitoring for all I/O events
+
+**Edge Case Fixtures (`edgeCaseTest`):**
+- `circularSubgraph` - Two subgraphs set up for circular reference testing
+- `deeplyNestedSubgraph` - 50 levels deep for performance/limit testing
+- `maxIOSubgraph` - 20 inputs and 20 outputs for stress testing
+
+### `testSubgraphs.json` - Sample Test Data
+Pre-defined subgraph configurations for consistent testing across different scenarios.
+
+**Note on Static UUIDs**: The hardcoded UUIDs in this file (e.g., "simple-subgraph-uuid", "complex-subgraph-uuid") are intentionally static to ensure test reproducibility and snapshot testing compatibility.
+
+## Usage Examples
+
+### Basic Test Creation
+
+```typescript
+import { describe, expect, it } from "vitest"
+import { createTestSubgraph, assertSubgraphStructure } from "./fixtures/subgraphHelpers"
+
+describe("My Subgraph Feature", () => {
+  it("should work correctly", () => {
+    const subgraph = createTestSubgraph({
+      name: "My Test",
+      inputCount: 2,
+      outputCount: 1,
+      nodeCount: 3
+    })
+    
+    assertSubgraphStructure(subgraph, {
+      inputCount: 2,
+      outputCount: 1,
+      nodeCount: 3,
+      name: "My Test"
+    })
+    
+    // Your specific test logic...
+  })
+})
+```
+
+### Using Fixtures
+
+```typescript
+import { subgraphTest } from "./fixtures/subgraphFixtures"
+
+subgraphTest("should handle events", ({ eventCapture }) => {
+  const { subgraph, capture } = eventCapture
+  
+  subgraph.addInput("test", "number")
+  
+  expect(capture.events).toHaveLength(2) // adding-input, input-added
+})
+```
+
+### Event Testing
+
+```typescript
+import { createEventCapture, verifyEventSequence } from "./fixtures/subgraphHelpers"
+
+it("should fire events in correct order", () => {
+  const subgraph = createTestSubgraph()
+  const capture = createEventCapture(subgraph.events, ["adding-input", "input-added"])
+  
+  subgraph.addInput("test", "number")
+  
+  verifyEventSequence(capture.events, ["adding-input", "input-added"])
+  
+  capture.cleanup() // Important: clean up listeners
+})
+```
+
+### Nested Structure Testing
+
+```typescript
+import { createNestedSubgraphs } from "./fixtures/subgraphHelpers"
+
+it("should handle deep nesting", () => {
+  const nested = createNestedSubgraphs({
+    depth: 5,
+    nodesPerLevel: 2
+  })
+  
+  expect(nested.subgraphs).toHaveLength(5)
+  expect(nested.leafSubgraph.nodes).toHaveLength(2)
+})
+```
+
+## Common Patterns
+
+### Testing SubgraphNode Instances
+
+```typescript
+it("should create and configure a SubgraphNode", () => {
+  // First create the subgraph definition
+  const subgraph = createTestSubgraph({
+    inputs: [{ name: "value", type: "number" }],
+    outputs: [{ name: "result", type: "number" }]
+  })
+  
+  // Then create an instance of it
+  const subgraphNode = createTestSubgraphNode(subgraph, {
+    pos: [100, 200],
+    size: [180, 100]
+  })
+  
+  // The SubgraphNode will have matching slots
+  expect(subgraphNode.inputs).toHaveLength(1)
+  expect(subgraphNode.outputs).toHaveLength(1)
+  expect(subgraphNode.subgraph).toBe(subgraph)
+})
+```
+
+### Complete Test with Parent Graph
+
+```typescript
+subgraphTest("should work in a parent graph", ({ subgraphWithNode }) => {
+  const { subgraph, subgraphNode, parentGraph } = subgraphWithNode
+  
+  // Everything is pre-configured and connected
+  expect(parentGraph.nodes).toContain(subgraphNode)
+  expect(subgraphNode.graph).toBe(parentGraph)
+  expect(subgraphNode.subgraph).toBe(subgraph)
+})
+```
+
+## Configuration Options
+
+### `createTestSubgraph(options)`
+```typescript
+interface TestSubgraphOptions {
+  id?: UUID                    // Custom UUID
+  name?: string               // Custom name
+  nodeCount?: number          // Number of internal nodes
+  inputCount?: number         // Number of inputs (uses generic types)
+  outputCount?: number        // Number of outputs (uses generic types)
+  inputs?: Array<{           // Specific input definitions
+    name: string
+    type: ISlotType
+  }>
+  outputs?: Array<{          // Specific output definitions
+    name: string
+    type: ISlotType
+  }>
+}
+```
+
+**Note**: Cannot specify both `inputs` array and `inputCount` (or `outputs` array and `outputCount`) - the function will throw an error with details.
+
+### `createNestedSubgraphs(options)`
+```typescript
+interface NestedSubgraphOptions {
+  depth?: number              // Nesting depth (default: 2)
+  nodesPerLevel?: number      // Nodes per subgraph (default: 2)
+  inputsPerSubgraph?: number  // Inputs per subgraph (default: 1)
+  outputsPerSubgraph?: number // Outputs per subgraph (default: 1)
+}
+```
+
+## Important Architecture Notes
+
+### Subgraph vs SubgraphNode
+- **Subgraph**: The definition/template (like a class definition)
+- **SubgraphNode**: An instance of a subgraph placed in a graph (like a class instance)
+- One Subgraph can have many SubgraphNode instances
+
+### Special Node IDs
+- Input node always has ID `-10` (SUBGRAPH_INPUT_ID)
+- Output node always has ID `-20` (SUBGRAPH_OUTPUT_ID)
+- These are virtual nodes that exist in every subgraph
+
+### Common Pitfalls
+
+1. **Array vs Index**: The `inputs` and `outputs` arrays don't have an `index` property on items. Use `indexOf()`:
+   ```typescript
+   // ❌ Wrong
+   expect(input.index).toBe(0)
+   
+   // ✅ Correct
+   expect(subgraph.inputs.indexOf(input)).toBe(0)
+   ```
+
+2. **Graph vs Subgraph Property**: SubgraphInputNode/OutputNode have `subgraph`, not `graph`:
+   ```typescript
+   // ❌ Wrong
+   expect(inputNode.graph).toBe(subgraph)
+   
+   // ✅ Correct
+   expect(inputNode.subgraph).toBe(subgraph)
+   ```
+
+3. **Event Detail Structure**: Events have specific detail structures:
+   ```typescript
+   // Input events
+   "adding-input": { name: string, type: string }
+   "input-added": { input: SubgraphInput, index: number }
+   
+   // Output events  
+   "adding-output": { name: string, type: string }
+   "output-added": { output: SubgraphOutput, index: number }
+   ```
+
+4. **Links are stored in a Map**: Use `.size` not `.length`:
+   ```typescript
+   // ❌ Wrong
+   expect(subgraph.links.length).toBe(1)
+   
+   // ✅ Correct
+   expect(subgraph.links.size).toBe(1)
+   ```
+
+## Testing Best Practices
+
+- Always use helper functions instead of manual setup
+- Use fixtures for common scenarios to avoid repetitive code
+- Clean up event listeners with `capture.cleanup()` after event tests
+- Use `verifyEventSequence()` to test event ordering
+- Remember fixtures are created fresh for each test (no shared state)
+- Use `assertSubgraphStructure()` for comprehensive validation
+
+## Debugging Tips
+
+- Use `logSubgraphStructure(subgraph)` to print subgraph details
+- Check `subgraph.rootGraph` to verify graph hierarchy
+- Event capture includes timestamps for debugging timing issues
+- All factory functions accept optional parameters for customization
+
+## Adding New Test Utilities
+
+When extending the test infrastructure:
+
+1. Add new helper functions to `subgraphHelpers.ts`
+2. Add new fixtures to `subgraphFixtures.ts`
+3. Update this README with usage examples
+4. Follow existing patterns for consistency
+5. Add TypeScript types for all parameters
+
+## Performance Notes
+
+- Helper functions are optimized for test clarity, not performance
+- Use `structuredClone()` for deep copying test data
+- Event capture systems automatically clean up listeners
+- Fixtures are created fresh for each test to avoid state contamination

src/lib/litegraph/test/subgraph/fixtures/advancedEventHelpers.ts

@@ -0,0 +1,244 @@
+import type { CapturedEvent } from "./subgraphHelpers"
+
+import { expect } from "vitest"
+
+/**
+ * Extended captured event with additional metadata not in the base infrastructure
+ */
+export interface ExtendedCapturedEvent<T = unknown> extends CapturedEvent<T> {
+  defaultPrevented: boolean
+  bubbles: boolean
+  cancelable: boolean
+}
+
+/**
+ * Creates an enhanced event capture that includes additional event properties
+ * This extends the basic createEventCapture with more metadata
+ */
+export function createExtendedEventCapture<T = unknown>(
+  eventTarget: EventTarget,
+  eventTypes: string[],
+) {
+  const capturedEvents: ExtendedCapturedEvent<T>[] = []
+  const listeners: Array<() => void> = []
+
+  for (const eventType of eventTypes) {
+    const listener = (event: Event) => {
+      capturedEvents.push({
+        type: eventType,
+        detail: (event as CustomEvent<T>).detail,
+        timestamp: Date.now(),
+        defaultPrevented: event.defaultPrevented,
+        bubbles: event.bubbles,
+        cancelable: event.cancelable,
+      })
+    }
+
+    eventTarget.addEventListener(eventType, listener)
+    listeners.push(() => eventTarget.removeEventListener(eventType, listener))
+  }
+
+  return {
+    events: capturedEvents,
+    clear: () => { capturedEvents.length = 0 },
+    cleanup: () => { for (const cleanup of listeners) cleanup() },
+    getEventsByType: (type: string) => capturedEvents.filter(e => e.type === type),
+    getLatestEvent: () => capturedEvents.at(-1),
+    getFirstEvent: () => capturedEvents[0],
+
+    /**
+     * Wait for a specific event type to be captured
+     */
+    async waitForEvent(type: string, timeoutMs: number = 1000): Promise<ExtendedCapturedEvent<T>> {
+      const existingEvent = capturedEvents.find(e => e.type === type)
+      if (existingEvent) return existingEvent
+
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          eventTarget.removeEventListener(type, eventListener)
+          reject(new Error(`Event ${type} not received within ${timeoutMs}ms`))
+        }, timeoutMs)
+
+        const eventListener = (_event: Event) => {
+          const capturedEvent = capturedEvents.find(e => e.type === type)
+          if (capturedEvent) {
+            clearTimeout(timeout)
+            eventTarget.removeEventListener(type, eventListener)
+            resolve(capturedEvent)
+          }
+        }
+
+        eventTarget.addEventListener(type, eventListener)
+      })
+    },
+
+    /**
+     * Wait for a sequence of events to occur in order
+     */
+    async waitForSequence(expectedSequence: string[], timeoutMs: number = 1000): Promise<ExtendedCapturedEvent<T>[]> {
+      // Check if sequence is already complete
+      if (capturedEvents.length >= expectedSequence.length) {
+        const actualSequence = capturedEvents.slice(0, expectedSequence.length).map(e => e.type)
+        if (JSON.stringify(actualSequence) === JSON.stringify(expectedSequence)) {
+          return capturedEvents.slice(0, expectedSequence.length)
+        }
+      }
+
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          cleanup()
+          const actual = capturedEvents.map(e => e.type).join(", ")
+          const expected = expectedSequence.join(", ")
+          reject(new Error(`Event sequence not completed within ${timeoutMs}ms. Expected: ${expected}, Got: ${actual}`))
+        }, timeoutMs)
+
+        const checkSequence = () => {
+          if (capturedEvents.length >= expectedSequence.length) {
+            const actualSequence = capturedEvents.slice(0, expectedSequence.length).map(e => e.type)
+            if (JSON.stringify(actualSequence) === JSON.stringify(expectedSequence)) {
+              cleanup()
+              resolve(capturedEvents.slice(0, expectedSequence.length))
+            }
+          }
+        }
+
+        const eventListener = () => checkSequence()
+
+        const cleanup = () => {
+          clearTimeout(timeout)
+          for (const type of expectedSequence) {
+            eventTarget.removeEventListener(type, eventListener)
+          }
+        }
+
+        // Listen for all expected event types
+        for (const type of expectedSequence) {
+          eventTarget.addEventListener(type, eventListener)
+        }
+
+        // Initial check in case events already exist
+        checkSequence()
+      })
+    },
+  }
+}
+
+/**
+ * Options for memory leak testing
+ */
+export interface MemoryLeakTestOptions {
+  cycles?: number
+  instancesPerCycle?: number
+  gcAfterEach?: boolean
+  maxMemoryGrowth?: number
+}
+
+/**
+ * Creates a memory leak test factory
+ * Useful for testing that event listeners and references are properly cleaned up
+ */
+export function createMemoryLeakTest<T>(
+  setupFn: () => { ref: WeakRef<T>, cleanup: () => void },
+  options: MemoryLeakTestOptions = {},
+) {
+  const {
+    cycles = 1,
+    instancesPerCycle = 1,
+    gcAfterEach = true,
+    maxMemoryGrowth = 0,
+  } = options
+
+  return async () => {
+    const refs: WeakRef<T>[] = []
+    const initialMemory = process.memoryUsage?.()?.heapUsed || 0
+
+    for (let cycle = 0; cycle < cycles; cycle++) {
+      const cycleRefs: WeakRef<T>[] = []
+
+      for (let instance = 0; instance < instancesPerCycle; instance++) {
+        const { ref, cleanup } = setupFn()
+        cycleRefs.push(ref)
+        cleanup()
+      }
+
+      refs.push(...cycleRefs)
+
+      if (gcAfterEach && global.gc) {
+        global.gc()
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+    }
+
+    // Final garbage collection
+    if (global.gc) {
+      global.gc()
+      await new Promise(resolve => setTimeout(resolve, 50))
+
+      // Check if objects were collected
+      const uncollectedRefs = refs.filter(ref => ref.deref() !== undefined)
+      if (uncollectedRefs.length > 0) {
+        console.warn(`${uncollectedRefs.length} objects were not garbage collected`)
+      }
+    }
+
+    // Memory growth check
+    if (maxMemoryGrowth > 0 && process.memoryUsage) {
+      const finalMemory = process.memoryUsage().heapUsed
+      const memoryGrowth = finalMemory - initialMemory
+
+      if (memoryGrowth > maxMemoryGrowth) {
+        throw new Error(`Memory growth ${memoryGrowth} bytes exceeds limit ${maxMemoryGrowth} bytes`)
+      }
+    }
+
+    return refs
+  }
+}
+
+/**
+ * Creates a performance monitor for event operations
+ */
+export function createEventPerformanceMonitor() {
+  const measurements: Array<{
+    operation: string
+    duration: number
+    timestamp: number
+  }> = []
+
+  return {
+    measure: <T>(operation: string, fn: () => T): T => {
+      const start = performance.now()
+      const result = fn()
+      const end = performance.now()
+
+      measurements.push({
+        operation,
+        duration: end - start,
+        timestamp: start,
+      })
+
+      return result
+    },
+
+    getMeasurements: () => [...measurements],
+
+    getAverageDuration: (operation: string) => {
+      const operationMeasurements = measurements.filter(m => m.operation === operation)
+      if (operationMeasurements.length === 0) return 0
+
+      const totalDuration = operationMeasurements.reduce((sum, m) => sum + m.duration, 0)
+      return totalDuration / operationMeasurements.length
+    },
+
+    clear: () => { measurements.length = 0 },
+
+    assertPerformance: (operation: string, maxDuration: number) => {
+      const measurements = this.getMeasurements()
+      const relevantMeasurements = measurements.filter(m => m.operation === operation)
+      if (relevantMeasurements.length === 0) return
+
+      const avgDuration = relevantMeasurements.reduce((sum, m) => sum + m.duration, 0) / relevantMeasurements.length
+      expect(avgDuration).toBeLessThan(maxDuration)
+    },
+  }
+}

src/lib/litegraph/test/subgraph/fixtures/subgraphFixtures.ts

@@ -0,0 +1,293 @@
+/**
+ * Vitest Fixtures for Subgraph Testing
+ *
+ * This file provides reusable Vitest fixtures that other developers can use
+ * in their test files. Each fixture provides a clean, pre-configured subgraph
+ * setup for different testing scenarios.
+ */
+
+import { LGraph, Subgraph } from "@/litegraph"
+import { SubgraphNode } from "@/subgraph/SubgraphNode"
+
+import { test } from "../../testExtensions"
+import {
+  createEventCapture,
+  createNestedSubgraphs,
+  createTestSubgraph,
+  createTestSubgraphNode,
+} from "./subgraphHelpers"
+
+export interface SubgraphFixtures {
+  /** A minimal subgraph with no inputs, outputs, or nodes */
+  emptySubgraph: Subgraph
+
+  /** A simple subgraph with 1 input and 1 output */
+  simpleSubgraph: Subgraph
+
+  /** A complex subgraph with multiple inputs, outputs, and internal nodes */
+  complexSubgraph: Subgraph
+
+  /** A nested subgraph structure (3 levels deep) */
+  nestedSubgraph: ReturnType<typeof createNestedSubgraphs>
+
+  /** A subgraph with its corresponding SubgraphNode instance */
+  subgraphWithNode: {
+    subgraph: Subgraph
+    subgraphNode: SubgraphNode
+    parentGraph: LGraph
+  }
+
+  /** Event capture system for testing subgraph events */
+  eventCapture: {
+    subgraph: Subgraph
+    capture: ReturnType<typeof createEventCapture>
+  }
+}
+
+/**
+ * Extended test with subgraph fixtures.
+ * Use this instead of the base `test` for subgraph testing.
+ * @example
+ * ```typescript
+ * import { subgraphTest } from "./fixtures/subgraphFixtures"
+ *
+ * subgraphTest("should handle simple operations", ({ simpleSubgraph }) => {
+ *   expect(simpleSubgraph.inputs.length).toBe(1)
+ *   expect(simpleSubgraph.outputs.length).toBe(1)
+ * })
+ * ```
+ */
+export const subgraphTest = test.extend<SubgraphFixtures>({
+
+  emptySubgraph: async ({ }, use: (value: unknown) => Promise<void>) => {
+    const subgraph = createTestSubgraph({
+      name: "Empty Test Subgraph",
+      inputCount: 0,
+      outputCount: 0,
+      nodeCount: 0,
+    })
+
+    await use(subgraph)
+  },
+
+  simpleSubgraph: async ({ }, use: (value: unknown) => Promise<void>) => {
+    const subgraph = createTestSubgraph({
+      name: "Simple Test Subgraph",
+      inputs: [{ name: "input", type: "number" }],
+      outputs: [{ name: "output", type: "number" }],
+      nodeCount: 2,
+    })
+
+    await use(subgraph)
+  },
+
+  complexSubgraph: async ({ }, use: (value: unknown) => Promise<void>) => {
+    const subgraph = createTestSubgraph({
+      name: "Complex Test Subgraph",
+      inputs: [
+        { name: "data", type: "number" },
+        { name: "control", type: "boolean" },
+        { name: "text", type: "string" },
+      ],
+      outputs: [
+        { name: "result", type: "number" },
+        { name: "status", type: "boolean" },
+      ],
+      nodeCount: 5,
+    })
+
+    await use(subgraph)
+  },
+
+  nestedSubgraph: async ({ }, use: (value: unknown) => Promise<void>) => {
+    const nested = createNestedSubgraphs({
+      depth: 3,
+      nodesPerLevel: 2,
+      inputsPerSubgraph: 1,
+      outputsPerSubgraph: 1,
+    })
+
+    await use(nested)
+  },
+
+  subgraphWithNode: async ({ }, use: (value: unknown) => Promise<void>) => {
+    // Create the subgraph definition
+    const subgraph = createTestSubgraph({
+      name: "Subgraph With Node",
+      inputs: [{ name: "input", type: "*" }],
+      outputs: [{ name: "output", type: "*" }],
+      nodeCount: 1,
+    })
+
+    // Create the parent graph and subgraph node instance
+    const parentGraph = new LGraph()
+    const subgraphNode = createTestSubgraphNode(subgraph, {
+      pos: [200, 200],
+      size: [180, 80],
+    })
+
+    // Add the subgraph node to the parent graph
+    parentGraph.add(subgraphNode)
+
+    await use({
+      subgraph,
+      subgraphNode,
+      parentGraph,
+    })
+  },
+
+  eventCapture: async ({ }, use: (value: unknown) => Promise<void>) => {
+    const subgraph = createTestSubgraph({
+      name: "Event Test Subgraph",
+    })
+
+    // Set up event capture for all subgraph events
+    const capture = createEventCapture(subgraph.events, [
+      "adding-input",
+      "input-added",
+      "removing-input",
+      "renaming-input",
+      "adding-output",
+      "output-added",
+      "removing-output",
+      "renaming-output",
+    ])
+
+    await use({ subgraph, capture })
+
+    // Cleanup event listeners
+    capture.cleanup()
+  },
+})
+
+/**
+ * Fixtures that test edge cases and error conditions.
+ * These may leave the system in an invalid state and should be used carefully.
+ */
+export interface EdgeCaseFixtures {
+  /** Subgraph with circular references (for testing recursion detection) */
+  circularSubgraph: {
+    rootGraph: LGraph
+    subgraphA: Subgraph
+    subgraphB: Subgraph
+    nodeA: SubgraphNode
+    nodeB: SubgraphNode
+  }
+
+  /** Deeply nested subgraphs approaching the theoretical limit */
+  deeplyNestedSubgraph: ReturnType<typeof createNestedSubgraphs>
+
+  /** Subgraph with maximum inputs and outputs */
+  maxIOSubgraph: Subgraph
+}
+
+/**
+ * Test with edge case fixtures. Use sparingly and with caution.
+ * These tests may intentionally create invalid states.
+ */
+export const edgeCaseTest = subgraphTest.extend<EdgeCaseFixtures>({
+
+  circularSubgraph: async ({ }, use: (value: unknown) => Promise<void>) => {
+    const rootGraph = new LGraph()
+
+    // Create two subgraphs that will reference each other
+    const subgraphA = createTestSubgraph({
+      name: "Subgraph A",
+      inputs: [{ name: "input", type: "*" }],
+      outputs: [{ name: "output", type: "*" }],
+    })
+
+    const subgraphB = createTestSubgraph({
+      name: "Subgraph B",
+      inputs: [{ name: "input", type: "*" }],
+      outputs: [{ name: "output", type: "*" }],
+    })
+
+    // Create instances (this doesn't create circular refs by itself)
+    const nodeA = createTestSubgraphNode(subgraphA, { pos: [100, 100] })
+    const nodeB = createTestSubgraphNode(subgraphB, { pos: [300, 100] })
+
+    // Add nodes to root graph
+    rootGraph.add(nodeA)
+    rootGraph.add(nodeB)
+
+    await use({
+      rootGraph,
+      subgraphA,
+      subgraphB,
+      nodeA,
+      nodeB,
+    })
+  },
+
+  deeplyNestedSubgraph: async ({ }, use: (value: unknown) => Promise<void>) => {
+    // Create a very deep nesting structure (but not exceeding MAX_NESTED_SUBGRAPHS)
+    const nested = createNestedSubgraphs({
+      depth: 50, // Deep but reasonable
+      nodesPerLevel: 1,
+      inputsPerSubgraph: 1,
+      outputsPerSubgraph: 1,
+    })
+
+    await use(nested)
+  },
+
+  maxIOSubgraph: async ({ }, use: (value: unknown) => Promise<void>) => {
+    // Create a subgraph with many inputs and outputs
+    const inputs = Array.from({ length: 20 }, (_, i) => ({
+      name: `input_${i}`,
+      type: i % 2 === 0 ? "number" : "string" as const,
+    }))
+
+    const outputs = Array.from({ length: 20 }, (_, i) => ({
+      name: `output_${i}`,
+      type: i % 2 === 0 ? "number" : "string" as const,
+    }))
+
+    const subgraph = createTestSubgraph({
+      name: "Max IO Subgraph",
+      inputs,
+      outputs,
+      nodeCount: 10,
+    })
+
+    await use(subgraph)
+  },
+})
+
+/**
+ * Helper to verify fixture integrity.
+ * Use this in tests to ensure fixtures are properly set up.
+ */
+export function verifyFixtureIntegrity<T extends Record<string, unknown>>(
+  fixture: T,
+  expectedProperties: (keyof T)[],
+): void {
+  for (const prop of expectedProperties) {
+    if (!(prop in fixture)) {
+      throw new Error(`Fixture missing required property: ${String(prop)}`)
+    }
+    if (fixture[prop] === undefined || fixture[prop] === null) {
+      throw new Error(`Fixture property ${String(prop)} is null or undefined`)
+    }
+  }
+}
+
+/**
+ * Creates a snapshot-friendly representation of a subgraph for testing.
+ * Useful for serialization tests and regression detection.
+ */
+export function createSubgraphSnapshot(subgraph: Subgraph) {
+  return {
+    id: subgraph.id,
+    name: subgraph.name,
+    inputCount: subgraph.inputs.length,
+    outputCount: subgraph.outputs.length,
+    nodeCount: subgraph.nodes.length,
+    linkCount: subgraph.links.size,
+    inputs: subgraph.inputs.map(i => ({ name: i.name, type: i.type })),
+    outputs: subgraph.outputs.map(o => ({ name: o.name, type: o.type })),
+    hasInputNode: !!subgraph.inputNode,
+    hasOutputNode: !!subgraph.outputNode,
+  }
+}

src/lib/litegraph/test/subgraph/fixtures/subgraphHelpers.ts

@@ -0,0 +1,493 @@
+/**
+ * Test Helper Functions for Subgraph Testing
+ *
+ * This file contains the core utilities that all subgraph developers will use.
+ * These functions provide consistent ways to create test subgraphs, nodes, and
+ * verify their behavior.
+ */
+
+import type { ISlotType, NodeId } from "@/litegraph"
+import type { ExportedSubgraph, ExportedSubgraphInstance } from "@/types/serialisation"
+import type { UUID } from "@/utils/uuid"
+
+import { expect } from "vitest"
+
+import { LGraph, LGraphNode, Subgraph } from "@/litegraph"
+import { SubgraphNode } from "@/subgraph/SubgraphNode"
+import { createUuidv4 } from "@/utils/uuid"
+
+export interface TestSubgraphOptions {
+  id?: UUID
+  name?: string
+  nodeCount?: number
+  inputCount?: number
+  outputCount?: number
+  inputs?: Array<{ name: string, type: ISlotType }>
+  outputs?: Array<{ name: string, type: ISlotType }>
+}
+
+export interface TestSubgraphNodeOptions {
+  id?: NodeId
+  pos?: [number, number]
+  size?: [number, number]
+}
+
+export interface NestedSubgraphOptions {
+  depth?: number
+  nodesPerLevel?: number
+  inputsPerSubgraph?: number
+  outputsPerSubgraph?: number
+}
+
+export interface SubgraphStructureExpectation {
+  inputCount?: number
+  outputCount?: number
+  nodeCount?: number
+  name?: string
+  hasInputNode?: boolean
+  hasOutputNode?: boolean
+}
+
+export interface CapturedEvent<T = unknown> {
+  type: string
+  detail: T
+  timestamp: number
+}
+
+/**
+ * Creates a test subgraph with specified inputs, outputs, and nodes.
+ * This is the primary function for creating subgraphs in tests.
+ * @param options Configuration options for the subgraph
+ * @returns A configured Subgraph instance
+ * @example
+ * ```typescript
+ * // Create empty subgraph
+ * const subgraph = createTestSubgraph()
+ *
+ * // Create subgraph with specific I/O
+ * const subgraph = createTestSubgraph({
+ *   inputs: [{ name: "value", type: "number" }],
+ *   outputs: [{ name: "result", type: "string" }],
+ *   nodeCount: 3
+ * })
+ * ```
+ */
+export function createTestSubgraph(options: TestSubgraphOptions = {}): Subgraph {
+  // Validate options - cannot specify both inputs array and inputCount
+  if (options.inputs && options.inputCount) {
+    throw new Error(`Cannot specify both 'inputs' array and 'inputCount'. Choose one approach. Received options: ${JSON.stringify(options)}`)
+  }
+
+  // Validate options - cannot specify both outputs array and outputCount
+  if (options.outputs && options.outputCount) {
+    throw new Error(`Cannot specify both 'outputs' array and 'outputCount'. Choose one approach. Received options: ${JSON.stringify(options)}`)
+  }
+  const rootGraph = new LGraph()
+
+  // Create the base subgraph data
+  const subgraphData: ExportedSubgraph = {
+    // Basic graph properties
+    version: 1,
+    nodes: [],
+    links: {},
+    groups: [],
+    config: {},
+    definitions: { subgraphs: [] },
+
+    // Subgraph-specific properties
+    id: options.id || createUuidv4(),
+    name: options.name || "Test Subgraph",
+
+    // IO Nodes (required for subgraph functionality)
+    inputNode: {
+      id: -10, // SUBGRAPH_INPUT_ID
+      bounding: [10, 100, 150, 126], // [x, y, width, height]
+      pinned: false,
+    },
+    outputNode: {
+      id: -20, // SUBGRAPH_OUTPUT_ID
+      bounding: [400, 100, 140, 126], // [x, y, width, height]
+      pinned: false,
+    },
+
+    // IO definitions - will be populated by addInput/addOutput calls
+    inputs: [],
+    outputs: [],
+    widgets: [],
+  }
+
+  // Create the subgraph
+  const subgraph = new Subgraph(rootGraph, subgraphData)
+
+  // Add requested inputs
+  if (options.inputs) {
+    for (const input of options.inputs) {
+      subgraph.addInput(input.name, input.type)
+    }
+  } else if (options.inputCount) {
+    for (let i = 0; i < options.inputCount; i++) {
+      subgraph.addInput(`input_${i}`, "*")
+    }
+  }
+
+  // Add requested outputs
+  if (options.outputs) {
+    for (const output of options.outputs) {
+      subgraph.addOutput(output.name, output.type)
+    }
+  } else if (options.outputCount) {
+    for (let i = 0; i < options.outputCount; i++) {
+      subgraph.addOutput(`output_${i}`, "*")
+    }
+  }
+
+  // Add test nodes if requested
+  if (options.nodeCount) {
+    for (let i = 0; i < options.nodeCount; i++) {
+      const node = new LGraphNode(`Test Node ${i}`)
+      node.addInput("in", "*")
+      node.addOutput("out", "*")
+      subgraph.add(node)
+    }
+  }
+
+  return subgraph
+}
+
+/**
+ * Creates a SubgraphNode instance from a subgraph definition.
+ * The node is automatically added to a test parent graph.
+ * @param subgraph The subgraph definition to create a node from
+ * @param options Configuration options for the subgraph node
+ * @returns A configured SubgraphNode instance
+ * @example
+ * ```typescript
+ * const subgraph = createTestSubgraph({ inputs: [{ name: "value", type: "number" }] })
+ * const subgraphNode = createTestSubgraphNode(subgraph, {
+ *   id: 42,
+ *   pos: [100, 200],
+ *   size: [180, 100]
+ * })
+ * ```
+ */
+export function createTestSubgraphNode(
+  subgraph: Subgraph,
+  options: TestSubgraphNodeOptions = {},
+): SubgraphNode {
+  const parentGraph = new LGraph()
+
+  const instanceData: ExportedSubgraphInstance = {
+    id: options.id || 1,
+    type: subgraph.id,
+    pos: options.pos || [100, 100],
+    size: options.size || [200, 100],
+    inputs: [],
+    outputs: [],
+    properties: {},
+    flags: {},
+    mode: 0,
+  }
+
+  return new SubgraphNode(parentGraph, subgraph, instanceData)
+}
+
+/**
+ * Creates a nested hierarchy of subgraphs for testing deep nesting scenarios.
+ * @param options Configuration for the nested structure
+ * @returns Object containing the root graph and all created subgraphs
+ * @example
+ * ```typescript
+ * const nested = createNestedSubgraphs({ depth: 3, nodesPerLevel: 2 })
+ * // Creates: Root -> Subgraph1 -> Subgraph2 -> Subgraph3
+ * ```
+ */
+export function createNestedSubgraphs(options: NestedSubgraphOptions = {}) {
+  const {
+    depth = 2,
+    nodesPerLevel = 2,
+    inputsPerSubgraph = 1,
+    outputsPerSubgraph = 1,
+  } = options
+
+  const rootGraph = new LGraph()
+  const subgraphs: Subgraph[] = []
+  const subgraphNodes: SubgraphNode[] = []
+
+  let currentParent = rootGraph
+
+  for (let level = 0; level < depth; level++) {
+    // Create subgraph for this level
+    const subgraph = createTestSubgraph({
+      name: `Level ${level} Subgraph`,
+      nodeCount: nodesPerLevel,
+      inputCount: inputsPerSubgraph,
+      outputCount: outputsPerSubgraph,
+    })
+
+    subgraphs.push(subgraph)
+
+    // Create instance in parent
+    const subgraphNode = createTestSubgraphNode(subgraph, {
+      pos: [100 + level * 200, 100],
+    })
+
+    if (currentParent instanceof LGraph) {
+      currentParent.add(subgraphNode)
+    } else {
+      currentParent.add(subgraphNode)
+    }
+
+    subgraphNodes.push(subgraphNode)
+
+    // Next level will be nested inside this subgraph
+    currentParent = subgraph
+  }
+
+  return {
+    rootGraph,
+    subgraphs,
+    subgraphNodes,
+    depth,
+    leafSubgraph: subgraphs.at(-1),
+  }
+}
+
+/**
+ * Asserts that a subgraph has the expected structure.
+ * This provides consistent validation across all tests.
+ * @param subgraph The subgraph to validate
+ * @param expected The expected structure
+ * @example
+ * ```typescript
+ * assertSubgraphStructure(subgraph, {
+ *   inputCount: 2,
+ *   outputCount: 1,
+ *   name: "Expected Name"
+ * })
+ * ```
+ */
+export function assertSubgraphStructure(
+  subgraph: Subgraph,
+  expected: SubgraphStructureExpectation,
+): void {
+  if (expected.inputCount !== undefined) {
+    expect(subgraph.inputs.length).toBe(expected.inputCount)
+  }
+
+  if (expected.outputCount !== undefined) {
+    expect(subgraph.outputs.length).toBe(expected.outputCount)
+  }
+
+  if (expected.nodeCount !== undefined) {
+    expect(subgraph.nodes.length).toBe(expected.nodeCount)
+  }
+
+  if (expected.name !== undefined) {
+    expect(subgraph.name).toBe(expected.name)
+  }
+
+  if (expected.hasInputNode !== false) {
+    expect(subgraph.inputNode).toBeDefined()
+    expect(subgraph.inputNode.id).toBe(-10)
+  }
+
+  if (expected.hasOutputNode !== false) {
+    expect(subgraph.outputNode).toBeDefined()
+    expect(subgraph.outputNode.id).toBe(-20)
+  }
+}
+
+/**
+ * Verifies that events were fired in the expected sequence.
+ * Useful for testing event-driven behavior.
+ * @param capturedEvents Array of captured events
+ * @param expectedSequence Expected sequence of event types
+ * @example
+ * ```typescript
+ * verifyEventSequence(events, [
+ *   "adding-input",
+ *   "input-added",
+ *   "adding-output",
+ *   "output-added"
+ * ])
+ * ```
+ */
+export function verifyEventSequence<T = unknown>(
+  capturedEvents: CapturedEvent<T>[],
+  expectedSequence: string[],
+): void {
+  expect(capturedEvents.length).toBe(expectedSequence.length)
+
+  for (const [i, element] of expectedSequence.entries()) {
+    expect(capturedEvents[i].type).toBe(element)
+  }
+
+  // Verify timestamps are in order
+  for (let i = 1; i < capturedEvents.length; i++) {
+    expect(capturedEvents[i].timestamp).toBeGreaterThanOrEqual(
+      capturedEvents[i - 1].timestamp,
+    )
+  }
+}
+
+/**
+ * Creates test subgraph data with optional overrides.
+ * Useful for serialization/deserialization tests.
+ * @param overrides Properties to override in the default data
+ * @returns ExportedSubgraph data structure
+ */
+export function createTestSubgraphData(overrides: Partial<ExportedSubgraph> = {}): ExportedSubgraph {
+  return {
+    version: 1,
+    nodes: [],
+    links: {},
+    groups: [],
+    config: {},
+    definitions: { subgraphs: [] },
+
+    id: createUuidv4(),
+    name: "Test Data Subgraph",
+
+    inputNode: {
+      id: -10,
+      bounding: [10, 100, 150, 126],
+      pinned: false,
+    },
+    outputNode: {
+      id: -20,
+      bounding: [400, 100, 140, 126],
+      pinned: false,
+    },
+
+    inputs: [],
+    outputs: [],
+    widgets: [],
+
+    ...overrides,
+  }
+}
+
+/**
+ * Creates a complex subgraph with multiple nodes and connections.
+ * Useful for testing realistic scenarios.
+ * @param nodeCount Number of internal nodes to create
+ * @returns Complex subgraph data structure
+ */
+export function createComplexSubgraphData(nodeCount: number = 5): ExportedSubgraph {
+  const nodes = []
+  const links: Record<string, {
+    id: number
+    origin_id: number
+    origin_slot: number
+    target_id: number
+    target_slot: number
+    type: string
+  }> = {}
+
+  // Create internal nodes
+  for (let i = 0; i < nodeCount; i++) {
+    nodes.push({
+      id: i + 1, // Start from 1 to avoid conflicts with IO nodes
+      type: "basic/test",
+      pos: [100 + i * 150, 200],
+      size: [120, 60],
+      inputs: [{ name: "in", type: "*", link: null }],
+      outputs: [{ name: "out", type: "*", links: [] }],
+      properties: { value: i },
+      flags: {},
+      mode: 0,
+    })
+  }
+
+  // Create some internal links
+  for (let i = 0; i < nodeCount - 1; i++) {
+    const linkId = i + 1
+    links[linkId] = {
+      id: linkId,
+      origin_id: i + 1,
+      origin_slot: 0,
+      target_id: i + 2,
+      target_slot: 0,
+      type: "*",
+    }
+  }
+
+  return createTestSubgraphData({
+    nodes,
+    links,
+    inputs: [
+      { name: "input1", type: "number", pos: [0, 0] },
+      { name: "input2", type: "string", pos: [0, 1] },
+    ],
+    outputs: [
+      { name: "output1", type: "number", pos: [0, 0] },
+      { name: "output2", type: "string", pos: [0, 1] },
+    ],
+  })
+}
+
+/**
+ * Creates an event capture system for testing event sequences.
+ * @param eventTarget The event target to monitor
+ * @param eventTypes Array of event types to capture
+ * @returns Object with captured events and helper methods
+ */
+export function createEventCapture<T = unknown>(
+  eventTarget: EventTarget,
+  eventTypes: string[],
+) {
+  const capturedEvents: CapturedEvent<T>[] = []
+  const listeners: Array<() => void> = []
+
+  // Set up listeners for each event type
+  for (const eventType of eventTypes) {
+    const listener = (event: Event) => {
+      capturedEvents.push({
+        type: eventType,
+        detail: (event as CustomEvent<T>).detail,
+        timestamp: Date.now(),
+      })
+    }
+
+    eventTarget.addEventListener(eventType, listener)
+    listeners.push(() => eventTarget.removeEventListener(eventType, listener))
+  }
+
+  return {
+    events: capturedEvents,
+    clear: () => { capturedEvents.length = 0 },
+    cleanup: () => {
+      // Remove all event listeners to prevent memory leaks
+      for (const cleanup of listeners) cleanup()
+    },
+    getEventsByType: (type: string) => capturedEvents.filter(e => e.type === type),
+  }
+}
+
+/**
+ * Utility to log subgraph structure for debugging tests.
+ * @param subgraph The subgraph to inspect
+ * @param label Optional label for the log output
+ */
+export function logSubgraphStructure(subgraph: Subgraph, label: string = "Subgraph"): void {
+  console.log(`\n=== ${label} Structure ===`)
+  console.log(`Name: ${subgraph.name}`)
+  console.log(`ID: ${subgraph.id}`)
+  console.log(`Inputs: ${subgraph.inputs.length}`)
+  console.log(`Outputs: ${subgraph.outputs.length}`)
+  console.log(`Nodes: ${subgraph.nodes.length}`)
+  console.log(`Links: ${subgraph.links.size}`)
+
+  if (subgraph.inputs.length > 0) {
+    console.log("Input details:", subgraph.inputs.map(i => ({ name: i.name, type: i.type })))
+  }
+
+  if (subgraph.outputs.length > 0) {
+    console.log("Output details:", subgraph.outputs.map(o => ({ name: o.name, type: o.type })))
+  }
+
+  console.log("========================\n")
+}
+
+// Re-export expect from vitest for convenience
+export { expect } from "vitest"

src/lib/litegraph/test/subgraph/fixtures/testSubgraphs.json

@@ -0,0 +1,444 @@
+{
+  "simpleSubgraph": {
+    "version": 1,
+    "nodes": [
+      {
+        "id": 1,
+        "type": "basic/math",
+        "pos": [200, 150],
+        "size": [120, 60],
+        "inputs": [
+          { "name": "a", "type": "number", "link": null },
+          { "name": "b", "type": "number", "link": null }
+        ],
+        "outputs": [
+          { "name": "result", "type": "number", "links": [] }
+        ],
+        "properties": { "operation": "add" },
+        "flags": {},
+        "mode": 0
+      }
+    ],
+    "links": {},
+    "groups": [],
+    "config": {},
+    "definitions": { "subgraphs": [] },
+    
+    "id": "simple-subgraph-uuid",
+    "name": "Simple Math Subgraph",
+    
+    "inputNode": {
+      "id": -10,
+      "type": "subgraph/input",
+      "pos": [10, 100],
+      "size": [140, 26],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    "outputNode": {
+      "id": -20,
+      "type": "subgraph/output",
+      "pos": [400, 100],
+      "size": [140, 26],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    
+    "inputs": [
+      {
+        "name": "input_a",
+        "type": "number",
+        "pos": [0, 0]
+      },
+      {
+        "name": "input_b", 
+        "type": "number",
+        "pos": [0, 1]
+      }
+    ],
+    "outputs": [
+      {
+        "name": "result",
+        "type": "number",
+        "pos": [0, 0]
+      }
+    ],
+    "widgets": []
+  },
+
+  "complexSubgraph": {
+    "version": 1,
+    "nodes": [
+      {
+        "id": 1,
+        "type": "math/multiply",
+        "pos": [150, 100],
+        "size": [120, 60],
+        "inputs": [
+          { "name": "a", "type": "number", "link": null },
+          { "name": "b", "type": "number", "link": null }
+        ],
+        "outputs": [
+          { "name": "result", "type": "number", "links": [1] }
+        ],
+        "properties": {},
+        "flags": {},
+        "mode": 0
+      },
+      {
+        "id": 2,
+        "type": "math/add",
+        "pos": [300, 100],
+        "size": [120, 60],
+        "inputs": [
+          { "name": "a", "type": "number", "link": 1 },
+          { "name": "b", "type": "number", "link": null }
+        ],
+        "outputs": [
+          { "name": "result", "type": "number", "links": [2] }
+        ],
+        "properties": {},
+        "flags": {},
+        "mode": 0
+      },
+      {
+        "id": 3,
+        "type": "logic/compare",
+        "pos": [150, 200],
+        "size": [120, 60],
+        "inputs": [
+          { "name": "a", "type": "number", "link": null },
+          { "name": "b", "type": "number", "link": null }
+        ],
+        "outputs": [
+          { "name": "result", "type": "boolean", "links": [] }
+        ],
+        "properties": { "operation": "greater_than" },
+        "flags": {},
+        "mode": 0
+      },
+      {
+        "id": 4,
+        "type": "string/concat",
+        "pos": [300, 200],
+        "size": [120, 60],
+        "inputs": [
+          { "name": "a", "type": "string", "link": null },
+          { "name": "b", "type": "string", "link": null }
+        ],
+        "outputs": [
+          { "name": "result", "type": "string", "links": [] }
+        ],
+        "properties": {},
+        "flags": {},
+        "mode": 0
+      }
+    ],
+    "links": {
+      "1": {
+        "id": 1,
+        "origin_id": 1,
+        "origin_slot": 0,
+        "target_id": 2,
+        "target_slot": 0,
+        "type": "number"
+      },
+      "2": {
+        "id": 2,
+        "origin_id": 2,
+        "origin_slot": 0,
+        "target_id": -20,
+        "target_slot": 0,
+        "type": "number"
+      }
+    },
+    "groups": [],
+    "config": {},
+    "definitions": { "subgraphs": [] },
+    
+    "id": "complex-subgraph-uuid",
+    "name": "Complex Processing Subgraph",
+    
+    "inputNode": {
+      "id": -10,
+      "type": "subgraph/input",
+      "pos": [10, 150],
+      "size": [140, 86],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    "outputNode": {
+      "id": -20,
+      "type": "subgraph/output",
+      "pos": [450, 150],
+      "size": [140, 66],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    
+    "inputs": [
+      {
+        "name": "number1",
+        "type": "number",
+        "pos": [0, 0]
+      },
+      {
+        "name": "number2",
+        "type": "number",
+        "pos": [0, 1]
+      },
+      {
+        "name": "text1",
+        "type": "string",
+        "pos": [0, 2]
+      },
+      {
+        "name": "text2",
+        "type": "string",
+        "pos": [0, 3]
+      }
+    ],
+    "outputs": [
+      {
+        "name": "calculated_result",
+        "type": "number",
+        "pos": [0, 0]
+      },
+      {
+        "name": "comparison_result",
+        "type": "boolean",
+        "pos": [0, 1]
+      },
+      {
+        "name": "concatenated_text",
+        "type": "string",
+        "pos": [0, 2]
+      }
+    ],
+    "widgets": []
+  },
+
+  "nestedSubgraphLevel1": {
+    "version": 1,
+    "nodes": [],
+    "links": {},
+    "groups": [],
+    "config": {},
+    "definitions": { 
+      "subgraphs": [
+        {
+          "version": 1,
+          "nodes": [
+            {
+              "id": 1,
+              "type": "basic/constant",
+              "pos": [200, 100],
+              "size": [100, 40],
+              "inputs": [],
+              "outputs": [
+                { "name": "value", "type": "number", "links": [] }
+              ],
+              "properties": { "value": 42 },
+              "flags": {},
+              "mode": 0
+            }
+          ],
+          "links": {},
+          "groups": [],
+          "config": {},
+          "definitions": { "subgraphs": [] },
+          
+          "id": "nested-level2-uuid",
+          "name": "Level 2 Subgraph",
+          
+          "inputNode": {
+            "id": -10,
+            "type": "subgraph/input",
+            "pos": [10, 100],
+            "size": [140, 26],
+            "inputs": [],
+            "outputs": [],
+            "properties": {},
+            "flags": {},
+            "mode": 0
+          },
+          "outputNode": {
+            "id": -20,
+            "type": "subgraph/output",
+            "pos": [350, 100],
+            "size": [140, 26],
+            "inputs": [],
+            "outputs": [],
+            "properties": {},
+            "flags": {},
+            "mode": 0
+          },
+          
+          "inputs": [],
+          "outputs": [
+            {
+              "name": "constant_value",
+              "type": "number",
+              "pos": [0, 0]
+            }
+          ],
+          "widgets": []
+        }
+      ]
+    },
+    
+    "id": "nested-level1-uuid",
+    "name": "Level 1 Subgraph",
+    
+    "inputNode": {
+      "id": -10,
+      "type": "subgraph/input",
+      "pos": [10, 100],
+      "size": [140, 26],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    "outputNode": {
+      "id": -20,
+      "type": "subgraph/output",
+      "pos": [400, 100],
+      "size": [140, 26],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    
+    "inputs": [
+      {
+        "name": "external_input",
+        "type": "string",
+        "pos": [0, 0]
+      }
+    ],
+    "outputs": [
+      {
+        "name": "processed_output",
+        "type": "number",
+        "pos": [0, 0]
+      }
+    ],
+    "widgets": []
+  },
+
+  "emptySubgraph": {
+    "version": 1,
+    "nodes": [],
+    "links": {},
+    "groups": [],
+    "config": {},
+    "definitions": { "subgraphs": [] },
+    
+    "id": "empty-subgraph-uuid",
+    "name": "Empty Subgraph",
+    
+    "inputNode": {
+      "id": -10,
+      "type": "subgraph/input",
+      "pos": [10, 100],
+      "size": [140, 26],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    "outputNode": {
+      "id": -20,
+      "type": "subgraph/output",
+      "pos": [400, 100],
+      "size": [140, 26],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    
+    "inputs": [],
+    "outputs": [],
+    "widgets": []
+  },
+
+  "maxIOSubgraph": {
+    "version": 1,
+    "nodes": [],
+    "links": {},
+    "groups": [],
+    "config": {},
+    "definitions": { "subgraphs": [] },
+    
+    "id": "max-io-subgraph-uuid",
+    "name": "Max I/O Subgraph",
+    
+    "inputNode": {
+      "id": -10,
+      "type": "subgraph/input",
+      "pos": [10, 100],
+      "size": [140, 200],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    "outputNode": {
+      "id": -20,
+      "type": "subgraph/output",
+      "pos": [400, 100],
+      "size": [140, 200],
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "flags": {},
+      "mode": 0
+    },
+    
+    "inputs": [
+      { "name": "input_0", "type": "number", "pos": [0, 0] },
+      { "name": "input_1", "type": "string", "pos": [0, 1] },
+      { "name": "input_2", "type": "boolean", "pos": [0, 2] },
+      { "name": "input_3", "type": "number", "pos": [0, 3] },
+      { "name": "input_4", "type": "string", "pos": [0, 4] },
+      { "name": "input_5", "type": "boolean", "pos": [0, 5] },
+      { "name": "input_6", "type": "number", "pos": [0, 6] },
+      { "name": "input_7", "type": "string", "pos": [0, 7] },
+      { "name": "input_8", "type": "boolean", "pos": [0, 8] },
+      { "name": "input_9", "type": "number", "pos": [0, 9] }
+    ],
+    "outputs": [
+      { "name": "output_0", "type": "number", "pos": [0, 0] },
+      { "name": "output_1", "type": "string", "pos": [0, 1] },
+      { "name": "output_2", "type": "boolean", "pos": [0, 2] },
+      { "name": "output_3", "type": "number", "pos": [0, 3] },
+      { "name": "output_4", "type": "string", "pos": [0, 4] },
+      { "name": "output_5", "type": "boolean", "pos": [0, 5] },
+      { "name": "output_6", "type": "number", "pos": [0, 6] },
+      { "name": "output_7", "type": "string", "pos": [0, 7] },
+      { "name": "output_8", "type": "boolean", "pos": [0, 8] },
+      { "name": "output_9", "type": "number", "pos": [0, 9] }
+    ],
+    "widgets": []
+  }
+}

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

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest"
+
+import { LGraph } from "@/litegraph"
+
+import { createTestSubgraph, createTestSubgraphNode } from "./fixtures/subgraphHelpers"
+
+describe("Subgraph Serialization", () => {
+  describe("LGraph.asSerialisable", () => {
+    it("should not include unused subgraph definitions", () => {
+      const rootGraph = new LGraph()
+
+      // Create subgraphs
+      const usedSubgraph = createTestSubgraph({ name: "Used Subgraph" })
+      const unusedSubgraph = createTestSubgraph({ name: "Unused Subgraph" })
+
+      // Add both to registry
+      rootGraph._subgraphs.set(usedSubgraph.id, usedSubgraph)
+      rootGraph._subgraphs.set(unusedSubgraph.id, unusedSubgraph)
+
+      // Only add node for used subgraph
+      const node = createTestSubgraphNode(usedSubgraph)
+      rootGraph.add(node)
+
+      // Serialize
+      const serialized = rootGraph.asSerialisable()
+
+      // Check that only used subgraph is included
+      expect(serialized.definitions?.subgraphs).toBeDefined()
+      expect(serialized.definitions!.subgraphs!.length).toBe(1)
+      expect(serialized.definitions!.subgraphs![0].id).toBe(usedSubgraph.id)
+      expect(serialized.definitions!.subgraphs![0].name).toBe("Used Subgraph")
+    })
+
+    it("should include nested subgraphs", () => {
+      const rootGraph = new LGraph()
+
+      // Create nested subgraphs
+      const level1Subgraph = createTestSubgraph({ name: "Level 1" })
+      const level2Subgraph = createTestSubgraph({ name: "Level 2" })
+
+      // Add to registry
+      rootGraph._subgraphs.set(level1Subgraph.id, level1Subgraph)
+      rootGraph._subgraphs.set(level2Subgraph.id, level2Subgraph)
+
+      // Add level1 to root
+      const level1Node = createTestSubgraphNode(level1Subgraph)
+      rootGraph.add(level1Node)
+
+      // Add level2 to level1
+      const level2Node = createTestSubgraphNode(level2Subgraph)
+      level1Subgraph.add(level2Node)
+
+      // Serialize
+      const serialized = rootGraph.asSerialisable()
+
+      // Both subgraphs should be included
+      expect(serialized.definitions?.subgraphs).toBeDefined()
+      expect(serialized.definitions!.subgraphs!.length).toBe(2)
+
+      const ids = serialized.definitions!.subgraphs!.map(s => s.id)
+      expect(ids).toContain(level1Subgraph.id)
+      expect(ids).toContain(level2Subgraph.id)
+    })
+
+    it("should handle circular subgraph references", () => {
+      const rootGraph = new LGraph()
+
+      // Create two subgraphs that reference each other
+      const subgraph1 = createTestSubgraph({ name: "Subgraph 1" })
+      const subgraph2 = createTestSubgraph({ name: "Subgraph 2" })
+
+      // Add to registry
+      rootGraph._subgraphs.set(subgraph1.id, subgraph1)
+      rootGraph._subgraphs.set(subgraph2.id, subgraph2)
+
+      // Add subgraph1 to root
+      const node1 = createTestSubgraphNode(subgraph1)
+      rootGraph.add(node1)
+
+      // Add subgraph2 to subgraph1
+      const node2 = createTestSubgraphNode(subgraph2)
+      subgraph1.add(node2)
+
+      // Add subgraph1 to subgraph2 (circular)
+      const node3 = createTestSubgraphNode(subgraph1, { id: 3 })
+      subgraph2.add(node3)
+
+      // Serialize - should not hang
+      const serialized = rootGraph.asSerialisable()
+
+      // Both should be included
+      expect(serialized.definitions?.subgraphs).toBeDefined()
+      expect(serialized.definitions!.subgraphs!.length).toBe(2)
+    })
+
+    it("should handle empty subgraph registry", () => {
+      const rootGraph = new LGraph()
+
+      // Serialize with no subgraphs
+      const serialized = rootGraph.asSerialisable()
+
+      // Should not include definitions
+      expect(serialized.definitions).toBeUndefined()
+    })
+
+    it("should only serialize from root graph", () => {
+      const rootGraph = new LGraph()
+      const subgraph = createTestSubgraph({ name: "Parent Subgraph" })
+
+      // Add subgraph to root registry
+      rootGraph._subgraphs.set(subgraph.id, subgraph)
+
+      // Try to serialize from subgraph (not root)
+      const serialized = subgraph.asSerialisable()
+
+      // Should not include definitions since it's not the root
+      expect(serialized.definitions).toBeUndefined()
+    })
+
+    it("should handle multiple instances of same subgraph", () => {
+      const rootGraph = new LGraph()
+      const subgraph = createTestSubgraph({ name: "Reused Subgraph" })
+
+      // Add to registry
+      rootGraph._subgraphs.set(subgraph.id, subgraph)
+
+      // Add multiple instances
+      const node1 = createTestSubgraphNode(subgraph, { id: 1 })
+      const node2 = createTestSubgraphNode(subgraph, { id: 2 })
+      const node3 = createTestSubgraphNode(subgraph, { id: 3 })
+
+      rootGraph.add(node1)
+      rootGraph.add(node2)
+      rootGraph.add(node3)
+
+      // Serialize
+      const serialized = rootGraph.asSerialisable()
+
+      // Should only include one definition
+      expect(serialized.definitions?.subgraphs).toBeDefined()
+      expect(serialized.definitions!.subgraphs!.length).toBe(1)
+      expect(serialized.definitions!.subgraphs![0].id).toBe(subgraph.id)
+    })
+  })
+})

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

@@ -0,0 +1,147 @@
+import type { UUID } from "@/utils/uuid"
+
+import { describe, expect, it } from "vitest"
+
+import { LGraph } from "@/litegraph"
+import {
+  findUsedSubgraphIds,
+  getDirectSubgraphIds,
+} from "@/subgraph/subgraphUtils"
+
+import { createTestSubgraph, createTestSubgraphNode } from "./fixtures/subgraphHelpers"
+
+describe("subgraphUtils", () => {
+  describe("getDirectSubgraphIds", () => {
+    it("should return empty set for graph with no subgraph nodes", () => {
+      const graph = new LGraph()
+      const result = getDirectSubgraphIds(graph)
+      expect(result.size).toBe(0)
+    })
+
+    it("should find single subgraph node", () => {
+      const graph = new LGraph()
+      const subgraph = createTestSubgraph()
+      const subgraphNode = createTestSubgraphNode(subgraph)
+      graph.add(subgraphNode)
+
+      const result = getDirectSubgraphIds(graph)
+      expect(result.size).toBe(1)
+      expect(result.has(subgraph.id)).toBe(true)
+    })
+
+    it("should find multiple unique subgraph nodes", () => {
+      const graph = new LGraph()
+      const subgraph1 = createTestSubgraph({ name: "Subgraph 1" })
+      const subgraph2 = createTestSubgraph({ name: "Subgraph 2" })
+
+      const node1 = createTestSubgraphNode(subgraph1)
+      const node2 = createTestSubgraphNode(subgraph2)
+
+      graph.add(node1)
+      graph.add(node2)
+
+      const result = getDirectSubgraphIds(graph)
+      expect(result.size).toBe(2)
+      expect(result.has(subgraph1.id)).toBe(true)
+      expect(result.has(subgraph2.id)).toBe(true)
+    })
+
+    it("should return unique IDs when same subgraph is used multiple times", () => {
+      const graph = new LGraph()
+      const subgraph = createTestSubgraph()
+
+      const node1 = createTestSubgraphNode(subgraph, { id: 1 })
+      const node2 = createTestSubgraphNode(subgraph, { id: 2 })
+
+      graph.add(node1)
+      graph.add(node2)
+
+      const result = getDirectSubgraphIds(graph)
+      expect(result.size).toBe(1)
+      expect(result.has(subgraph.id)).toBe(true)
+    })
+  })
+
+  describe("findUsedSubgraphIds", () => {
+    it("should handle graph with no subgraphs", () => {
+      const graph = new LGraph()
+      const registry = new Map<UUID, any>()
+
+      const result = findUsedSubgraphIds(graph, registry)
+      expect(result.size).toBe(0)
+    })
+
+    it("should find nested subgraphs", () => {
+      const rootGraph = new LGraph()
+      const subgraph1 = createTestSubgraph({ name: "Level 1" })
+      const subgraph2 = createTestSubgraph({ name: "Level 2" })
+
+      // Add subgraph1 node to root
+      const node1 = createTestSubgraphNode(subgraph1)
+      rootGraph.add(node1)
+
+      // Add subgraph2 node inside subgraph1
+      const node2 = createTestSubgraphNode(subgraph2)
+      subgraph1.add(node2)
+
+      const registry = new Map<UUID, any>([
+        [subgraph1.id, subgraph1],
+        [subgraph2.id, subgraph2],
+      ])
+
+      const result = findUsedSubgraphIds(rootGraph, registry)
+      expect(result.size).toBe(2)
+      expect(result.has(subgraph1.id)).toBe(true)
+      expect(result.has(subgraph2.id)).toBe(true)
+    })
+
+    it("should handle circular references without infinite loop", () => {
+      const rootGraph = new LGraph()
+      const subgraph1 = createTestSubgraph({ name: "Subgraph 1" })
+      const subgraph2 = createTestSubgraph({ name: "Subgraph 2" })
+
+      // Add subgraph1 to root
+      const node1 = createTestSubgraphNode(subgraph1)
+      rootGraph.add(node1)
+
+      // Add subgraph2 to subgraph1
+      const node2 = createTestSubgraphNode(subgraph2)
+      subgraph1.add(node2)
+
+      // Add subgraph1 to subgraph2 (circular reference)
+      const node3 = createTestSubgraphNode(subgraph1, { id: 3 })
+      subgraph2.add(node3)
+
+      const registry = new Map<UUID, any>([
+        [subgraph1.id, subgraph1],
+        [subgraph2.id, subgraph2],
+      ])
+
+      const result = findUsedSubgraphIds(rootGraph, registry)
+      expect(result.size).toBe(2)
+      expect(result.has(subgraph1.id)).toBe(true)
+      expect(result.has(subgraph2.id)).toBe(true)
+    })
+
+    it("should handle missing subgraphs in registry gracefully", () => {
+      const rootGraph = new LGraph()
+      const subgraph1 = createTestSubgraph({ name: "Subgraph 1" })
+      const subgraph2 = createTestSubgraph({ name: "Subgraph 2" })
+
+      // Add both subgraph nodes
+      const node1 = createTestSubgraphNode(subgraph1)
+      const node2 = createTestSubgraphNode(subgraph2)
+
+      rootGraph.add(node1)
+      rootGraph.add(node2)
+
+      // Only register subgraph1
+      const registry = new Map<UUID, any>([[subgraph1.id, subgraph1]])
+
+      const result = findUsedSubgraphIds(rootGraph, registry)
+      expect(result.size).toBe(2)
+      expect(result.has(subgraph1.id)).toBe(true)
+      expect(result.has(subgraph2.id)).toBe(true) // Still found, just can't recurse into it
+    })
+  })
+})