feat: some updates

fix: make the runtime work with groups
feat(ci): split e2e and unit tests
2026-05-04 11:27:21 +02:00 · 2026-05-03 17:49:14 +02:00 · 2026-05-03 17:49:00 +02:00 · 2026-05-03 17:12:49 +02:00 · 2026-05-03 17:10:13 +02:00 · 2026-05-03 17:04:13 +02:00
38 changed files with 1761 additions and 427 deletions
@@ -0,0 +1,28 @@
+name: Setup
+description: Restore caches and install pnpm dependencies (run after checkout)
+
+runs:
+  using: composite
+  steps:
+    - name: 💾 Setup pnpm Cache
+      uses: actions/cache@v4
+      with:
+        path: .pnpm-store
+        key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-
+
+    - name: 🦀 Cache Cargo
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+          target
+        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-cargo-
+
+    - name: 📦 Install Dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile --store-dir .pnpm-store
@@ -12,9 +12,9 @@ env:
  CARGO_TARGET_DIR: target

 jobs:
-  release:
+  benchmark:
    runs-on: ubuntu-latest
-    container: git.max-richter.dev/max/nodarium-ci:bce06da456e3c008851ac006033cfff256015a47
+    container: git.max-richter.dev/max/nodarium-ci:a56e8f445edb6064ae7a7b3b783fb7445f1b4e69

    steps:
      - name: 📑 Checkout Code
@@ -23,37 +23,45 @@ jobs:
          fetch-depth: 0
          token: ${{ secrets.GITEA_TOKEN }}

-      - name: 💾 Setup pnpm Cache
-        uses: actions/cache@v4
-        with:
-          path: ${{ env.PNPM_CACHE_FOLDER }}
-          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-
+      - name: 🔧 Setup
+        uses: ./.gitea/actions/setup

-      - name: 🦀 Cache Cargo
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-
-
-      - name: 📦 Install Dependencies
-        run: pnpm install --frozen-lockfile --store-dir ${{ env.PNPM_CACHE_FOLDER }}
-
-      - name: 🛠️Build Nodes
+      - name: 🛠️ Build Nodes
        run: pnpm build:nodes

      - name: 🏃 Execute Runtime
        run: pnpm run --filter @nodarium/app bench

-      - name: 📤 Upload Benchmark Results
-        uses: actions/upload-artifact@v3
-        with:
-          name: benchmark-data
-          path: app/benchmark/out/
-          compression: 9
+      - name: 🔑 Setup SSH key
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.GIT_SSH_PRIVATE_KEY }}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          cat >> ~/.ssh/config <<'EOF'
+          Host git.max-richter.dev
+            Port 2222
+            IdentityFile ~/.ssh/id_ed25519
+            IdentitiesOnly yes
+          EOF
+          ssh-keyscan -p 2222 -H git.max-richter.dev >> ~/.ssh/known_hosts
+
+      - name: 📤 Push Results
+        env:
+          BENCH_REPO: "git@git.max-richter.dev:max/nodarium-benchmarks.git"
+        run: |
+          git config --global user.name "nodarium-bot"
+          git config --global user.email "nodarium-bot@max-richter.dev"
+
+          git clone git@git.max-richter.dev:max/nodarium-benchmarks.git target_bench_repo
+
+          BRANCH="${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}"
+          SAFE_PR_NAME=$(printf "%s" "$BRANCH" | tr '/' '-')
+          DEST_DIR="target_bench_repo/data/$SAFE_PR_NAME/$(date +%s)"
+          mkdir -p "$DEST_DIR"
+
+          cp app/benchmark/out/*.json "$DEST_DIR/"
+
+          cd target_bench_repo
+          git add .
+          git commit -m "Update benchmarks for $SAFE_PR_NAME: ${{ gitea.sha }}"
+          git push origin main
@@ -13,9 +13,9 @@ env:
  CARGO_TARGET_DIR: target

 jobs:
-  release:
+  quality:
    runs-on: ubuntu-latest
-    container: git.max-richter.dev/max/nodarium-ci:bce06da456e3c008851ac006033cfff256015a47
+    container: git.max-richter.dev/max/nodarium-ci:a56e8f445edb6064ae7a7b3b783fb7445f1b4e69

    steps:
      - name: 📑 Checkout Code
@@ -24,27 +24,8 @@ jobs:
          fetch-depth: 0
          token: ${{ secrets.GITEA_TOKEN }}

-      - name: 💾 Setup pnpm Cache
-        uses: actions/cache@v4
-        with:
-          path: ${{ env.PNPM_CACHE_FOLDER }}
-          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-
-
-      - name: 🦀 Cache Cargo
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-
-
-      - name: 📦 Install Dependencies
-        run: pnpm install --frozen-lockfile --store-dir ${{ env.PNPM_CACHE_FOLDER }}
+      - name: 🔧 Setup
+        uses: ./.gitea/actions/setup

      - name: 🧹 Quality Control
        run: |
@@ -52,7 +33,58 @@ jobs:
          pnpm format:check
          pnpm check
          pnpm build
-          xvfb-run --auto-servernum --server-args="-screen 0 1280x1024x24" pnpm test
+
+  test-unit:
+    runs-on: ubuntu-latest
+    container: git.max-richter.dev/max/nodarium-ci:a56e8f445edb6064ae7a7b3b783fb7445f1b4e69
+
+    steps:
+      - name: 📑 Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITEA_TOKEN }}
+
+      - name: 🔧 Setup
+        uses: ./.gitea/actions/setup
+
+      - name: 🧪 Run Tests
+        run: xvfb-run --auto-servernum --server-args="-screen 0 1280x1024x24" pnpm test:unit
+
+  test-e2e:
+    runs-on: ubuntu-latest
+    container: git.max-richter.dev/max/nodarium-ci:a56e8f445edb6064ae7a7b3b783fb7445f1b4e69
+
+    steps:
+      - name: 📑 Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITEA_TOKEN }}
+
+      - name: 🔧 Setup
+        uses: ./.gitea/actions/setup
+
+      - name: 🧪 Run Tests
+        run: xvfb-run --auto-servernum --server-args="-screen 0 1280x1024x24" pnpm test:e2e
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [quality, test-e2e, test-unit]
+    container: git.max-richter.dev/max/nodarium-ci:a56e8f445edb6064ae7a7b3b783fb7445f1b4e69
+
+    steps:
+      - name: 📑 Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITEA_TOKEN }}
+
+      - name: 🔧 Setup
+        uses: ./.gitea/actions/setup
+
+      - name: 🏗️ Build Web Assets
+        run: pnpm build

      - name: 🚀 Create Release Commit
        if: gitea.ref_type == 'tag'
@@ -5,6 +5,7 @@ ENV RUSTUP_HOME=/usr/local/rustup \
  PATH=/usr/local/cargo/bin:$PATH

 RUN apt-get update && apt-get install -y \
+  openssh-client \
  ca-certificates=20230311+deb12u1 \
  gpg=2.2.40-1.1+deb12u2 \
  gpg-agent=2.2.40-1.1+deb12u2 \
@@ -1,5 +1,5 @@
 import type { Graph, Graph as GraphType, NodeId } from '@nodarium/types';
-import { createLogger, createPerformanceStore } from '@nodarium/utils';
+import { createLogger, createPerformanceStore, splitNestedArray } from '@nodarium/utils';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { MemoryRuntimeExecutor } from '../src/lib/runtime/runtime-executor.ts';
@@ -20,6 +20,26 @@ const templates: Record<string, Graph> = {
  'default': defaultPlantTemplate as unknown as GraphType
 };

+function countGeometry(result: Int32Array): { totalVertices: number; totalFaces: number } {
+  const parts = splitNestedArray(result);
+  let totalVertices = 0;
+  let totalFaces = 0;
+  for (const part of parts) {
+    const type = part[0];
+    const vertexCount = part[1];
+    const faceCount = part[2];
+    if (type === 2) {
+      const instanceCount = part[3];
+      totalVertices += vertexCount * instanceCount;
+      totalFaces += faceCount * instanceCount;
+    } else {
+      totalVertices += vertexCount;
+      totalFaces += faceCount;
+    }
+  }
+  return { totalVertices, totalFaces };
+}
+
 async function run(g: GraphType, amount: number) {
  await registry.load(plantTemplate.nodes.map(n => n.type) as NodeId[]);
  log.log('loaded ' + g.nodes.length + ' nodes');
@@ -33,10 +53,14 @@ async function run(g: GraphType, amount: number) {

  log.log('executing');
  r.perf = perfStore;
+  let res;
  for (let i = 0; i < amount; i++) {
    r.perf?.startRun();
-    await r.execute(g, { randomSeed: true });
+    res = await r.execute(g, { randomSeed: true });
    r.perf?.stopRun();
+    const { totalVertices, totalFaces } = countGeometry(res!);
+    r.perf?.addToLastRun('total-vertices', totalVertices);
+    r.perf?.addToLastRun('total-faces', totalFaces);
  }
  log.log('finished');
  return r.perf.get();
@@ -183,7 +183,7 @@
            activeNodeId = node.id;
          }}
        >
-          {node.id.split('/').at(-1)}
+          {node.meta?.title ?? node.id.split('/').at(-1)}
        </div>
      {/each}
    </div>
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { assert, describe, expect, it } from 'vitest';
 import { GraphManager } from './graph-manager.svelte';
 import {
  createMockNodeRegistry,
@@ -9,8 +9,151 @@ import {
  mockVec3OutputNode
 } from './test-utils';

-describe('GraphManager', () => {
-  describe('getPossibleSockets', () => {
+describe('groupNodes', () => {
+  it('should not do anything if no nodes are selected', () => {
+    const registry = createMockNodeRegistry([
+      mockFloatOutputNode,
+      mockFloatInputNode,
+      mockGeometryOutputNode,
+      mockPathInputNode
+    ]);
+
+    const manager = new GraphManager(registry);
+
+    const floatInputNode = manager.createNode({
+      type: 'test/node/input',
+      position: [100, 100],
+      props: {}
+    });
+
+    assert.isDefined(floatInputNode);
+
+    const floatOutputNode = manager.createNode({
+      type: 'test/node/output',
+      position: [0, 0],
+      props: {}
+    });
+    assert.isDefined(floatOutputNode);
+
+    const edge = manager.createEdge(floatInputNode, 0, floatOutputNode, 'input');
+    assert.isDefined(edge);
+    manager.save();
+
+    manager.groupNodes([]);
+
+    const graph = manager.serialize();
+    expect(graph.nodes.length).toBe(2);
+    expect(graph.edges.length).toBe(1);
+    expect(graph.groups.length).toBe(0);
+  });
+
+  it('should group selected nodes and create a group node', () => {
+    const registry = createMockNodeRegistry([
+      mockFloatOutputNode,
+      mockFloatInputNode,
+      mockGeometryOutputNode,
+      mockPathInputNode
+    ]);
+
+    const manager = new GraphManager(registry);
+
+    const floatInputNode = manager.createNode({
+      type: 'test/node/input',
+      position: [100, 100],
+      props: {}
+    });
+
+    assert.isDefined(floatInputNode);
+
+    const floatOutputNode = manager.createNode({
+      type: 'test/node/output',
+      position: [0, 0],
+      props: {}
+    });
+    assert.isDefined(floatOutputNode);
+
+    const edge = manager.createEdge(floatInputNode, 0, floatOutputNode, 'input');
+    assert.isDefined(edge);
+    manager.save();
+
+    const groupNode = manager.groupNodes([floatInputNode.id]);
+    assert.isDefined(groupNode);
+
+    const graph = manager.serialize();
+
+    expect(graph.nodes.map(n => n.id), 'graph to contain group node').to.contain(groupNode.id);
+    expect(graph.groups[0].nodes.map(n => n.id), 'group graph to contain float node').to.contain(
+      floatInputNode.id
+    );
+    expect(graph.nodes.map(n => n.id)).not.to.contain(floatInputNode.id);
+
+    expect(graph.nodes.length).toBe(2);
+    expect(graph.edges.length).toBe(1);
+    expect(graph.groups.length).toBe(1);
+  });
+
+  it('should rewire external edges when grouping a middle node in a chain', () => {
+    const registry = createMockNodeRegistry([mockFloatOutputNode, mockFloatInputNode]);
+    const manager = new GraphManager(registry);
+
+    // A → B → C  (float chain: output → middle → input)
+    const nodeA = manager.createNode({ type: 'test/node/output', position: [0, 0], props: {} });
+    const nodeB = manager.createNode({ type: 'test/node/output', position: [100, 0], props: {} });
+    const nodeC = manager.createNode({ type: 'test/node/input', position: [200, 0], props: {} });
+
+    assert.isDefined(nodeA);
+    assert.isDefined(nodeB);
+    assert.isDefined(nodeC);
+
+    manager.createEdge(nodeA, 0, nodeB, 'input');
+    manager.createEdge(nodeB, 0, nodeC, 'value');
+
+    const groupNode = manager.groupNodes([nodeB.id]);
+    assert.isDefined(groupNode);
+
+    const graph = manager.serialize();
+
+    // Top-level: A, C, groupNode — B is gone
+    expect(graph.nodes.length, 'top-level node count').toBe(3);
+    const topLevelIds = graph.nodes.map(n => n.id);
+    expect(topLevelIds).toContain(nodeA.id);
+    expect(topLevelIds).toContain(nodeC.id);
+    expect(topLevelIds).toContain(groupNode.id);
+    expect(topLevelIds).not.toContain(nodeB.id);
+
+    // Both original edges survive, now routing through the group node
+    expect(graph.edges.length, 'edge count unchanged').toBe(2);
+    const edgeSources = graph.edges.map(e => e[0]);
+    const edgeTargets = graph.edges.map(e => e[2]);
+    expect(edgeTargets).toContain(groupNode.id); // A → groupNode
+    expect(edgeSources).toContain(groupNode.id); // groupNode → C
+
+    // One group definition was created
+    expect(graph.groups.length).toBe(1);
+    const group = graph.groups[0];
+
+    // Group contains B plus the two boundary nodes
+    const groupNodeIds = group.nodes.map(n => n.id);
+    expect(groupNodeIds).toContain(nodeB.id);
+    const inputBoundary = group.nodes.find(n => n.type === '__internal/group/input');
+    const outputBoundary = group.nodes.find(n => n.type === '__internal/group/output');
+    expect(inputBoundary, 'group input boundary node').toBeDefined();
+    expect(outputBoundary, 'group output boundary node').toBeDefined();
+
+    // Group declares one input slot and one output slot
+    expect(Object.keys(group.inputs ?? {}).length, 'group input count').toBe(1);
+    expect(group.outputs?.length, 'group output count').toBe(1);
+
+    // Internal edges wire: inputBoundary → B → outputBoundary
+    expect(group.edges.length, 'internal edge count').toBe(2);
+    const internalSources = group.edges.map(e => e[0]);
+    const internalTargets = group.edges.map(e => e[2]);
+    expect(internalTargets).toContain(nodeB.id);
+    expect(internalSources).toContain(nodeB.id);
+  });
+});
+
+describe('getPossibleSockets', () => {
  describe('when dragging an output socket', () => {
    it('should return compatible input sockets based on type', () => {
      const registry = createMockNodeRegistry([
@@ -261,5 +404,4 @@ describe('GraphManager', () => {
      expect(possibleSocketsForFloat.map(([n]) => n.id)).toContain(floatInputNode!.id);
    });
  });
-  });
 });
@@ -1,8 +1,10 @@
 import throttle from '$lib/helpers/throttle';
 import { RemoteNodeRegistry } from '$lib/node-registry/index';
 import type {
+  Box,
  Edge,
  Graph,
+  GroupDefinition,
  NodeDefinition,
  NodeId,
  NodeInput,
@@ -17,7 +19,7 @@ import EventEmitter from './helpers/EventEmitter';
 import { HistoryManager } from './history-manager';

 const logger = createLogger('graph-manager');
-logger.mute();
+// logger.mute();

 const remoteRegistry = new RemoteNodeRegistry('');

@@ -67,13 +69,26 @@ export class GraphManager extends EventEmitter<{
  status = $state<'loading' | 'idle' | 'error'>();
  loaded = false;

-  graph: Graph = { id: 0, nodes: [], edges: [] };
+  graph: Graph = { id: 0, nodes: [], edges: [], groups: [] };
  id = $state(0);

  nodes = new SvelteMap<number, NodeInstance>();
+  nodeArray = $derived(Array.from(this.nodes.values()));

  edges = $state<Edge[]>([]);

+  // Plain array — NOT $state. rootGraph items are plain-serialized (safe for structuredClone).
+  // savedNodes/savedEdges hold live reactive references so reactivity is preserved on exit.
+  graphStack: {
+    rootGraph: Graph;
+    savedNodes: Map<number, NodeInstance>;
+    savedEdges: Edge[];
+    outerGraph: Graph;
+    groupId: number;
+    nodeId: number;
+    cameraPosition: [number, number, number];
+  }[] = [];
+
  settingTypes: Record<string, NodeInput> = {};
  settings = $state<Record<string, unknown>>();

@@ -88,9 +103,25 @@ export class GraphManager extends EventEmitter<{
  });

  history: HistoryManager = new HistoryManager();
+
+  private serializeFullGraph(): Graph {
+    if (this.graphStack.length === 0) return this.serialize();
+    let merged = this.serialize();
+    for (let i = this.graphStack.length - 1; i >= 0; i--) {
+      const { rootGraph, groupId } = this.graphStack[i];
+      merged = {
+        ...rootGraph,
+        groups: rootGraph.groups.map(g =>
+          g.id === groupId ? { ...g, nodes: merged.nodes, edges: merged.edges } : g
+        )
+      };
+    }
+    return merged;
+  }
+
  execute = throttle(() => {
    if (this.loaded === false) return;
-    this.emit('result', this.serialize());
+    this.emit('result', this.serializeFullGraph());
  }, 10);

  constructor(public registry: NodeRegistry) {
@@ -110,10 +141,29 @@ export class GraphManager extends EventEmitter<{
      edge[2].id,
      edge[3]
    ]) as Graph['edges'];
+
+    const groups = this.graph.groups?.map((group) => {
+      const groupNodes = group.nodes.map((node) => ({
+        id: node.id,
+        position: [...node.position],
+        type: node.type,
+        props: node.props
+      })) as NodeInstance[];
+
+      return {
+        id: group.id,
+        inputs: group.inputs,
+        outputs: group.outputs,
+        nodes: groupNodes,
+        edges: group.edges
+      };
+    });
+
    const serialized = {
      id: this.graph.id,
      settings: $state.snapshot(this.settings),
      meta: $state.snapshot(this.graph.meta),
+      groups,
      nodes,
      edges
    };
@@ -242,6 +292,28 @@ export class GraphManager extends EventEmitter<{
    });
  }

+  tryConnectToDebugNode(nodeId: number) {
+    const node = this.nodes.get(nodeId);
+    if (!node) return;
+    if (node.type.endsWith('/debug')) return;
+    if (!node.state.type?.outputs?.length) return;
+    let debugNode = this.nodes.values().find(n => n.type.endsWith('/debug'));
+
+    if (!debugNode) {
+      debugNode = this.createNode({
+        type: '__internal/node/debug',
+        position: [node.position[0] + 30, node.position[1]],
+        props: {}
+      });
+    }
+
+    if (debugNode) {
+      this.createEdge(node, 0, debugNode, 'input');
+    }
+
+    return debugNode;
+  }
+
  getEdgesBetweenNodes(nodes: NodeInstance[]): [number, number, number, string][] {
    const edges = [];
    for (const node of nodes) {
@@ -269,13 +341,11 @@ export class GraphManager extends EventEmitter<{
  private _init(graph: Graph) {
    const nodes = new SvelteMap(
      graph.nodes.map((node) => {
-        const nodeType = this.registry.getNode(node.type);
        const n = node as NodeInstance;
-        if (nodeType) {
-          n.state = {
-            type: nodeType
-          };
-        }
+        const registryType = this.registry.getNode(node.type);
+        n.state = registryType ? { type: registryType } : {};
+        const resolvedType = this.getNodeType(n);
+        if (resolvedType) n.state = { type: resolvedType };
        return [node.id, n];
      })
    );
@@ -305,19 +375,36 @@ export class GraphManager extends EventEmitter<{
    const a = performance.now();

    this.loaded = false;
+    graph.groups ??= [];
    this.graph = graph;
    this.status = 'loading';
    this.id = graph.id;

-    logger.info('loading graph', { nodes: graph.nodes, edges: graph.edges, id: graph.id });
+    logger.info(
+      'loading graph',
+      { nodes: graph.nodes, edges: graph.edges, id: graph.id }
+    );
+
+    const nodeIds = Array
+      .from(
+        new SvelteSet(
+          [
+            ...graph.nodes,
+            graph?.groups?.map(g => g.nodes).flat()
+          ]
+            .filter(n => n && 'type' in n)
+            .map((n) => n.type)
+        )
+      )
+      .filter(n => !n.startsWith('__internal/'));

-    const nodeIds = Array.from(new SvelteSet([...graph.nodes.map((n) => n.type)]));
    await this.registry.load(nodeIds);

    // Fetch all nodes from all collections of the loaded nodes
    const allCollections = new SvelteSet<`${string}/${string}`>();
    for (const id of nodeIds) {
      const [user, collection] = id.split('/');
+      if (user === '__internal') continue;
      allCollections.add(`${user}/${collection}`);
    }
    for (const collection of allCollections) {
@@ -333,7 +420,7 @@ export class GraphManager extends EventEmitter<{

    for (const node of this.graph.nodes) {
      const nodeType = this.registry.getNode(node.type);
-      if (!nodeType) {
+      if (!nodeType && !node.type.startsWith('__internal/')) {
        logger.error(`Node type not found: ${node.type}`);
        this.status = 'error';
        return;
@@ -389,15 +476,79 @@ export class GraphManager extends EventEmitter<{
  }

  getAllNodes() {
-    return Array.from(this.nodes.values());
+    return Array
+      .from(this.nodes.values());
  }

  getNode(id: number) {
    return this.nodes.get(id);
  }

-  getNodeType(id: string) {
-    return this.registry.getNode(id);
+  getNodeType(node: NodeInstance) {
+    if (!node) {
+      console.trace('failed to get node type');
+      return;
+    }
+
+    if (node.type === '__internal/group/input') {
+      const groupId = this.graphStack.at(-1)?.groupId;
+      const group = groupId !== undefined ? this.getGroup(groupId) : undefined;
+      if (!group) return node.state.type;
+      return {
+        id: '__internal/group/input' as NodeId,
+        outputs: Object.values(group.inputs ?? {}).map(i => i.type),
+        execute: (x: Int32Array) => x
+      } as NodeDefinition;
+    }
+
+    if (node.type === '__internal/group/output') {
+      const groupId = this.graphStack.at(-1)?.groupId;
+      const group = groupId !== undefined ? this.getGroup(groupId) : undefined;
+      if (!group) return node.state.type;
+      return {
+        id: '__internal/group/output' as NodeId,
+        inputs: Object.fromEntries(
+          (group.outputs ?? []).map((
+            o,
+            i
+          ) => [`out_${i}`, { type: o.type, label: o.label, external: true }])
+        ),
+        outputs: [],
+        execute: (x: Int32Array) => x
+      } as NodeDefinition;
+    }
+
+    // Construct the group inputs on the fly
+    if (node.type === '__internal/group/instance') {
+      const groupDefinition = this.getGroup(node.props?.groupId as number);
+
+      if (!groupDefinition) {
+        logger.error(`Group not found: ${node.props?.groupId}`);
+        return;
+      }
+
+      const inputs = {
+        ...(node.state.type?.inputs || {}),
+        ...groupDefinition?.inputs,
+        'groupId': {
+          type: 'select',
+          label: '',
+          value: node.props?.groupId,
+          internal: true,
+          options: this.graph.groups.map(g => g.id)
+        }
+      };
+
+      const groupType = {
+        ...node.state.type,
+        inputs,
+        outputs: groupDefinition?.outputs?.map(o => o.type)
+      } as NodeDefinition;
+
+      return groupType;
+    }
+
+    return node.state.type;
  }

  async loadNodeType(id: NodeId) {
@@ -459,6 +610,7 @@ export class GraphManager extends EventEmitter<{
  }

  removeNode(node: NodeInstance, { restoreEdges = false } = {}) {
+    console.log('REMOVING NODE', $state.snapshot({ node }));
    const edgesToNode = this.edges.filter((edge) => edge[2].id === node.id);
    const edgesFromNode = this.edges.filter((edge) => edge[0].id === node.id);
    for (const edge of [...edgesToNode, ...edgesFromNode]) {
@@ -502,8 +654,76 @@ export class GraphManager extends EventEmitter<{
    }
  }

+  getGroup(id: number) {
+    return this.graph.groups.find(g => g.id === id);
+  }
+
+  isInsideGroup = $state(false);
+
+  enterGroup(nodeId: number, cameraPosition: [number, number, number]): boolean {
+    const groupNode = this.getNode(nodeId);
+    if (!groupNode || groupNode.type !== '__internal/group/instance') return false;
+    const groupId = groupNode.props?.groupId as number;
+    const group = this.getGroup(groupId);
+    if (!group) return false;
+
+    this.graphStack.push({
+      rootGraph: this.serialize(),
+      savedNodes: new Map(this.nodes),
+      savedEdges: [...this.edges],
+      outerGraph: this.graph,
+      groupId,
+      nodeId,
+      cameraPosition
+    });
+    this.graph = { ...this.graph, nodes: group.nodes, edges: group.edges };
+    this._init(this.graph);
+    this.history.reset();
+    this.isInsideGroup = true;
+    return true;
+  }
+
+  exitGroup(): { camera: [number, number, number]; nodeId: number } | false {
+    if (!this.graphStack.length) return false;
+    const { savedNodes, savedEdges, outerGraph, groupId, nodeId, cameraPosition } = this.graphStack.pop()!;
+    const internalState = this.serialize();
+
+    // Restore live reactive nodes and edges so drag-reactivity is preserved
+    this.nodes.clear();
+    for (const [id, node] of savedNodes) {
+      this.nodes.set(id, node);
+    }
+    this.edges = savedEdges;
+
+    // Patch the group definition with the edited internal graph
+    this.graph = {
+      ...outerGraph,
+      groups: (outerGraph.groups ?? []).map(g =>
+        g.id === groupId ? { ...g, nodes: internalState.nodes, edges: internalState.edges } : g
+      )
+    };
+
+    this.history.reset();
+    this.isInsideGroup = this.graphStack.length > 0;
+    this.execute();
+    this.save();
+    return { camera: cameraPosition, nodeId };
+  }
+
  createNodeId() {
-    return Math.max(0, ...this.nodes.keys()) + 1;
+    const ids = [
+      ...this.nodes.keys(),
+      ...this.graph.groups.map(g => g.id),
+      ...this.graph.groups.flatMap(g => g.nodes.map(n => n.id))
+    ];
+
+    console.log('CREATE NODE ID', ids);
+
+    let id = 0;
+    while (ids.includes(id)) {
+      id++;
+    }
+    return id;
  }

  createGraph(nodes: NodeInstance[], edges: [number, number, number, string][]) {
@@ -516,7 +736,7 @@ export class GraphManager extends EventEmitter<{
      const id = startId++;
      idMap.set(node.id, id);
      const type = this.registry.getNode(node.type);
-      if (!type) {
+      if (!type && !node.type.startsWith('__internal/')) {
        throw new Error(`Node type not found: ${node.type}`);
      }
      return { ...node, id, tmp: { type } };
@@ -549,6 +769,148 @@ export class GraphManager extends EventEmitter<{
    return nodes;
  }

+  removeUnusedGroups() {
+    const usedGroups = new Set(this.getAllNodes().map(n => n.props?.groupId));
+    const unusedGroupAmount = this.graph.groups.length - usedGroups.size;
+    this.graph.groups = this.graph.groups.filter(g => usedGroups.has(g.id));
+    this.save();
+    return unusedGroupAmount;
+  }
+
+  groupNodes(nodeIds: number[]) {
+    this.startUndoGroup();
+    this.removeUnusedGroups();
+
+    const nodes = [
+      ...new Set(nodeIds).values().map(id => this.getNode(id)).filter(Boolean)
+    ] as NodeInstance[];
+
+    if (!nodes.length) return;
+
+    logger.log(`Grouping ${nodes.length} nodes`, { nodes });
+
+    const ids = new Set(nodes.map(n => n.id));
+
+    // We use the map to dedupe when one external node is connected to multiple internal nodes
+    //           ┌──internal_a
+    // external──┤
+    //           └──internal_b
+    // This should only result in one group input not two
+    const incomingEdges = this.edges.filter((edge) => ids.has(edge[2].id) && !ids.has(edge[0].id));
+    const groupInputs = new Map<string, Edge>();
+    for (const edge of incomingEdges) {
+      groupInputs.set(`${edge[0].id}-${edge[1]}`, edge);
+    }
+
+    // And the same for the outputs
+    const outgoingEdges = this.edges.filter((edge) => ids.has(edge[0].id) && !ids.has(edge[2].id));
+    const groupOutputs = new Map<string, Edge>();
+    for (const edge of outgoingEdges) {
+      groupOutputs.set(`${edge[2].id}-${edge[3]}`, edge);
+    }
+
+    const inputs: Record<string, NodeInput> = {};
+    [...groupInputs.values()].forEach((edge, i) => {
+      const input = {
+        label: `Input ${i}`,
+        type: edge[0].state.type?.outputs?.[edge[1]] || '*'
+      };
+      inputs[`input_${i}`] = input as NodeInput;
+    });
+
+    const outputs = [...groupOutputs.values()].map((edge, i) => ({
+      label: `Output ${i}`,
+      type: edge[2].state.type?.inputs?.[edge[3]].type || '*'
+    }));
+
+    const groupPosition = [0, 0] as [number, number];
+    const bounds: Box = { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity };
+    for (const node of nodes) {
+      groupPosition[0] += node.position[0];
+      groupPosition[1] += node.position[1];
+      bounds.minX = Math.min(bounds.minX, node.position[0]);
+      bounds.maxX = Math.max(bounds.maxX, node.position[0]);
+      bounds.minY = Math.min(bounds.minY, node.position[1]);
+      bounds.maxY = Math.max(bounds.maxY, node.position[1]);
+    }
+    groupPosition[0] /= nodes.length;
+    groupPosition[1] /= nodes.length;
+
+    const groupInputNode: NodeInstance = {
+      id: this.createNodeId(),
+      type: '__internal/group/input',
+      position: [bounds.minX - 50, (bounds.minY + bounds.maxY) / 2],
+      state: {}
+    };
+
+    const groupOutputNode: NodeInstance = {
+      id: this.createNodeId(),
+      type: '__internal/group/output',
+      position: [bounds.maxX + 25, (bounds.minY + bounds.maxY) / 2],
+      state: {}
+    };
+
+    // Edges that are inside the group
+    const internalEdges = this.edges.filter((edge) => {
+      return ids.has(edge[0].id) || ids.has(edge[2].id);
+    }).map((edge) => {
+      // Going in from the group
+      if (!ids.has(edge[0].id)) {
+        return [groupInputNode.id, 0, edge[2].id, edge[3]];
+        // Going out to the group
+      } else if (!ids.has(edge[2].id)) {
+        return [edge[0].id, edge[1], groupOutputNode.id, 'out_0'];
+      }
+      return [edge[0].id, edge[1], edge[2].id, edge[3]];
+    }) as [number, number, number, string][];
+
+    const groupId = this.createNodeId();
+    const groupDefinition: GroupDefinition = {
+      id: groupId,
+      inputs: inputs,
+      outputs: outputs,
+      edges: internalEdges,
+      nodes: [groupInputNode, ...nodes, groupOutputNode]
+    };
+
+    const groupNode = this.createNode({
+      type: '__internal/group/instance',
+      position: [groupPosition[0], groupPosition[1]],
+      props: {
+        groupId: groupId
+      }
+    });
+
+    if (!groupNode) throw new Error('Failed to create group node');
+
+    // Update the edges that are now inside
+    // the group to be connected to that group node
+    const externalEdges = this.edges.map((edge) => {
+      if (ids.has(edge[2].id)) {
+        // Edge going into the group
+        return [edge[0], edge[1], groupNode, 'input_0'] as Edge;
+      } else if (ids.has(edge[0].id)) {
+        // Edge going out of the group
+        return [groupNode, 0, edge[2], edge[3]] as Edge;
+      }
+      return edge;
+    });
+
+    this.graph.groups.push(groupDefinition);
+    this.nodes.set(groupNode.id, groupNode);
+    this.edges = externalEdges;
+
+    // Remove nodes from graph which are not part of the group
+    for (const node of nodes) {
+      this.removeNode(node);
+    }
+
+    console.log('FINISHED', this.serialize());
+    this.saveUndoGroup();
+
+    return groupNode;
+  }
+
  createNode({
    type,
    position,
@@ -559,7 +921,7 @@ export class GraphManager extends EventEmitter<{
    props: NodeInstance['props'];
  }) {
    const nodeType = this.registry.getNode(type);
-    if (!nodeType) {
+    if (!nodeType && !type.startsWith('__internal/')) {
      logger.error(`Node type not found: ${type}`);
      return;
    }
@@ -597,11 +959,14 @@ export class GraphManager extends EventEmitter<{
      return;
    }

+    const fromType = this.getNodeType(from);
+    const toType = this.getNodeType(to);
+
    // check if socket types match
-    const fromSocketType = from.state?.type?.outputs?.[fromSocket];
-    const toSocketType = [to.state?.type?.inputs?.[toSocket]?.type];
-    if (to.state?.type?.inputs?.[toSocket]?.accepts) {
-      toSocketType.push(...(to?.state?.type?.inputs?.[toSocket]?.accepts || []));
+    const fromSocketType = fromType?.outputs?.[fromSocket];
+    const toSocketType = [toType?.inputs?.[toSocket]?.type];
+    if (toType?.inputs?.[toSocket]?.accepts) {
+      toSocketType.push(...(toType?.inputs?.[toSocket]?.accepts || []));
    }

    if (!areSocketsCompatible(fromSocketType, toSocketType)) {
@@ -671,8 +1036,9 @@ export class GraphManager extends EventEmitter<{
      return;
    }

-    this.emit('save', state);
-    logger.log('saving graphs', state);
+    const fullState = this.graphStack.length > 0 ? this.serializeFullGraph() : state;
+    this.emit('save', fullState);
+    logger.log('saving graphs', fullState);
  }

  getParentsOfNode(node: NodeInstance) {
@@ -724,7 +1090,7 @@ export class GraphManager extends EventEmitter<{
  }

  getPossibleSockets({ node, index }: Socket): [NodeInstance, string | number][] {
-    const nodeType = node?.state?.type;
+    const nodeType = this.getNodeType(node);
    if (!nodeType) return [];

    const sockets: [NodeInstance, string | number][] = [];
@@ -740,7 +1106,7 @@ export class GraphManager extends EventEmitter<{
      const ownType = nodeType?.inputs?.[index].type;

      for (const node of nodes) {
-        const nodeType = node?.state?.type;
+        const nodeType = this.getNodeType(node);
        const inputs = nodeType?.outputs;
        if (!inputs) continue;
        for (let index = 0; index < inputs.length; index++) {
@@ -772,7 +1138,7 @@ export class GraphManager extends EventEmitter<{
      const ownType = nodeType.outputs?.[index];

      for (const node of nodes) {
-        const inputs = node?.state?.type?.inputs;
+        const inputs = this.getNodeType(node)?.inputs;
        if (!inputs) continue;
        for (const key in inputs) {
          const otherType = [inputs[key].type];
@@ -5,7 +5,7 @@ import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import type { OrthographicCamera, Vector3 } from 'three';
 import type { GraphManager } from './graph-manager.svelte';
 import { ColorGenerator } from './graph/colors';
-import { getNodeHeight, getSocketPosition } from './helpers/nodeHelpers';
+import { getNodeHeight, getParameterHeight } from './helpers/nodeHelpers';

 const graphStateKey = Symbol('graph-state');
 export function getGraphState() {
@@ -152,10 +152,6 @@ export class GraphState {
    this.edges.delete(edgeId);
  }

-  getEdgeData() {
-    return this.edges;
-  }
-
  updateNodePosition(node: NodeInstance) {
    if (
      node.state.x === node.position[0]
@@ -190,29 +186,6 @@ export class GraphState {
    return 1;
  }

-  tryConnectToDebugNode(nodeId: number) {
-    const node = this.graph.nodes.get(nodeId);
-    if (!node) return;
-    if (node.type.endsWith('/debug')) return;
-    if (!node.state.type?.outputs?.length) return;
-    for (const _node of this.graph.nodes.values()) {
-      if (_node.type.endsWith('/debug')) {
-        this.graph.createEdge(node, 0, _node, 'input');
-        return;
-      }
-    }
-
-    const debugNode = this.graph.createNode({
-      type: 'max/plantarium/debug',
-      position: [node.position[0] + 30, node.position[1]],
-      props: {}
-    });
-
-    if (debugNode) {
-      this.graph.createEdge(node, 0, debugNode, 'input');
-    }
-  }
-
  copyNodes() {
    if (this.activeNodeId === -1 && !this.selectedNodes?.size) {
      return;
@@ -240,6 +213,10 @@ export class GraphState {
    };
  }

+  groupSelectedNodes() {
+    return this.graph.groupNodes([...this.selectedNodes.keys(), this.activeNodeId]);
+  }
+
  centerNode(node?: NodeInstance) {
    const average = [0, 0, 4];
    if (node) {
@@ -301,7 +278,7 @@ export class GraphState {
        if (edge[3] === index) {
          node = edge[0];
          index = edge[1];
-          position = getSocketPosition(node, index);
+          position = this.getSocketPosition(node, index);
          this.graph.removeEdge(edge);
          break;
        }
@@ -321,7 +298,7 @@ export class GraphState {
        return {
          node,
          index,
-          position: getSocketPosition(node, index)
+          position: this.getSocketPosition(node, index)
        };
      });
  }
@@ -358,7 +335,8 @@ export class GraphState {
        for (const node of this.graph.nodes.values()) {
          const x = node.position[0];
          const y = node.position[1];
-          const height = getNodeHeight(node.state.type!);
+          const nodeType = this.graph.getNodeType(node);
+          const height = nodeType ? getNodeHeight(nodeType) : 20;
          if (downX > x && downX < x + 20 && downY > y && downY < y + height) {
            clickedNodeId = node.id;
            break;
@@ -370,7 +348,8 @@ export class GraphState {
  }

  isNodeInView(node: NodeInstance) {
-    const height = getNodeHeight(node.state.type!);
+    if (!node) return false;
+    const height = getNodeHeight(this.graph.getNodeType(node)!);
    const width = 20;
    return node.position[0] > this.cameraBounds[0] - width
      && node.position[0] < this.cameraBounds[1]
@@ -381,4 +360,51 @@ export class GraphState {
  openNodePalette() {
    this.addMenuPosition = [this.mousePosition[0], this.mousePosition[1]];
  }
+
+  enterGroupNode() {
+    if (this.activeNodeId === -1) return;
+    const node = this.graph.getNode(this.activeNodeId);
+    if (!node || node.type !== '__internal/group/instance') return;
+    const ok = this.graph.enterGroup(this.activeNodeId, [...this.cameraPosition]);
+    if (ok) {
+      this.activeNodeId = -1;
+      this.clearSelection();
+    }
+  }
+
+  exitGroupNode() {
+    const result = this.graph.exitGroup();
+    if (!result) return;
+    this.cameraPosition = result.camera;
+    this.activeNodeId = -1;
+    this.clearSelection();
+  }
+
+  getSocketPosition(
+    node: NodeInstance,
+    index: string | number
+  ): [number, number] {
+    if (typeof index === 'number') {
+      return [
+        (node?.state?.x ?? node.position[0]) + 20,
+        (node?.state?.y ?? node.position[1]) + 2.5 + 10 * index
+      ];
+    } else {
+      let height = 5;
+      const nodeType = this.graph.getNodeType(node)!;
+      const inputs = nodeType.inputs || {};
+      for (const inputKey in inputs) {
+        const h = getParameterHeight(nodeType, inputKey) / 10;
+        if (inputKey === index) {
+          height += h / 2;
+          break;
+        }
+        height += h;
+      }
+      return [
+        node?.state?.x ?? node.position[0],
+        (node?.state?.y ?? node.position[1]) + height
+      ];
+    }
+  }
 }
@@ -11,7 +11,6 @@
  import Debug from '../debug/Debug.svelte';
  import EdgeEl from '../edges/Edge.svelte';
  import { getGraphManager, getGraphState } from '../graph-state.svelte';
-  import { getSocketPosition } from '../helpers/nodeHelpers';
  import NodeEl from '../node/Node.svelte';
  import { maxZoom, minZoom } from './constants';
  import { FileDropEventManager } from './drop.events';
@@ -39,8 +38,8 @@
      return [0, 0, 0, 0];
    }

-    const pos1 = getSocketPosition(fromNode, edge[1]);
-    const pos2 = getSocketPosition(toNode, edge[3]);
+    const pos1 = graphState.getSocketPosition(fromNode, edge[1]);
+    const pos2 = graphState.getSocketPosition(toNode, edge[3]);
    return [pos1[0], pos1[1], pos2[0], pos2[1]];
  }

@@ -97,10 +96,12 @@
  }

  function getSocketType(node: NodeInstance, index: number | string): string {
+    const nodeType = graph.getNodeType(node);
+    console.log({ nodeType, index });
    if (typeof index === 'string') {
-      return node.state.type?.inputs?.[index].type || 'unknown';
+      return nodeType?.inputs?.[index].type || 'unknown';
    }
-    return node.state.type?.outputs?.[index] || 'unknown';
+    return nodeType?.outputs?.[index] || 'unknown';
  }
 </script>

@@ -169,6 +170,14 @@
    {/if}

    {#if graph.status === 'idle'}
+      {#if graph.isInsideGroup}
+        <HTML transform={false}>
+          <button class="exit-group" onclick={() => graphState.exitGroupNode()}>
+            ↑ Exit Group
+          </button>
+        </HTML>
+      {/if}
+
      {#if graphState.addMenuPosition}
        <AddMenu
          onnode={handleNodeCreation}
@@ -216,10 +225,10 @@
          style:transform={`scale(${graphState.cameraPosition[2] * 0.1})`}
          class:hovering-sockets={graphState.activeSocket}
        >
-          {#each graph.nodes.values() as node (node.id)}
+          {#each graph.nodeArray as node, index (node.id)}
            <NodeEl
-              {node}
-              inView={graphState.isNodeInView(node)}
+              bind:node={graph.nodeArray[index]}
+              inView={node ? graphState.isNodeInView(node) : false}
            />
          {/each}
        </div>
@@ -244,6 +253,26 @@
    height: 100%;
  }

+  :global(.exit-group) {
+    position: fixed;
+    top: 12px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 1000;
+    padding: 4px 12px;
+    background: var(--color-layer-2);
+    border: 1px solid var(--stroke);
+    border-radius: 4px;
+    color: inherit;
+    font-size: 0.85em;
+    cursor: pointer;
+    opacity: 0.85;
+  }
+
+  :global(.exit-group:hover) {
+    opacity: 1;
+  }
+
  .wrapper {
    position: absolute;
    z-index: 100;
@@ -1,6 +1,7 @@
 <script lang="ts">
  import { createKeyMap } from '$lib/helpers/createKeyMap';
  import type { Graph, NodeInstance, NodeRegistry } from '@nodarium/types';
+  import { onMount } from 'svelte';
  import { GraphManager } from '../graph-manager.svelte';
  import { GraphState, setGraphManager, setGraphState } from '../graph-state.svelte';
  import { setupKeymaps } from '../keymaps';
@@ -83,7 +84,7 @@
  manager.on('save', (save) => onsave?.(save));

  $effect(() => {
-    if (graph) {
+    if (graph && (manager.status !== 'idle' || manager.graph.id !== graph.id)) {
      manager.load(graph);
    }
  });
@@ -190,7 +190,7 @@ export class MouseEventManager {
    // if we clicked on a node
    if (clickedNodeId !== -1) {
      if (event.ctrlKey && event.shiftKey) {
-        this.state.tryConnectToDebugNode(clickedNodeId);
+        this.graph.tryConnectToDebugNode(clickedNodeId);
        return;
      }
      if (this.state.activeNodeId === -1) {
@@ -23,42 +23,14 @@ export function getParameterHeight(node: NodeDefinition, inputKey: string) {
  return 50;
 }

-export function getSocketPosition(
-  node: NodeInstance,
-  index: string | number
-): [number, number] {
-  if (typeof index === 'number') {
-    return [
-      (node?.state?.x ?? node.position[0]) + 20,
-      (node?.state?.y ?? node.position[1]) + 2.5 + 10 * index
-    ];
-  } else {
-    let height = 5;
-    const nodeType = node.state.type!;
-    const inputs = nodeType.inputs || {};
-    for (const inputKey in inputs) {
-      const h = getParameterHeight(nodeType, inputKey) / 10;
-      if (inputKey === index) {
-        height += h / 2;
-        break;
-      }
-      height += h;
-    }
-    return [
-      node?.state?.x ?? node.position[0],
-      (node?.state?.y ?? node.position[1]) + height
-    ];
-  }
-}
-
 const nodeHeightCache: Record<string, number> = {};
 export function getNodeHeight(node: NodeDefinition) {
+  if (!node || !('inputs' in node)) {
+    return 5;
+  }
  if (node.id in nodeHeightCache) {
    return nodeHeightCache[node.id];
  }
-  if (!node?.inputs) {
-    return 5;
-  }
  let height = 5;

  for (const key in node.inputs) {
@@ -47,6 +47,10 @@ export function setupKeymaps(keymap: Keymap, graph: GraphManager, graphState: Gr
    key: 'Escape',
    description: 'Deselect nodes',
    callback: () => {
+      if (graph.isInsideGroup) {
+        graphState.exitGroupNode();
+        return;
+      }
      graphState.activeNodeId = -1;
      graphState.clearSelection();
      graphState.edgeEndPosition = null;
@@ -54,6 +58,21 @@ export function setupKeymaps(keymap: Keymap, graph: GraphManager, graphState: Gr
    }
  });

+  keymap.addShortcut({
+    key: 'g',
+    ctrl: true,
+    preventDefault: true,
+    description: 'Group selected nodes',
+    callback: () => graphState.groupSelectedNodes()
+  });
+
+  keymap.addShortcut({
+    key: 'Tab',
+    preventDefault: true,
+    description: 'Enter selected node group',
+    callback: () => graphState.enterGroupNode()
+  });
+
  keymap.addShortcut({
    key: 'A',
    shift: true,
@@ -3,13 +3,14 @@
  import type { NodeInstance } from '@nodarium/types';
  import { T } from '@threlte/core';
  import { type Mesh } from 'three';
-  import { getGraphState } from '../graph-state.svelte';
+  import { getGraphManager, getGraphState } from '../graph-state.svelte';
  import { colors } from '../graph/colors.svelte';
  import { getNodeHeight, getParameterHeight } from '../helpers/nodeHelpers';
  import NodeFrag from './Node.frag';
  import NodeVert from './Node.vert';
  import NodeHtml from './NodeHTML.svelte';

+  const graph = getGraphManager();
  const graphState = getGraphState();

  type Props = {
@@ -18,7 +19,7 @@
  };
  let { node = $bindable(), inView }: Props = $props();

-  const nodeType = $derived(node.state.type!);
+  const nodeType = $derived(graph.getNodeType(node)!);

  const isActive = $derived(graphState.activeNodeId === node.id);
  const isSelected = $derived(graphState.selectedNodes.has(node.id));
@@ -33,14 +34,14 @@

  const sectionHeights = $derived(
    Object
-      .keys(nodeType.inputs || {})
+      .keys(nodeType?.inputs || {})
      .map(key => getParameterHeight(nodeType, key) / 10)
      .filter(b => !!b)
  );

  let meshRef: Mesh | undefined = $state();

-  const height = getNodeHeight(node.state.type!);
+  const height = $derived(nodeType ? getNodeHeight(nodeType) : 20);

  const zoom = $derived(graphState.cameraPosition[2]);

@@ -1,11 +1,12 @@
 <script lang="ts">
  import type { NodeInstance } from '@nodarium/types';
-  import { getGraphState } from '../graph-state.svelte';
+  import { getGraphManager, getGraphState } from '../graph-state.svelte';
  import NodeHeader from './NodeHeader.svelte';
  import NodeParameter from './NodeParameter.svelte';

  let ref: HTMLDivElement;

+  const graph = getGraphManager();
  const graphState = getGraphState();

  type Props = {
@@ -30,8 +31,12 @@
  const zOffset = Math.random() - 0.5;
  const zLimit = 2 - zOffset;

-  const parameters = Object.entries(node.state?.type?.inputs || {}).filter(
+  const nodeType = $derived(graph.getNodeType(node));
+
+  const parameters = $derived(
+    Object.entries(nodeType?.inputs || {}).filter(
      (p) => p[1].type !== 'seed' && !('setting' in p[1]) && p[1]?.hidden !== true
+    ) || {}
  );

  $effect(() => {
@@ -1,11 +1,11 @@
 <script lang="ts">
  import { appSettings } from '$lib/settings/app-settings.svelte';
  import type { NodeInstance, Socket } from '@nodarium/types';
-  import { getGraphState } from '../graph-state.svelte';
+  import { getGraphManager, getGraphState } from '../graph-state.svelte';
  import { createNodePath } from '../helpers/index.js';
-  import { getSocketPosition } from '../helpers/nodeHelpers';

  const graphState = getGraphState();
+  const graph = getGraphManager();

  const { node }: { node: NodeInstance } = $props();

@@ -16,13 +16,14 @@
      graphState.setDownSocket?.({
        node,
        index: 0,
-        position: getSocketPosition?.(node, 0)
+        position: graphState.getSocketPosition?.(node, 0)
      });
    }
  }

  const cornerTop = 10;
-  const rightBump = $derived(!!node?.state?.type?.outputs?.length);
+  const nodeType = $derived(graph.getNodeType(node));
+  const rightBump = $derived(!!nodeType?.outputs?.length);
  const aspectRatio = 0.25;

  const path = $derived(
@@ -2,7 +2,7 @@
  import type { NodeInput, NodeInstance, Socket } from '@nodarium/types';
  import { getGraphManager, getGraphState } from '../graph-state.svelte';
  import { createNodePath } from '../helpers';
-  import { getParameterHeight, getSocketPosition } from '../helpers/nodeHelpers';
+  import { getParameterHeight } from '../helpers/nodeHelpers';
  import NodeInputEl from './NodeInput.svelte';

  type Props = {
@@ -19,7 +19,7 @@

  let { node = $bindable(), input, id, isLast }: Props = $props();

-  const nodeType = $derived(node.state.type!);
+  let nodeType = $derived(graph.getNodeType(node)!);

  const inputType = $derived(nodeType.inputs?.[id]);

@@ -32,7 +32,7 @@
    graphState.setDownSocket({
      node,
      index: id,
-      position: getSocketPosition(node, id)
+      position: graphState.getSocketPosition(node, id)
    });
  }

@@ -23,7 +23,11 @@ export function createMockNodeRegistry(nodes: NodeDefinition[]): NodeRegistry {

 export const mockFloatOutputNode: NodeDefinition = {
  id: 'test/node/output',
-  inputs: {},
+  inputs: {
+    'input': {
+      type: 'float'
+    }
+  },
  outputs: ['float'],
  meta: { title: 'Float Output' },
  execute: () => new Int32Array()
@@ -32,7 +36,7 @@ export const mockFloatOutputNode: NodeDefinition = {
 export const mockFloatInputNode: NodeDefinition = {
  id: 'test/node/input',
  inputs: { value: { type: 'float' } },
-  outputs: [],
+  outputs: ['float'],
  meta: { title: 'Float Input' },
  execute: () => new Int32Array()
 };
@@ -4,7 +4,8 @@ export function grid(width: number, height: number) {
  const graph: Graph = {
    id: Math.floor(Math.random() * 100000),
    edges: [],
-    nodes: []
+    nodes: [],
+    groups: []
  };

  const amount = width * height;
@@ -47,6 +47,7 @@ export function tree(depth: number): Graph {
  return {
    id: Math.floor(Math.random() * 100000),
    nodes,
-    edges
+    edges,
+    groups: []
  };
 }
@@ -1,5 +1,5 @@
 export const debugNode = {
-  id: 'max/plantarium/debug',
+  id: '__internal/debug/instance',
  inputs: {
    input: {
      type: '*'
@@ -0,0 +1,13 @@
+export const groupNode = {
+  id: '__internal/group/instance',
+  meta: { title: 'Group' },
+  inputs: {
+    input: {
+      type: 'select',
+      values: []
+    }
+  },
+  execute(_data: Int32Array): Int32Array {
+    return _data;
+  }
+} as const;
@@ -88,6 +88,7 @@ export class RemoteNodeRegistry implements NodeRegistry {
  }

  async fetchNodeDefinition(nodeId: `${string}/${string}/${string}`) {
+    if (nodeId.startsWith('__internal/')) return;
    return this.fetchJson(`nodes/${nodeId}.json`);
  }

@@ -109,6 +110,8 @@ export class RemoteNodeRegistry implements NodeRegistry {
          return this.nodes.get(id)!;
        }

+        if (id.startsWith('__internal/')) return;
+
        const wasmBuffer = await this.fetchNodeWasm(id);

        try {
@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+import { expandGroups } from './runtime-executor';
+import type { Graph } from '@nodarium/types';
+
+// Helpers to build minimal serialized nodes/edges
+function node(id: number, type: string, props?: Record<string, number>) {
+  return { id, type: type as Graph['nodes'][0]['type'], position: [0, 0] as [number, number], ...(props ? { props } : {}) };
+}
+
+function edge(from: number, fromSocket: number, to: number, toSocket: string): [number, number, number, string] {
+  return [from, fromSocket, to, toSocket];
+}
+
+describe('expandGroups', () => {
+  it('returns graph unchanged when there are no groups', () => {
+    const graph: Graph = {
+      id: 1,
+      nodes: [node(0, 'test/node/output'), node(1, 'test/node/input')],
+      edges: [edge(0, 0, 1, 'value')],
+      groups: []
+    };
+
+    const result = expandGroups(graph);
+
+    expect(result.nodes.length).toBe(2);
+    expect(result.edges.length).toBe(1);
+    expect(result).toBe(graph); // same reference — no copy needed
+  });
+
+  it('expands a simple group: A → [B] → C rewires to A → B → C', () => {
+    // IDs: A=1, B=2, C=3, groupNode=4, group.id=5, inputBoundary=6, outputBoundary=7
+    const groupId = 5;
+    const groupNodeId = 4;
+    const remappedB = (groupNodeId + 1) * 1_000_000 + 2; // 5_000_002
+
+    const graph: Graph = {
+      id: 1,
+      nodes: [
+        node(1, 'test/node/output'),
+        node(groupNodeId, '__internal/group/instance', { groupId }),
+        node(3, 'test/node/input')
+      ],
+      edges: [
+        edge(1, 0, groupNodeId, 'input_0'),  // A → group
+        edge(groupNodeId, 0, 3, 'value')     // group → C
+      ],
+      groups: [{
+        id: groupId,
+        nodes: [
+          node(6, '__internal/group/input'),
+          node(2, 'test/node/output'),
+          node(7, '__internal/group/output')
+        ],
+        edges: [
+          edge(6, 0, 2, 'input'),  // inputBoundary → B
+          edge(2, 0, 7, 'Out')     // B → outputBoundary
+        ],
+        inputs: { input_0: { type: 'float' } },
+        outputs: [{ type: 'float', label: 'Output 0' }]
+      }]
+    };
+
+    const result = expandGroups(graph);
+
+    const ids = result.nodes.map(n => n.id);
+    expect(ids).not.toContain(groupNodeId);
+    expect(ids).toContain(remappedB);
+    expect(ids).toContain(1); // A
+    expect(ids).toContain(3); // C
+    expect(result.nodes.length).toBe(3); // A, B(remapped), C
+
+    expect(result.edges).toContainEqual(edge(1, 0, remappedB, 'input'));   // A → B
+    expect(result.edges).toContainEqual(edge(remappedB, 0, 3, 'value')); // B → C
+    expect(result.edges.length).toBe(2);
+  });
+
+  it('expands a group with two internal nodes (B→D) and preserves the internal edge', () => {
+    // A → [B → D] → C
+    const groupId = 10;
+    const groupNodeId = 5;
+    const remappedB = (groupNodeId + 1) * 1_000_000 + 1; // 6_000_001
+    const remappedD = (groupNodeId + 1) * 1_000_000 + 2; // 6_000_002
+
+    const graph: Graph = {
+      id: 1,
+      nodes: [
+        node(0, 'test/node/output'),
+        node(groupNodeId, '__internal/group/instance', { groupId }),
+        node(9, 'test/node/input')
+      ],
+      edges: [
+        edge(0, 0, groupNodeId, 'input_0'),
+        edge(groupNodeId, 0, 9, 'value')
+      ],
+      groups: [{
+        id: groupId,
+        nodes: [
+          node(3, '__internal/group/input'),
+          node(1, 'test/node/output'),  // B
+          node(2, 'test/node/output'),  // D
+          node(4, '__internal/group/output')
+        ],
+        edges: [
+          edge(3, 0, 1, 'input'),  // inputBoundary → B
+          edge(1, 0, 2, 'input'),  // B → D (internal)
+          edge(2, 0, 4, 'Out')     // D → outputBoundary
+        ],
+        inputs: { input_0: { type: 'float' } },
+        outputs: [{ type: 'float' }]
+      }]
+    };
+
+    const result = expandGroups(graph);
+
+    expect(result.nodes.map(n => n.id)).not.toContain(groupNodeId);
+    expect(result.nodes.map(n => n.id)).toContain(remappedB);
+    expect(result.nodes.map(n => n.id)).toContain(remappedD);
+
+    expect(result.edges).toContainEqual(edge(0, 0, remappedB, 'input'));    // A → B
+    expect(result.edges).toContainEqual(edge(remappedB, 0, remappedD, 'input')); // B → D (internal)
+    expect(result.edges).toContainEqual(edge(remappedD, 0, 9, 'value'));    // D → C
+    expect(result.edges.length).toBe(3);
+  });
+
+  it('expands a group with no external connections (isolated)', () => {
+    const groupId = 20;
+    const groupNodeId = 1;
+    const remappedB = (groupNodeId + 1) * 1_000_000 + 2; // 2_000_002
+
+    const graph: Graph = {
+      id: 1,
+      nodes: [node(groupNodeId, '__internal/group/instance', { groupId })],
+      edges: [],
+      groups: [{
+        id: groupId,
+        nodes: [
+          node(3, '__internal/group/input'),
+          node(2, 'test/node/output'),
+          node(4, '__internal/group/output')
+        ],
+        edges: [
+          edge(3, 0, 2, 'input'),
+          edge(2, 0, 4, 'Out')
+        ]
+      }]
+    };
+
+    const result = expandGroups(graph);
+
+    expect(result.nodes.map(n => n.id)).not.toContain(groupNodeId);
+    expect(result.nodes.map(n => n.id)).toContain(remappedB);
+    expect(result.edges.length).toBe(0);
+  });
+});
@@ -6,6 +6,87 @@ import type {
  RuntimeExecutor,
  SyncCache
 } from '@nodarium/types';
+
+export function expandGroups(graph: Graph): Graph {
+  if (!graph.groups || graph.groups.length === 0) return graph;
+
+  let nodes = [...graph.nodes];
+  let edges = [...graph.edges];
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i];
+      if (node.type !== '__internal/group/instance') continue;
+
+      const groupId = node.props?.groupId as number | undefined;
+      if (groupId === undefined) continue;
+
+      const group = graph.groups.find(g => g.id === groupId);
+      if (!group) continue;
+
+      changed = true;
+
+      const ID_OFFSET = (node.id + 1) * 1_000_000;
+      const idMap = new Map<number, number>();
+
+      const inputBoundary = group.nodes.find(n => n.type === '__internal/group/input');
+      const outputBoundary = group.nodes.find(n => n.type === '__internal/group/output');
+
+      const realNodes = group.nodes.filter(
+        n => n.type !== '__internal/group/input' && n.type !== '__internal/group/output'
+      );
+
+      for (const n of realNodes) idMap.set(n.id, ID_OFFSET + n.id);
+
+      const incomingExternal = edges.filter(e => e[2] === node.id);
+      const outgoingExternal = edges.filter(e => e[0] === node.id);
+      const newEdges: Graph['edges'] = [];
+
+      // external_source → [inputBoundary →] internal_target
+      if (inputBoundary) {
+        const fromInput = group.edges.filter(e => e[0] === inputBoundary.id);
+        for (const extEdge of incomingExternal) {
+          for (const intEdge of fromInput) {
+            const toId = idMap.get(intEdge[2]);
+            if (toId !== undefined) newEdges.push([extEdge[0], extEdge[1], toId, intEdge[3]]);
+          }
+        }
+      }
+
+      // internal_source → [outputBoundary →] external_target
+      if (outputBoundary) {
+        const toOutput = group.edges.filter(e => e[2] === outputBoundary.id);
+        for (const extEdge of outgoingExternal) {
+          for (const intEdge of toOutput) {
+            const fromId = idMap.get(intEdge[0]);
+            if (fromId !== undefined) newEdges.push([fromId, intEdge[1], extEdge[2], extEdge[3]]);
+          }
+        }
+      }
+
+      // internal-to-internal edges (skip boundary edges)
+      for (const e of group.edges) {
+        if (e[0] === inputBoundary?.id || e[2] === outputBoundary?.id) continue;
+        const fromId = idMap.get(e[0]);
+        const toId = idMap.get(e[2]);
+        if (fromId !== undefined && toId !== undefined) newEdges.push([fromId, e[1], toId, e[3]]);
+      }
+
+      nodes.splice(i, 1);
+      for (const n of realNodes) nodes.push({ ...n, id: idMap.get(n.id)! });
+
+      edges = edges.filter(e => e[0] !== node.id && e[2] !== node.id);
+      edges.push(...newEdges);
+
+      break;
+    }
+  }
+
+  return { ...graph, nodes, edges };
+}
 import {
  concatEncodedArrays,
  createLogger,
@@ -75,7 +156,11 @@ export class MemoryRuntimeExecutor implements RuntimeExecutor {
      throw new Error('Node registry is not ready');
    }

-    await this.registry.load(graph.nodes.map((node) => node.type));
+    // Only load non-virtual types (virtual nodes are resolved locally)
+    const nonVirtualTypes = graph.nodes
+      .map(node => node.type)
+      .filter(t => !t.startsWith('__internal/'));
+    await this.registry.load(nonVirtualTypes as any);

    const typeMap = new Map<string, NodeDefinition>();
    for (const node of graph.nodes) {
@@ -163,6 +248,9 @@ export class MemoryRuntimeExecutor implements RuntimeExecutor {
    let a = performance.now();
    this.debugData = {};

+    // Expand group nodes into a flat graph before execution
+    graph = expandGroups(graph);
+
    // Then we add some metadata to the graph
    const [outputNode, nodes] = await this.addMetaData(graph);
    let b = performance.now();
@@ -219,7 +307,7 @@ export class MemoryRuntimeExecutor implements RuntimeExecutor {
          if (inputNode) {
            if (results[inputNode.id] === undefined) {
              throw new Error(
-                `Node ${node.type} is missing input from node ${inputNode.type}`
+                `Node ${node.type} is missing input from node ${inputNode.type}#${inputNode.id}`
              );
            }
            return results[inputNode.id];
@@ -24,3 +24,9 @@
 {:else}
  <p class="mx-4 mt-4">No node selected</p>
 {/if}
+
+{#if manager?.graph.groups.length}
+  <button onclick={() => manager.removeUnusedGroups()}>
+    remove unused groups
+  </button>
+{/if}
@@ -1,20 +1,23 @@
 <script lang="ts">
  import type { Graph } from '$lib/types';
+  import { JsonViewer } from '@nodarium/ui';

  const { graph }: { graph?: Graph } = $props();

-  function convert(g: Graph): string {
-    return JSON.stringify(
-      {
-        ...g,
-        nodes: g.nodes.map((n: object) => ({ ...n, tmp: undefined, state: undefined }))
-      },
-      null,
-      2
-    );
+  const data = $derived(
+    graph
+      ? {
+        ...graph,
+        nodes: graph.nodes.map((n: object) => ({ ...n, tmp: undefined, state: undefined }))
      }
+      : null
+  );
 </script>

-<pre>
-  {graph ? convert(graph) : "No graph loaded"}
-</pre>
+<div class="overflow-auto p-2">
+  {#if data}
+    <JsonViewer value={data} path="graph" />
+  {:else}
+    <span class="font-mono text-xs text-neutral-500">No graph loaded</span>
+  {/if}
+</div>
@@ -4,7 +4,7 @@
  import Grid from '$lib/grid';
  import { debounceAsyncFunction } from '$lib/helpers';
  import { createKeyMap } from '$lib/helpers/createKeyMap';
-  import { debugNode } from '$lib/node-registry/debugNode.js';
+  import { debugNode } from '$lib/node-registry/debugNode';
  import { IndexDBCache, RemoteNodeRegistry } from '$lib/node-registry/index';
  import NodeStore from '$lib/node-store/NodeStore.svelte';
  import PerformanceViewer from '$lib/performance/PerformanceViewer.svelte';
@@ -321,7 +321,7 @@
          hidden={!appSettings.value.debug.advancedMode}
          icon="i-[tabler--code]"
        >
-          <GraphSource graph={pm.graph ?? manager?.serialize()} />
+          <GraphSource graph={manager?.serialize()} />
        </Panel>
        <Panel
          id="benchmark"
@@ -0,0 +1,204 @@
+# Nodarium — LLM Reference
+
+## What It Is
+
+Nodarium is a **node-based visual programming editor**. Users wire together nodes on a 2D canvas; each node is a WebAssembly module that receives typed inputs and produces typed outputs. A live Three.js viewer renders the resulting 3D geometry/paths/instances.
+
+---
+
+## Repository Layout
+
+```
+/
+├── app/                        # SvelteKit web app
+│   └── src/
+│       ├── routes/+page.svelte # App entry point
+│       └── lib/
+│           ├── graph-interface/  # Canvas editor (UI + state)
+│           ├── runtime/          # WASM execution engine
+│           ├── node-registry/    # Fetch & cache node definitions
+│           ├── project-manager/  # IndexDB persistence
+│           ├── result-viewer/    # Three.js 3D output
+│           ├── sidebar/          # UI panels
+│           └── settings/         # App + graph settings
+├── packages/
+│   ├── types/    # Shared TypeScript types + Zod schemas
+│   ├── utils/    # Logging, hashing, WASM wrapping, perf
+│   ├── ui/       # Reusable Svelte UI components
+│   ├── planty/   # Tutorial system
+│   └── macros/   # Build-time macros
+└── docs/
+```
+
+---
+
+## Core Architecture
+
+```
+User Interaction
+  └── GraphInterface
+        ├── GraphState   ← UI: selection, camera, mouse, clipboard
+        └── GraphManager ← Logic: nodes, edges, history, serialization
+              ├── NodeRegistry   ← fetches WASM definitions (remote API + IndexDB cache)
+              ├── HistoryManager ← undo/redo (jsondiffpatch deltas)
+              └── emit('result') → RuntimeExecutor
+                                      └── node.execute(Int32Array) per node
+                                            └── ResultViewer (Three.js/Threlte)
+```
+
+**Event flow:**
+1. User edits graph → GraphManager mutates state
+2. GraphManager emits `save` → ProjectManager persists to IndexDB
+3. GraphManager emits `result` → Runtime executes graph → Viewer updates
+
+---
+
+## Critical Files
+
+| File | Role |
+|------|------|
+| `app/src/routes/+page.svelte` | Wires all systems; creates GraphManager, runtime, registry |
+| `app/src/lib/graph-interface/graph-manager.svelte.ts` | Central graph logic: createNode, createEdge, serialize, load, history |
+| `app/src/lib/graph-interface/graph-state.svelte.ts` | UI state: camera, selection, mouse, clipboard, groupSelectedNodes |
+| `app/src/lib/graph-interface/graph/Graph.svelte` | Canvas renderer |
+| `app/src/lib/graph-interface/node/Node.svelte` | 3D mesh node (Three.js shader) |
+| `app/src/lib/graph-interface/node/NodeHTML.svelte` | HTML overlay: labels + parameters |
+| `app/src/lib/graph-interface/node/NodeHeader.svelte` | Node title bar |
+| `app/src/lib/graph-interface/keymaps.ts` | Keyboard shortcuts |
+| `app/src/lib/graph-interface/helpers/nodeHelpers.ts` | Node height calculations |
+| `app/src/lib/graph-interface/graph/colors.svelte.ts` | Socket type → color mapping |
+| `app/src/lib/runtime/runtime-executor.ts` | Executes nodes in DAG order; expandGroups() |
+| `app/src/lib/node-registry/index.ts` | RemoteNodeRegistry entry |
+| `app/src/lib/node-registry/groupNode.ts` | Built-in group node definition |
+| `app/src/lib/node-registry/debugNode.ts` | Built-in debug node |
+| `app/src/lib/sidebar/panels/ActiveNodeSettings.svelte` | Per-node settings panel |
+| `packages/types/src/types.ts` | Graph, NodeInstance, NodeDefinition, Edge, GroupDefinition |
+| `packages/types/src/inputs.ts` | NodeInput union types (float, vec3, geometry, path, …) |
+| `packages/utils/src/wasm.ts` | createWasmWrapper() — wraps WASM bytes into a NodeDefinition |
+
+---
+
+## Key Types
+
+```typescript
+// packages/types/src/types.ts
+
+type NodeId = `${string}/${string}/${string}` // e.g. "max/plantarium/stem"
+
+type NodeInstance = {
+  id: number
+  type: NodeId
+  position: [number, number]
+  props?: Record<string, number | number[]>  // current parameter values
+  meta?: { title?: string; lastModified?: string }
+  state: NodeRuntimeState   // runtime-only, NOT serialized
+}
+
+type NodeRuntimeState = {
+  type?: NodeDefinition     // resolved definition
+  parents?: NodeInstance[]
+  children?: NodeInstance[]
+  x?: number; y?: number    // interpolated position
+  mesh?: Mesh               // Three.js mesh reference
+  ref?: HTMLElement
+}
+
+type NodeDefinition = {
+  id: NodeId
+  inputs?: Record<string, NodeInput>
+  outputs?: string[]                      // output type names
+  meta?: { title?: string; description?: string }
+  execute(input: Int32Array): Int32Array  // WASM function
+}
+
+// Edge: [fromNode, outputIndex, toNode, inputSocketName]
+type Edge = [NodeInstance, number, NodeInstance, string]
+
+type Graph = {
+  nodes: NodeInstance[]
+  edges: [number, number, number, string][]  // serialized (IDs, not refs)
+  settings: Record<string, unknown>
+  groups: GroupDefinition[]
+}
+
+type GroupDefinition = {
+  id: number
+  nodes: NodeInstance[]
+  edges: Edge[]
+  inputs?: Record<string, NodeInput>
+  outputs?: string[]
+}
+```
+
+### NodeInput socket types
+`float` | `integer` | `boolean` | `select` | `seed` | `vec3` | `geometry` | `path` | `shape` | `color` | `*` (wildcard)
+
+Each input can have: `value` (default), `label`, `hidden`, `external`, `setting` (link to graph setting), `accepts` (extra compatible types).
+
+---
+
+## Patterns & Conventions
+
+### Svelte 5 reactivity
+The codebase uses Svelte 5 runes throughout — `$state`, `$derived`, `$effect`. Collections use `SvelteMap<K,V>` and `SvelteSet<T>` (from `svelte/reactivity`) instead of plain Map/Set so that mutations trigger reactive updates.
+
+### Context API
+`GraphManager` and `GraphState` are provided via Svelte context (`setContext` / `getContext`) inside `GraphInterface`. All child components (Node, Edge, etc.) consume them via context rather than props.
+
+### Edge representation
+In memory, edges are `[NodeInstance, outputIndex, NodeInstance, inputSocketName]` — direct object references for fast traversal. On serialization (`Graph.edges`), they become `[nodeId, outputIndex, nodeId, inputSocketName]` (plain IDs).
+
+### Socket compatibility
+```typescript
+areSocketsCompatible(outputType: string, inputType: string | string[]): boolean
+// '*' wildcard matches any type; 'geometry' accepts ['geometry', 'instances']
+```
+
+### WASM execution interface
+Every node exposes a single function: `execute(input: Int32Array): Int32Array`.
+Data encoding (Plantarium):
+- `[0, stemDepth, ...x,y,z,thickness]` — path
+- `[1, vertexCount, faceCount, ...faces, ...vertices, ...normals]` — geometry
+- `[2, vertexCount, faceCount, instanceCount, stemDepth, ...]` — instances
+
+### Event emitter
+`GraphManager extends EventEmitter<{ save, result, settings }>`. Subscribe with `manager.on('result', cb)`. Used to decouple the editor UI from runtime execution and persistence.
+
+### History
+Every mutation goes through `HistoryManager`. Call `this.history.save(this.serialize())` before mutations; undo/redo replays jsondiffpatch deltas.
+
+### Internal node IDs
+Built-in nodes use the `__internal/` namespace: `__internal/group/instance`, `__internal/node/debug`. Virtual boundary nodes use `__virtual/`: `__virtual/group/input`, `__virtual/group/output`.
+
+---
+
+## In-Progress: Node Groups (`feat/group-node-own`)
+
+Group selected nodes with **Ctrl+G**. A `GroupDefinition` is stored in `Graph.groups[]`; a group instance node (`__internal/group/instance`) referencing it by `props.groupId` replaces the selected nodes.
+
+**Known gaps as of 2026-05-03:**
+
+| Issue | Location |
+|-------|----------|
+| `createGroupNode()` called but not defined | `graph-state.svelte.ts:334` → missing in `graph-manager.svelte.ts` |
+| Runtime expects `group.graph.nodes/edges`; schema has flat `nodes/edges` | `runtime-executor.ts` vs `types.ts` |
+| Runtime expects `group.inputs` as array; schema defines it as `Record<string, NodeInput>` | Same mismatch |
+| `enterGroupNode()` is a stub — no group navigation | `graph-state.svelte.ts` |
+| `serialize()` writes parent-graph edges into group instead of group-internal edges | `graph-manager.svelte.ts` |
+
+---
+
+## Dev Commands
+
+Run from `app/`:
+
+```bash
+npm run dev          # start dev server (Vite)
+npm run build        # production build
+npm run check        # svelte-check + tsc
+npm run lint         # eslint
+npm run test         # unit (vitest) + e2e (playwright)
+npm run test:unit    # vitest only
+npm run test:e2e     # playwright only
+npm run bench        # benchmark runner
+```
@@ -6,7 +6,8 @@
    "qa": "pnpm lint && pnpm check && pnpm test",
    "format": "pnpm dprint fmt",
    "format:check": "pnpm dprint check",
-    "test": "pnpm run -r --parallel test",
+    "test:e2e": "pnpm run -r --parallel test:e2e",
+    "test:unit": "pnpm run -r --parallel test:unit",
    "check": "pnpm run -r --parallel check",
    "build": "pnpm build:nodes && pnpm build:app",
    "build:app": "BASE_PATH=/ui pnpm -r --filter 'ui' build && pnpm -r --filter 'app'... build",
@@ -4,11 +4,12 @@ export type {
  Box,
  Edge,
  Graph,
+  GroupDefinition,
  NodeDefinition,
  NodeId,
  NodeInstance,
  SerializedNode,
  Socket
 } from './types';
-export { GraphSchema, NodeSchema } from './types';
+export { GraphSchema, GroupSchema, NodeSchema } from './types';
 export { NodeDefinitionSchema } from './types';
@@ -76,6 +76,19 @@ export type Socket = {

 export type Edge = [NodeInstance, number, NodeInstance, string];

+export const GroupSchema = z.object({
+  id: z.number(),
+  nodes: z.array(NodeSchema),
+  edges: z.array(z.tuple([z.number(), z.number(), z.number(), z.string()])),
+  inputs: z.record(z.string(), NodeInputSchema).optional(),
+  outputs: z.array(z.object({
+    type: z.string(),
+    label: z.string().optional()
+  })).optional()
+});
+
+export type GroupDefinition = z.infer<typeof GroupSchema>;
+
 export const GraphSchema = z.object({
  id: z.number(),
  meta: z
@@ -86,7 +99,8 @@ export const GraphSchema = z.object({
    .optional(),
  settings: z.record(z.string(), z.any()).optional(),
  nodes: z.array(NodeSchema),
-  edges: z.array(z.tuple([z.number(), z.number(), z.number(), z.string()]))
+  edges: z.array(z.tuple([z.number(), z.number(), z.number(), z.string()])),
+  groups: z.array(GroupSchema)
 });

 export type Graph = z.infer<typeof GraphSchema>;
@@ -0,0 +1,137 @@
+<script module>
+  const cache = new Map<string, Record<string, boolean>>();
+
+  function getStore(root: string): Record<string, boolean> {
+    if (!cache.has(root)) {
+      try {
+        const raw = localStorage.getItem(`json_viewer:${root}`);
+        cache.set(root, raw ? JSON.parse(raw) : {});
+      } catch {
+        cache.set(root, {});
+      }
+    }
+    return cache.get(root)!;
+  }
+
+  function readOpen(path: string, fallback: boolean): boolean {
+    const root = path.split('/')[0];
+    const store = getStore(root);
+    return path in store ? store[path] : fallback;
+  }
+
+  function writeOpen(path: string, value: boolean) {
+    const root = path.split('/')[0];
+    const store = getStore(root);
+    store[path] = value;
+    try {
+      localStorage.setItem(`json_viewer:${root}`, JSON.stringify(store));
+    } catch { /* quota exceeded etc */ }
+  }
+</script>
+
+<script lang="ts">
+  import { browser } from '$app/environment';
+  import JsonViewer from './JsonViewer.svelte';
+
+  let {
+    value,
+    key,
+    depth = 0,
+    path = ''
+  }: { value: unknown; key?: string; depth?: number; path?: string } = $props();
+
+  const defaultOpen = $derived(depth < 4);
+  let open = $derived(browser && path ? readOpen(path, defaultOpen) : defaultOpen);
+  let flashing = $state(false);
+
+  const isArr = $derived(Array.isArray(value));
+  const isExpandable = $derived(value !== null && typeof value === 'object');
+  const open_bracket = $derived(isArr ? '[' : '{');
+  const close_bracket = $derived(isArr ? ']' : '}');
+  const items = $derived.by(() => {
+    if (isArr) {
+      return (value as unknown[]).map((v, i) => [String(i), v] as [string, unknown]);
+    }
+    if (value !== null && typeof value === 'object') {
+      return Object.entries(value as Record<string, unknown>).filter(
+        ([, v]) => v !== undefined
+      );
+    }
+    return [] as [string, unknown][];
+  });
+  const showKeys = $derived(!isArr || typeof items[0]?.[1] === "object")
+
+  function toggle(next: boolean) {
+    open = next;
+    if (browser && path) writeOpen(path, next);
+  }
+
+  let prevJson = '';
+  let flashTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  $effect(() => {
+    const json = JSON.stringify(value);
+    if (prevJson && json !== prevJson) {
+      if (flashTimeout) clearTimeout(flashTimeout);
+      flashing = true;
+      flashTimeout = setTimeout(() => {
+        flashing = false;
+        flashTimeout = null;
+      }, 500);
+    }
+    prevJson = json;
+  });
+</script>
+
+<span
+  class="font-mono text-xs leading-[1.6] rounded transition-[background-color] duration-500"
+  class:bg-layer-3={flashing}
+>
+  {#if key !== undefined}
+    <span class="text-text">{key}</span><span class="text-text/40">: </span>
+  {/if}
+
+  {#if isExpandable}
+    {#if items.length === 0}
+      <span class="text-text/50">{open_bracket}{close_bracket}</span>
+    {:else if open}
+      {#if depth > 0}
+        <button class="w-3 text-text/50 hover:text-text" onclick={() => toggle(false)}>
+          ▼
+        </button>
+      {/if}
+      <span class="text-text/50">{open_bracket}</span>
+      <div class="pl-4 border-l border-outline">
+        {#each items as [k, v], i (k)}
+          <div>
+            <JsonViewer
+              value={v}
+              key={showKeys ? k : undefined }
+              depth={depth + 1}
+              path={path ? `${path}/${k}` : k}
+            />{#if i < items.length - 1}<span class="text-text/20">,</span>{/if}
+          </div>
+        {/each}
+      </div>
+      <span class="text-text/50">{close_bracket}</span>
+    {:else}
+      <button
+        class="inline text-text/50 hover:text-text"
+        onclick={() => toggle(true)}
+      >
+        <span class="w-3 inline-block">▶</span>
+        {open_bracket}<span class="text-text/40 mx-1">{items.length}</span>{close_bracket}
+      </button>
+    {/if}
+  {:else if value === null}
+    <span class="text-emerald-500!">null</span>
+  {:else if typeof value === 'boolean'}
+    <span class="text-blue-500!">{value}</span>
+  {:else if typeof value === 'number'}
+    <span class="text-orange-400!">{value}</span>
+  {:else if typeof value === 'string'}
+    <span class="text-emerald-500!">"{value}"</span>
+  {:else}
+    <span class="text-text/70">{String(value)}</span>
+  {/if}
+</span>
@@ -7,6 +7,7 @@ export { default as InputShape } from './inputs/InputShape.svelte';
 export { default as InputVec3 } from './inputs/InputVec3.svelte';

 export { default as Details } from './Details.svelte';
+export { default as JsonViewer } from './JsonViewer.svelte';
 export { default as ShortCut } from './ShortCut.svelte';

 import Input from './Input.svelte';
@@ -8,6 +8,7 @@
    InputSelect,
    InputShape,
    InputVec3,
+    JsonViewer,
    ShortCut
  } from '$lib';
  import Section from './Section.svelte';
@@ -25,6 +26,32 @@
  let colorValue = $state<[number, number, number]>([59, 130, 246]);
  let mirrorShape = $state(true);
  let detailsOpen = $state(false);
+  let jsonValue = $state({
+    id: 1,
+    nodes: [{ id: 0, type: 'max/test/node', position: [0, 0] }, {
+      id: 1,
+      type: 'max/test/other',
+      position: [100, 50]
+    }],
+    edges: [[0, 0, 1, 'input']],
+    groups: [],
+    settings: { seed: 42, enabled: true }
+  });
+
+  function randomlyUpdateJson() {
+    const rand = Math.floor(Math.random() * 5);
+    if (rand === 0) {
+      jsonValue.nodes[0].position[0] += 1;
+    } else if (rand === 1) {
+      jsonValue.nodes[0].position[1] += 1;
+    } else if (rand === 2) {
+      jsonValue.settings.seed += 1;
+    } else if (rand === 3) {
+      jsonValue.settings.enabled = !jsonValue.settings.enabled;
+    } else if (rand === 4) {
+      jsonValue.id += Math.floor(Math.random() * 10 - 5);
+    }
+  }

  let points = $state([]);
  let theme = $state('dark');
@@ -56,6 +83,7 @@
  </Section>

  <Section title="Select" value={d}>
+    <i>Select with simple values</i>
    <InputSelect bind:value={selectValue} {options} />
  </Section>

@@ -86,6 +114,23 @@
    </Details>
  </Section>

+  <Section title="JsonViewer">
+    {#snippet header()}
+      <button
+        onclick={() => randomlyUpdateJson()}
+        class="-mt-1 bg-layer-2 p-1 px-2 rounded-sm cursor-pointer"
+      >
+        update
+      </button>
+    {/snippet}
+    <div class="w-64 bg-layer-1 p-2 rounded">
+      <JsonViewer
+        value={jsonValue}
+        path="demo"
+      />
+    </div>
+  </Section>
+
  <Section title="Shortcut">
    <div class="flex gap-4">
      <ShortCut ctrl key="S" />
@@ -4,6 +4,7 @@ export interface PerformanceStore {
  startRun(): void;
  stopRun(): void;
  addPoint(name: string, value?: number): void;
+  addToLastRun(name: string, value: number): void;
  endPoint(name?: string): void;
  mergeData(data: PerformanceData[number]): void;
  get: () => PerformanceData;
@@ -63,6 +64,13 @@ export function createPerformanceStore(): PerformanceStore {
    }
  }

+  function addToLastRun(name: string, value: number) {
+    const last = data[data.length - 1];
+    if (!last) return;
+    last[name] = last[name] || [];
+    last[name].push(value);
+  }
+
  function get() {
    return data;
  }
@@ -94,6 +102,7 @@ export function createPerformanceStore(): PerformanceStore {
    startRun,
    stopRun,
    addPoint,
+    addToLastRun,
    endPoint,
    mergeData,
    get
@@ -4,12 +4,6 @@ settings:
  autoInstallPeers: true
  excludeLinksFromLockfile: false

-catalogs:
-  default:
-    chokidar-cli:
-      specifier: github:open-cli-tools/chokidar-cli#semver:v4.0.0
-      version: 4.0.0
-
 importers:

  .:
Author	SHA1	Message	Date
max	ef217b1c40	feat: some updates 📊 Benchmark the Runtime / benchmark (pull_request) Successful in 1m13s Details 🚀 Lint & Test & Deploy / quality (pull_request) Failing after 44s Details 🚀 Lint & Test & Deploy / test-unit (pull_request) Failing after 29s Details 🚀 Lint & Test & Deploy / test-e2e (pull_request) Failing after 33s Details 🚀 Lint & Test & Deploy / deploy (pull_request) Has been skipped Details	2026-05-04 11:27:21 +02:00
max	7499b80789	fix: make the runtime work with groups	2026-05-03 17:49:14 +02:00
max	a5b663f6fc	feat(ci): split e2e and unit tests	2026-05-03 17:49:00 +02:00
max	05506704bf	feat: let claude fix ci 📊 Benchmark the Runtime / benchmark (pull_request) Successful in 1m1s Details 🚀 Lint & Test & Deploy / quality (pull_request) Failing after 42s Details 🚀 Lint & Test & Deploy / test (pull_request) Failing after 39s Details 🚀 Lint & Test & Deploy / deploy (pull_request) Has been skipped Details	2026-05-03 17:12:49 +02:00
max	63188e57fd	feat: let claude fix ci 📊 Benchmark the Runtime / benchmark (pull_request) Failing after 1m0s Details 🚀 Lint & Test & Deploy / quality (pull_request) Failing after 41s Details 🚀 Lint & Test & Deploy / test (pull_request) Failing after 30s Details 🚀 Lint & Test & Deploy / deploy (pull_request) Has been skipped Details	2026-05-03 17:10:13 +02:00
max	4572d30005	feat: let claude refactor ci 📊 Benchmark the Runtime / benchmark (pull_request) Failing after 1s Details 🚀 Lint & Test & Deploy / quality (pull_request) Failing after 1s Details 🚀 Lint & Test & Deploy / test (pull_request) Failing after 1s Details 🚀 Lint & Test & Deploy / deploy (pull_request) Has been skipped Details	2026-05-03 17:04:13 +02:00
max	ccc376d158	feat: store total vertices/faces in benchmarkl 📊 Benchmark the Runtime / release (pull_request) Successful in 1m19s Details 🚀 Lint & Test & Deploy / release (pull_request) Failing after 49s Details	2026-05-03 16:46:18 +02:00
max	7e432e9033	chore: update ci workflow 📊 Benchmark the Runtime / release (pull_request) Successful in 2m24s Details 🚀 Lint & Test & Deploy / release (pull_request) Failing after 50s Details	2026-05-03 16:44:02 +02:00
max	01f58377c2	feat: make more node group features work 📊 Benchmark the Runtime / release (pull_request) Successful in 4m32s Details 🚀 Lint & Test & Deploy / release (pull_request) Failing after 1m5s Details	2026-05-03 16:34:52 +02:00
max	6ef5dc28ed	chore: move jsonviewer into ui package	2026-05-03 16:28:40 +02:00
max	3450d70047	docs: add LLM.md	2026-05-03 13:51:33 +02:00
max	731b9e9b1e	feat: upgrade graph source panel	2026-05-03 13:51:17 +02:00
max	72f07d0a50	feat: initial node groups	2026-04-26 18:41:25 +02:00
max	a56e8f445e	feat(ci): install openssh client 📊 Benchmark the Runtime / release (push) Successful in 44s Details 🚀 Lint & Test & Deploy / release (push) Successful in 4m17s Details Build & Push CI Image / build-and-push (push) Successful in 11m54s Details	2026-04-24 13:56:07 +02:00