chore: debug ci ssh

.cargo/config.toml

@@ -1,9 +0,0 @@
-[target.wasm32-unknown-unknown]
-rustflags = [
-  "-C",
-  "link-arg=--import-memory",
-  "-C",
-  "link-arg=--initial-memory=67108864", # 64 MiB
-  "-C",
-  "link-arg=--max-memory=536870912", # 512 MiB
-]

.gitea/workflows/benchmark.yaml

@@ -14,7 +14,7 @@ env:
 jobs:
   release:
     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
@@ -51,9 +51,37 @@ jobs:
       - 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
+          ssh-keyscan -p 2222 -H git.max-richter.dev >> ~/.ssh/known_hosts
+          ssh -vvv -p 2222 -i ~/.ssh/id_ed25519 -T git@git.max-richter.dev
+
+      - 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"
+
+          # 2. Clone the benchmarks repo into a temp folder
+          git config --global core.sshCommand "ssh -vv -p 2222 -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes"
+          git clone git@git.max-richter.dev:max/nodarium-benchmarks.git target_bench_repo
+          
+          # 3. Create a directory structure based on the branch
+          # This allows the UI to "switch between branches"
+          BRANCH_NAME="${{ github.ref_name }}"
+          DEST_DIR="target_bench_repo/data/$BRANCH_NAME/$(date +%s)"
+          mkdir -p "$DEST_DIR"
+
+          # 4. Copy the new results
+          # Assuming your bench tool outputs a file named 'results.json'
+          cp app/benchmark/out/*.json "$DEST_DIR/"
+
+          # 5. Commit and Push
+          cd target_bench_repo
+          git add .
+          git commit -m "Update benchmarks for $BRANCH_NAME: ${{ github.sha }}"
+          git push origin main

.gitea/workflows/release.yaml

@@ -15,7 +15,7 @@ env:
 jobs:
   release:
     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

Cargo.lock

@@ -24,14 +24,6 @@ dependencies = [
  "nodarium_utils",
 ]
 
-[[package]]
-name = "debug"
-version = "0.1.0"
-dependencies = [
- "nodarium_macros",
- "nodarium_utils",
-]
-
 [[package]]
 name = "float"
 version = "0.1.0"

README.md

@@ -27,6 +27,7 @@ Currently this visual programming language is used to develop <https://nodes.max
 - [Node.js](https://nodejs.org/en/download)
 - [pnpm](https://pnpm.io/installation)
 - [rust](https://www.rust-lang.org/tools/install)
+- wasm-pack
 
 ### Install dependencies
 

SHARED_MEMORY_REFACTOR_PLAN.md

@@ -1,783 +0,0 @@
-# Shared Memory Refactor Plan
-
-## Executive Summary
-
-Migrate to a single shared `WebAssembly.Memory` instance imported by all nodes using `--import-memory`. The `#[nodarium_execute]` macro writes the function's return value directly to shared memory at the specified offset.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                        Shared WebAssembly.Memory                    │
-│  ┌───────────────────────────────────────────────────────────────┐  │
-│  │  [Node A output]  [Node B output]  [Node C output]  ...       │  │
-│  │  ┌────────────┐   ┌────────────┐   ┌────────────┐             │  │
-│  │  │ Vec<i32>   │   │ Vec<i32>   │   │ Vec<i32>   │             │  │
-│  │  │ 4 bytes    │   │ 12 bytes   │   │ 2KB        │             │  │
-│  │  └────────────┘   └────────────┘   └────────────┘             │  │
-│  │                                                               │  │
-│  │  offset: 0 ────────────────────────────────────────────────►  │  │
-│  └───────────────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────────────┘
-                                   ▲
-                                   │
-                                   │ import { memory } from "env"
-         ┌─────────────────────────┼─────────────────────────┐
-         │                         │                         │
-    ┌────┴────┐               ┌────┴────┐               ┌────┴────┐
-    │  Node A │               │  Node B │               │  Node C │
-    │  WASM   │               │  WASM   │               │  WASM   │
-    └─────────┘               └─────────┘               └─────────┘
-```
-
-## Phase 1: Compilation Configuration
-
-### 1.1 Cargo Config
-
-```toml
-# nodes/max/plantarium/box/.cargo/config.toml
-[build]
-rustflags = ["-C", "link-arg=--import-memory"]
-```
-
-Or globally in `Cargo.toml`:
-
-```toml
-[profile.release]
-rustflags = ["-C", "link-arg=--import-memory"]
-```
-
-### 1.2 Import Memory Semantics
-
-With `--import-memory`:
-
-- Nodes **import** memory from the host (not export their own)
-- All nodes receive the same `WebAssembly.Memory` instance
-- Memory is read/write accessible from all modules
-- No `memory.grow` needed (host manages allocation)
-
-## Phase 2: Macro Design
-
-### 2.1 Clean Node API
-
-```rust
-// input.json has 3 inputs: op_type, a, b
-nodarium_definition_file!("src/input.json");
-
-#[nodarium_execute]
-pub fn execute(op_type: *i32, a: *i32, b: *i32) -> Vec<i32> {
-    // Read inputs directly from shared memory
-    let op = unsafe { *op_type };
-    let a_val = f32::from_bits(unsafe { *a } as u32);
-    let b_val = f32::from_bits(unsafe { *b } as u32);
-
-    let result = match op {
-        0 => a_val + b_val,
-        1 => a_val - b_val,
-        2 => a_val * b_val,
-        3 => a_val / b_val,
-        _ => 0.0,
-    };
-
-    // Return Vec<i32>, macro handles writing to shared memory
-    vec![result.to_bits()]
-}
-```
-
-### 2.2 Macro Implementation
-
-```rust
-// packages/macros/src/lib.rs
-
-#[proc_macro_attribute]
-pub fn nodarium_execute(_attr: TokenStream, item: TokenStream) -> TokenStream {
-    let input_fn = parse_macro_input!(item as syn::ItemFn);
-    let fn_name = &input_fn.sig.ident;
-
-    // Parse definition to get input count
-    let project_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
-    let def: NodeDefinition = serde_json::from_str(&fs::read_to_string(
-        Path::new(&project_dir).join("src/input.json")
-    ).unwrap()).unwrap();
-
-    let input_count = def.inputs.as_ref().map(|i| i.len()).unwrap_or(0);
-
-    // Validate signature
-    validate_signature(&input_fn, input_count);
-
-    // Generate wrapper
-    generate_execute_wrapper(input_fn, fn_name, input_count)
-}
-
-fn validate_signature(fn_sig: &syn::Signature, expected_inputs: usize) {
-    let param_count = fn_sig.inputs.len();
-    if param_count != expected_inputs {
-        panic!(
-            "Execute function has {} parameters but definition has {} inputs\n\
-             Definition inputs: {:?}\n\
-             Expected signature:\n\
-             pub fn execute({}) -> Vec<i32>",
-            param_count,
-            expected_inputs,
-            def.inputs.as_ref().map(|i| i.keys().collect::<Vec<_>>()),
-            (0..expected_inputs)
-                .map(|i| format!("arg{}: *const i32", i))
-                .collect::<Vec<_>>()
-                .join(", ")
-        );
-    }
-
-    // Verify return type is Vec<i32>
-    match &fn_sig.output {
-        syn::ReturnType::Type(_, ty) => {
-            if !matches!(&**ty, syn::Type::Path(tp) if tp.path.is_ident("Vec")) {
-                panic!("Execute function must return Vec<i32>");
-            }
-        }
-        syn::ReturnType::Default => {
-            panic!("Execute function must return Vec<i32>");
-        }
-    }
-}
-
-fn generate_execute_wrapper(
-    input_fn: syn::ItemFn,
-    fn_name: &syn::Ident,
-    input_count: usize,
-) -> TokenStream {
-    let arg_names: Vec<_> = (0..input_count)
-        .map(|i| syn::Ident::new(&format!("arg{}", i), proc_macro2::Span::call_site()))
-        .collect();
-
-    let expanded = quote! {
-        #input_fn
-
-        #[no_mangle]
-        pub extern "C" fn execute(
-            output_pos: i32,
-            #( #arg_names: i32 ),*
-        ) -> i32 {
-            extern "C" {
-                fn __nodarium_log(ptr: *const u8, len: usize);
-                fn __nodarium_log_panic(ptr: *const u8, len: usize);
-            }
-
-            // Setup panic hook
-            static SET_HOOK: std::sync::Once = std::sync::Once::new();
-            SET_HOOK.call_once(|| {
-                std::panic::set_hook(Box::new(|info| {
-                    let msg = info.to_string();
-                    unsafe { __nodarium_log_panic(msg.as_ptr(), msg.len()); }
-                }));
-            });
-
-            // Call user function
-            let result = #fn_name(
-                #( #arg_names as *const i32 ),*
-            );
-
-            // Write result directly to shared memory at output_pos
-            let len_bytes = result.len() * 4;
-            unsafe {
-                let src = result.as_ptr() as *const u8;
-                let dst = output_pos as *mut u8;
-                dst.copy_from_nonoverlapping(src, len_bytes);
-            }
-
-            // Forget the Vec to prevent deallocation (data is in shared memory now)
-            core::mem::forget(result);
-
-            len_bytes as i32
-        }
-    };
-
-    TokenStream::from(expanded)
-}
-```
-
-### 2.3 Generated Assembly
-
-The macro generates:
-
-```asm
-; Input: output_pos in register r0, arg0 in r1, arg1 in r2, arg2 in r3
-execute:
-    ; Call user function
-    bl    user_execute           ; returns pointer to Vec<i32> in r0
-
-    ; Calculate byte length
-    ldr   r4, [r0, #8]           ; Vec::len field
-    lsl   r4, r4, #2             ; len * 4 (i32 = 4 bytes)
-
-    ; Copy Vec data to shared memory at output_pos
-    ldr   r5, [r0, #0]           ; Vec::ptr field
-    ldr   r6, [r0, #4]           ; capacity (unused)
-
-    ; memcpy(dst=output_pos, src=r5, len=r4)
-    ; (implemented via copy_from_nonoverlapping)
-
-    ; Return length
-    mov   r0, r4
-    bx    lr
-```
-
-## Phase 3: Input Reading Helpers
-
-```rust
-// packages/utils/src/accessor.rs
-
-/// Read i32 from shared memory
-#[inline]
-pub unsafe fn read_i32(ptr: *const i32) -> i32 {
-    *ptr
-}
-
-/// Read f32 from shared memory (stored as i32 bits)
-#[inline]
-pub unsafe fn read_f32(ptr: *const i32) -> f32 {
-    f32::from_bits(*ptr as u32)
-}
-
-/// Read boolean from shared memory
-#[inline]
-pub unsafe fn read_bool(ptr: *const i32) -> bool {
-    *ptr != 0
-}
-
-/// Read vec3 (3 f32s) from shared memory
-#[inline]
-pub unsafe fn read_vec3(ptr: *const i32) -> [f32; 3] {
-    let p = ptr as *const f32;
-    [p.read(), p.add(1).read(), p.add(2).read()]
-}
-
-/// Read slice from shared memory
-#[inline]
-pub unsafe fn read_i32_slice(ptr: *const i32, len: usize) -> &[i32] {
-    std::slice::from_raw_parts(ptr, len)
-}
-
-/// Read f32 slice from shared memory
-#[inline]
-pub unsafe fn read_f32_slice(ptr: *const i32, len: usize) -> &[f32] {
-    std::slice::from_raw_parts(ptr as *const f32, len)
-}
-
-/// Read with default value
-#[inline]
-pub unsafe fn read_f32_default(ptr: *const i32, default: f32) -> f32 {
-    if ptr.is_null() { default } else { read_f32(ptr) }
-}
-
-#[inline]
-pub unsafe fn read_i32_default(ptr: *const i32, default: i32) -> i32 {
-    if ptr.is_null() { default } else { read_i32(ptr) }
-}
-```
-
-## Phase 4: Node Implementation Examples
-
-### 4.1 Math Node
-
-```rust
-// nodes/max/plantarium/math/src/lib.rs
-
-nodarium_definition_file!("src/input.json");
-
-#[nodarium_execute]
-pub fn execute(op_type: *const i32, a: *const i32, b: *const i32) -> Vec<i32> {
-    use nodarium_utils::{read_i32, read_f32};
-
-    let op = unsafe { read_i32(op_type) };
-    let a_val = unsafe { read_f32(a) };
-    let b_val = unsafe { read_f32(b) };
-
-    let result = match op {
-        0 => a_val + b_val,  // add
-        1 => a_val - b_val,  // subtract
-        2 => a_val * b_val,  // multiply
-        3 => a_val / b_val,  // divide
-        _ => 0.0,
-    };
-
-    vec![result.to_bits()]
-}
-```
-
-### 4.2 Vec3 Node
-
-```rust
-// nodes/max/plantarium/vec3/src/lib.rs
-
-nodarium_definition_file!("src/input.json");
-
-#[nodarium_execute]
-pub fn execute(x: *const i32, y: *const i32, z: *const i32) -> Vec<i32> {
-    use nodarium_utils::read_f32;
-
-    let x_val = unsafe { read_f32(x) };
-    let y_val = unsafe { read_f32(y) };
-    let z_val = unsafe { read_f32(z) };
-
-    vec![x_val.to_bits(), y_val.to_bits(), z_val.to_bits()]
-}
-```
-
-### 4.3 Box Node
-
-```rust
-// nodes/max/plantarium/box/src/lib.rs
-
-nodarium_definition_file!("src/input.json");
-
-#[nodarium_execute]
-pub fn execute(size: *const i32) -> Vec<i32> {
-    use nodarium_utils::{read_f32, encode_float, calculate_normals};
-
-    let size = unsafe { read_f32(size) };
-    let p = encode_float(size);
-    let n = encode_float(-size);
-
-    let mut cube_geometry = vec![
-        1,          // 1: geometry
-        8,          // 8 vertices
-        12,         // 12 faces
-
-        // Face indices
-        0, 1, 2, 0, 2, 3,
-        0, 3, 4, 4, 5, 0,
-        6, 1, 0, 5, 6, 0,
-        7, 2, 1, 6, 7, 1,
-        2, 7, 3, 3, 7, 4,
-        7, 6, 4, 4, 6, 5,
-
-        // Bottom plate
-        p, n, n, p, n, p, n, n, p, n, n, n,
-
-        // Top plate
-        n, p, n, p, p, n, p, p, p, n, p, p,
-
-        // Normals
-        0, 0, 0, 0, 0, 0, 0, 0, 0,
-        0, 0, 0, 0, 0, 0, 0, 0, 0,
-    ];
-
-    calculate_normals(&mut cube_geometry);
-    cube_geometry
-}
-```
-
-### 4.4 Stem Node
-
-```rust
-// nodes/max/plantarium/stem/src/lib.rs
-
-nodarium_definition_file!("src/input.json");
-
-#[nodarium_execute]
-pub fn execute(
-    origin: *const i32,
-    amount: *const i32,
-    length: *const i32,
-    thickness: *const i32,
-    resolution: *const i32,
-) -> Vec<i32> {
-    use nodarium_utils::{
-        read_vec3, read_i32, read_f32,
-        geometry::{create_multiple_paths, wrap_multiple_paths},
-    };
-
-    let origin = unsafe { read_vec3(origin) };
-    let amount = unsafe { read_i32(amount) } as usize;
-    let length = unsafe { read_f32(length) };
-    let thickness = unsafe { read_f32(thickness) };
-    let resolution = unsafe { read_i32(resolution) } as usize;
-
-    let mut stem_data = create_multiple_paths(amount, resolution, 1);
-    let mut stems = wrap_multiple_paths(&mut stem_data);
-
-    for stem in stems.iter_mut() {
-        let points = stem.get_points_mut();
-        for (i, point) in points.iter_mut().enumerate() {
-            let t = i as f32 / (resolution as f32 - 1.0);
-            point.x = origin[0];
-            point.y = origin[1] + t * length;
-            point.z = origin[2];
-            point.w = thickness * (1.0 - t);
-        }
-    }
-
-    stem_data
-}
-```
-
-## Phase 5: Runtime Implementation
-
-```typescript
-// app/src/lib/runtime/memory-manager.ts
-
-export const SHARED_MEMORY = new WebAssembly.Memory({
-  initial: 1024, // 64MB initial
-  maximum: 4096, // 256MB maximum
-});
-
-export class MemoryManager {
-  private offset: number = 0;
-  private readonly start: number = 0;
-
-  reset() {
-    this.offset = this.start;
-  }
-
-  alloc(bytes: number): number {
-    const pos = this.offset;
-    this.offset += bytes;
-    return pos;
-  }
-
-  readInt32(pos: number): number {
-    return new Int32Array(SHARED_MEMORY.buffer)[pos / 4];
-  }
-
-  readFloat32(pos: number): number {
-    return new Float32Array(SHARED_MEMORY.buffer)[pos / 4];
-  }
-
-  readBytes(pos: number, length: number): Uint8Array {
-    return new Uint8Array(SHARED_MEMORY.buffer, pos, length);
-  }
-
-  getInt32View(): Int32Array {
-    return new Int32Array(SHARED_MEMORY.buffer);
-  }
-
-  getFloat32View(): Float32Array {
-    return new Float32Array(SHARED_MEMORY.buffer);
-  }
-
-  getRemaining(): number {
-    return SHARED_MEMORY.buffer.byteLength - this.offset;
-  }
-}
-```
-
-```typescript
-// app/src/lib/runtime/imports.ts
-
-import { SHARED_MEMORY } from "./memory-manager";
-
-export function createImportObject(nodeId: string): WebAssembly.Imports {
-  return {
-    env: {
-      // Import shared memory
-      memory: SHARED_MEMORY,
-
-      // Logging
-      __nodarium_log: (ptr: number, len: number) => {
-        const msg = new TextDecoder().decode(
-          new Uint8Array(SHARED_MEMORY.buffer, ptr, len),
-        );
-        console.log(`[${nodeId}] ${msg}`);
-      },
-
-      __nodarium_log_panic: (ptr: number, len: number) => {
-        const msg = new TextDecoder().decode(
-          new Uint8Array(SHARED_MEMORY.buffer, ptr, len),
-        );
-        console.error(`[${nodeId}] PANIC: ${msg}`);
-      },
-    },
-  };
-}
-```
-
-```typescript
-// app/src/lib/runtime/executor.ts
-
-import { SHARED_MEMORY } from "./memory-manager";
-import { createImportObject } from "./imports";
-
-export class SharedMemoryRuntimeExecutor implements RuntimeExecutor {
-  private memory: MemoryManager;
-  private results: Map<string, { pos: number; len: number }> = new Map();
-  private instances: Map<string, WebAssembly.Instance> = new Map();
-
-  constructor(private registry: NodeRegistry) {
-    this.memory = new MemoryManager();
-  }
-
-  async execute(graph: Graph, settings: Record<string, unknown>) {
-    this.memory.reset();
-    this.results.clear();
-
-    const [outputNode, nodes] = await this.addMetaData(graph);
-    const sortedNodes = nodes.sort((a, b) => b.depth - a.depth);
-
-    for (const node of sortedNodes) {
-      await this.executeNode(node, settings);
-    }
-
-    const result = this.results.get(outputNode.id);
-    const view = this.memory.getInt32View();
-    return view.subarray(result.pos / 4, result.pos / 4 + result.len / 4);
-  }
-
-  private async executeNode(
-    node: RuntimeNode,
-    settings: Record<string, unknown>,
-  ) {
-    const def = this.definitionMap.get(node.type)!;
-    const inputs = def.inputs || {};
-    const inputNames = Object.keys(inputs);
-
-    const outputSize = this.estimateOutputSize(def);
-    const outputPos = this.memory.alloc(outputSize);
-    const args: number[] = [outputPos];
-
-    for (const inputName of inputNames) {
-      const inputDef = inputs[inputName];
-      const inputNode = node.state.inputNodes[inputName];
-      if (inputNode) {
-        const parentResult = this.results.get(inputNode.id)!;
-        args.push(parentResult.pos);
-        continue;
-      }
-
-      const valuePos = this.memory.alloc(16);
-      this.writeValue(
-        valuePos,
-        inputDef,
-        node.props?.[inputName] ??
-          settings[inputDef.setting ?? ""] ??
-          inputDef.value,
-      );
-      args.push(valuePos);
-    }
-
-    let instance = this.instances.get(node.type);
-    if (!instance) {
-      instance = await this.instantiateNode(node.type);
-      this.instances.set(node.type, instance);
-    }
-
-    const writtenLen = instance.exports.execute(...args);
-    this.results.set(node.id, { pos: outputPos, len: writtenLen });
-  }
-
-  private writeValue(pos: number, inputDef: NodeInput, value: unknown) {
-    const view = this.memory.getFloat32View();
-    const intView = this.memory.getInt32View();
-
-    switch (inputDef.type) {
-      case "float":
-        view[pos / 4] = value as number;
-        break;
-      case "integer":
-      case "select":
-      case "seed":
-        intView[pos / 4] = value as number;
-        break;
-      case "boolean":
-        intView[pos / 4] = value ? 1 : 0;
-        break;
-      case "vec3":
-        const arr = value as number[];
-        view[pos / 4] = arr[0];
-        view[pos / 4 + 1] = arr[1];
-        view[pos / 4 + 2] = arr[2];
-        break;
-    }
-  }
-
-  private estimateOutputSize(def: NodeDefinition): number {
-    const sizes: Record<string, number> = {
-      float: 16,
-      integer: 16,
-      boolean: 16,
-      vec3: 16,
-      geometry: 8192,
-      path: 4096,
-    };
-    return sizes[def.outputs?.[0] || "float"] || 64;
-  }
-
-  private async instantiateNode(
-    nodeType: string,
-  ): Promise<WebAssembly.Instance> {
-    const wasmBytes = await this.fetchWasm(nodeType);
-    const module = await WebAssembly.compile(wasmBytes);
-    const importObject = createImportObject(nodeType);
-    return WebAssembly.instantiate(module, importObject);
-  }
-}
-```
-
-## Phase 7: Execution Flow Visualization
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                           Execution Timeline                                │
-└─────────────────────────────────────────────────────────────────────────────┘
-
-Step 1: Setup
-  SHARED_MEMORY = new WebAssembly.Memory({ initial: 1024 })
-  memory.offset = 0
-
-Step 2: Execute Node A (math with 3 inputs)
-  outputPos = memory.alloc(16) = 0
-  args = [0, ptr_to_op_type, ptr_to_a, ptr_to_b]
-
-  Node A reads:
-    *ptr_to_op_type → op
-    *ptr_to_a → a
-    *ptr_to_b → b
-
-  Node A returns: vec![result.to_bits()]
-
-  Macro writes result directly to SHARED_MEMORY[0..4]
-  Returns: 4
-
-  results['A'] = { pos: 0, len: 4 }
-  memory.offset = 4
-
-Step 3: Execute Node B (stem with 5 inputs, input[0] from A)
-  outputPos = memory.alloc(4096) = 4
-  args = [4, results['A'].pos, ptr_to_amount, ptr_to_length, ...]
-
-  Node B reads:
-    *results['A'].pos → value from Node A
-    *ptr_to_amount → amount
-    ...
-
-  Node B returns: stem_data Vec<i32> (1000 elements = 4000 bytes)
-
-  Macro writes stem_data directly to SHARED_MEMORY[4..4004]
-  Returns: 4000
-
-  results['B'] = { pos: 4, len: 4000 }
-  memory.offset = 4004
-
-Step 4: Execute Node C (output, 1 input from B)
-  outputPos = memory.alloc(16) = 4004
-  args = [4004, results['B'].pos, results['B'].len]
-
-  Node C reads:
-    *results['B'].pos → stem geometry
-
-  Node C returns: vec![1] (identity)
-  Macro writes to SHARED_MEMORY[4004..4008]
-
-  results['C'] = { pos: 4004, len: 4 }
-
-Final: Return SHARED_MEMORY[4004..4008] as geometry result
-```
-
-## Phase 6: Memory Growth Strategy
-
-```typescript
-class MemoryManager {
-  alloc(bytes: number): number {
-    const required = this.offset + bytes;
-    const currentBytes = SHARED_MEMORY.buffer.byteLength;
-
-    if (required > currentBytes) {
-      const pagesNeeded = Math.ceil((required - currentBytes) / 65536);
-      const success = SHARED_MEMORY.grow(pagesNeeded);
-
-      if (!success) {
-        throw new Error(`Out of memory: need ${bytes} bytes`);
-      }
-
-      this.int32View = new Int32Array(SHARED_MEMORY.buffer);
-      this.float32View = new Float32Array(SHARED_MEMORY.buffer);
-    }
-
-    const pos = this.offset;
-    this.offset += bytes;
-    return pos;
-  }
-}
-```
-
-## Phase 8: Migration Checklist
-
-### Build Configuration
-
-- [ ] Add `--import-memory` to Rust flags in `Cargo.toml`
-- [ ] Ensure no nodes export memory
-
-### Runtime
-
-- [ ] Create `SHARED_MEMORY` instance
-- [ ] Implement `MemoryManager` with alloc/read/write
-- [ ] Create import object factory
-- [ ] Implement `SharedMemoryRuntimeExecutor`
-
-### Macro
-
-- [ ] Parse definition JSON
-- [ ] Validate function signature (N params, Vec<i32> return)
-- [ ] Generate wrapper that writes return value to `output_pos`
-- [ ] Add panic hook
-
-### Utilities
-
-- [ ] `read_i32(ptr: *const i32) -> i32`
-- [ ] `read_f32(ptr: *const i32) -> f32`
-- [ ] `read_bool(ptr: *const i32) -> bool`
-- [ ] `read_vec3(ptr: *const i32) -> [f32; 3]`
-- [ ] `read_i32_slice(ptr: *const i32, len: usize) -> &[i32]`
-
-### Nodes
-
-- [ ] `float`, `integer`, `boolean` nodes
-- [ ] `vec3` node
-- [ ] `math` node
-- [ ] `random` node
-- [ ] `box` node
-- [ ] `stem` node
-- [ ] `branch` node
-- [ ] `instance` node
-- [ ] `output` node
-
-## Phase 9: Before vs After
-
-### Before (per-node memory)
-
-```rust
-#[nodarium_execute]
-pub fn execute(input: &[i32]) -> Vec<i32> {
-    let args = split_args(input);
-    let a = evaluate_float(args[0]);
-    let b = evaluate_float(args[1]);
-    vec![(a + b).to_bits()]
-}
-```
-
-### After (shared memory)
-
-```rust
-#[nodarium_execute]
-pub fn execute(a: *const i32, b: *const i32) -> Vec<i32> {
-    use nodarium_utils::read_f32;
-    let a_val = unsafe { read_f32(a) };
-    let b_val = unsafe { read_f32(b) };
-    vec![(a_val + b_val).to_bits()]
-}
-```
-
-**Key differences:**
-
-- Parameters are input pointers, not a slice
-- Use `read_f32` helper instead of `evaluate_float`
-- Macro writes result directly to shared memory
-- All nodes share the same memory import
-
-## Phase 10: Benefits
-
-| Aspect            | Before         | After                |
-| ----------------- | -------------- | -------------------- |
-| Memory            | N × ~1MB heaps | 1 × 64-256MB shared  |
-| Cross-node access | Copy via JS    | Direct read          |
-| API               | `&[i32]` slice | `*const i32` pointer |
-| Validation        | Runtime        | Compile-time         |

SUMMARY.md

@@ -1,227 +0,0 @@
-# Nodarium - AI Coding Agent Summary
-
-## Project Overview
-
-Nodarium is a WebAssembly-based visual programming language used to build <https://nodes.max-richter.dev>, a procedural 3D plant modeling tool. The system allows users to create visual node graphs where each node is a compiled WebAssembly module.
-
-## Technology Stack
-
-**Frontend (SvelteKit):**
-
-- Framework: SvelteKit with Svelte 5
-- 3D Rendering: Three.js via Threlte
-- Styling: Tailwind CSS 4
-- Build Tool: Vite
-- State Management: Custom store-client package
-- WASM Integration: vite-plugin-wasm, comlink
-
-**Backend/Core (Rust/WASM):**
-
-- Language: Rust
-- Output: WebAssembly (wasm32-unknown-unknown target)
-- Build Tool: cargo
-- Procedural Macros: custom macros package
-
-**Package Management:**
-
-- Node packages: pnpm workspace (v10.28.1)
-- Rust packages: Cargo workspace
-
-## Directory Structure
-
-```
-nodarium/
-├── app/                          # SvelteKit web application
-│   ├── src/
-│   │   ├── lib/                  # App-specific components and utilities
-│   │   ├── routes/               # SvelteKit routes (pages)
-│   │   ├── app.css               # Global styles
-│   │   └── app.html              # HTML template
-│   ├── static/
-│   │   └── nodes/                # Compiled WASM node files served statically
-│   ├── package.json              # App dependencies
-│   ├── svelte.config.js          # SvelteKit configuration
-│   ├── vite.config.ts            # Vite configuration
-│   └── tsconfig.json             # TypeScript configuration
-│
-├── packages/                     # Shared workspace packages
-│   ├── ui/                       # Svelte UI component library (published as @nodarium/ui)
-│   │   ├── src/                  # UI components
-│   │   ├── static/               # Static assets for UI
-│   │   ├── dist/                 # Built output
-│   │   └── package.json
-│   ├── registry/                 # Node registry with IndexedDB persistence (@nodarium/registry)
-│   │   └── src/
-│   ├── types/                    # Shared TypeScript types (@nodarium/types)
-│   │   └── src/
-│   ├── utils/                    # Shared utilities (@nodarium/utils)
-│   │   └── src/
-│   └── macros/                   # Rust procedural macros for node development
-│
-├── nodes/                        # WebAssembly node packages (Rust)
-│   └── max/plantarium/           # Plantarium nodes namespace
-│       ├── box/                  # Box geometry node
-│       ├── branch/               # Branch generation node
-│       ├── float/                # Float value node
-│       ├── gravity/              # Gravity simulation node
-│       ├── instance/             # Geometry instancing node
-│       ├── math/                 # Math operations node
-│       ├── noise/                # Noise generation node
-│       ├── output/               # Output node for results
-│       ├── random/               # Random value node
-│       ├── rotate/               # Rotation transformation node
-│       ├── stem/                 # Stem geometry node
-│       ├── triangle/             # Triangle geometry node
-│       ├── vec3/                 # Vector3 manipulation node
-│       └── .template/            # Node template for creating new nodes
-│
-├── docs/                         # Documentation
-│   ├── ARCHITECTURE.md           # System architecture overview
-│   ├── DEVELOPING_NODES.md       # Guide for creating new nodes
-│   ├── NODE_DEFINITION.md        # Node definition schema
-│   └── PLANTARIUM.md             # Plantarium-specific documentation
-│
-├── Cargo.toml                    # Rust workspace configuration
-├── package.json                  # Root npm scripts
-├── pnpm-workspace.yaml           # pnpm workspace configuration
-├── pnpm-lock.yaml                # Locked dependency versions
-└── README.md                     # Project readme
-```
-
-## Node System Architecture
-
-### What is a Node?
-
-Nodes are WebAssembly modules that:
-
-- Have a unique ID (e.g., `max/plantarium/stem`)
-- Define inputs with types and default values
-- Define outputs they produce
-- Execute logic when called with arguments
-
-### Node Definition Schema
-
-Nodes are defined via `definition.json` embedded in each WASM module:
-
-```json
-{
-  "id": "namespace/category/node-name",
-  "outputs": ["geometry"],
-  "inputs": {
-    "height": { "type": "float", "value": 1.0 },
-    "radius": { "type": "float", "value": 0.1 }
-  }
-}
-```
-
-For now the outputs are limited to a single output.
-
-### Node Execution
-
-Nodes receive serialized arguments and return serialized outputs. The `nodarium_utils` Rust crate provides helpers for:
-
-- Parsing input arguments
-- Creating geometry data
-- Concatenating output vectors
-
-### Node Registration
-
-Nodes are:
-
-1. Compiled to WASM files in `target/wasm32-unknown-unknown/release/`
-2. Copied to `app/static/nodes/` for serving
-3. Registered in the browser via IndexedDB using the registry package
-
-## Key Dependencies
-
-**Frontend:**
-
-- `@sveltejs/kit` - Application framework
-- `@threlte/core` & `@threlte/extras` - Three.js Svelte integration
-- `three` - 3D graphics library
-- `tailwindcss` - CSS framework
-- `comlink` - WebWorker RPC
-- `idb` - IndexedDB wrapper
-- `wabt` - WebAssembly binary toolkit
-
-**Rust/WASM:**
-
-- Language: Rust (compiled with plain cargo)
-- Output: WebAssembly (wasm32-unknown-unknown target)
-- Generic WASM wrapper for language-agnostic node development
-- `glam` - Math library (Vec2, Vec3, Mat4, etc.)
-- `nodarium_macros` - Custom procedural macros
-- `nodarium_utils` - Shared node utilities
-
-## Build Commands
-
-From root directory:
-
-```bash
-# Install dependencies
-pnpm i
-
-# Build all WASM nodes (compiles Rust, copies to app/static)
-pnpm build:nodes
-
-# Build the app (builds UI library + SvelteKit app)
-pnpm build:app
-
-# Full build (nodes + app)
-pnpm build
-
-# Development
-pnpm dev              # Run all dev commands in parallel
-pnpm dev:nodes        # Watch nodes/, auto-rebuild on changes
-pnpm dev:app_ui       # Watch app and UI package
-pnpm dev_ui           # Watch UI package only
-```
-
-## Workspace Packages
-
-The project uses pnpm workspaces with the following packages:
-
-| Package            | Location           | Purpose                        |
-| ------------------ | ------------------ | ------------------------------ |
-| @nodarium/app      | app/               | Main SvelteKit application     |
-| @nodarium/ui       | packages/ui/       | Reusable UI component library  |
-| @nodarium/registry | packages/registry/ | Node registry with persistence |
-| @nodarium/types    | packages/types/    | Shared TypeScript types        |
-| @nodarium/utils    | packages/utils/    | Shared utilities               |
-| nodarium macros    | packages/macros/   | Rust procedural macros         |
-
-## Configuration Files
-
-- `.dprint.jsonc` - Dprint formatter configuration
-- `svelte.config.js` - SvelteKit configuration (app and ui)
-- `vite.config.ts` - Vite bundler configuration
-- `tsconfig.json` - TypeScript configuration (app and packages)
-- `Cargo.toml` - Rust workspace with member packages
-- `flake.nix` - Nix development environment
-
-## Development Workflow
-
-### Adding a New Node
-
-1. Copy the `.template` directory in `nodes/max/plantarium/` to create a new node directory
-2. Define node in `src/definition.json`
-3. Implement logic in `src/lib.rs`
-4. Build with `cargo build --release --target wasm32-unknown-unknown`
-5. Test by dragging onto the node graph
-
-### Modifying UI Components
-
-1. Changes to `packages/ui/` automatically rebuild with watch mode
-2. App imports from `@nodarium/ui`
-3. Run `pnpm dev:app_ui` for hot reload
-
-## Important Notes for AI Agents
-
-1. **WASM Compilation**: Nodes require `wasm32-unknown-unknown` target (`rustup target add wasm32-unknown-unknown`)
-2. **Cross-Compilation**: WASM build happens on host, not in containers/VMs
-3. **Static Serving**: Compiled WASM files must exist in `app/static/nodes/` before dev server runs
-4. **Workspace Dependencies**: Use `workspace:*` protocol for internal packages
-5. **Threlte Version**: Uses Threlte 8.x, not 7.x (important for 3D component APIs)
-6. **Svelte 5**: Project uses Svelte 5 with runes (`$state`, `$derived`, `$effect`)
-7. **Tailwind 4**: Uses Tailwind CSS v4 with `@tailwindcss/vite` plugin
-8. **IndexedDB**: Registry uses IDB for persistent node storage in browser

SUMMARY_RUNTIME.md

@@ -1,294 +0,0 @@
-# Node Compilation and Runtime Execution
-
-## Overview
-
-Nodarium nodes are WebAssembly modules written in Rust. Each node is a compiled WASM binary that exposes a standardized C ABI interface. The system uses procedural macros to generate the necessary boilerplate for node definitions, memory management, and execution.
-
-## Node Compilation
-
-### 1. Node Definition (JSON)
-
-Each node has a `src/input.json` file that defines:
-
-```json
-{
-  "id": "max/plantarium/stem",
-  "meta": { "description": "Creates a stem" },
-  "outputs": ["path"],
-  "inputs": {
-    "origin": { "type": "vec3", "value": [0, 0, 0], "external": true },
-    "amount": { "type": "integer", "value": 1, "min": 1, "max": 64 },
-    "length": { "type": "float", "value": 5 },
-    "thickness": { "type": "float", "value": 0.2 }
-  }
-}
-```
-
-### 2. Procedural Macros
-
-The `nodarium_macros` crate provides two procedural macros:
-
-#### `#[nodarium_execute]`
-
-Transforms a Rust function into a WASM-compatible entry point:
-
-```rust
-#[nodarium_execute]
-pub fn execute(input: &[i32]) -> Vec<i32> {
-    // Node logic here
-}
-```
-
-The macro generates:
-- **C ABI wrapper**: Converts the WASM interface to a standard C FFI
-- **`execute` function**: Takes `(ptr: *const i32, len: usize)` and returns `*mut i32`
-- **Memory allocation**: `__alloc(len: usize) -> *mut i32` for buffer allocation
-- **Memory deallocation**: `__free(ptr: *mut i32, len: usize)` for cleanup
-- **Static output buffer**: `OUTPUT_BUFFER` for returning results
-- **Panic hook**: Routes panics through `host_log_panic` for debugging
-- **Internal logic wrapper**: Wraps the original function
-
-#### `nodarium_definition_file!("path")`
-
-Embeds the node definition JSON into the WASM binary:
-
-```rust
-nodarium_definition_file!("src/input.json");
-```
-
-Generates:
-- **`DEFINITION_DATA`**: Static byte array in `nodarium_definition` section
-- **`get_definition_ptr()`**: Returns pointer to definition data
-- **`get_definition_len()`**: Returns length of definition data
-
-### 3. Build Process
-
-Nodes are compiled with:
-```bash
-cargo build --release --target wasm32-unknown-unknown
-```
-
-The resulting `.wasm` files are copied to `app/static/nodes/` for serving.
-
-## Node Execution Runtime
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    WebWorker Thread                          │
-│  ┌─────────────────────────────────────────────────────────┐│
-│  │              WorkerRuntimeExecutor                       ││
-│  │  ┌───────────────────────────────────────────────────┐  ││
-│  │  │           MemoryRuntimeExecutor                    ││
-│  │  │  ┌─────────────────────────────────────────────┐  ││
-│  │  │  │  Node Registry (WASM + Definitions)         ││
-│  │  │  └─────────────────────────────────────────────┘  ││
-│  │  │  ┌─────────────────────────────────────────────┐  ││
-│  │  │  │  Execution Engine (Bottom-Up Evaluation)    ││
-│  │  │  └─────────────────────────────────────────────┘  ││
-│  │  └───────────────────────────────────────────────────┘  ││
-│  └─────────────────────────────────────────────────────────┘│
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 1. MemoryRuntimeExecutor
-
-The core execution engine in `runtime-executor.ts`:
-
-#### Metadata Collection (`addMetaData`)
-
-1. Load node definitions from registry
-2. Build parent/child relationships from graph edges
-3. Calculate execution depth via reverse BFS from output node
-
-#### Node Sorting
-
-Nodes are sorted by depth (highest depth first) for bottom-up execution:
-
-```
-Depth 3:  n3  n6
-Depth 2:  n2  n4  n5
-Depth 1:  n1
-Depth 0:  Output
-Execution order: n3, n6, n2, n4, n5, n1, Output
-```
-
-#### Input Collection
-
-For each node, inputs are gathered from:
-1. **Connected nodes**: Results from parent nodes in the graph
-2. **Node props**: Values stored directly on the node instance
-3. **Settings**: Global settings mapped via `setting` property
-4. **Defaults**: Values from node definition
-
-#### Input Encoding
-
-Values are encoded as `Int32Array`:
-- **Floats**: IEEE 754 bits cast to i32
-- **Vectors**: `[0, count, v1, v2, v3, 1, 1]` (nested bracket format)
-- **Booleans**: `0` or `1`
-- **Integers**: Direct i32 value
-
-#### Caching
-
-Results are cached using:
-```typescript
-inputHash = `node-${node.id}-${fastHashArrayBuffer(encoded_inputs)}`
-```
-
-The cache uses LRU eviction (default size: 50 entries).
-
-### 2. Execution Flow
-
-```typescript
-async execute(graph: Graph, settings) {
-  // 1. Load definitions and build node relationships
-  const [outputNode, nodes] = await this.addMetaData(graph);
-
-  // 2. Sort nodes by depth (bottom-up)
-  const sortedNodes = nodes.sort((a, b) => b.depth - a.depth);
-
-  // 3. Execute each node
-  for (const node of sortedNodes) {
-    const inputs = this.collectInputs(node, settings);
-    const encoded = concatEncodedArrays(inputs);
-    const result = nodeType.execute(encoded);
-    this.results[node.id] = result;
-  }
-
-  // 4. Return output node result
-  return this.results[outputNode.id];
-}
-```
-
-### 3. Worker Isolation
-
-`WorkerRuntimeExecutor` runs execution in a WebWorker via Comlink:
-
-```typescript
-class WorkerRuntimeExecutor implements RuntimeExecutor {
-  private worker = new ComlinkWorker(...);
-
-  async execute(graph, settings) {
-    return this.worker.executeGraph(graph, settings);
-  }
-}
-```
-
-The worker backend (`worker-runtime-executor-backend.ts`):
-- Creates a single `MemoryRuntimeExecutor` instance
-- Manages caching state
-- Collects performance metrics
-
-### 4. Remote Execution (Optional)
-
-`RemoteRuntimeExecutor` can execute graphs on a remote server:
-
-```typescript
-class RemoteRuntimeExecutor implements RuntimeExecutor {
-  async execute(graph, settings) {
-    const res = await fetch(this.url, {
-      method: "POST",
-      body: JSON.stringify({ graph, settings })
-    });
-    return new Int32Array(await res.arrayBuffer());
-  }
-}
-```
-
-## Data Encoding Format
-
-### Bracket Notation
-
-Inputs and outputs use a nested bracket encoding:
-
-```
-[0, count, item1, item2, ..., 1, 1]
-   ^    ^       items                ^  ^
-   |    |                         |  |
-   |    |                         |  +-- closing bracket
-   |    +-- number of items + 1   |
-   +-- opening bracket (0)         +-- closing bracket (1)
-```
-
-### Example Encodings
-
-**Float (5.0)**:
-```typescript
-encodeFloat(5.0) // → 1084227584 (IEEE 754 bits as i32)
-```
-
-**Vec3 ([1, 2, 3])**:
-```typescript
-[0, 4, encodeFloat(1), encodeFloat(2), encodeFloat(3), 1, 1]
-```
-
-**Nested Math Expression**:
-```
-[0, 3, 0, 2, 0, 3, 0, 0, 0, 3, 7549747, 127, 1, 1, ...]
-```
-
-### Decoding Utilities
-
-From `packages/utils/src/tree.rs`:
-- `split_args()`: Parses nested bracket arrays into segments
-- `evaluate_float()`: Recursively evaluates and decodes float expressions
-- `evaluate_int()`: Evaluates integer/math node expressions
-- `evaluate_vec3()`: Decodes vec3 arrays
-
-## Geometry Data Format
-
-### Path Data
-
-Paths represent procedural plant structures:
-
-```
-[0, count, [0, header_size, node_type, depth, x, y, z, w, ...], 1, 1]
-```
-
-Each point has 4 values: x, y, z position + thickness (w).
-
-### Geometry Data
-
-Meshes use a similar format with vertices and face indices.
-
-## Performance Tracking
-
-The runtime collects detailed performance metrics:
-- `collect-metadata`: Time to build node graph
-- `collected-inputs`: Time to gather inputs
-- `encoded-inputs`: Time to encode inputs
-- `hash-inputs`: Time to compute cache hash
-- `cache-hit`: 1 if cache hit, 0 if miss
-- `node/{node_type}`: Time per node execution
-
-## Caching Strategy
-
-### MemoryRuntimeCache
-
-LRU cache implementation:
-```typescript
-class MemoryRuntimeCache {
-  private map = new Map<string, unknown>();
-  size: number = 50;
-
-  get(key) { /* move to front */ }
-  set(key, value) { /* evict oldest if at capacity */ }
-}
-```
-
-### IndexDBCache
-
-For persistence across sessions, the registry uses IndexedDB caching.
-
-## Summary
-
-The Nodarium node system works as follows:
-
-1. **Compilation**: Rust functions are decorated with macros that generate C ABI WASM exports
-2. **Registration**: Node definitions are embedded in WASM and loaded at runtime
-3. **Graph Analysis**: Runtime builds node relationships and execution order
-4. **Bottom-Up Execution**: Nodes execute from leaves to output
-5. **Caching**: Results are cached per-node-inputs hash for performance
-6. **Isolation**: Execution runs in a WebWorker to prevent main thread blocking

app/Dockerfile

@@ -28,6 +28,5 @@ RUN rm /etc/nginx/conf.d/default.conf
 COPY app/docker/app.conf /etc/nginx/conf.d/app.conf
 
 COPY --from=builder /app/app/build /app
-COPY --from=builder /app/packages/ui/build /app/ui
 
 EXPOSE 80

app/e2e/main.test.ts

@@ -23,9 +23,9 @@ test('test', async ({ page }) => {
       id: '10',
       type: 'max/plantarium/stem',
       props: {
-        amount: 50,
+        amount: 4,
         length: 4,
-        thickness: 1
+        thickness: 0.2
       }
     },
     {

app/package.json

@@ -20,6 +20,7 @@
   "dependencies": {
     "@nodarium/ui": "workspace:*",
     "@nodarium/utils": "workspace:*",
+    "@nodarium/planty": "workspace:*",
     "@sveltejs/kit": "^2.50.2",
     "@tailwindcss/vite": "^4.1.18",
     "@threlte/core": "8.3.1",

app/src/app.css

@@ -1,5 +1,7 @@
 @import "tailwindcss";
 @source "../../packages/ui/**/*.svelte";
+@source "../../packages/planty/src/lib/**/*.svelte";
+
 @plugin "@iconify/tailwind4" {
   prefix: "i";
   icon-sets: from-folder("custom", "./src/lib/icons");

app/src/app.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <link rel="icon" href="%sveltekit.assets%/favicon.svg" />
+    <meta name="color-scheme" content="light dark">
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     %sveltekit.head%
     <title>Nodes</title>

app/src/lib/graph-interface/components/AddMenu.svelte

@@ -183,7 +183,7 @@
             activeNodeId = node.id;
           }}
         >
-          {node.id.split('/').at(-1)}
+          {node.meta?.title ?? node.id.split('/').at(-1)}
         </div>
       {/each}
     </div>

app/src/lib/graph-interface/graph-manager.svelte.ts

@@ -3,11 +3,14 @@ import { RemoteNodeRegistry } from '$lib/node-registry/index';
 import type {
   Edge,
   Graph,
+  GroupSocket,
   NodeDefinition,
+  NodeGroupDefinition,
   NodeId,
   NodeInput,
   NodeInstance,
   NodeRegistry,
+  SerializedNode,
   Socket
 } from '@nodarium/types';
 import { fastHashString } from '@nodarium/utils';
@@ -25,7 +28,7 @@ const clone = 'structuredClone' in self
   ? self.structuredClone
   : (args: unknown) => JSON.parse(JSON.stringify(args));
 
-export function areSocketsCompatible(
+function areSocketsCompatible(
   output: string | undefined,
   inputs: string | (string | undefined)[] | undefined
 ) {
@@ -33,7 +36,7 @@ export function areSocketsCompatible(
   if (Array.isArray(inputs) && output) {
     return inputs.includes('*') || inputs.includes(output);
   }
-  return inputs === output || inputs === '*';
+  return inputs === output;
 }
 
 function areEdgesEqual(firstEdge: Edge, secondEdge: Edge) {
@@ -56,6 +59,14 @@ function areEdgesEqual(firstEdge: Edge, secondEdge: Edge) {
   return true;
 }
 
+function isVirtualType(type: string): boolean {
+  return type.startsWith('__virtual/');
+}
+
+function isGroupInstanceType(type: string): boolean {
+  return type === '__virtual/group/instance';
+}
+
 export class GraphManager extends EventEmitter<{
   save: Graph;
   result: unknown;
@@ -79,6 +90,12 @@ export class GraphManager extends EventEmitter<{
 
   currentUndoGroup: number | null = null;
 
+  // Group-related state
+  groups: Map<string, NodeGroupDefinition> = new Map();
+  groupNodeDefinitions: Map<string, NodeDefinition> = new Map();
+  currentGroupContext: string | null = null;
+  graphStack: { rootGraph: Graph; groupId: string; cameraPosition: [number, number, number] }[] = $state([]);
+
   inputSockets = $derived.by(() => {
     const s = new SvelteSet<string>();
     for (const edge of this.edges) {
@@ -88,37 +105,523 @@ export class GraphManager extends EventEmitter<{
   });
 
   history: HistoryManager = new HistoryManager();
+  private serializeFullGraph(): Graph {
+    if (this.graphStack.length === 0) return this.serialize();
+    // Merge the current internal state upward through every stack level.
+    // $state.snapshot strips Svelte reactive proxies so the result can cross
+    // the postMessage boundary to the worker.
+    let merged: Graph = this.serialize();
+    for (let i = this.graphStack.length - 1; i >= 0; i--) {
+      const { rootGraph, groupId } = $state.snapshot(this.graphStack[i]);
+      merged = {
+        ...rootGraph,
+        groups: {
+          ...rootGraph.groups,
+          [groupId]: {
+            ...rootGraph.groups?.[groupId]!,
+            graph: { nodes: merged.nodes, edges: merged.edges }
+          }
+        }
+      };
+    }
+    return merged;
+  }
+
   execute = throttle(() => {
     if (this.loaded === false) return;
-    this.emit('result', this.serialize());
+    this.emit('result', this.serializeFullGraph());
   }, 10);
 
   constructor(public registry: NodeRegistry) {
     super();
   }
 
+  // --- Group helpers ---
+
+  private buildGroupNodeDefinition(group: NodeGroupDefinition): NodeDefinition {
+    return {
+      id: `__virtual/group/${group.id}` as NodeId,
+      meta: { title: group.name },
+      inputs: Object.fromEntries(
+        group.inputs.map(s => [s.name, { type: s.type, external: true } as NodeInput])
+      ),
+      outputs: group.outputs.map(s => s.type),
+      execute(input: Int32Array): Int32Array { return input; }
+    };
+  }
+
+  buildGroupInputNodeDef(group: NodeGroupDefinition): NodeDefinition {
+    return {
+      id: '__virtual/group/input' as NodeId,
+      inputs: {},
+      outputs: group.inputs.map(s => s.type),
+      execute(input: Int32Array): Int32Array { return input; }
+    };
+  }
+
+  buildGroupOutputNodeDef(group: NodeGroupDefinition): NodeDefinition {
+    return {
+      id: '__virtual/group/output' as NodeId,
+      inputs: Object.fromEntries(
+        group.outputs.map(s => [s.name, { type: s.type }])
+      ) as Record<string, NodeInput>,
+      outputs: [],
+      execute(input: Int32Array): Int32Array { return input; }
+    };
+  }
+
+  private getNodeTypeWithContext(type: string, props?: Record<string, unknown>): NodeDefinition | undefined {
+    if (type === '__virtual/group/input' && this.currentGroupContext) {
+      const group = this.groups.get(this.currentGroupContext);
+      if (group) return this.buildGroupInputNodeDef(group);
+    }
+    if (type === '__virtual/group/output' && this.currentGroupContext) {
+      const group = this.groups.get(this.currentGroupContext);
+      if (group) return this.buildGroupOutputNodeDef(group);
+    }
+    if (type === '__virtual/group/instance') {
+      const groupId = props?.groupId as string | undefined;
+      if (groupId) return this.groupNodeDefinitions.get(`__virtual/group/${groupId}`);
+      return undefined;
+    }
+    return this.groupNodeDefinitions.get(type) || this.registry.getNode(type);
+  }
+
+  // --- Group creation ---
+
+  createGroup(nodeIds: number[]): NodeInstance | undefined {
+    if (nodeIds.length === 0) return;
+
+    const selectedNodes = nodeIds
+      .map(id => this.getNode(id))
+      .filter(Boolean) as NodeInstance[];
+    if (selectedNodes.length === 0) return;
+
+    const selectedSet = new Set(nodeIds);
+
+    // Snapshot boundary edges
+    const incomingEdges = this.edges.filter(e =>
+      !selectedSet.has(e[0].id) && selectedSet.has(e[2].id)
+    );
+    const outgoingEdges = this.edges.filter(e =>
+      selectedSet.has(e[0].id) && !selectedSet.has(e[2].id)
+    );
+
+    const inputs: GroupSocket[] = incomingEdges.map((e, i) => ({
+      name: `input_${i}`,
+      type: e[0].state.type?.outputs?.[e[1]] || '*'
+    }));
+
+    const outputs: GroupSocket[] = outgoingEdges.map((e, i) => ({
+      name: `output_${i}`,
+      type: e[0].state.type?.outputs?.[e[1]] || '*'
+    }));
+
+    const groupId = `grp_${Date.now().toString(36)}`;
+
+    const xs = selectedNodes.map(n => n.position[0]);
+    const ys = selectedNodes.map(n => n.position[1]);
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const avgY = ys.reduce((a, b) => a + b, 0) / ys.length;
+    const centroidX = xs.reduce((a, b) => a + b, 0) / xs.length;
+
+    // Find unique IDs for virtual nodes in the internal graph
+    const existingIds = new Set(selectedNodes.map(n => n.id));
+    let internalInputId = 1;
+    while (existingIds.has(internalInputId)) internalInputId++;
+    existingIds.add(internalInputId);
+    let internalOutputId = internalInputId + 1;
+    while (existingIds.has(internalOutputId)) internalOutputId++;
+
+    const internalNodes: SerializedNode[] = [
+      {
+        id: internalInputId,
+        type: '__virtual/group/input' as NodeId,
+        position: [minX - 25, avgY]
+      },
+      ...selectedNodes.map(n => {
+        // Use $state.snapshot to get plain values (no reactive proxies)
+        const props = n.props ? $state.snapshot(n.props) : undefined;
+        const meta = n.meta ? $state.snapshot(n.meta) : undefined;
+        return {
+          id: n.id,
+          type: n.type,
+          position: [n.position[0], n.position[1]] as [number, number],
+          ...(props !== undefined ? { props } : {}),
+          ...(meta ? { meta } : {})
+        };
+      }),
+      {
+        id: internalOutputId,
+        type: '__virtual/group/output' as NodeId,
+        position: [maxX + 25, avgY]
+      }
+    ];
+
+    const internalEdges: Graph['edges'] = [
+      ...this.getEdgesBetweenNodes(selectedNodes),
+      ...incomingEdges.map((e, i) =>
+        [internalInputId, i, e[2].id, e[3]] as [number, number, number, string]
+      ),
+      ...outgoingEdges.map((e, i) =>
+        [e[0].id, e[1], internalOutputId, `output_${i}`] as [number, number, number, string]
+      )
+    ];
+
+    const group: NodeGroupDefinition = {
+      id: groupId,
+      name: 'Group',
+      inputs,
+      outputs,
+      graph: { nodes: internalNodes, edges: internalEdges }
+    };
+
+    this.groups.set(groupId, group);
+    if (!this.graph.groups) this.graph.groups = {};
+    this.graph.groups[groupId] = group;
+
+    const groupNodeDef = this.buildGroupNodeDefinition(group);
+    this.groupNodeDefinitions.set(groupNodeDef.id, groupNodeDef);
+
+    this.startUndoGroup();
+
+    // Remove selected nodes and all their edges
+    for (const node of selectedNodes) {
+      const connectedEdges = this.edges.filter(
+        e => e[0].id === node.id || e[2].id === node.id
+      );
+      for (const e of connectedEdges) {
+        this.removeEdge(e, { applyDeletion: false });
+      }
+      this.nodes.delete(node.id);
+    }
+
+    // Place group instance node (plain object like _init — don't wrap in $state()
+    // to avoid Svelte 5 deeply-proxying the NodeDefinition execute function)
+    const groupNodeId = this.createNodeId();
+    const groupNode = {
+      id: groupNodeId,
+      type: '__virtual/group/instance' as NodeId,
+      position: [centroidX, avgY] as [number, number],
+      props: { groupId },
+      state: { type: groupNodeDef }
+    } as NodeInstance;
+    this.nodes.set(groupNodeId, groupNode);
+
+    // Reconnect boundary edges
+    for (let i = 0; i < incomingEdges.length; i++) {
+      const e = incomingEdges[i];
+      this.createEdge(e[0], e[1], groupNode, inputs[i].name, { applyUpdate: false });
+    }
+    for (let i = 0; i < outgoingEdges.length; i++) {
+      const e = outgoingEdges[i];
+      this.createEdge(groupNode, i, e[2], e[3], { applyUpdate: false });
+    }
+
+    this.saveUndoGroup();
+    this.execute();
+
+    return groupNode;
+  }
+
+  // --- Ungrouping ---
+
+  ungroup(nodeId: number) {
+    const groupNode = this.getNode(nodeId);
+    if (!groupNode || !isGroupInstanceType(groupNode.type)) return;
+
+    const groupId = groupNode.props?.groupId as string | undefined;
+    if (!groupId) return;
+    const group = this.groups.get(groupId);
+    if (!group) return;
+
+    const incomingEdges = this.getEdgesToNode(groupNode);
+    const outgoingEdges = this.getEdgesFromNode(groupNode);
+
+    const inputVirtualId = group.graph.nodes.find(
+      n => n.type === '__virtual/group/input'
+    )?.id;
+    const outputVirtualId = group.graph.nodes.find(
+      n => n.type === '__virtual/group/output'
+    )?.id;
+
+    this.startUndoGroup();
+
+    // Remove the group instance node (and its edges)
+    this.removeNode(groupNode, { restoreEdges: false });
+
+    // Re-insert internal nodes
+    const idMap = new Map<number, number>();
+    const realInternalNodes = group.graph.nodes.filter(
+      n => n.type !== '__virtual/group/input' && n.type !== '__virtual/group/output'
+    );
+
+    for (const n of realInternalNodes) {
+      const newId = this.createNodeId();
+      idMap.set(n.id, newId);
+      const nodeType = this.getNodeTypeWithContext(n.type, n.props as Record<string, unknown>);
+      const newNode: NodeInstance = $state({
+        id: newId,
+        type: n.type,
+        position: [...n.position] as [number, number],
+        ...(n.props ? { props: { ...n.props } } : {}),
+        state: nodeType ? { type: nodeType } : {}
+      });
+      this.nodes.set(newId, newNode);
+    }
+
+    // Re-wire edges
+    for (const e of group.graph.edges) {
+      const fromIsInput = e[0] === inputVirtualId;
+      const toIsOutput = e[2] === outputVirtualId;
+
+      if (fromIsInput) {
+        const inputIdx = e[1];
+        const parentEdge = incomingEdges.find(
+          pe => pe[3] === group.inputs[inputIdx]?.name
+        );
+        if (parentEdge) {
+          const toNode = this.getNode(idMap.get(e[2])!);
+          if (toNode) {
+            this.createEdge(parentEdge[0], parentEdge[1], toNode, e[3], {
+              applyUpdate: false
+            });
+          }
+        }
+      } else if (toIsOutput) {
+        const outputSocketName = e[3];
+        const outputIdx = group.outputs.findIndex(s => s.name === outputSocketName);
+        const parentEdge = outgoingEdges.find(pe => pe[1] === outputIdx);
+        if (parentEdge) {
+          const fromNode = this.getNode(idMap.get(e[0])!);
+          const toNode = this.getNode(parentEdge[2].id);
+          if (fromNode && toNode) {
+            this.createEdge(fromNode, e[1], toNode, parentEdge[3], {
+              applyUpdate: false
+            });
+          }
+        }
+      } else {
+        const fromNode = this.getNode(idMap.get(e[0])!);
+        const toNode = this.getNode(idMap.get(e[2])!);
+        if (fromNode && toNode) {
+          this.createEdge(fromNode, e[1], toNode, e[3], { applyUpdate: false });
+        }
+      }
+    }
+
+    // Remove group definition if no more instances
+    const hasOtherInstances = Array.from(this.nodes.values()).some(
+      n => n.type === '__virtual/group/instance' && (n.props?.groupId as string) === groupId
+    );
+    if (!hasOtherInstances) {
+      this.groups.delete(groupId);
+      this.groupNodeDefinitions.delete(`__virtual/group/${groupId}`);
+      if (this.graph.groups) {
+        delete this.graph.groups[groupId];
+      }
+    }
+
+    this.saveUndoGroup();
+    this.execute();
+  }
+
+  // --- Group socket management (called from inside a group) ---
+
+  addGroupSocket(kind: 'input' | 'output', socketType: string) {
+    if (!this.currentGroupContext) return;
+    const group = this.groups.get(this.currentGroupContext);
+    if (!group) return;
+
+    const arr = kind === 'input' ? group.inputs : group.outputs;
+    const name = `${kind}_${arr.length}`;
+    arr.push({ name, type: socketType });
+
+    this._refreshGroupContext(group);
+    this.save();
+  }
+
+  removeGroupSocket(kind: 'input' | 'output', index: number) {
+    if (!this.currentGroupContext) return;
+    const group = this.groups.get(this.currentGroupContext);
+    if (!group) return;
+
+    const arr = kind === 'input' ? group.inputs : group.outputs;
+    arr.splice(index, 1);
+
+    this._refreshGroupContext(group);
+    this.save();
+  }
+
+  private _refreshGroupContext(group: NodeGroupDefinition) {
+    const groupId = group.id;
+
+    // Keep graph.groups in sync
+    if (this.graph.groups?.[groupId]) {
+      this.graph.groups[groupId] = group;
+    }
+
+    // Rebuild the group node definition (used in parent graph)
+    const groupNodeDef = this.buildGroupNodeDefinition(group);
+    this.groupNodeDefinitions.set(groupNodeDef.id, groupNodeDef);
+
+    // Update virtual input/output nodes in the current internal graph,
+    // and any group instance nodes that reference this group
+    const inputDef = this.buildGroupInputNodeDef(group);
+    const outputDef = this.buildGroupOutputNodeDef(group);
+    for (const node of this.nodes.values()) {
+      if (node.type === '__virtual/group/input') node.state.type = inputDef;
+      if (node.type === '__virtual/group/output') node.state.type = outputDef;
+      if (node.type === '__virtual/group/instance' && (node.props?.groupId as string) === groupId) {
+        node.state.type = groupNodeDef;
+      }
+    }
+  }
+
+  // --- Group navigation ---
+
+  enterGroup(nodeId: number, cameraPosition: [number, number, number] = [0, 0, 4]): boolean {
+    const groupNode = this.getNode(nodeId);
+    if (!groupNode || !isGroupInstanceType(groupNode.type)) return false;
+
+    const groupId = groupNode.props?.groupId as string | undefined;
+    if (!groupId) return false;
+    const group = this.groups.get(groupId);
+    if (!group) return false;
+
+    const currentSerialized = this.serialize();
+    this.graphStack.push({ rootGraph: currentSerialized, groupId, cameraPosition });
+
+    this.currentGroupContext = groupId;
+
+    const internalGraph: Graph = {
+      id: this.graph.id,
+      nodes: group.graph.nodes,
+      edges: group.graph.edges,
+      groups: this.graph.groups
+    };
+
+    this.graph = internalGraph;
+    this._init(internalGraph);
+    this.history.reset();
+
+    return true;
+  }
+
+  exitGroup(): [number, number, number] | false {
+    if (this.graphStack.length === 0) return false;
+
+    const { rootGraph, groupId, cameraPosition } = this.graphStack[this.graphStack.length - 1];
+    this.graphStack.pop();
+
+    // Serialize current internal graph state
+    const internalState = this.serialize();
+
+    // Update the group definition in the root graph
+    const updatedRootGraph: Graph = {
+      ...rootGraph,
+      groups: {
+        ...rootGraph.groups,
+        [groupId]: {
+          ...rootGraph.groups?.[groupId]!,
+          graph: {
+            nodes: internalState.nodes,
+            edges: internalState.edges
+          }
+        }
+      }
+    };
+
+    this.currentGroupContext = this.graphStack.length > 0
+      ? this.graphStack[this.graphStack.length - 1].groupId
+      : null;
+
+    this.graph = updatedRootGraph;
+    this._init(updatedRootGraph);
+    this.history.reset();
+    this.save();
+
+    return cameraPosition;
+  }
+
+  get isInsideGroup(): boolean {
+    return this.graphStack.length > 0;
+  }
+
+  get breadcrumbs(): { name: string; groupId: string | null }[] {
+    const crumbs: { name: string; groupId: string | null }[] = [
+      { name: 'Root', groupId: null }
+    ];
+    for (const entry of this.graphStack) {
+      const group = this.groups.get(entry.groupId);
+      crumbs.push({ name: group?.name ?? entry.groupId, groupId: entry.groupId });
+    }
+    return crumbs;
+  }
+
+  // --- Serialization ---
+
+  private serializeGroups(): Graph['groups'] | undefined {
+    const src = this.graph.groups;
+    if (!src || Object.keys(src).length === 0) return undefined;
+    const result: NonNullable<Graph['groups']> = {};
+    for (const [id, group] of Object.entries(src)) {
+      result[id] = {
+        id: group.id,
+        name: group.name,
+        inputs: group.inputs.map(s => ({ name: s.name, type: s.type })),
+        outputs: group.outputs.map(s => ({ name: s.name, type: s.type })),
+        graph: {
+          nodes: group.graph.nodes.map(n => ({
+            id: n.id,
+            type: n.type,
+            position: [n.position[0], n.position[1]] as [number, number],
+            ...(n.props !== undefined ? {
+              props: Object.fromEntries(
+                Object.entries(n.props).map(([k, v]) => [
+                  k,
+                  Array.isArray(v) ? [...v] : v
+                ])
+              )
+            } : {}),
+            ...(n.meta ? { meta: { title: n.meta.title, lastModified: n.meta.lastModified } } : {})
+          })),
+          edges: group.graph.edges.map(
+            e => [e[0], e[1], e[2], e[3]] as [number, number, number, string]
+          )
+        }
+      };
+    }
+    return result;
+  }
+
   serialize(): Graph {
     const nodes = Array.from(this.nodes.values()).map((node) => ({
       id: node.id,
-      position: [...node.position],
+      position: [...node.position] as [number, number],
       type: node.type,
-      props: node.props
-    })) as NodeInstance[];
+      props: node.props ? $state.snapshot(node.props) : undefined
+    }));
     const edges = this.edges.map((edge) => [
       edge[0].id,
       edge[1],
       edge[2].id,
       edge[3]
     ]) as Graph['edges'];
+
+    const groups = this.serializeGroups();
+
     const serialized = {
       id: this.graph.id,
       settings: $state.snapshot(this.settings),
       meta: $state.snapshot(this.graph.meta),
       nodes,
-      edges
+      edges,
+      ...(groups ? { groups } : {})
     };
     logger.log('serializing graph', serialized);
-    return clone($state.snapshot(serialized));
+    return clone(serialized) as Graph;
   }
 
   private lastSettingsHash = 0;
@@ -133,7 +636,12 @@ export class GraphManager extends EventEmitter<{
   }
 
   getNodeDefinitions() {
-    return this.registry.getAllNodes();
+    const all = this.registry.getAllNodes();
+    // Only show the Group node in AddMenu when there's at least one group to assign
+    if (this.groups.size === 0) {
+      return all.filter(n => n.id !== '__virtual/group/instance');
+    }
+    return all;
   }
 
   getLinkedNodes(node: NodeInstance) {
@@ -209,19 +717,14 @@ export class GraphManager extends EventEmitter<{
     const draggedInputs = Object.values(draggedNode.state.type.inputs ?? {});
     const draggedOutputs = draggedNode.state.type.outputs ?? [];
 
-    // Optimization: Pre-calculate parents to avoid cycles
     const parentIds = new SvelteSet(this.getParentsOfNode(draggedNode).map(n => n.id));
 
     return this.edges.filter((edge) => {
       const [fromNode, fromSocketIdx, toNode, toSocketKey] = edge;
 
-      // 1. Prevent cycles: If the target node is already a parent, we can't drop here
       if (parentIds.has(toNode.id)) return false;
-
-      // 2. Prevent self-dropping: Don't drop on edges already connected to this node
       if (fromNode.id === nodeId || toNode.id === nodeId) return false;
 
-      // 3. Check if edge.source can plug into ANY draggedNode.input
       const edgeOutputSocketType = fromNode.state?.type?.outputs?.[fromSocketIdx];
       const canPlugIntoDragged = draggedInputs.some(input => {
         const acceptedTypes = [input.type, ...(input.accepts || [])];
@@ -230,7 +733,6 @@ export class GraphManager extends EventEmitter<{
 
       if (!canPlugIntoDragged) return false;
 
-      // 4. Check if ANY draggedNode.output can plug into edge.target
       const targetInput = toNode.state?.type?.inputs?.[toSocketKey];
       const targetAcceptedTypes = [targetInput?.type, ...(targetInput?.accepts || [])];
 
@@ -267,9 +769,36 @@ export class GraphManager extends EventEmitter<{
   }
 
   private _init(graph: Graph) {
+    // Rebuild group definitions from the graph
+    this.groups.clear();
+    this.groupNodeDefinitions.clear();
+    if (graph.groups) {
+      for (const [groupId, group] of Object.entries(graph.groups)) {
+        this.groups.set(groupId, group);
+        const def = this.buildGroupNodeDefinition(group);
+        this.groupNodeDefinitions.set(def.id, def);
+      }
+    }
+
     const nodes = new SvelteMap(
-      graph.nodes.map((node) => {
-        return [node.id, node as NodeInstance];
+      graph.nodes.map((serialized) => {
+        // Migration: old __virtual/group/{groupId} format → __virtual/group/instance with props.groupId
+        let node = serialized;
+        if (node.type.startsWith('__virtual/group/')
+            && node.type !== '__virtual/group/input'
+            && node.type !== '__virtual/group/output'
+            && node.type !== '__virtual/group/instance') {
+          const oldGroupId = node.type.split('/')[2];
+          node = { ...node, type: '__virtual/group/instance' as NodeId, props: { ...node.props, groupId: oldGroupId } };
+        }
+
+        // IMPORTANT: copy the node so we don't mutate the original SerializedNode
+        // (which may be stored in a group definition). Mutating it would add
+        // state.type (with an execute fn) making it non-cloneable.
+        const nodeType = this.getNodeTypeWithContext(node.type, node.props as Record<string, unknown>);
+        const n = { ...node } as NodeInstance;
+        n.state = nodeType ? { type: nodeType } : {};
+        return [node.id, n];
       })
     );
 
@@ -294,30 +823,6 @@ export class GraphManager extends EventEmitter<{
     this.execute();
   }
 
-  private async loadAllCollections() {
-    // Fetch all nodes from all collections of the loaded nodes
-    const nodeIds = Array.from(new Set([...this.graph.nodes.map((n) => n.type)]));
-    const allCollections = new Set<`${string}/${string}`>();
-    for (const id of nodeIds) {
-      const [user, collection] = id.split('/');
-      allCollections.add(`${user}/${collection}`);
-    }
-
-    const allCollectionIds = await Promise
-      .all([...allCollections]
-        .map(async (collection) =>
-          remoteRegistry
-            .fetchCollection(collection)
-            .then((collection: { nodes: { id: NodeId }[] }) => {
-              return collection.nodes.map(n => n.id.replace(/\.wasm$/, '') as NodeId);
-            })
-        ));
-
-    const missingNodeIds = [...new Set(allCollectionIds.flat())];
-
-    this.registry.load(missingNodeIds);
-  }
-
   async load(graph: Graph) {
     const a = performance.now();
 
@@ -328,7 +833,10 @@ export class GraphManager extends EventEmitter<{
 
     logger.info('loading graph', { nodes: graph.nodes, edges: graph.edges, id: graph.id });
 
-    const nodeIds = Array.from(new SvelteSet([...graph.nodes.map((n) => n.type)]));
+    // Filter out virtual group types — they are resolved locally, not fetched remotely
+    const nodeIds = Array.from(new SvelteSet([
+      ...graph.nodes.map((n) => n.type).filter(t => !isVirtualType(t))
+    ]));
     await this.registry.load(nodeIds);
 
     // Fetch all nodes from all collections of the loaded nodes
@@ -349,13 +857,13 @@ export class GraphManager extends EventEmitter<{
     logger.info('loaded node types', this.registry.getAllNodes());
 
     for (const node of this.graph.nodes) {
+      if (isVirtualType(node.type)) continue;
       const nodeType = this.registry.getNode(node.type);
       if (!nodeType) {
         logger.error(`Node type not found: ${node.type}`);
         this.status = 'error';
         return;
       }
-      // Turn into runtime node
       const n = node as NodeInstance;
       n.state = {};
       n.state.type = nodeType;
@@ -364,7 +872,6 @@ export class GraphManager extends EventEmitter<{
     // load settings
     const settingTypes: Record<
       string,
-      // Optional metadata to map settings to specific nodes
       NodeInput & { __node_type: string; __node_input: string }
     > = {};
     const settingValues = graph.settings || {};
@@ -393,6 +900,10 @@ export class GraphManager extends EventEmitter<{
     this.settings = settingValues;
     this.emit('settings', { types: settingTypes, values: settingValues });
 
+    // Reset navigation
+    this.graphStack = [];
+    this.currentGroupContext = null;
+
     this.history.reset();
     this._init(this.graph);
 
@@ -402,9 +913,7 @@ export class GraphManager extends EventEmitter<{
 
     this.loaded = true;
     logger.log(`Graph loaded in ${performance.now() - a}ms`);
-
     setTimeout(() => this.execute(), 100);
-    this.loadAllCollections(); // lazily load all nodes from all collections
   }
 
   getAllNodes() {
@@ -461,9 +970,7 @@ export class GraphManager extends EventEmitter<{
   }
 
   getNodesBetween(from: NodeInstance, to: NodeInstance): NodeInstance[] | undefined {
-    //  < - - - - from
     const toParents = this.getParentsOfNode(to);
-    //  < - - - - from - - - - to
     const fromParents = this.getParentsOfNode(from);
     if (toParents.includes(from)) {
       const fromChildren = this.getChildren(from);
@@ -472,7 +979,6 @@ export class GraphManager extends EventEmitter<{
       const toChildren = this.getChildren(to);
       return fromParents.filter((n) => toChildren.includes(n));
     } else {
-      // these two nodes are not connected
       return;
     }
   }
@@ -511,10 +1017,10 @@ export class GraphManager extends EventEmitter<{
     const inputs = Object.entries(to.state?.type?.inputs ?? {});
     const outputs = from.state?.type?.outputs ?? [];
     for (let i = 0; i < inputs.length; i++) {
-      const [inputName, input] = inputs[i];
+      const [inputName, input] = inputs[0];
       for (let o = 0; o < outputs.length; o++) {
-        const output = outputs[o];
-        if (input.type === output || input.type === '*') {
+        const output = outputs[0];
+        if (input.type === output) {
           return this.createEdge(from, o, to, inputName);
         }
       }
@@ -526,7 +1032,6 @@ export class GraphManager extends EventEmitter<{
   }
 
   createGraph(nodes: NodeInstance[], edges: [number, number, number, string][]) {
-    // map old ids to new ids
     const idMap = new SvelteMap<number, number>();
 
     let startId = this.createNodeId();
@@ -577,6 +1082,26 @@ export class GraphManager extends EventEmitter<{
     position: NodeInstance['position'];
     props: NodeInstance['props'];
   }) {
+    if (type === '__virtual/group/instance') {
+      const firstEntry = this.groups.entries().next();
+      if (firstEntry.done) {
+        logger.error('No groups available to create a group node');
+        return;
+      }
+      const [groupId] = firstEntry.value;
+      const groupNodeDef = this.groupNodeDefinitions.get(`__virtual/group/${groupId}`);
+      const node = {
+        id: this.createNodeId(),
+        type: '__virtual/group/instance' as NodeId,
+        position,
+        props: { groupId, ...props },
+        state: { type: groupNodeDef }
+      } as NodeInstance;
+      this.nodes.set(node.id, node);
+      this.save();
+      return node;
+    }
+
     const nodeType = this.registry.getNode(type);
     if (!nodeType) {
       logger.error(`Node type not found: ${type}`);
@@ -607,7 +1132,6 @@ export class GraphManager extends EventEmitter<{
   ): Edge | undefined {
     const existingEdges = this.getEdgesToNode(to);
 
-    // check if this exact edge already exists
     const existingEdge = existingEdges.find(
       (e) => e[0].id === from.id && e[1] === fromSocket && e[3] === toSocket
     );
@@ -616,14 +1140,10 @@ export class GraphManager extends EventEmitter<{
       return;
     }
 
-    const fromType = from.state.type || this.registry.getNode(from.type);
-    const toType = to.state.type || this.registry.getNode(to.type);
-
-    // check if socket types match
-    const fromSocketType = fromType?.outputs?.[fromSocket];
-    const toSocketType = [toType?.inputs?.[toSocket]?.type];
-    if (toType?.inputs?.[toSocket]?.accepts) {
-      toSocketType.push(...(toType?.inputs?.[toSocket]?.accepts || []));
+    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 || []));
     }
 
     if (!areSocketsCompatible(fromSocketType, toSocketType)) {
@@ -687,12 +1207,13 @@ export class GraphManager extends EventEmitter<{
     const state = this.serialize();
     this.history.save(state);
 
-    // This is some stupid race condition where the graph-manager emits a save event
-    // when the graph is not fully loaded
     if (this.nodes.size === 0 && this.edges.length === 0) {
       return;
     }
 
+    // Don't emit save event while navigating inside a group
+    if (this.graphStack.length > 0) return;
+
     this.emit('save', state);
     logger.log('saving graphs', state);
   }
@@ -746,15 +1267,12 @@ export class GraphManager extends EventEmitter<{
   }
 
   getPossibleSockets({ node, index }: Socket): [NodeInstance, string | number][] {
-    const nodeType = this.registry.getNode(node.type);
+    const nodeType = node?.state?.type;
     if (!nodeType) return [];
-    console.log({ index });
 
     const sockets: [NodeInstance, string | number][] = [];
 
-    // if index is a string, we are an input looking for outputs
     if (typeof index === 'string') {
-      // filter out self and child nodes
       const children = new SvelteSet(this.getChildren(node).map((n) => n.id));
       const nodes = this.getAllNodes().filter(
         (n) => n.id !== node.id && !children.has(n.id)
@@ -763,7 +1281,7 @@ export class GraphManager extends EventEmitter<{
       const ownType = nodeType?.inputs?.[index].type;
 
       for (const node of nodes) {
-        const nodeType = this.registry.getNode(node.type);
+        const nodeType = node?.state?.type;
         const inputs = nodeType?.outputs;
         if (!inputs) continue;
         for (let index = 0; index < inputs.length; index++) {
@@ -773,9 +1291,6 @@ export class GraphManager extends EventEmitter<{
         }
       }
     } else if (typeof index === 'number') {
-      // if index is a number, we are an output looking for inputs
-
-      // filter out self and parent nodes
       const parents = new SvelteSet(this.getParentsOfNode(node).map((n) => n.id));
       const nodes = this.getAllNodes().filter(
         (n) => n.id !== node.id && !parents.has(n.id)
@@ -795,7 +1310,7 @@ export class GraphManager extends EventEmitter<{
       const ownType = nodeType.outputs?.[index];
 
       for (const node of nodes) {
-        const inputs = this.registry.getNode(node.type)?.inputs;
+        const inputs = node?.state?.type?.inputs;
         if (!inputs) continue;
         for (const key in inputs) {
           const otherType = [inputs[key].type];
@@ -811,7 +1326,6 @@ export class GraphManager extends EventEmitter<{
       }
     }
 
-    console.log(`Found ${sockets.length} possible sockets`, sockets);
     return sockets;
   }
 

app/src/lib/graph-interface/graph-state.svelte.ts

@@ -1,3 +1,4 @@
+import { animate, lerp } from '$lib/helpers';
 import type { NodeInstance, Socket } from '@nodarium/types';
 import { getContext, setContext } from 'svelte';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
@@ -98,6 +99,9 @@ export class GraphState {
     edges: [number, number, number, string][];
   } = null;
 
+  // Saved camera position per group so re-entering restores where you left off
+  groupCameras = new Map<string, [number, number, number]>();
+
   cameraBounds = $derived([
     this.cameraPosition[0] - this.width / this.cameraPosition[2] / 2,
     this.cameraPosition[0] + this.width / this.cameraPosition[2] / 2,
@@ -124,6 +128,9 @@ export class GraphState {
   activeNodeId = $state(-1);
   selectedNodes = new SvelteSet<number>();
   activeSocket = $state<Socket | null>(null);
+  safePadding = $state<{ left?: number; right?: number; bottom?: number; top?: number } | null>(
+    null
+  );
   hoveredSocket = $state<Socket | null>(null);
   possibleSockets = $state<Socket[]>([]);
   possibleSocketIds = $derived(
@@ -236,6 +243,37 @@ export class GraphState {
     };
   }
 
+  centerNode(node?: NodeInstance) {
+    const average = [0, 0, 4];
+    if (node) {
+      average[0] = node.position[0] + (this.safePadding?.right || 0) / 10;
+      average[1] = node.position[1];
+      average[2] = 10;
+    } else {
+      for (const node of this.graph.nodes.values()) {
+        average[0] += node.position[0];
+        average[1] += node.position[1];
+      }
+      average[0] = (average[0] / this.graph.nodes.size)
+        + (this.safePadding?.right || 0) / (average[2] * 2);
+      average[1] /= this.graph.nodes.size;
+    }
+
+    const camX = this.cameraPosition[0];
+    const camY = this.cameraPosition[1];
+    const camZ = this.cameraPosition[2];
+
+    const ease = (t: number) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t);
+    const easeZoom = (t: number) => t * t * (3 - 2 * t);
+
+    animate(500, (a: number) => {
+      this.cameraPosition[0] = lerp(camX, average[0], ease(a));
+      this.cameraPosition[1] = lerp(camY, average[1], ease(a));
+      this.cameraPosition[2] = lerp(camZ, average[2], easeZoom(a));
+      if (this.mouseDown) return false;
+    });
+  }
+
   pasteNodes() {
     if (!this.clipboard) return;
 
@@ -259,7 +297,7 @@ export class GraphState {
 
     let { node, index, position } = socket;
 
-    // if the socket is an input socket -> remove existing edges
+    // remove existing edge
     if (typeof index === 'string') {
       const edges = this.graph.getEdgesToNode(node);
       for (const edge of edges) {

app/src/lib/graph-interface/graph/Graph.svelte

@@ -19,10 +19,10 @@
 
   const {
     keymap,
-    addMenuPadding
+    safePadding
   }: {
     keymap: ReturnType<typeof createKeyMap>;
-    addMenuPadding?: { left?: number; right?: number; bottom?: number; top?: number };
+    safePadding?: { left?: number; right?: number; bottom?: number; top?: number };
   } = $props();
 
   const graph = getGraphManager();
@@ -100,6 +100,9 @@
     if (typeof index === 'string') {
       return node.state.type?.inputs?.[index].type || 'unknown';
     }
+    if (node.type === '__virtual/group/instance') {
+      index += 1;
+    }
     return node.state.type?.outputs?.[index] || 'unknown';
   }
 </script>
@@ -172,10 +175,10 @@
       {#if graphState.addMenuPosition}
         <AddMenu
           onnode={handleNodeCreation}
-          paddingTop={addMenuPadding?.top}
-          paddingRight={addMenuPadding?.right}
-          paddingBottom={addMenuPadding?.bottom}
-          paddingLeft={addMenuPadding?.left}
+          paddingTop={safePadding?.top}
+          paddingRight={safePadding?.right}
+          paddingBottom={safePadding?.bottom}
+          paddingLeft={safePadding?.left}
         />
       {/if}
 

app/src/lib/graph-interface/graph/Wrapper.svelte

@@ -18,7 +18,7 @@
     showHelp?: boolean;
     settingTypes?: Record<string, unknown>;
 
-    addMenuPadding?: { left?: number; right?: number; bottom?: number; top?: number };
+    safePadding?: { left?: number; right?: number; bottom?: number; top?: number };
 
     onsave?: (save: Graph) => void;
     onresult?: (result: unknown) => void;
@@ -27,13 +27,12 @@
   let {
     graph,
     registry,
-    addMenuPadding,
+    safePadding,
     settings = $bindable(),
     activeNode = $bindable(),
     backgroundType = $bindable('grid'),
     snapToGrid = $bindable(true),
     showHelp = $bindable(false),
-    settings = $bindable(),
     settingTypes = $bindable(),
     onsave,
     onresult
@@ -45,29 +44,32 @@
   export const manager = new GraphManager(registry);
   setGraphManager(manager);
 
-  const graphState = new GraphState(manager);
+  export const state = new GraphState(manager);
   $effect(() => {
-    graphState.backgroundType = backgroundType;
-    graphState.snapToGrid = snapToGrid;
-    graphState.showHelp = showHelp;
+    if (safePadding) {
+      state.safePadding = safePadding;
+    }
+    state.backgroundType = backgroundType;
+    state.snapToGrid = snapToGrid;
+    state.showHelp = showHelp;
   });
 
-  setGraphState(graphState);
+  setGraphState(state);
 
-  setupKeymaps(keymap, manager, graphState);
+  setupKeymaps(keymap, manager, state);
 
   $effect(() => {
-    if (graphState.activeNodeId !== -1) {
-      activeNode = manager.getNode(graphState.activeNodeId);
+    if (state.activeNodeId !== -1) {
+      activeNode = manager.getNode(state.activeNodeId);
     } else if (activeNode) {
       activeNode = undefined;
     }
   });
 
   $effect(() => {
-    if (!graphState.addMenuPosition) {
-      graphState.edgeEndPosition = null;
-      graphState.activeSocket = null;
+    if (!state.addMenuPosition) {
+      state.edgeEndPosition = null;
+      state.activeSocket = null;
     }
   });
 
@@ -85,6 +87,95 @@
       manager.load(graph);
     }
   });
+
+  function navigateToBreadcrumb(index: number) {
+    const crumbs = manager.breadcrumbs;
+    const depth = crumbs.length - 1 - index;
+    let restoredCamera: [number, number, number] | false = false;
+    for (let i = 0; i < depth; i++) {
+      const groupId = manager.currentGroupContext;
+      if (groupId) {
+        state.groupCameras.set(groupId, [...state.cameraPosition] as [number, number, number]);
+      }
+      restoredCamera = manager.exitGroup();
+    }
+    state.activeNodeId = -1;
+    state.clearSelection();
+    if (restoredCamera !== false) {
+      state.cameraPosition[0] = restoredCamera[0];
+      state.cameraPosition[1] = restoredCamera[1];
+      state.cameraPosition[2] = restoredCamera[2];
+    } else {
+      state.centerNode();
+    }
+  }
 </script>
 
-<GraphEl {keymap} {addMenuPadding} />
+{#if manager.isInsideGroup}
+  <div class="breadcrumb-bar">
+    {#each manager.breadcrumbs as crumb, i}
+      {#if i > 0}
+        <span class="sep">›</span>
+      {/if}
+      <button
+        class="crumb"
+        class:active={i === manager.breadcrumbs.length - 1}
+        onclick={() => navigateToBreadcrumb(i)}
+      >
+        {crumb.name}
+      </button>
+    {/each}
+  </div>
+{/if}
+
+<GraphEl {keymap} {safePadding} />
+
+<style>
+  .breadcrumb-bar {
+    position: absolute;
+    top: 8px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 100;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    background: rgba(10, 15, 28, 0.85);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 6px;
+    padding: 4px 10px;
+    font-size: 12px;
+    pointer-events: all;
+    backdrop-filter: blur(8px);
+  }
+
+  .sep {
+    opacity: 0.4;
+    font-size: 14px;
+  }
+
+  .crumb {
+    background: none;
+    border: none;
+    color: rgba(255, 255, 255, 0.6);
+    cursor: pointer;
+    padding: 2px 4px;
+    border-radius: 4px;
+    font-size: 12px;
+    transition: color 0.15s, background 0.15s;
+  }
+
+  .crumb:hover {
+    color: white;
+    background: rgba(255, 255, 255, 0.08);
+  }
+
+  .crumb.active {
+    color: white;
+    cursor: default;
+  }
+
+  .crumb.active:hover {
+    background: none;
+  }
+</style>

app/src/lib/graph-interface/helpers/nodeHelpers.ts

@@ -3,6 +3,9 @@ import type { NodeDefinition, NodeInstance } from '@nodarium/types';
 export function getParameterHeight(node: NodeDefinition, inputKey: string) {
   const input = node.inputs?.[inputKey];
   if (!input) {
+    if (inputKey.startsWith('__virtual')) {
+      return 50;
+    }
     return 0;
   }
 
@@ -53,7 +56,9 @@ export function getSocketPosition(
 
 const nodeHeightCache: Record<string, number> = {};
 export function getNodeHeight(node: NodeDefinition) {
-  if (node.id in nodeHeightCache) {
+  // Don't cache virtual nodes — their inputs can change dynamically
+  const isVirtual = (node.id as string).startsWith('__virtual/');
+  if (!isVirtual && node.id in nodeHeightCache) {
     return nodeHeightCache[node.id];
   }
   if (!node?.inputs) {
@@ -66,6 +71,8 @@ export function getNodeHeight(node: NodeDefinition) {
     height += h;
   }
 
+  if (!isVirtual) {
     nodeHeightCache[node.id] = height;
+  }
   return height;
 }

app/src/lib/graph-interface/keymaps.ts

@@ -1,4 +1,3 @@
-import { animate, lerp } from '$lib/helpers';
 import type { createKeyMap } from '$lib/helpers/createKeyMap';
 import { panelState } from '$lib/sidebar/PanelState.svelte';
 import FileSaver from 'file-saver';
@@ -46,8 +45,26 @@ export function setupKeymaps(keymap: Keymap, graph: GraphManager, graphState: Gr
 
   keymap.addShortcut({
     key: 'Escape',
-    description: 'Deselect nodes',
+    description: 'Deselect nodes / Exit group',
     callback: () => {
+      if (graph.isInsideGroup) {
+        const groupId = graph.currentGroupContext;
+        if (groupId) {
+          graphState.groupCameras.set(
+            groupId,
+            [...graphState.cameraPosition] as [number, number, number]
+          );
+        }
+        const savedCamera = graph.exitGroup();
+        if (savedCamera !== false) {
+          graphState.activeNodeId = -1;
+          graphState.clearSelection();
+          graphState.cameraPosition[0] = savedCamera[0];
+          graphState.cameraPosition[1] = savedCamera[1];
+          graphState.cameraPosition[2] = savedCamera[2];
+          return;
+        }
+      }
       graphState.activeNodeId = -1;
       graphState.clearSelection();
       graphState.edgeEndPosition = null;
@@ -67,27 +84,7 @@ export function setupKeymaps(keymap: Keymap, graph: GraphManager, graphState: Gr
     description: 'Center camera',
     callback: () => {
       if (!graphState.isBodyFocused()) return;
-
-      const average = [0, 0];
-      for (const node of graph.nodes.values()) {
-        average[0] += node.position[0];
-        average[1] += node.position[1];
-      }
-      average[0] = average[0] ? average[0] / graph.nodes.size : 0;
-      average[1] = average[1] ? average[1] / graph.nodes.size : 0;
-
-      const camX = graphState.cameraPosition[0];
-      const camY = graphState.cameraPosition[1];
-      const camZ = graphState.cameraPosition[2];
-
-      const ease = (t: number) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t);
-
-      animate(500, (a: number) => {
-        graphState.cameraPosition[0] = lerp(camX, average[0], ease(a));
-        graphState.cameraPosition[1] = lerp(camY, average[1], ease(a));
-        graphState.cameraPosition[2] = lerp(camZ, 2, ease(a));
-        if (graphState.mouseDown) return false;
-      });
+      graphState.centerNode(graph.getNode(graphState.activeNodeId));
     }
   });
 
@@ -180,4 +177,80 @@ export function setupKeymaps(keymap: Keymap, graph: GraphManager, graphState: Gr
       if (!edge) graph.smartConnect(nodes[1], nodes[0]);
     }
   });
+
+  keymap.addShortcut({
+    key: 'g',
+    ctrl: true,
+    preventDefault: true,
+    description: 'Group selected nodes',
+    callback: () => {
+      if (!graphState.isBodyFocused()) return;
+      const nodeIds = Array.from(
+        new Set([
+          ...(graphState.selectedNodes.size > 0 ? graphState.selectedNodes.values() : []),
+          ...(graphState.activeNodeId !== -1 ? [graphState.activeNodeId] : [])
+        ])
+      );
+      if (nodeIds.length === 0) return;
+      const groupNode = graph.createGroup(nodeIds);
+      if (groupNode) {
+        graphState.selectedNodes.clear();
+        graphState.activeNodeId = groupNode.id;
+      }
+    }
+  });
+
+  keymap.addShortcut({
+    key: 'g',
+    alt: true,
+    shift: true,
+    preventDefault: true,
+    description: 'Ungroup selected node',
+    callback: () => {
+      if (!graphState.isBodyFocused()) return;
+      const nodeId = graphState.activeNodeId !== -1
+        ? graphState.activeNodeId
+        : graphState.selectedNodes.size === 1
+        ? [...graphState.selectedNodes.values()][0]
+        : -1;
+      if (nodeId === -1) return;
+      graph.ungroup(nodeId);
+      graphState.activeNodeId = -1;
+      graphState.clearSelection();
+    }
+  });
+
+  keymap.addShortcut({
+    key: 'Tab',
+    preventDefault: true,
+    description: 'Enter focused group node',
+    callback: () => {
+      if (!graphState.isBodyFocused()) return;
+      const entered = graph.enterGroup(
+        graphState.activeNodeId,
+        [...graphState.cameraPosition] as [number, number, number]
+      );
+      if (entered) {
+        graphState.activeNodeId = -1;
+        graphState.clearSelection();
+        // Restore group-specific camera if we've been here before, else snap to center
+        const groupId = graph.currentGroupContext;
+        const saved = groupId ? graphState.groupCameras.get(groupId) : undefined;
+        if (saved) {
+          graphState.cameraPosition[0] = saved[0];
+          graphState.cameraPosition[1] = saved[1];
+          graphState.cameraPosition[2] = saved[2];
+        } else {
+          const nodes = [...graph.nodes.values()];
+          if (nodes.length) {
+            const avgX = nodes.reduce((s, n) => s + n.position[0], 0) / nodes.length;
+            const avgY = nodes.reduce((s, n) => s + n.position[1], 0) / nodes.length;
+            graphState.cameraPosition[0] = avgX;
+            graphState.cameraPosition[1] = avgY;
+            graphState.cameraPosition[2] = 10;
+          }
+        }
+      }
+    }
+  });
 }

app/src/lib/graph-interface/node/NodeHTML.svelte

@@ -1,12 +1,13 @@
 <script lang="ts">
-  import type { NodeInstance } from '@nodarium/types';
-  import { getGraphState } from '../graph-state.svelte';
+  import type { NodeDefinition, NodeInstance } from '@nodarium/types';
+  import { getGraphManager, getGraphState } from '../graph-state.svelte';
   import NodeHeader from './NodeHeader.svelte';
   import NodeParameter from './NodeParameter.svelte';
 
   let ref: HTMLDivElement;
 
   const graphState = getGraphState();
+  const manager = getGraphManager();
 
   type Props = {
     node: NodeInstance;
@@ -30,10 +31,38 @@
   const zOffset = Math.random() - 0.5;
   const zLimit = 2 - zOffset;
 
-  const parameters = Object.entries(node.state?.type?.inputs || {}).filter(
+  function buildParameters(node: NodeInstance, inputs: NodeDefinition['inputs']) {
+    let parameters = Object.entries(inputs || {}).filter(
       (p) => p[1].type !== 'seed' && !('setting' in p[1]) && p[1]?.hidden !== true
     );
 
+    if (node.type === '__virtual/group/instance') {
+      parameters = [['__virtual/groupId', {
+        type: 'select',
+        value: node.props?.groupId as string,
+        options: [...manager?.groups?.keys()]
+      }], ...parameters];
+    }
+
+    return parameters;
+  }
+
+  const parameters = $derived(buildParameters(node, node?.state?.type?.inputs || {}));
+
+  const currentGroupId = $derived((node.props?.groupId as string) ?? '');
+
+  function onGroupSelect(event: Event) {
+    const select = event.target as HTMLSelectElement;
+    const newGroupId = select.value;
+    if (!manager || newGroupId === currentGroupId) return;
+    const newGroupDef = manager.groupNodeDefinitions.get(`__virtual/group/${newGroupId}`);
+    if (!newGroupDef) return;
+    node.props = { ...(node.props ?? {}), groupId: newGroupId };
+    node.state = { type: newGroupDef };
+    manager.execute();
+    manager.save();
+  }
+
   $effect(() => {
     if ('state' in node && !node.state.ref) {
       node.state.ref = ref;
@@ -55,6 +84,22 @@
 >
   <NodeHeader {node} />
 
+  {#if false && node.type === '__virtual/group/instance'}
+    <div class="group-param">
+      <select
+        value={currentGroupId}
+        onchange={onGroupSelect}
+        onmousedown={(e) => e.stopPropagation()}
+        onclick={(e) => e.stopPropagation()}
+        onkeydown={(e) => e.stopPropagation()}
+      >
+        {#each manager?.groups?.entries() ?? [] as [gid, gdef]}
+          <option value={gid}>{gdef.name}</option>
+        {/each}
+      </select>
+    </div>
+  {/if}
+
   {#each parameters as [key, value], i (key)}
     <NodeParameter
       bind:node
@@ -66,6 +111,24 @@
 </div>
 
 <style>
+  .group-param {
+    padding: 5px 8px;
+    border-bottom: solid 1px var(--color-layer-2);
+    background: var(--color-layer-1);
+  }
+
+  .group-param select {
+    width: 100%;
+    background: var(--color-layer-2);
+    color: var(--color-text);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 4px;
+    padding: 4px 6px;
+    font-size: 0.8em;
+    cursor: pointer;
+    box-sizing: border-box;
+  }
+
   .node {
     box-sizing: border-box;
     user-select: none !important;

app/src/lib/graph-interface/node/NodeHeader.svelte

@@ -70,7 +70,7 @@
     {#if appSettings.value.debug.advancedMode}
       <span class="bg-white text-black! mr-2 px-1 rounded-sm opacity-30">{node.id}</span>
     {/if}
-    {node.type.split('/').pop()}
+    {node.state?.type?.meta?.title ?? node.type.split('/').pop()}
   </div>
   <div
     class="target"

app/src/lib/graph-interface/node/NodeInput.svelte

@@ -45,7 +45,7 @@
 
   $effect(() => {
     const a = $state.snapshot(value);
-    const b = $state.snapshot(node?.props?.[id]);
+    const b = $state.snapshot(node?.props?.[id]) as number | number[] | undefined;
     const isDiff = Array.isArray(a) ? diffArray(a, b) : a !== b;
     if (value !== undefined && isDiff) {
       node.props = { ...node.props, [id]: a };

app/src/lib/graph-interface/node/NodeParameter.svelte

@@ -36,7 +36,7 @@
     });
   }
 
-  const leftBump = $derived(nodeType.inputs?.[id].internal !== true);
+  const leftBump = $derived(!id.startsWith('__virtual') && nodeType.inputs?.[id].internal !== true);
   const cornerBottom = $derived(isLast ? 5 : 0);
   const aspectRatio = 0.5;
 
@@ -83,7 +83,7 @@
 >
   {#key id && graphId}
     <div class="content" class:disabled={graph?.inputSockets?.has(socketId)}>
-      {#if inputType?.label !== ''}
+      {#if inputType?.label !== '' && !id.startsWith('__virtual')}
         <label for={elementId} title={input.description}>{input.label || id}</label>
       {/if}
       {#if inputType?.external !== true}

app/src/lib/graph-templates/index.ts

@@ -6,3 +6,4 @@ export { default as lottaNodes } from './lotta-nodes.json';
 export { plant } from './plant';
 export { default as simple } from './simple.json';
 export { tree } from './tree';
+export { default as tutorial } from './tutorial.json';

app/src/lib/graph-templates/simple.json

@@ -3,7 +3,7 @@
   "settings": {
     "resolution.circle": 54,
     "resolution.curve": 20,
-    "randomSeed": true
+    "randomSeed": false
   },
   "meta": {
     "title": "New Project",
@@ -27,9 +27,9 @@
       ],
       "type": "max/plantarium/stem",
       "props": {
-        "amount": 50,
+        "amount": 4,
         "length": 4,
-        "thickness": 1
+        "thickness": 0.2
       }
     },
     {

app/src/lib/graph-templates/tutorial.json

@@ -0,0 +1,24 @@
+{
+  "id": 0,
+  "settings": {
+    "resolution.circle": 54,
+    "resolution.curve": 20,
+    "randomSeed": false
+  },
+  "meta": {
+    "title": "New Project",
+    "lastModified": "2026-02-03T16:56:40.375Z"
+  },
+  "nodes": [
+    {
+      "id": 9,
+      "position": [
+        215,
+        85
+      ],
+      "type": "max/plantarium/output",
+      "props": {}
+    }
+  ],
+  "edges": []
+}

app/src/lib/node-registry/groupNodes.ts

@@ -0,0 +1,25 @@
+import type { NodeDefinition } from '@nodarium/types';
+
+export const groupInputNode: NodeDefinition = {
+  id: '__virtual/group/input',
+  inputs: {},
+  outputs: [],
+  execute(_data: Int32Array): Int32Array { return _data; }
+} as unknown as NodeDefinition;
+
+export const groupOutputNode: NodeDefinition = {
+  id: '__virtual/group/output',
+  inputs: {},
+  outputs: [],
+  execute(_data: Int32Array): Int32Array { return _data; }
+} as unknown as NodeDefinition;
+
+// Stub registered in the registry so it appears in AddMenu.
+// Actual inputs/outputs are resolved from props.groupId at runtime.
+export const groupNode: NodeDefinition = {
+  id: '__virtual/group/instance',
+  meta: { title: 'Group' },
+  inputs: {},
+  outputs: [],
+  execute(_data: Int32Array): Int32Array { return _data; }
+} as unknown as NodeDefinition;

app/src/lib/node-registry/node-registry-client.ts

@@ -2,7 +2,6 @@ import {
   type AsyncCache,
   type NodeDefinition,
   NodeDefinitionSchema,
-  type NodeId,
   type NodeRegistry
 } from '@nodarium/types';
 import { createLogger, createWasmWrapper } from '@nodarium/utils';
@@ -13,7 +12,6 @@ log.mute();
 export class RemoteNodeRegistry implements NodeRegistry {
   status: 'loading' | 'ready' | 'error' = 'loading';
   private nodes: Map<string, NodeDefinition> = new Map();
-  private memory = new WebAssembly.Memory({ initial: 1024, maximum: 8192 });
 
   constructor(
     private url: string,
@@ -172,13 +170,6 @@ export class RemoteNodeRegistry implements NodeRegistry {
   }
 
   getAllNodes() {
-    const allNodes = [...this.nodes.values()];
-    log.info('getting all nodes', allNodes);
-    return allNodes;
-  }
-
-  async overwriteNode(nodeId: NodeId, node: NodeDefinition) {
-    log.info('Overwritten node', { nodeId, node });
-    this.nodes.set(nodeId, node);
+    return [...this.nodes.values()];
   }
 }

app/src/lib/result-viewer/Viewer.svelte

@@ -24,6 +24,10 @@
   let geometryPool: ReturnType<typeof createGeometryPool>;
   let instancePool: ReturnType<typeof createInstancedGeometryPool>;
 
+  export function invalidate() {
+    sceneComponent?.invalidate();
+  }
+
   export function updateGeometries(inputs: Int32Array[], group: Group) {
     geometryPool = geometryPool || createGeometryPool(group, material);
     instancePool = instancePool || createInstancedGeometryPool(group, material);

app/src/lib/runtime/helpers.ts

@@ -1,39 +0,0 @@
-export function logInt32ArrayChanges(
-  before: Int32Array,
-  after: Int32Array,
-  clamp = 10
-): void {
-  if (before.length !== after.length) {
-    throw new Error('Arrays must have the same length');
-  }
-
-  let rangeStart: number | null = null;
-  let collected: number[] = [];
-
-  const flush = (endIndex: number) => {
-    if (rangeStart === null) return;
-
-    const preview = collected.slice(0, clamp);
-    const suffix = collected.length > clamp ? '...' : '';
-
-    console.log(
-      `Change ${rangeStart}-${endIndex}: [${preview.join(', ')}${suffix}]`
-    );
-
-    rangeStart = null;
-    collected = [];
-  };
-
-  for (let i = 0; i < before.length; i++) {
-    if (before[i] !== after[i]) {
-      if (rangeStart === null) {
-        rangeStart = i;
-      }
-      collected.push(after[i]);
-    } else {
-      flush(i - 1);
-    }
-  }
-
-  flush(before.length - 1);
-}

app/src/lib/runtime/runtime-executor.ts

@@ -1,5 +1,3 @@
-import type { SettingsToStore } from '$lib/settings/app-settings.svelte';
-import { RemoteNodeRegistry } from '@nodarium/registry';
 import type {
   Graph,
   NodeDefinition,
@@ -8,39 +6,161 @@ import type {
   RuntimeExecutor,
   SyncCache
 } from '@nodarium/types';
+
+function isGroupInstanceType(type: string): boolean {
+  return type === '__virtual/group/instance';
+}
+
+export function expandGroups(graph: Graph): Graph {
+  if (!graph.groups || Object.keys(graph.groups).length === 0) {
+    return graph;
+  }
+
+  let nodes = [...graph.nodes];
+  let edges = [...graph.edges];
+  const groups = graph.groups;
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i];
+      if (!isGroupInstanceType(node.type)) continue;
+
+      const groupId = (node.props as Record<string, unknown> | undefined)?.groupId as string | undefined;
+      if (!groupId) continue;
+      const group = groups[groupId];
+      if (!group) continue;
+
+      changed = true;
+
+      // Recursively expand nested groups inside this group's internal graph
+      const expandedInternal = expandGroups({
+        id: 0,
+        nodes: group.graph.nodes,
+        edges: group.graph.edges,
+        groups
+      });
+
+      const ID_PREFIX = node.id * 1000000;
+      const idMap = new Map<number, number>();
+
+      const inputVirtualNode = expandedInternal.nodes.find(
+        n => n.type === '__virtual/group/input'
+      );
+      const outputVirtualNode = expandedInternal.nodes.find(
+        n => n.type === '__virtual/group/output'
+      );
+
+      const realInternalNodes = expandedInternal.nodes.filter(
+        n => n.type !== '__virtual/group/input' && n.type !== '__virtual/group/output'
+      );
+
+      for (const n of realInternalNodes) {
+        idMap.set(n.id, ID_PREFIX + n.id);
+      }
+
+      const parentIncomingEdges = edges.filter(e => e[2] === node.id);
+      const parentOutgoingEdges = edges.filter(e => e[0] === node.id);
+
+      // Edges from/to virtual nodes in the expanded internal graph
+      const edgesFromInput = expandedInternal.edges.filter(
+        e => e[0] === inputVirtualNode?.id
+      );
+      const edgesToOutput = expandedInternal.edges.filter(
+        e => e[2] === outputVirtualNode?.id
+      );
+
+      const newEdges: Graph['edges'] = [];
+
+      // Short-circuit: parent source → internal target (via group input)
+      for (const parentEdge of parentIncomingEdges) {
+        const socketName = parentEdge[3];
+        const socketIdx = group.inputs.findIndex(s => s.name === socketName);
+        if (socketIdx === -1) continue;
+
+        for (const internalEdge of edgesFromInput.filter(e => e[1] === socketIdx)) {
+          const remappedId = idMap.get(internalEdge[2]);
+          if (remappedId !== undefined) {
+            newEdges.push([parentEdge[0], parentEdge[1], remappedId, internalEdge[3]]);
+          }
+        }
+      }
+
+      // Short-circuit: internal source → parent target (via group output)
+      for (const parentEdge of parentOutgoingEdges) {
+        const outputIdx = parentEdge[1];
+        const outputSocketName = group.outputs[outputIdx]?.name;
+        if (!outputSocketName) continue;
+
+        for (const internalEdge of edgesToOutput.filter(e => e[3] === outputSocketName)) {
+          const remappedId = idMap.get(internalEdge[0]);
+          if (remappedId !== undefined) {
+            newEdges.push([remappedId, internalEdge[1], parentEdge[2], parentEdge[3]]);
+          }
+        }
+      }
+
+      // Remap internal-to-internal edges
+      const internalEdges = expandedInternal.edges.filter(
+        e => e[0] !== inputVirtualNode?.id
+          && e[0] !== outputVirtualNode?.id
+          && e[2] !== inputVirtualNode?.id
+          && e[2] !== outputVirtualNode?.id
+      );
+
+      for (const e of internalEdges) {
+        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]]);
+        }
+      }
+
+      // Remove the group node
+      nodes.splice(i, 1);
+
+      // Add remapped internal nodes
+      for (const n of realInternalNodes) {
+        nodes.push({ ...n, id: idMap.get(n.id)! });
+      }
+
+      // Remove group node's edges and add short-circuit edges
+      const groupEdgeKeys = new Set([
+        ...parentIncomingEdges.map(e => `${e[0]}-${e[1]}-${e[2]}-${e[3]}`),
+        ...parentOutgoingEdges.map(e => `${e[0]}-${e[1]}-${e[2]}-${e[3]}`)
+      ]);
+      edges = edges.filter(
+        e => !groupEdgeKeys.has(`${e[0]}-${e[1]}-${e[2]}-${e[3]}`)
+      );
+      edges.push(...newEdges);
+
+      break; // Restart loop with updated nodes array
+    }
+  }
+
+  return { ...graph, nodes, edges };
+}
 import {
+  concatEncodedArrays,
   createLogger,
-  createWasmWrapper,
   encodeFloat,
+  fastHashArrayBuffer,
   type PerformanceStore
 } from '@nodarium/utils';
-import { DevSettingsType } from '../../routes/dev/settings.svelte';
-import { logInt32ArrayChanges } from './helpers';
 import type { RuntimeNode } from './types';
 
 const log = createLogger('runtime-executor');
-// log.mute(); // Keep logging enabled for debug info
+log.mute();
 
-const remoteRegistry = new RemoteNodeRegistry('');
-
-type WasmExecute = (outputPos: number, args: number[]) => number;
-
-function getValue(input: NodeInput, value?: unknown): number | number[] | Int32Array {
+function getValue(input: NodeInput, value?: unknown) {
   if (value === undefined && 'value' in input) {
     value = input.value;
   }
 
-  switch (input.type) {
-    case 'float':
+  if (input.type === 'float') {
     return encodeFloat(value as number);
-
-    case 'select':
-      return (value as number) ?? 0;
-
-    case 'vec3': {
-      const arr = Array.isArray(value) ? value : [];
-      return [0, arr.length + 1, ...arr.map(v => encodeFloat(v)), 1, 1];
-    }
   }
 
   if (Array.isArray(value)) {
@@ -56,26 +176,23 @@ function getValue(input: NodeInput, value?: unknown): number | number[] | Int32A
     return [0, value.length + 1, ...value, 1, 1] as number[];
   }
 
-  if (typeof value === 'boolean') return value ? 1 : 0;
-  if (typeof value === 'number') return value;
-  if (value instanceof Int32Array) return value;
-
-  throw new Error(`Unsupported input type: ${input.type}`);
+  if (typeof value === 'boolean') {
+    return value ? 1 : 0;
   }
 
-function compareInt32(a: Int32Array, b: Int32Array): boolean {
-  if (a.length !== b.length) return false;
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] !== b[i]) return false;
-  }
-  return true;
+  if (typeof value === 'number') {
+    return value;
   }
 
-export type Pointer = {
-  start: number;
-  end: number;
-  _title?: string;
-};
+  if (value instanceof Int32Array) {
+    return value;
+  }
+
+  throw new Error(`Unknown input type ${input.type}`);
+}
+
+export class MemoryRuntimeExecutor implements RuntimeExecutor {
+  private definitionMap: Map<string, NodeDefinition> = new Map();
 
   private seed = Math.floor(Math.random() * 100000000);
   private debugData: Record<number, { type: string; data: Int32Array }> = {};
@@ -83,55 +200,38 @@ export type Pointer = {
   perf?: PerformanceStore;
 
   constructor(
-    private readonly registry: NodeRegistry,
+    private registry: NodeRegistry,
     public cache?: SyncCache<Int32Array>
   ) {
     this.cache = undefined;
-    this.refreshView();
-    log.info('MemoryRuntimeExecutor initialized');
   }
 
-  private refreshView(): void {
-    this.memoryView = new Int32Array(this.memory.buffer);
-    log.info(`Memory view refreshed, length: ${this.memoryView.length}`);
-  }
-
-  public getMemory(): Int32Array {
-    return new Int32Array(this.memory.buffer);
-  }
-
-  private map = new Map<string, { definition: NodeDefinition; execute: WasmExecute }>();
   private async getNodeDefinitions(graph: Graph) {
     if (this.registry.status !== 'ready') {
       throw new Error('Node registry is not ready');
     }
 
-    await this.registry.load(graph.nodes.map(n => n.type));
-    log.info(`Loaded ${graph.nodes.length} node types from registry`);
+    // Only load non-virtual types (virtual nodes are resolved locally)
+    const nonVirtualTypes = graph.nodes
+      .map(node => node.type)
+      .filter(t => !t.startsWith('__virtual/'));
+    await this.registry.load(nonVirtualTypes as any);
 
-    for (const { type } of graph.nodes) {
-      if (this.map.has(type)) continue;
-
-      const def = this.registry.getNode(type);
-      if (!def) continue;
-
-      log.info(`Fetching WASM for node type: ${type}`);
-      const buffer = await remoteRegistry.fetchArrayBuffer(`nodes/${type}.wasm`);
-      const wrapper = createWasmWrapper(buffer, this.memory);
-
-      this.map.set(type, {
-        definition: def,
-        execute: wrapper.execute
-      });
-      log.info(`Node type ${type} loaded and wrapped`);
+    const typeMap = new Map<string, NodeDefinition>();
+    for (const node of graph.nodes) {
+      if (!typeMap.has(node.type)) {
+        const type = this.registry.getNode(node.type);
+        if (type) {
+          typeMap.set(node.type, type);
         }
-
-    return this.map;
+      }
+    }
+    return typeMap;
   }
 
   private async addMetaData(graph: Graph) {
-    this.nodes = await this.getNodeDefinitions(graph);
-    log.info(`Metadata added for ${this.nodes.size} nodes`);
+    // First, lets check if all nodes have a definition
+    this.definitionMap = await this.getNodeDefinitions(graph);
 
     const graphNodes = graph.nodes.map(node => {
       const n = node as RuntimeNode;
@@ -144,30 +244,36 @@ export type Pointer = {
       return n;
     });
 
-    const outputNode = graphNodes.find(n => n.type.endsWith('/output') || n.type.endsWith('/debug'))
-      ?? graphNodes[0];
+    const outputNode = graphNodes.find((node) => node.type.endsWith('/output'));
+    if (!outputNode) {
+      throw new Error('No output node found');
+    }
 
-    const nodeMap = new Map(graphNodes.map(n => [n.id, n]));
+    const nodeMap = new Map(
+      graphNodes.map((node) => [node.id, node])
+    );
 
     // loop through all edges and assign the parent and child nodes to each node
     for (const edge of graph.edges) {
       const [parentId, /*_parentOutput*/, childId, childInput] = edge;
       const parent = nodeMap.get(parentId);
       const child = nodeMap.get(childId);
-      if (!parent || !child) continue;
-
+      if (parent && child) {
         parent.state.children.push(child);
         child.state.parents.push(parent);
         child.state.inputNodes[childInput] = parent;
       }
+    }
 
     const nodes = new Map<number, RuntimeNode>();
 
     // loop through all the nodes and assign each nodes its depth
     const stack = [outputNode, ...graphNodes.filter(n => n.type.endsWith('/debug'))];
     while (stack.length) {
-      const node = stack.pop()!;
+      const node = stack.pop();
+      if (!node) continue;
       for (const parent of node.state.parents) {
+        parent.state = parent.state || {};
         parent.state.depth = node.state.depth + 1;
         stack.push(parent);
       }
@@ -191,21 +297,20 @@ export type Pointer = {
     return [outputNode, _nodes] as const;
   }
 
-  private writeToMemory(value: number | number[] | Int32Array, title?: string): Pointer {
-    const start = this.offset;
-
-    if (typeof value === 'number') {
-      this.memoryView[this.offset++] = value;
-    } else {
-      this.memoryView.set(value, this.offset);
-      this.offset += value.length;
-    }
+  async execute(graph: Graph, settings: Record<string, unknown>) {
+    this.perf?.addPoint('runtime');
 
     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);
+    const [outputNode, nodes] = await this.addMetaData(graph);
+    let b = performance.now();
+
+    this.perf?.addPoint('collect-metadata', b - a);
 
     /*
      * Here we sort the nodes into buckets, which we then execute one by one
@@ -223,75 +328,58 @@ export type Pointer = {
       (a, b) => (b.state?.depth || 0) - (a.state?.depth || 0)
     );
 
-    console.log({ settings });
+    // here we store the intermediate results of the nodes
+    const results: Record<string, Int32Array> = {};
 
-    this.printMemory();
-    const seedPtr = this.writeToMemory(this.seed, 'seed');
-
-    const settingPtrs = new Map<string, Pointer>(
-      Object.entries(settings).map((
-        [key, value]
-      ) => [key as string, this.writeToMemory(value as number, `setting.${key}`)])
-    );
+    if (settings['randomSeed']) {
+      this.seed = Math.floor(Math.random() * 100000000);
+    }
 
     for (const node of sortedNodes) {
-      const node_type = this.nodes.get(node.type)!;
-
-      console.log('---------------');
-      console.log('STARTING NODE EXECUTION', node_type.definition.id + '/' + node.id);
-      this.printMemory();
-
-      // console.log(node_type.definition.inputs);
-      const inputs = Object.entries(node_type.definition.inputs || {}).map(
-        ([key, input]) => {
-          // We should probably initially write this to memory
-          if (input.type === 'seed') {
-            return seedPtr;
-          }
-
-          const title = `${node.id}.${key}`;
-
-          // We should probably initially write this to memory
-          // If the input is linked to a setting, we use that value
-          // TODO: handle nodes which reference undefined settings
-          if (input.setting) {
-            return settingPtrs.get(input.setting)!;
-          }
-
-          // check if the input is connected to another node
-          const inputNode = node.state.inputNodes[key];
-          if (inputNode) {
-            if (this.results[inputNode.id] === undefined) {
-              throw new Error(
-                `Node ${node.type}/${node.id} is missing input from node ${inputNode.type}/${inputNode.id}`
-              );
-            }
-            return this.results[inputNode.id];
-          }
-
-          // If the value is stored in the node itself, we use that value
-          if (node.props?.[key] !== undefined) {
-            const value = getValue(input, node.props[key]);
-            console.log(`Writing prop for ${node.id} -> ${key} to memory`, node.props[key], value);
-            return this.writeToMemory(value, title);
-          }
-
-          return this.writeToMemory(getValue(input), title);
-        }
-      );
-
-      this.printMemory();
+      const node_type = this.definitionMap.get(node.type)!;
 
       if (!node_type || !node.state || !node_type.execute) {
         log.warn(`Node ${node.id} has no definition`);
         continue;
       }
 
-      this.inputPtrs[node.id] = inputs;
-      const args = inputs.map(s => [s.start, s.end]).flat();
-      console.log('ARGS', inputs);
+      a = performance.now();
+
+      // Collect the inputs for the node
+      const inputs = Object.entries(node_type.inputs || {}).map(
+        ([key, input]) => {
+          if (input.type === 'seed') {
+            return this.seed;
+          }
+
+          // If the input is linked to a setting, we use that value
+          if (input.setting) {
+            return getValue(input, settings[input.setting]);
+          }
+
+          // check if the input is connected to another node
+          const inputNode = node.state.inputNodes[key];
+          if (inputNode) {
+            if (results[inputNode.id] === undefined) {
+              throw new Error(
+                `Node ${node.type} is missing input from node ${inputNode.type}`
+              );
+            }
+            return results[inputNode.id];
+          }
+
+          // If the value is stored in the node itself, we use that value
+          if (node.props?.[key] !== undefined) {
+            return getValue(input, node.props[key]);
+          }
+
+          return getValue(input);
+        }
+      );
+      b = performance.now();
+
+      this.perf?.addPoint('collected-inputs', b - a);
 
-      this.printMemory();
       try {
         a = performance.now();
         const encoded_inputs = concatEncodedArrays(inputs);
@@ -332,138 +420,28 @@ export type Pointer = {
         b = performance.now();
 
         if (this.cache && node.id !== outputNode.id) {
-          this.cache.set(inputHash, this.results[node.id]);
+          this.cache.set(inputHash, results[node.id]);
         }
 
         this.perf?.addPoint('node/' + node_type.id, b - a);
         log.log('Result:', results[node.id]);
         log.groupEnd();
       } catch (e) {
-        console.error(`Failed to execute node ${node.type}/${node.id}`, e);
-        this.isRunning = false;
+        log.groupEnd();
+        log.error(`Error executing node ${node_type.id || node.id}`, e);
       }
     }
 
-    this.isRunning = true;
-    log.info('Execution started');
+    // return the result of the parent of the output node
+    const res = results[outputNode.id];
 
-    try {
-      this.offset = 0;
-      this.results = {};
-      this.inputPtrs = {};
-      this.allPtrs = [];
-      this.seed += 2;
-
-      this.refreshView();
-
-      const [outputNode, nodes] = await this.addMetaData(graph);
-
-      const sortedNodes = [...nodes].sort(
-        (a, b) => (b.state.depth ?? 0) - (a.state.depth ?? 0)
-      );
-
-      const seedPtr = this.writeToMemory(this.seed, 'seed');
-
-      const settingPtrs = new Map<string, Pointer>();
-      for (const [key, value] of Object.entries(settings)) {
-        const ptr = this.writeToMemory(value as number, `setting.${key}`);
-        settingPtrs.set(key, ptr);
+    if (this.cache) {
+      this.cache.size = sortedNodes.length * 2;
     }
 
-      let lastNodePtr: Pointer | undefined = undefined;
-
-      for (const node of sortedNodes) {
-        const nodeType = this.nodes.get(node.type);
-        if (!nodeType) continue;
-
-        log.info(`Executing node: ${node.id} (type: ${node.type})`);
-
-        const inputs = Object.entries(nodeType.definition.inputs || {}).map(
-          ([key, input]) => {
-            if (input.type === 'seed') return seedPtr;
-
-            if (input.setting) {
-              const ptr = settingPtrs.get(input.setting);
-              if (!ptr) throw new Error(`Missing setting: ${input.setting}`);
-              return ptr;
-            }
-
-            const src = node.state.inputNodes[key];
-            if (src) {
-              const res = this.results[src.id];
-              if (!res) {
-                throw new Error(`Missing input from ${src.type}/${src.id}`);
-              }
-              return res;
-            }
-
-            if (node.props?.[key] !== undefined) {
-              return this.writeToMemory(
-                getValue(input, node.props[key]),
-                `${node.id}.${key}`
-              );
-            }
-
-            return this.writeToMemory(getValue(input), `${node.id}.${key}`);
-          }
-        );
-
-        this.inputPtrs[node.id] = inputs;
-        const args = inputs.flatMap(p => [p.start * 4, p.end * 4]);
-
-        log.info(`Executing node ${node.type}/${node.id}`);
-        const memoryBefore = this.memoryView.slice(0, this.offset);
-        const bytesWritten = nodeType.execute(this.offset * 4, args);
-        this.refreshView();
-        const memoryAfter = this.memoryView.slice(0, this.offset);
-        logInt32ArrayChanges(memoryBefore, memoryAfter);
-        this.refreshView();
-
-        const outLen = bytesWritten >> 2;
-        const outputStart = this.offset;
-
-        if (
-          args.length === 2
-          && inputs[0].end - inputs[0].start === outLen
-          && compareInt32(
-            this.memoryView.slice(inputs[0].start, inputs[0].end),
-            this.memoryView.slice(outputStart, outputStart + outLen)
-          )
-        ) {
-          this.results[node.id] = inputs[0];
-          this.allPtrs.push(this.results[node.id]);
-          log.info(`Node ${node.id} result reused input memory`);
-        } else {
-          this.results[node.id] = {
-            start: outputStart,
-            end: outputStart + outLen,
-            _title: `${node.id} ->`
-          };
-          this.allPtrs.push(this.results[node.id]);
-          this.offset += outLen;
-          lastNodePtr = this.results[node.id];
-          log.info(
-            `Node ${node.id} wrote result to memory: start=${outputStart}, end=${outputStart + outLen
-            }`
-          );
-        }
-      }
-
-      const res = this.results[outputNode.id] ?? lastNodePtr;
-      if (!res) throw new Error('Output node produced no result');
-
-      log.info(`Execution finished, output pointer: start=${res.start}, end=${res.end}`);
-      this.refreshView();
-      return this.memoryView.slice(res.start, res.end);
-    } catch (e) {
-      log.info('Execution error:', e);
-      console.error(e);
-    } finally {
-      this.isRunning = false;
-      console.log('Final Memory', [...this.memoryView.slice(0, 20)]);
     this.perf?.endPoint('runtime');
-      log.info('Executor state reset');
-    }
+
+    return res as unknown as Int32Array;
   }
 
   getDebugData() {

app/src/lib/runtime/worker-runtime-executor-backend.ts

@@ -1,12 +1,18 @@
 import { debugNode } from '$lib/node-registry/debugNode';
+import { groupInputNode, groupNode, groupOutputNode } from '$lib/node-registry/groupNodes';
 import { IndexDBCache, RemoteNodeRegistry } from '$lib/node-registry/index';
 import type { Graph } from '@nodarium/types';
 import { createPerformanceStore } from '@nodarium/utils';
-import { MemoryRuntimeExecutor } from './runtime-executor';
+import { expandGroups, MemoryRuntimeExecutor } from './runtime-executor';
 import { MemoryRuntimeCache } from './runtime-executor-cache';
 
 const indexDbCache = new IndexDBCache('node-registry');
-const nodeRegistry = new RemoteNodeRegistry('', indexDbCache, [debugNode]);
+const nodeRegistry = new RemoteNodeRegistry('', indexDbCache, [
+  debugNode,
+  groupInputNode,
+  groupOutputNode,
+  groupNode
+]);
 
 const cache = new MemoryRuntimeCache();
 const executor = new MemoryRuntimeExecutor(nodeRegistry, cache);
@@ -34,7 +40,13 @@ export async function executeGraph(
   graph: Graph,
   settings: Record<string, unknown>
 ): Promise<Int32Array> {
-  await nodeRegistry.load(graph.nodes.map((n) => n.type));
+  // Expand groups before loading types so we only load real (non-virtual) node types
+  const expandedGraph = expandGroups(graph);
+  await nodeRegistry.load(
+    expandedGraph.nodes
+      .map(n => n.type)
+      .filter(t => !t.startsWith('__virtual/')) as any
+  );
   performanceStore.startRun();
   const res = await executor.execute(graph, settings);
   performanceStore.stopRun();

app/src/lib/settings/NestedSettings.svelte

@@ -28,13 +28,14 @@
     key?: string;
     value: SettingsValue;
     type: SettingsType;
+    onButtonClick?: (id: string) => void;
     depth?: number;
   };
 
   // Local persistent state for <details> sections
   const openSections = localState<Record<string, boolean>>('open-details', {});
 
-  let { id, key = '', value = $bindable(), type, depth = 0 }: Props = $props();
+  let { id, key = '', value = $bindable(), type, onButtonClick, depth = 0 }: Props = $props();
 
   function isNodeInput(v: SettingsNode | undefined): v is InputType {
     return !!v && typeof v === 'object' && 'type' in v;
@@ -107,11 +108,6 @@
     }
   });
 
-  function handleClick() {
-    const callback = value[key] as unknown as () => void;
-    callback();
-  }
-
   onMount(() => {
     open = openSections.value[id];
 
@@ -130,7 +126,7 @@
   {@const inputType = type[key]}
   <div class="input input-{inputType.type}" class:first-level={depth === 1}>
     {#if inputType.type === 'button'}
-      <button onclick={handleClick}>
+      <button onclick={() => onButtonClick?.(id)}>
         {inputType.label || key}
       </button>
     {:else}
@@ -143,6 +139,7 @@
 {:else if depth === 0}
   {#each Object.keys(type ?? {}).filter((k) => k !== 'title') as childKey (childKey)}
     <NestedSettings
+      {onButtonClick}
       id={`${id}.${childKey}`}
       key={childKey}
       bind:value
@@ -160,6 +157,7 @@
     <div class="content">
       {#each Object.keys(type[key] as SettingsGroup).filter((k) => k !== 'title') as childKey (childKey)}
         <NestedSettings
+          {onButtonClick}
           id={`${id}.${childKey}`}
           key={childKey}
           bind:value={value[key] as SettingsValue}
@@ -221,6 +219,9 @@
 
   button {
     cursor: pointer;
+    background: var(--color-layer-2);
+    padding-block: 5px;
+    border-radius: 4px;
   }
 
   hr {

app/src/lib/settings/app-settings.svelte.ts

@@ -28,6 +28,10 @@ export const AppSettingTypes = {
     label: 'Center Camera',
     value: true
   },
+  clippy: {
+    type: 'button',
+    label: '🌱 Open Planty'
+  },
   nodeInterface: {
     title: 'Node Interface',
     backgroundType: {
@@ -109,8 +113,7 @@ export const AppSettingTypes = {
   }
 } as const;
 
-type SettingsToStore<T> = T extends { type: 'button' } ? () => void
-  : T extends { value: infer V } ? V extends readonly string[] ? V[number]
+type SettingsToStore<T> = T extends { value: infer V } ? V extends readonly string[] ? V[number]
   : V
   : T extends object ? {
       -readonly [K in keyof T as T[K] extends object ? K : never]: SettingsToStore<T[K]>;

app/src/lib/sidebar/panels/ActiveNodeSelected.svelte

@@ -96,6 +96,4 @@
     bind:value={store}
     type={nodeDefinition}
   />
-{:else}
-  <p class="mx-4 mt-4">Node has no settings</p>
 {/if}

app/src/lib/sidebar/panels/ActiveNodeSettings.svelte

@@ -5,22 +5,27 @@
 
   type Props = {
     manager: GraphManager;
-    node: NodeInstance | undefined;
+    node: NodeInstance;
   };
 
   let { manager, node = $bindable() }: Props = $props();
+
+  const inputs = $derived(node?.state?.type?.inputs || {});
+
+  const hasSettings = $derived(
+    Object.values(inputs).find(entry => {
+      return entry.hidden === true;
+    }) !== undefined
+  );
+
+  $inspect({ inputs, hasSettings });
 </script>
 
-<div class='{node?"border-l-2 pl-3.5!":""} bg-layer-2 flex items-center h-[70px] border-b-1 border-l-selected border-b-outline pl-4'>
+{#key node.id}
+  {#if node && hasSettings}
+    <div class="border-l-2 pl-3.5! bg-layer-2 flex items-center h-[70px] border-b-1 border-l-selected border-b-outline pl-4">
       <h3>Node Settings</h3>
     </div>
-
-{#if node}
-  {#key node.id}
-    {#if node}
     <ActiveNodeSelected {manager} bind:node />
   {/if}
 {/key}
-{:else}
-  <p class="mx-4 mt-4">No node selected</p>
-{/if}

app/src/lib/sidebar/panels/GroupContextPanel.svelte

@@ -0,0 +1,148 @@
+<script lang="ts">
+  import type { GraphManager } from '$lib/graph-interface/graph-manager.svelte';
+  import { InputSelect } from '@nodarium/ui';
+
+  type Props = { manager: GraphManager; groupId: string };
+  const { manager, groupId }: Props = $props();
+
+  $inspect({ groupId });
+
+  const group = $derived(manager.groups.get(groupId));
+
+  const COMMON_TYPES = ['plant', 'float', 'int', 'vec3', 'bool'];
+  let selectedTypeIdx = $state(0);
+  let customType = $state('');
+
+  function rename(e: Event) {
+    if (!group) return;
+    const name = (e.target as HTMLInputElement).value.trim();
+    if (!name) return;
+    group.name = name;
+    if (manager.graph.groups?.[groupId]) manager.graph.groups[groupId].name = name;
+    const def = manager.groupNodeDefinitions.get(`__virtual/group/${groupId}`);
+    if (def?.meta) def.meta.title = name;
+    manager.save();
+  }
+
+  function addSocket() {
+    const type = customType.trim() || COMMON_TYPES[selectedTypeIdx];
+    if (!type) return;
+    manager.addGroupSocket('input', type);
+    customType = '';
+  }
+
+  function removeSocket(index: number) {
+    manager.removeGroupSocket('input', index);
+  }
+</script>
+
+<div class="bg-layer-2 flex items-center h-[70px] border-b-1 border-outline pl-4">
+  <h3>Group Settings</h3>
+</div>
+
+<div class="px-4 py-3 flex flex-col gap-4">
+  <div class="flex flex-col gap-1.5">
+    <span class="section-label">Group name</span>
+    <input
+      type="text"
+      value={group?.name ?? ''}
+      onchange={rename}
+      onkeydown={(e) => e.stopPropagation()}
+      placeholder="Group name"
+      class="bg-layer-2 text-text rounded-[5px] px-2 py-1.5 text-sm w-full box-border outline outline-1 outline-outline"
+    />
+  </div>
+
+  <div class="flex flex-col gap-1.5">
+    <span class="section-label">Inputs</span>
+
+    {#if (group?.inputs?.length ?? 0) === 0}
+      <p class="text-sm opacity-40 italic m-0">No inputs yet</p>
+    {:else}
+      <ul class="socket-list">
+        {#each group?.inputs ?? [] as socket, i}
+          <li class="socket-item">
+            <span class="flex-1 opacity-80 text-sm">{socket.name}</span>
+            <span class="text-xs opacity-45 italic">{socket.type}</span>
+            <button class="remove-btn" onclick={() => removeSocket(i)} title="Remove">×</button>
+          </li>
+        {/each}
+      </ul>
+    {/if}
+
+    <div class="flex gap-1.5 items-center">
+      <InputSelect options={COMMON_TYPES} bind:value={selectedTypeIdx} />
+      <input
+        type="text"
+        placeholder="custom type…"
+        bind:value={customType}
+        onkeydown={(e) => {
+          e.stopPropagation();
+          if (e.key === 'Enter') addSocket();
+        }}
+        class="bg-layer-2 text-text rounded-[5px] px-2 py-1 text-sm flex-1 min-w-0 outline outline-1 outline-outline"
+      />
+      <button class="add-btn" onclick={addSocket}>+ Add</button>
+    </div>
+  </div>
+</div>
+
+<style>
+  .section-label {
+    font-size: 0.72em;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    opacity: 0.5;
+  }
+
+  .socket-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+  }
+
+  .socket-item {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    background: var(--color-layer-2);
+    border-radius: 5px;
+    padding: 4px 8px;
+    outline: 1px solid var(--color-outline);
+  }
+
+  .remove-btn {
+    background: none;
+    border: none;
+    color: var(--color-text);
+    cursor: pointer;
+    opacity: 0.4;
+    padding: 0 2px;
+    font-size: 1.1em;
+    line-height: 1;
+  }
+
+  .remove-btn:hover {
+    opacity: 1;
+  }
+
+  .add-btn {
+    background: var(--color-layer-2);
+    color: var(--color-text);
+    border: none;
+    outline: 1px solid var(--color-outline);
+    border-radius: 5px;
+    padding: 0.4em 0.7em;
+    font-size: 0.8em;
+    cursor: pointer;
+    white-space: nowrap;
+    font-family: var(--font-family);
+  }
+
+  .add-btn:hover {
+    outline-color: var(--color-selected);
+  }
+</style>

app/src/lib/tutorial/tutorial-config.ts

@@ -0,0 +1,240 @@
+import type { PlantyConfig } from '@nodarium/planty';
+
+export const tutorialConfig: PlantyConfig = {
+  id: 'nodarium-tutorial',
+  avatar: {
+    name: 'Planty',
+    defaultPosition: 'bottom-right'
+  },
+  start: 'intro',
+  nodes: {
+    // ── Entry ──────────────────────────────────────────────────────────────
+    intro: {
+      position: 'center',
+      text:
+        "# Hi, I'm Planty! 🌱\nI'll show you around Nodarium — a tool for building 3D plants by connecting nodes together.\nHow much detail do you want?",
+      choices: [
+        { label: '🌱 Show me the basics', next: 'tour_canvas' },
+        { label: '🤓 I want the technical details', next: 'tour_canvas_nerd' },
+        { label: 'Skip the tour for now', next: null }
+      ]
+    },
+
+    // ── Simple path ────────────────────────────────────────────────────────
+
+    tour_canvas: {
+      position: 'bottom-left',
+      action: 'setup-default',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        'This is the **graph canvas**. Nodes connect together to build a plant — the 3D model updates automatically whenever you make a change.\nEach node does one specific job: grow stems, add noise, produce output.',
+      next: 'tour_viewer'
+    },
+
+    tour_viewer: {
+      position: 'top-left',
+      highlight: { selector: '.cell:first-child', padding: 8 },
+      text:
+        'This is the **3D viewer** — the live preview of your plant.\nLeft-click to rotate · right-click to pan · scroll to zoom.',
+      next: 'try_params'
+    },
+
+    try_params: {
+      position: 'bottom-right',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        'Click a node to select it. Its settings appear **directly on the node** — try changing a value and watch the plant update.\nThe sidebar shows extra hidden settings for the selected node.',
+      next: 'start_building'
+    },
+
+    start_building: {
+      position: 'center',
+      action: 'load-tutorial-template',
+      text:
+        "Now let's build your own plant from scratch!\nI've loaded a blank project — it only has an **Output** node. Your goal: connect nodes to make a plant.",
+      next: 'add_stem_node'
+    },
+
+    add_stem_node: {
+      position: 'bottom-right',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        "Open the **Add Menu** with **Shift+A** or **right-click** on the canvas.\nAdd a **Stem** node, then connect its output socket to the Output node's input.",
+      next: 'add_noise_node'
+    },
+
+    add_noise_node: {
+      position: 'bottom-right',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        'Add a **Noise** node the same way.\nConnect: Stem → Noise input, then Noise output → Output.\nThis makes the stems grow in organic, curved shapes.',
+      next: 'add_random_node'
+    },
+
+    add_random_node: {
+      position: 'bottom-right',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        "Let's add some randomness! Add a **Random** node and connect its output to the **thickness** or **length** input of the Stem node.\nThe default min/max range is small — **Ctrl+drag** any number field to exceed its normal limits.",
+      next: 'prompt_regenerate'
+    },
+
+    prompt_regenerate: {
+      position: 'bottom-right',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        'Now press **R** to regenerate. Each press gives the Random node a new value — your plant changes every run!',
+      next: 'tour_sidebar'
+    },
+
+    tour_sidebar: {
+      position: 'right',
+      highlight: { selector: '.tabs', padding: 4 },
+      text:
+        'The **sidebar** holds all your tools:\n⚙️ Settings · ⌨️ Shortcuts · 📦 Export · 📁 Projects · 📊 Graph Settings\nEnable **Advanced Mode** in Settings to unlock performance and benchmark panels.',
+      next: 'save_project'
+    },
+
+    save_project: {
+      position: 'right',
+      text:
+        'Your work is saved in the **Projects panel** — rename it, create new projects, or switch between them anytime.',
+      next: 'congrats'
+    },
+
+    congrats: {
+      position: 'center',
+      text:
+        "# You're all set! 🎉\nYou know how to build plants, tweak parameters, and save your work.\nWant to explore more?",
+      choices: [
+        { label: '🔗 How do node connections work?', next: 'connections_intro' },
+        { label: '💡 Ideas for improving this plant', next: 'improvements_hint' },
+        { label: '⌨️ Keyboard shortcuts', next: 'shortcuts_tour' },
+        { label: "I'm ready to build!", next: null }
+      ]
+    },
+
+    // ── Technical / nerd path ──────────────────────────────────────────────
+
+    tour_canvas_nerd: {
+      position: 'bottom-left',
+      action: 'setup-default',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        "The **graph canvas** renders a directed acyclic graph. Each node is an individual **WASM module** executed in isolation — inputs in, output out. The 3D model updates automatically on every change.\nI've loaded a starter graph so you can see it in action.",
+      choices: [
+        {
+          label: '🔍 Explore Node Sourcecode',
+          action: 'open-github-nodes'
+        }
+      ],
+      next: 'tour_viewer_nerd'
+    },
+
+    tour_viewer_nerd: {
+      position: 'top-left',
+      highlight: { selector: '.cell:first-child', padding: 8 },
+      text:
+        'The **3D viewer** uses `@threlte/core` (Svelte + Three.js). Mesh data streams from WASM execution results. OrbitControls: left-drag rotate, right-drag pan, scroll zoom.',
+      next: 'tour_runtime_nerd'
+    },
+
+    tour_runtime_nerd: {
+      position: 'bottom-right',
+      text:
+        'By default, nodes execute in a **WebWorker** for better performance. You can switch to main-thread execution by disabling **Debug → Execute in WebWorker** in Settings.\nEnable **Advanced Mode** to unlock the Performance and Benchmark panels.',
+      next: 'start_building'
+    },
+
+    // ── Deep dives (shared between paths) ─────────────────────────────────
+
+    connections_intro: {
+      position: 'bottom-right',
+      text:
+        'Node sockets are **type-checked**. The coloured dots tell you what kind of data flows through:\n🔵 `number` · 🟢 `vec3` · 🟣 `shape` · ⚪ `*` (wildcard)',
+      next: 'connections_rules'
+    },
+
+    connections_rules: {
+      position: 'right',
+      text:
+        'Drag from an output socket to an input socket to connect them.\n• Types must match (or use `*`)\n• No circular loops\n• Optional inputs can stay empty\nInvalid connections snap back automatically.',
+      choices: [
+        { label: '🔧 Node parameters', next: 'params_intro' },
+        { label: '🐛 Debug node', next: 'debug_intro' },
+        { label: 'Start building!', next: null }
+      ]
+    },
+
+    params_intro: {
+      position: 'bottom-right',
+      highlight: { selector: '.graph-wrapper', padding: 12 },
+      text:
+        'Click any node to select it. Basic settings are shown **on the node itself**.\nThe sidebar under *Graph Settings → Active Node* shows the full list:\n**Number** — drag or type · **Vec3** — X/Y/Z · **Select** — dropdown · **Color** — picker',
+      next: 'params_tip'
+    },
+
+    params_tip: {
+      position: 'right',
+      text:
+        'Pro tips:\n• Parameters can be connected from other nodes — drag an edge to the input socket\n• The **Random Seed** in Graph Settings gives you the same result every run\n• **f** key smart-connects two selected nodes · **Ctrl+Delete** removes a node and restores its edges',
+      choices: [
+        { label: '🔗 How connections work', next: 'connections_intro' },
+        { label: '💡 Plant improvement ideas', next: 'improvements_hint' },
+        { label: 'Start building!', next: null }
+      ]
+    },
+
+    debug_intro: {
+      position: 'bottom-right',
+      text:
+        'Add a **Debug node** from the Add Menu (Shift+A or right-click). It accepts `*` wildcard inputs — connect any socket to inspect the data flowing through.\nEnable **Advanced Mode** in Settings to also see Performance and Graph Source panels.',
+      next: 'debug_done'
+    },
+
+    debug_done: {
+      position: 'center',
+      text: 'The Debug node is your best friend when building complex graphs.\nAnything else?',
+      choices: [
+        { label: '🔗 Connection types', next: 'connections_intro' },
+        { label: '🔧 Node parameters', next: 'params_intro' },
+        { label: 'Start building!', next: null }
+      ]
+    },
+
+    shortcuts_tour: {
+      position: 'bottom-right',
+      text:
+        '**Essential shortcuts:**\n`R` — Regenerate\n`Shift+A` / right-click — Add node\n`f` — Smart-connect selected nodes\n`.` — Center camera\n`Ctrl+Z` / `Ctrl+Y` — Undo / Redo\n`Delete` — Remove selected · `Ctrl+Delete` — Remove and restore edges',
+      next: 'shortcuts_done'
+    },
+
+    shortcuts_done: {
+      position: 'right',
+      text:
+        'All shortcuts are also listed in the sidebar under the ⌨️ icon.\nReady to build something?',
+      choices: [
+        { label: '🔗 Node connections', next: 'connections_intro' },
+        { label: '🔧 Parameters', next: 'params_intro' },
+        { label: "Let's build! 🌿", next: null }
+      ]
+    },
+
+    export_tour: {
+      position: 'right',
+      text:
+        'Export your 3D model from the **📦 Export** panel:\n**GLB** — standard for 3D apps (Blender, Three.js)\n**OBJ** — legacy format · **STL** — 3D printing · **PNG** — screenshot',
+      next: 'congrats'
+    },
+
+    improvements_hint: {
+      position: 'center',
+      text:
+        '# Ideas to grow your plant 🌿\n• Add a **Vec3** node → connect to *origin* on the Stem to spread stems across 3D space\n• Use a **Random** node on a parameter so each run produces a unique shape\n• Chain **multiple Stem nodes** with different settings for complex branching\n• Add a **Gravity** or **Branch** node for even more organic results',
+      choices: [
+        { label: '⌨️ Keyboard shortcuts', next: 'shortcuts_tour' },
+        { label: "Let's build! 🌿", next: null }
+      ]
+    }
+  }
+};

app/src/routes/+page.svelte

@@ -5,6 +5,7 @@
   import { debounceAsyncFunction } from '$lib/helpers';
   import { createKeyMap } from '$lib/helpers/createKeyMap';
   import { debugNode } from '$lib/node-registry/debugNode.js';
+  import { groupInputNode, groupNode, groupOutputNode } from '$lib/node-registry/groupNodes.js';
   import { IndexDBCache, RemoteNodeRegistry } from '$lib/node-registry/index';
   import NodeStore from '$lib/node-store/NodeStore.svelte';
   import PerformanceViewer from '$lib/performance/PerformanceViewer.svelte';
@@ -21,20 +22,29 @@
   import Changelog from '$lib/sidebar/panels/Changelog.svelte';
   import ExportSettings from '$lib/sidebar/panels/ExportSettings.svelte';
   import GraphSource from '$lib/sidebar/panels/GraphSource.svelte';
+  import GroupContextPanel from '$lib/sidebar/panels/GroupContextPanel.svelte';
   import Keymap from '$lib/sidebar/panels/Keymap.svelte';
+  import { panelState } from '$lib/sidebar/PanelState.svelte';
   import Sidebar from '$lib/sidebar/Sidebar.svelte';
+  import { tutorialConfig } from '$lib/tutorial/tutorial-config';
+  import { Planty } from '@nodarium/planty';
   import type { Graph, NodeInstance } from '@nodarium/types';
   import { createPerformanceStore } from '@nodarium/utils';
-  import { onMount } from 'svelte';
   import type { Group } from 'three';
 
   let performanceStore = createPerformanceStore();
+  let planty = $state<ReturnType<typeof Planty>>();
 
   const { data } = $props();
 
   const registryCache = new IndexDBCache('node-registry');
 
-  const nodeRegistry = new RemoteNodeRegistry('', registryCache, [debugNode]);
+  const nodeRegistry = new RemoteNodeRegistry('', registryCache, [
+    debugNode,
+    groupInputNode,
+    groupOutputNode,
+    groupNode
+  ]);
   const workerRuntime = new WorkerRuntimeExecutor();
   const runtimeCache = new MemoryRuntimeCache();
   const memoryRuntime = new MemoryRuntimeExecutor(nodeRegistry, runtimeCache);
@@ -90,6 +100,11 @@
   let graphSettingTypes = $state({
     randomSeed: { type: 'boolean', value: false }
   });
+  $effect(() => {
+    if (graphSettings && graphSettingTypes) {
+      manager?.setSettings($state.snapshot(graphSettings));
+    }
+  });
 
   async function update(
     g: Graph,
@@ -125,35 +140,113 @@
 
   const handleUpdate = debounceAsyncFunction(update);
 
-  onMount(() => {
-    appSettings.value.debug.stressTest = {
-      ...appSettings.value.debug.stressTest,
-      loadGrid: () => {
+  function handleSettingsButton(id: string) {
+    switch (id) {
+      case 'general.clippy':
+        planty?.start();
+        break;
+      case 'general.debug.stressTest.loadGrid':
         manager.load(
           templates.grid(
             appSettings.value.debug.stressTest.amount,
             appSettings.value.debug.stressTest.amount
           )
         );
-      },
-      loadTree: () => {
+        break;
+      case 'general.debug.stressTest.loadTree':
         manager.load(templates.tree(appSettings.value.debug.stressTest.amount));
-      },
-      lottaFaces: () => {
+        break;
+      case 'general.debug.stressTest.lottaFaces':
         manager.load(templates.lottaFaces as unknown as Graph);
-      },
-      lottaNodes: () => {
+        break;
+      case 'general.debug.stressTest.lottaNodes':
         manager.load(templates.lottaNodes as unknown as Graph);
-      },
-      lottaNodesAndFaces: () => {
+        break;
+      case 'general.debug.stressTest.lottaNodesAndFaces':
         manager.load(templates.lottaNodesAndFaces as unknown as Graph);
+        break;
+      default:
+    }
   }
-    };
-  });
 </script>
 
 <svelte:document onkeydown={applicationKeymap.handleKeyboardEvent} />
 
+<Planty
+  bind:this={planty}
+  config={tutorialConfig}
+  actions={{
+    'setup-default': () => {
+      const ts = new Date().toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
+      pm.handleCreateProject(
+        structuredClone(templates.defaultPlant) as unknown as Graph,
+        `Tutorial Project (${ts})`
+      );
+    },
+    'load-tutorial-template': () => {
+      if (!pm.graph) return;
+      const g = structuredClone(templates.tutorial) as unknown as Graph;
+      g.id = pm.graph.id;
+      g.meta = { ...pm.graph.meta };
+      pm.graph = g;
+      pm.saveGraph(g);
+      graphInterface.state.centerNode(graphInterface.manager.getAllNodes()[0]);
+    },
+    'open-github-nodes': () => {
+      window.open(
+        'https://github.com/jim-fx/nodarium/tree/main/nodes/max/plantarium',
+        '__blank'
+      );
+    }
+  }}
+  hooks={{
+    'action:add_stem_node': (cb) => {
+      const unsub = manager.on('save', () => {
+        const allNodes = graphInterface.manager.getAllNodes();
+        const stemNode = allNodes.find(n => n.type === 'max/plantarium/stem');
+        if (stemNode && graphInterface.manager.edges.length) {
+          unsub();
+          (cb as () => void)();
+        }
+      });
+    },
+    'action:add_noise_node': (cb) => {
+      const unsub = manager.on('save', () => {
+        const allNodes = graphInterface.manager.getAllNodes();
+        const noiseNode = allNodes.find(n => n.type === 'max/plantarium/noise');
+        if (noiseNode && graphInterface.manager.edges.length > 1) {
+          unsub();
+          (cb as () => void)();
+        }
+      });
+    },
+    'action:add_random_node': (cb) => {
+      const unsub = manager.on('save', () => {
+        const allNodes = graphInterface.manager.getAllNodes();
+        const noiseNode = allNodes.find(n => n.type === 'max/plantarium/random');
+        if (noiseNode && graphInterface.manager.edges.length > 2) {
+          unsub();
+          (cb as () => void)();
+        }
+      });
+    },
+    'action:prompt_regenerate': (cb) => {
+      function handleKeydown(e: KeyboardEvent) {
+        if (e.key === 'r') {
+          window.removeEventListener('keydown', handleKeydown);
+          (cb as () => void)();
+        }
+      }
+      window.addEventListener('keydown', handleKeydown);
+    },
+    'before:save_project': () => panelState.setActivePanel('projects'),
+    'before:export_tour': () => panelState.setActivePanel('exports'),
+    'before:shortcuts_tour': () => panelState.setActivePanel('shortcuts'),
+    'after:save_project': () => panelState.setActivePanel('graph-settings'),
+    'before:tour_runtime_nerd': () => panelState.setActivePanel('general')
+  }}
+/>
+
 <div class="wrapper manager-{manager?.status}">
   <header></header>
   <Grid.Row>
@@ -172,7 +265,7 @@
           graph={pm.graph}
           bind:this={graphInterface}
           registry={nodeRegistry}
-          addMenuPadding={{ right: sidebarOpen ? 330 : undefined }}
+          safePadding={{ right: sidebarOpen ? 330 : undefined }}
           backgroundType={appSettings.value.nodeInterface.backgroundType}
           snapToGrid={appSettings.value.nodeInterface.snapToGrid}
           bind:activeNode
@@ -187,6 +280,7 @@
         <Panel id="general" title="General" icon="i-[tabler--settings]">
           <NestedSettings
             id="general"
+            onButtonClick={handleSettingsButton}
             bind:value={appSettings.value}
             type={AppSettingTypes}
           />
@@ -206,6 +300,7 @@
         <Panel id="exports" title="Exporter" icon="i-[tabler--package-export]">
           <ExportSettings {scene} />
         </Panel>
+        {#if 0 > 1}
           <Panel
             id="node-store"
             title="Node Store"
@@ -213,6 +308,7 @@
           >
             <NodeStore registry={nodeRegistry} />
           </Panel>
+        {/if}
         <Panel
           id="performance"
           title="Performance"
@@ -252,7 +348,20 @@
             type={graphSettingTypes}
             bind:value={graphSettings}
           />
+          {#if activeNode?.id}
             <ActiveNodeSettings {manager} bind:node={activeNode} />
+          {/if}
+          {#if manager?.isInsideGroup}
+            <GroupContextPanel
+              {manager}
+              groupId={manager.currentGroupContext!}
+            />
+          {:else if activeNode?.type === '__virtual/group/instance'}
+            <GroupContextPanel
+              {manager}
+              groupId={activeNode?.props?.groupId as string}
+            />
+          {/if}
         </Panel>
         <Panel
           id="changelog"
@@ -269,6 +378,25 @@
 <style>
   header {
     background-color: var(--color-layer-1);
+    display: flex;
+    align-items: center;
+    padding: 0 8px;
+  }
+
+  .tutorial-btn {
+    background: none;
+    border: none;
+    cursor: pointer;
+    font-size: 18px;
+    padding: 4px 6px;
+    border-radius: 6px;
+    opacity: 0.7;
+    transition: opacity 0.15s, background 0.15s;
+  }
+
+  .tutorial-btn:hover {
+    opacity: 1;
+    background: rgba(255, 255, 255, 0.08);
   }
 
   .wrapper {

app/src/routes/dev/+layout.svelte

@@ -3,6 +3,6 @@
   const { children } = $props<{ children?: Snippet }>();
 </script>
 
-<main class="w-screen h-screen overflow-x-hidden">
+<main class="w-screen overflow-x-hidden">
   {@render children()}
 </main>

app/src/routes/dev/+page.svelte

@@ -44,9 +44,8 @@
     }
   }
 
-  let graphSettings = $state<Record<string, any>>({});
-  let graphSettingTypes = $state({
-    randomSeed: { type: "boolean", value: false },
+  $effect(() => {
+    fetchNodeData(activeNode.value);
   });
 
   $effect(() => {
@@ -62,85 +61,19 @@
   });
 </script>
 
-<svelte:window
-  bind:innerHeight={windowHeight}
-  onkeydown={(ev) => ev.key === "r" && handleResult()}
-/>
+<div class="node-wrapper absolute bottom-8 left-8">
+  {#if nodeInstance}
+    <NodeHTML inView position="relative" z={5} bind:node={nodeInstance} />
+  {/if}
+</div>
 
 <Grid.Row>
   <Grid.Cell>
-    {#if visibleRows?.length}
-      <table
-        class="min-w-full select-none overflow-auto text-left text-sm flex-1"
-        onscroll={(e) => {
-          const scrollTop = e.currentTarget.scrollTop;
-          start.value = Math.floor(scrollTop / rowHeight);
-        }}
-      >
-        <thead class="">
-          <tr>
-            <th class="px-4 py-2 border-b border-[var(--outline)]">i</th>
-            <th
-              class="px-4 py-2 border-b border-[var(--outline)] w-[50px]"
-              style:width="50px">Ptrs</th
-            >
-            <th class="px-4 py-2 border-b border-[var(--outline)]">Value</th>
-            <th class="px-4 py-2 border-b border-[var(--outline)]">Float</th>
-          </tr>
-        </thead>
-        <tbody
-          onscroll={(e) => {
-            const scrollTop = e.currentTarget.scrollTop;
-            start.value = Math.floor(scrollTop / rowHeight);
-          }}
-        >
-          {#each visibleRows as r, i}
-            {@const index = i + start.value}
-            {@const ptr = ptrs[i]}
-            <tr class="h-[40px] odd:bg-[var(--layer-1)]">
-              <td class="px-4 border-b border-[var(--outline)] w-8">{index}</td>
-              <td
-                class="border-b border-[var(--outline)] overflow-hidden text-ellipsis pl-2
-                        {ptr?._title?.includes('->')
-                  ? 'bg-red-500'
-                  : 'bg-blue-500'}"
-                style="width: 100px; min-width: 100px; max-width: 100px;"
-              >
-                {ptr?._title}
-              </td>
-              <td
-                class="px-4 border-b border-[var(--outline)] cursor-pointer text-blue-600 hover:text-blue-800"
-                onclick={() =>
-                  (rowIsFloat.value[index] = !rowIsFloat.value[index])}
-              >
-                {decodeValue(r, rowIsFloat.value[index])}
-              </td>
-              <td class="px-4 border-b border-[var(--outline)] italic w-5">
-                <input
-                  type="checkbox"
-                  checked={rowIsFloat.value[index]}
-                  onclick={() =>
-                    (rowIsFloat.value[index] = !rowIsFloat.value[index])}
-                />
-              </td>
-            </tr>
-          {/each}
-        </tbody>
-      </table>
-      <button
-        onclick={() => copyVisibleMemory(visibleRows, ptrs, start.value)}
-        class="flex items-center cursor-pointer absolute bottom-4 left-4 z-100 bg-gray-200 px-2 py-1 rounded hover:bg-gray-300"
-      >
-        Copy Visible Memory
-      </button>
-      <input
-        class="absolute bottom-4 right-4 bg-white"
-        bind:value={start.value}
-        min="0"
-        type="number"
-        step="1"
-      />
-    {/if}
+    <pre>
+      <code>
+        {JSON.stringify(nodeInstance?.props)}
+      </code>
+    </pre>
   </Grid.Cell>
 
   <Grid.Cell>
@@ -149,20 +82,6 @@
 </Grid.Row>
 
 <Sidebar>
-  <Panel id="general" title="General" icon="i-[tabler--settings]">
-    <h3 class="p-4 pb-0">Debug Settings</h3>
-    <NestedSettings
-      id="Debug"
-      bind:value={devSettings.value}
-      type={DevSettingsType}
-    />
-    <hr />
-    <NestedSettings
-      id="general"
-      bind:value={appSettings.value}
-      type={AppSettingTypes}
-    />
-  </Panel>
   <Panel
     id="node-store"
     classes="text-green-400"

app/src/routes/dev/dev-graph.json

@@ -1,74 +0,0 @@
-{
-  "settings": {
-    "resolution.circle": 26,
-    "resolution.curve": 39
-  },
-  "nodes": [
-    {
-      "id": 9,
-      "position": [
-        225,
-        65
-      ],
-      "type": "max/plantarium/output",
-      "props": {
-        "out": 0
-      }
-    },
-    {
-      "id": 10,
-      "position": [
-        200,
-        60
-      ],
-      "type": "max/plantarium/math",
-      "props": {
-        "op_type": 3,
-        "a": 2,
-        "b": 0.38
-      }
-    },
-    {
-      "id": 11,
-      "position": [
-        175,
-        60
-      ],
-      "type": "max/plantarium/float",
-      "props": {
-        "value": 0.66
-      }
-    },
-    {
-      "id": 12,
-      "position": [
-        175,
-        80
-      ],
-      "type": "max/plantarium/float",
-      "props": {
-        "value": 1
-      }
-    }
-  ],
-  "edges": [
-    [
-      11,
-      0,
-      10,
-      "a"
-    ],
-    [
-      12,
-      0,
-      10,
-      "b"
-    ],
-    [
-      10,
-      0,
-      9,
-      "out"
-    ]
-  ]
-}

app/src/routes/dev/helpers.ts

@@ -1,48 +0,0 @@
-import type { Pointer } from '$lib/runtime';
-
-export function copyVisibleMemory(rows: Int32Array, currentPtrs: Pointer[], start: number) {
-  if (!rows?.length) return;
-
-  // Build an array of rows for the table
-  const tableRows = [...rows].map((value, i) => {
-    const index = start + i;
-    const ptr = currentPtrs[i];
-    return {
-      index,
-      ptr: ptr?._title ?? '',
-      value: value
-    };
-  });
-
-  // Compute column widths
-  const indexWidth = Math.max(
-    5,
-    ...tableRows.map((r) => r.index.toString().length)
-  );
-  const ptrWidth = Math.max(
-    10,
-    ...tableRows.map((r) => r.ptr.length)
-  );
-  const valueWidth = Math.max(
-    10,
-    ...tableRows.map((r) => r.value.toString().length)
-  );
-
-  // Build header
-  let output =
-    `| ${'Index'.padEnd(indexWidth)} | ${'Ptr'.padEnd(ptrWidth)} | ${'Value'.padEnd(valueWidth)
-    } |\n`
-    + `|-${'-'.repeat(indexWidth)}-|-${'-'.repeat(ptrWidth)}-|-${'-'.repeat(valueWidth)}-|\n`;
-
-  // Add rows
-  for (const row of tableRows) {
-    output += `| ${row.index.toString().padEnd(indexWidth)} | ${row.ptr.padEnd(ptrWidth)} | ${row.value.toString().padEnd(valueWidth)
-      } |\n`;
-  }
-
-  // Copy to clipboard
-  navigator.clipboard
-    .writeText(output)
-    .then(() => console.log('Memory + metadata copied as table'))
-    .catch((err) => console.error('Failed to copy memory:', err));
-}

app/src/routes/dev/settings.svelte.ts

@@ -1,15 +0,0 @@
-import { localState } from '$lib/helpers/localState.svelte';
-import { settingsToStore } from '$lib/settings/app-settings.svelte';
-
-export const DevSettingsType = {
-  debugNode: {
-    type: 'boolean',
-    label: 'Debug Nodes',
-    value: true
-  }
-} as const;
-
-export let devSettings = localState(
-  'dev-settings',
-  settingsToStore(DevSettingsType)
-);

app/vite.config.ts

@@ -1,6 +1,7 @@
 import { sveltekit } from '@sveltejs/kit/vite';
 import tailwindcss from '@tailwindcss/vite';
 import { playwright } from '@vitest/browser-playwright';
+import path from 'path';
 import comlink from 'vite-plugin-comlink';
 import glsl from 'vite-plugin-glsl';
 import wasm from 'vite-plugin-wasm';
@@ -19,6 +20,11 @@ export default defineConfig({
       comlink()
     ]
   },
+  resolve: {
+    alias: {
+      '@nodarium/planty': path.resolve(__dirname, '../packages/planty/src/lib/index.ts')
+    }
+  },
   ssr: {
     noExternal: ['three']
   },

docs/DEVELOPING_NODES.md

@@ -4,19 +4,20 @@ This guide will help you developing your first Nodarium Node written in Rust. As
 
 ## Prerequesites
 
-You need to have [Rust](https://www.rust-lang.org/tools/install) installed. Rust is the language we are going to develop our node in and cargo compiles our rust code into webassembly.
+You need to have [Rust](https://www.rust-lang.org/tools/install) and [wasm-pack](https://rustwasm.github.io/docs/wasm-pack/) installed. Rust is the language we are going to develop our node in and wasm-pack helps us compile our rust code into a webassembly file.
 
 ```bash
 # install rust
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+# install wasm-pack
+cargo install wasm-pack
 ```
 
 ## Clone Template
 
 ```bash
-# copy the template directory
-cp -r nodes/max/plantarium/.template nodes/max/plantarium/my-new-node
-cd nodes/max/plantarium/my-new-node
+wasm-pack new my-new-node --template https://github.com/jim-fx/nodarium_template
+cd my-new-node
 ```
 
 ## Setup Definition

docs/LLM.md

@@ -0,0 +1,312 @@
+# Nodarium - LLM Documentation
+
+## Overview
+
+Nodarium is a **WebAssembly-based visual programming language** for creating procedural 3D plants. The app features a node-based interface where users connect WASM modules to generate plant models in real-time. Currently used to develop https://nodes.max-richter.dev, a procedural modelling tool for 3D plants.
+
+## Architecture
+
+### Core Components
+
+#### 1. Node System (`app/static/nodes/`)
+
+WASM-based nodes that perform computations. All nodes must implement the NodeDefinition interface.
+
+- **Node Storage**: `app/static/nodes/max/plantarium/`
+  - `box.wasm` - Box geometry node
+  - `branch.wasm` - Branch generation
+  - `float.wasm` - Float value node
+  - `gravity.wasm` - Gravity/physics node
+  - `instance.wasm` - Instance rendering
+  - `leaf.wasm` - Leaf geometry
+  - `math.wasm` - Math operations
+  - `noise.wasm` - Noise generation
+  - `output.wasm` - Output node
+  - `random.wasm` - Random value generation
+  - `rotate.wasm` - Rotation node
+  - `shape.wasm` - Shape geometry
+  - `stem.wasm` - Stem generation
+  - `triangle.wasm` - Triangle geometry
+  - `vec3.wasm` - Vector3 node
+
+- **Node Registry**: `app/src/lib/node-registry.ts`
+  - Loads and manages WASM nodes
+  - `getNodeWasm()` - Creates WASM wrapper from bytes
+  - `getNode()` - Retrieves node definition
+
+- **Debug Node**: `app/src/lib/node-registry/debugNode.js`
+  - Special debug node with wildcard inputs
+  - Variable-height nodes and parameters
+  - Quick-connect shortcut
+
+#### 2. Graph Interface
+
+Visual node editor built with Svelte 5.
+
+- **Main Wrapper**: `app/src/lib/graph-interface/graph/Wrapper.svelte`
+  - Entry point for graph interface
+  - Manages GraphManager and GraphState
+
+- **GraphManager**: `app/src/lib/graph-interface/graph-manager.svelte.ts`
+  - Core entity managing the node graph
+  - Handles node connections and execution flow
+
+- **GraphState**: `app/src/lib/graph-interface/graph-state.svelte.ts`
+  - Tracks UI state (selection, snapping, help, active nodes)
+
+- **Graph Components**:
+  - `app/src/lib/graph-interface/graph/` - Graph rendering
+  - `app/src/lib/graph-interface/node/` - Node rendering
+  - `app/src/lib/graph-interface/edges/` - Edge rendering
+  - `app/src/lib/graph-interface/components/` - UI components (AddMenu, Socket, etc.)
+  - `app/src/lib/graph-interface/debug/` - Debug overlays
+  - `app/src/lib/graph-interface/background/` - Grid/dots backgrounds
+
+- **Helpers**:
+  - `app/src/lib/helpers/` - Utility functions
+  - `app/src/lib/helpers/createKeyMap.ts` - Keyboard shortcuts
+
+#### 3. Runtime Execution
+
+Performs graph execution via WASM nodes.
+
+- **Runtime Executors** (`app/src/lib/runtime/`):
+  - **MemoryRuntime**: Direct WASM execution in main thread
+  - **WorkerRuntime**: WebWorker-based execution for performance
+  - Both implement the RuntimeExecutor interface
+
+- **Runtime Cache**: `app/src/lib/runtime/cache.ts`
+  - Memory-based caching for graph execution
+
+- **Execution Flow**:
+  1. Graph serialized from graph interface
+  2. Runtime executes nodes in topological order
+  3. Results passed through connected edges
+  4. Final mesh output rendered
+
+#### 4. 3D Viewer (`app/src/lib/result-viewer/`)
+
+Three.js-based rendering for 3D output.
+
+- **Viewer**: `app/src/lib/result-viewer/Viewer.svelte`
+  - Renders generated 3D meshes
+  - Uses @threlte/core (Svelte-Three.js wrapper)
+
+#### 5. Application Structure (`app/src/routes/`)
+
+SvelteKit application routing.
+
+- **Main Page**: `app/src/routes/+page.svelte`
+  - Combines GraphInterface + 3D Viewer
+  - Manages runtime selection (memory vs worker)
+  - Handles settings and performance tracking
+
+- **Layout**: `app/src/routes/+layout.svelte`
+  - Application shell
+
+- **Server**: `app/src/routes/+layout.server.ts`
+  - Loads git metadata and changelog
+
+#### 6. Settings System (`app/src/lib/settings/`)
+
+Application and graph settings.
+
+- **App Settings**: `app/src/lib/settings/app-settings.svelte.ts`
+  - Debug mode, themes, node interface options
+
+- **NestedSettings**: `app/src/lib/settings/NestedSettings.svelte`
+  - Recursive settings UI component
+
+#### 7. Sidebar Panels (`app/src/lib/sidebar/`)
+
+- `app/src/lib/sidebar/Sidebar.svelte` - Main sidebar
+- `app/src/lib/sidebar/panels/` - Individual panels:
+  - `ActiveNodeSettings.svelte` - Selected node properties
+  - `BenchmarkPanel.svelte` - Performance benchmarking
+  - `Changelog.svelte` - Version history
+  - `ExportSettings.svelte` - Export options
+  - `GraphSource.svelte` - Graph JSON view
+  - `Keymap.svelte` - Keyboard shortcuts
+
+#### 8. Project Management (`app/src/lib/project-manager/`)
+
+- `app/src/lib/project-manager/project-manager.svelte` - Project save/load
+- Uses IndexedDB for persistence
+
+#### 9. Node Store (`app/src/lib/node-store/`)
+
+- `app/src/lib/node-store/NodeStore.svelte`
+- Remote node registry management
+- IndexDBCache for offline storage
+
+#### 10. Graph Templates (`app/src/lib/graph-templates/`)
+
+Pre-built graph templates for testing:
+
+- Grid, Tree, LottaFaces, LottaNodes, LottaNodesAndFaces
+
+## Key Types (`app/src/lib/types.ts`)
+
+```typescript
+interface NodeDefinition {
+  id: string;
+  name: string;
+  inputs: Socket[];
+  outputs: Socket[];
+  parameters: Parameter[];
+  execute: (inputs: any[], parameters: any[]) => any[];
+}
+
+interface Socket {
+  id: string;
+  name: string;
+  type: string; // datatype (e.g., "number", "vec3", "*")
+  defaultValue?: any;
+  optional?: boolean;
+}
+
+interface Parameter {
+  id: string;
+  name: string;
+  type: string;
+  defaultValue: any;
+  min?: number;
+  max?: number;
+  options?: string[];
+}
+
+interface Graph {
+  nodes: NodeInstance[];
+  edges: Edge[];
+}
+
+interface NodeInstance {
+  id: number;
+  nodeId: string;
+  position: { x: number; y: number };
+  parameters: Record<string, any>;
+}
+
+interface Edge {
+  id: number;
+  fromNode: number;
+  fromSocket: string;
+  toNode: number;
+  toSocket: string;
+}
+```
+
+## Development Workflow
+
+### Prerequisites
+
+- Node.js
+- pnpm
+- Rust
+- wasm-pack
+
+### Build Commands
+
+```bash
+# Install dependencies
+pnpm i
+
+# Build WASM nodes
+pnpm build:nodes
+
+# Start development server
+cd app && pnpm dev
+
+# Run tests
+cd app && pnpm test
+
+# Lint and typecheck
+cd app && pnpm lint
+cd app && pnpm check
+
+# Format code
+cd app && pnpm format
+```
+
+### Creating New Nodes
+
+See `docs/DEVELOPING_NODES.md` for detailed instructions on creating custom WASM nodes.
+
+## Features
+
+### Current Features
+
+- Visual node-based programming with real-time 3D preview
+- WebAssembly nodes for high-performance computation
+- Debug node with wildcard inputs and runtime integration
+- Color-coded node sockets and edges (indicating data types)
+- Variable-height nodes and parameters
+- Edge dragging with valid socket highlighting
+- InputNumber snapping to predefined values (Alt+click)
+- Project save/load with IndexedDB
+- Performance monitoring and benchmarking
+- Changelog viewer
+- Advanced mode settings
+
+### UI Components
+
+- **InputNumber**: Numeric input with arrow controls
+- **InputColor**: Color picker
+- **InputShape**: Shape selector with preview
+- **InputSelect**: Dropdown with options
+
+## File Structure
+
+```
+nodarium/
+├── app/
+│   ├── src/
+│   │   ├── lib/
+│   │   │   ├── config.ts
+│   │   │   ├── graph-interface/    # Node editor
+│   │   │   ├── graph-manager.svelte.ts
+│   │   │   ├── graph-state.svelte.ts
+│   │   │   ├── graph-templates/   # Test templates
+│   │   │   ├── grid/
+│   │   │   ├── helpers/
+│   │   │   ├── node-registry.ts
+│   │   │   ├── node-registry/     # Node loading
+│   │   │   ├── node-store/
+│   │   │   ├── performance/
+│   │   │   ├── project-manager/
+│   │   │   ├── result-viewer/       # 3D viewer
+│   │   │   ├── runtime/           # Execution
+│   │   │   ├── settings/         # App settings
+│   │   │   ├── sidebar/
+│   │   │   └── types.ts
+│   │   └── routes/
+│   │       ├── +page.svelte
+│   │       └── +layout.svelte
+│   ├── static/
+│   │   └── nodes/
+│   │       └── max/
+│   │           └── plantarium/    # WASM nodes
+│   └── package.json
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── DEVELOPING_NODES.md
+│   ├── NODE_DEFINITION.md
+│   └── PLANTARIUM.md
+├── nodes/                        # WASM node source (Rust)
+└── package.json
+```
+
+## Release Process
+
+1. Create annotated tag:
+   ```bash
+   git tag -a v1.0.0 -m "Release notes"
+   git push origin v1.0.0
+   ```
+
+2. CI workflow:
+   - Runs lint, format check, type check
+   - Builds project
+   - Updates package.json versions
+   - Generates CHANGELOG.md
+   - Creates Gitea release

nodes/max/plantarium/box/src/lib.rs

@@ -1,18 +1,20 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
 use nodarium_utils::{
-    encode_float, evaluate_float, geometry::calculate_normals, wrap_arg,
-    read_i32_slice
+    encode_float, evaluate_float, geometry::calculate_normals,log,
+    split_args, wrap_arg,
 };
 
 nodarium_definition_file!("src/input.json");
 
 #[nodarium_execute]
-pub fn execute(size: (i32, i32)) -> Vec<i32> {
+pub fn execute(input: &[i32]) -> Vec<i32> {
 
-    let args = read_i32_slice(size);
+    let args = split_args(input);
 
-    let size = evaluate_float(&args);
+    log!("WASM(cube): input: {:?} -> {:?}", input, args);
+
+    let size = evaluate_float(args[0]);
 
     let p = encode_float(size);
     let n = encode_float(-size);
@@ -75,6 +77,8 @@ pub fn execute(size: (i32, i32)) -> Vec<i32> {
 
     let res = wrap_arg(&cube_geometry);
 
+    log!("WASM(box): output: {:?}", res);
+
     res
 
 }

nodes/max/plantarium/branch/src/lib.rs

@@ -1,6 +1,5 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::read_i32_slice;
 use nodarium_utils::{
     concat_arg_vecs, evaluate_float, evaluate_int,
     geometry::{
@@ -14,25 +13,15 @@ use std::f32::consts::PI;
 nodarium_definition_file!("src/input.json");
 
 #[nodarium_execute]
-pub fn execute(
-    path: (i32, i32),
-    length: (i32, i32),
-    thickness: (i32, i32),
-    offset_single: (i32, i32),
-    lowest_branch: (i32, i32),
-    highest_branch: (i32, i32),
-    depth: (i32, i32),
-    amount: (i32, i32),
-    resolution_curve: (i32, i32),
-    rotation: (i32, i32),
-) -> Vec<i32> {
-    let arg = read_i32_slice(path);
-    let paths = split_args(arg.as_slice());
+pub fn execute(input: &[i32]) -> Vec<i32> {
+    let args = split_args(input);
+
+    let paths = split_args(args[0]);
 
     let mut output: Vec<Vec<i32>> = Vec::new();
 
-    let resolution = evaluate_int(read_i32_slice(resolution_curve).as_slice()).max(4) as usize;
-    let depth = evaluate_int(read_i32_slice(depth).as_slice());
+    let resolution = evaluate_int(args[8]).max(4) as usize;
+    let depth = evaluate_int(args[6]);
 
     let mut max_depth = 0;
     for path_data in paths.iter() {
@@ -51,18 +40,18 @@ pub fn execute(
 
         let path = wrap_path(path_data);
 
-        let branch_amount = evaluate_int(read_i32_slice(amount).as_slice()).max(1);
+        let branch_amount = evaluate_int(args[7]).max(1);
 
-        let lowest_branch = evaluate_float(read_i32_slice(lowest_branch).as_slice());
-        let highest_branch = evaluate_float(read_i32_slice(highest_branch).as_slice());
+        let lowest_branch = evaluate_float(args[4]);
+        let highest_branch = evaluate_float(args[5]);
 
         for i in 0..branch_amount {
             let a = i as f32 / (branch_amount - 1).max(1) as f32;
 
-            let length = evaluate_float(read_i32_slice(length).as_slice());
-            let thickness = evaluate_float(read_i32_slice(thickness).as_slice());
+            let length = evaluate_float(args[1]);
+            let thickness = evaluate_float(args[2]);
             let offset_single = if i % 2 == 0 {
-                evaluate_float(read_i32_slice(offset_single).as_slice())
+                evaluate_float(args[3])
             } else {
                 0.0
             };
@@ -76,8 +65,7 @@ pub fn execute(
                 root_alpha + (offset_single - 0.5) * 6.0 / resolution as f32,
             );
 
-            let rotation_angle =
-                (evaluate_float(read_i32_slice(rotation).as_slice()) * PI / 180.0) * i as f32;
+            let rotation_angle = (evaluate_float(args[9]) * PI / 180.0) * i as f32;
 
             // check if diration contains NaN
             if orthogonal[0].is_nan() || orthogonal[1].is_nan() || orthogonal[2].is_nan() {

nodes/max/plantarium/debug/.gitignore

@@ -1,6 +0,0 @@
-/target
-**/*.rs.bk
-Cargo.lock
-bin/
-pkg/
-wasm-pack.log

nodes/max/plantarium/debug/Cargo.toml

@@ -1,12 +0,0 @@
-[package]
-name = "debug"
-version = "0.1.0"
-authors = ["Max Richter <jim-x@web.de>"]
-edition = "2018"
-
-[lib]
-crate-type = ["cdylib", "rlib"]
-
-[dependencies]
-nodarium_macros = { version = "0.1.0", path = "../../../../packages/macros" }
-nodarium_utils = { version = "0.1.0", path = "../../../../packages/utils" }

nodes/max/plantarium/debug/src/input.json

@@ -1,22 +0,0 @@
-{
-  "id": "max/plantarium/debug",
-  "outputs": [],
-  "inputs": {
-    "input": {
-      "type": "float",
-      "accepts": [
-        "*"
-      ],
-      "external": true
-    },
-    "type": {
-      "type": "select",
-      "options": [
-        "float",
-        "vec3",
-        "geometry"
-      ],
-      "internal": true
-    }
-  }
-}

nodes/max/plantarium/debug/src/lib.rs

@@ -1,25 +0,0 @@
-use nodarium_macros::nodarium_definition_file;
-use nodarium_macros::nodarium_execute;
-use nodarium_utils::encode_float;
-use nodarium_utils::evaluate_float;
-use nodarium_utils::evaluate_vec3;
-use nodarium_utils::read_i32;
-use nodarium_utils::read_i32_slice;
-
-nodarium_definition_file!("src/input.json");
-
-#[nodarium_execute]
-pub fn execute(input: (i32, i32), input_type: (i32, i32)) -> Vec<i32> {
-    let inp = read_i32_slice(input);
-    let t = read_i32(input_type.0);
-    if t == 0 {
-        let f = evaluate_float(inp.as_slice());
-        return vec![encode_float(f)];
-    }
-    if t == 1 {
-        let f = evaluate_vec3(inp.as_slice());
-        return vec![encode_float(f[0]), encode_float(f[1]), encode_float(f[2])];
-    }
-
-    return inp;
-}

nodes/max/plantarium/float/Cargo.toml

@@ -2,14 +2,11 @@
 name = "float"
 version = "0.1.0"
 authors = ["Max Richter <jim-x@web.de>"]
-edition = "2021"
+edition = "2018"
 
 [lib]
 crate-type = ["cdylib", "rlib"]
 
-[profile.dev]
-panic = "unwind"
-
 [dependencies]
 nodarium_macros = { version = "0.1.0", path = "../../../../packages/macros" }
 nodarium_utils = { version = "0.1.0", path = "../../../../packages/utils" }

nodes/max/plantarium/float/src/lib.rs

@@ -1,10 +1,9 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::read_i32;
 
 nodarium_definition_file!("src/input.json");
 
 #[nodarium_execute]
-pub fn execute(a: (i32, i32)) -> Vec<i32> {
-    vec![read_i32(a.0)]
+pub fn execute(args: &[i32]) -> Vec<i32> {
+    args.into()
 }

nodes/max/plantarium/gravity/src/lib.rs

@@ -1,7 +1,6 @@
 use glam::Vec3;
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::read_i32_slice;
 use nodarium_utils::{
     concat_args, evaluate_float, evaluate_int,
     geometry::{wrap_path, wrap_path_mut},
@@ -15,17 +14,13 @@ fn lerp_vec3(a: Vec3, b: Vec3, t: f32) -> Vec3 {
 }
 
 #[nodarium_execute]
-pub fn execute(
-    plant: (i32, i32),
-    strength: (i32, i32),
-    curviness: (i32, i32),
-    depth: (i32, i32),
-) -> Vec<i32> {
+pub fn execute(input: &[i32]) -> Vec<i32> {
     reset_call_count();
 
-    let arg = read_i32_slice(plant);
-    let plants = split_args(arg.as_slice());
-    let depth = evaluate_int(read_i32_slice(depth).as_slice());
+    let args = split_args(input);
+
+    let plants = split_args(args[0]);
+    let depth = evaluate_int(args[3]);
 
     let mut max_depth = 0;
     for path_data in plants.iter() {
@@ -60,9 +55,9 @@ pub fn execute(
 
                 let length = direction.length();
 
-                let str = evaluate_float(read_i32_slice(strength).as_slice());
-                let curviness = evaluate_float(read_i32_slice(curviness).as_slice());
-                let strength = str / curviness.max(0.0001) * str;
+                let curviness = evaluate_float(args[2]);
+                let strength =
+                    evaluate_float(args[1]) / curviness.max(0.0001) * evaluate_float(args[1]);
 
                 log!(
                     "length: {}, curviness: {}, strength: {}",

nodes/max/plantarium/instance/src/lib.rs

@@ -13,7 +13,7 @@ pub fn execute(input: &[i32]) -> Vec<i32> {
     let args = split_args(input);
     let mut inputs = split_args(args[0]);
 
-    let mut geo_data = read_i32_slice(geometry);
+    let mut geo_data = args[1].to_vec();
     let geo = wrap_geometry_data(&mut geo_data);
 
     let mut transforms: Vec<Mat4> = Vec::new();

nodes/max/plantarium/math/src/lib.rs

@@ -1,15 +1,13 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::log;
-use nodarium_utils::{concat_arg_vecs, read_i32_slice};
-
-nodarium_definition_file!("src/input.json");
+use nodarium_utils::{
+    concat_args, split_args
+};
 
 #[nodarium_execute]
-pub fn execute(op_type: (i32, i32), a: (i32, i32), b: (i32, i32)) -> Vec<i32> {
-    log!("math.op {:?}", op_type);
-    let op = read_i32_slice(op_type);
-    let a_val = read_i32_slice(a);
-    let b_val = read_i32_slice(b);
-    concat_arg_vecs(vec![vec![0], op, a_val, b_val])
+pub fn execute(args: &[i32]) -> Vec<i32> {
+    let args = split_args(args);
+    concat_args(vec![&[0], args[0], args[1], args[2]])
 }
+
+nodarium_definition_file!("src/input.json");

nodes/max/plantarium/noise/Cargo.toml

@@ -2,7 +2,7 @@
 name = "noise"
 version = "0.1.0"
 authors = ["Max Richter <jim-x@web.de>"]
-edition = "2021"
+edition = "2018"
 
 [lib]
 crate-type = ["cdylib", "rlib"]

nodes/max/plantarium/noise/src/input.json

@@ -10,12 +10,14 @@
     "scale": {
       "type": "float",
       "min": 0.1,
-      "max": 10
+      "max": 10,
+      "value": 1
     },
     "strength": {
       "type": "float",
       "min": 0.1,
-      "max": 10
+      "max": 10,
+      "value": 2
     },
     "fixBottom": {
       "type": "float",

nodes/max/plantarium/noise/src/lib.rs

@@ -1,8 +1,7 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::read_i32_slice;
 use nodarium_utils::{
-    concat_args, evaluate_float, evaluate_int, evaluate_vec3, geometry::wrap_path_mut, read_i32,
+    concat_args, evaluate_float, evaluate_int, evaluate_vec3, geometry::wrap_path_mut,
     reset_call_count, split_args,
 };
 use noise::{HybridMulti, MultiFractal, NoiseFn, OpenSimplex};
@@ -14,31 +13,23 @@ fn lerp(a: f32, b: f32, t: f32) -> f32 {
 }
 
 #[nodarium_execute]
-pub fn execute(
-    plant: (i32, i32),
-    scale: (i32, i32),
-    strength: (i32, i32),
-    fix_bottom: (i32, i32),
-    seed: (i32, i32),
-    directional_strength: (i32, i32),
-    depth: (i32, i32),
-    octaves: (i32, i32),
-) -> Vec<i32> {
+pub fn execute(input: &[i32]) -> Vec<i32> {
     reset_call_count();
 
-    let arg = read_i32_slice(plant);
-    let plants = split_args(arg.as_slice());
-    let scale = (evaluate_float(read_i32_slice(scale).as_slice()) * 0.1) as f64;
-    let strength = evaluate_float(read_i32_slice(strength).as_slice());
-    let fix_bottom = evaluate_float(read_i32_slice(fix_bottom).as_slice());
+    let args = split_args(input);
 
-    let seed = read_i32(seed.0);
+    let plants = split_args(args[0]);
+    let scale = (evaluate_float(args[1]) * 0.1) as f64;
+    let strength = evaluate_float(args[2]);
+    let fix_bottom = evaluate_float(args[3]);
 
-    let directional_strength = evaluate_vec3(read_i32_slice(directional_strength).as_slice());
+    let seed = args[4][0];
 
-    let depth = evaluate_int(read_i32_slice(depth).as_slice());
+    let directional_strength = evaluate_vec3(args[5]);
 
-    let octaves = evaluate_int(read_i32_slice(octaves).as_slice());
+    let depth = evaluate_int(args[6]);
+
+    let octaves = evaluate_int(args[7]);
 
     let noise_x: HybridMulti<OpenSimplex> =
         HybridMulti::new(seed as u32 + 1).set_octaves(octaves as usize);

nodes/max/plantarium/output/src/inputs.json

@@ -5,7 +5,7 @@
     "input": {
       "type": "path",
       "accepts": [
-        "*"
+        "geometry"
       ],
       "external": true
     },

nodes/max/plantarium/output/src/lib.rs

@@ -1,11 +1,44 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::read_i32_slice;
+use nodarium_utils::{
+    concat_args, evaluate_int,
+    geometry::{extrude_path, wrap_path},
+    log, split_args,
+};
 
-nodarium_definition_file!("src/input.json");
+nodarium_definition_file!("src/inputs.json");
 
 #[nodarium_execute]
-pub fn execute(input: (i32, i32), _res: (i32, i32)) -> Vec<i32> {
-    let inp = read_i32_slice(input);
-    return inp;
+pub fn execute(input: &[i32]) -> Vec<i32> {
+    log!("WASM(output): input: {:?}", input);
+
+    let args = split_args(input);
+
+    log!("WASM(output) args: {:?}", args);
+
+    assert_eq!(args.len(), 2, "Expected 2 arguments, got {}", args.len());
+    let inputs = split_args(args[0]);
+
+    let resolution = evaluate_int(args[1]) as usize;
+
+    log!("inputs: {}, resolution: {}", inputs.len(), resolution);
+
+    let mut output: Vec<Vec<i32>> = Vec::new();
+    for arg in inputs {
+        let arg_type = arg[2];
+        log!("arg_type: {}, \n {:?}", arg_type, arg,);
+
+        if arg_type == 0 {
+            // if this is path we need to extrude it
+            output.push(arg.to_vec());
+            let path_data = wrap_path(arg);
+            let geometry = extrude_path(path_data, resolution);
+            output.push(geometry);
+            continue;
+        }
+
+        output.push(arg.to_vec());
+    }
+
+    concat_args(output.iter().map(|v| v.as_slice()).collect())
 }

nodes/max/plantarium/random/src/definition.json

@@ -6,7 +6,7 @@
   "inputs": {
     "min": {
       "type": "float",
-      "value": 2
+      "value": 1
     },
     "max": {
       "type": "float",

nodes/max/plantarium/random/src/lib.rs

@@ -1,17 +1,11 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::concat_arg_vecs;
-use nodarium_utils::read_i32_slice;
+use nodarium_utils::{concat_args, split_args};
 
-nodarium_definition_file!("src/input.json");
+nodarium_definition_file!("src/definition.json");
 
 #[nodarium_execute]
-pub fn execute(min: (i32, i32), max: (i32, i32), seed: (i32, i32)) -> Vec<i32> {
-    nodarium_utils::log!("random execute start");
-    concat_arg_vecs(vec![
-        vec![1],
-        read_i32_slice(min),
-        read_i32_slice(max),
-        read_i32_slice(seed),
-    ])
+pub fn execute(args: &[i32]) -> Vec<i32> {
+    let args = split_args(args);
+    concat_args(vec![&[1], args[0], args[1], args[2]])
 }

nodes/max/plantarium/rotate/src/lib.rs

@@ -1,26 +1,23 @@
 use glam::{Mat4, Vec3};
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::read_i32_slice;
 use nodarium_utils::{
-    concat_args, evaluate_float, evaluate_int, geometry::wrap_path_mut, log, split_args,
+    concat_args, evaluate_float, evaluate_int, geometry::wrap_path_mut, log,
+    split_args,
 };
 
 nodarium_definition_file!("src/input.json");
 
 #[nodarium_execute]
-pub fn execute(
-    plant: (i32, i32),
-    axis: (i32, i32),
-    angle: (i32, i32),
-    spread: (i32, i32),
-) -> Vec<i32> {
-    log!("DEBUG args: {:?}", plant);
+pub fn execute(input: &[i32]) -> Vec<i32> {
 
-    let arg = read_i32_slice(plant);
-    let plants = split_args(arg.as_slice());
-    let axis = evaluate_int(read_i32_slice(axis).as_slice()); // 0 =x, 1 = y, 2 = z
-    let spread = evaluate_int(read_i32_slice(spread).as_slice());
+    log!("DEBUG args: {:?}", input);
+
+    let args = split_args(input);
+
+    let plants = split_args(args[0]);
+    let axis = evaluate_int(args[1]); // 0 =x, 1 = y, 2 = z
+    let spread = evaluate_int(args[3]);
 
     let output: Vec<Vec<i32>> = plants
         .iter()
@@ -35,7 +32,7 @@ pub fn execute(
 
             let path = wrap_path_mut(&mut path_data);
 
-            let angle = evaluate_float(read_i32_slice(angle).as_slice());
+            let angle = evaluate_float(args[2]);
 
             let origin = [path.points[0], path.points[1], path.points[2]];
 

nodes/max/plantarium/stem/src/lib.rs

@@ -3,29 +3,30 @@ use nodarium_macros::nodarium_execute;
 use nodarium_utils::{
     evaluate_float, evaluate_int, evaluate_vec3,
     geometry::{create_multiple_paths, wrap_multiple_paths},
-    log, reset_call_count,
-    read_i32_slice, read_i32, 
+    log, reset_call_count, split_args,
 };
 
 nodarium_definition_file!("src/input.json");
 
 #[nodarium_execute]
-pub fn execute(origin: (i32, i32), _amount: (i32,i32), length: (i32, i32), thickness: (i32, i32), resolution_curve: (i32, i32)) -> Vec<i32> {
+pub fn execute(input: &[i32]) -> Vec<i32> {
     reset_call_count();
 
-    let amount = evaluate_int(read_i32_slice(_amount).as_slice()) as usize;
-    let path_resolution = read_i32(resolution_curve.0) as usize;
+    let args = split_args(input);
 
-    log!("stem args: amount={:?}", amount);
+    let amount = evaluate_int(args[1]) as usize;
+    let path_resolution = evaluate_int(args[4]) as usize;
+
+    log!("stem args: {:?}", args);
 
     let mut stem_data = create_multiple_paths(amount, path_resolution, 1);
 
     let mut stems = wrap_multiple_paths(&mut stem_data);
 
     for stem in stems.iter_mut() {
-        let origin = evaluate_vec3(read_i32_slice(origin).as_slice());
-        let length = evaluate_float(read_i32_slice(length).as_slice());
-        let thickness = evaluate_float(read_i32_slice(thickness).as_slice());
+        let origin = evaluate_vec3(args[0]);
+        let length = evaluate_float(args[2]);
+        let thickness = evaluate_float(args[3]);
         let amount_points = stem.points.len() / 4;
 
         for i in 0..amount_points {

nodes/max/plantarium/triangle/src/lib.rs

@@ -1,17 +1,21 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::read_i32_slice;
-use nodarium_utils::{decode_float, encode_float, evaluate_int, log, wrap_arg};
+use nodarium_utils::{
+    decode_float, encode_float, evaluate_int, split_args, wrap_arg, log
+};
 
 nodarium_definition_file!("src/input.json");
 
 #[nodarium_execute]
-pub fn execute(size: (i32, i32)) -> Vec<i32> {
-    let size = evaluate_int(read_i32_slice(size).as_slice());
+pub fn execute(input: &[i32]) -> Vec<i32> {
+
+    let args = split_args(input);
+
+    let size = evaluate_int(args[0]);
     let decoded = decode_float(size);
     let negative_size = encode_float(-decoded);
 
-    log!("WASM(triangle): input: {:?} -> {}", size, decoded);
+    log!("WASM(triangle): input: {:?} -> {}", args[0],decoded);
 
     // [[1,3, x, y, z, x, y,z,x,y,z]];
     wrap_arg(&[
@@ -19,9 +23,7 @@ pub fn execute(size: (i32, i32)) -> Vec<i32> {
         3,          // 3 vertices
         1,          // 1 face
         // this are the indeces for the face
-        0,
-        2,
-        1,
+        0, 2, 1,
         //
         negative_size,  // x -> point 1
         0,              // y
@@ -35,14 +37,9 @@ pub fn execute(size: (i32, i32)) -> Vec<i32> {
         0,          // y
         size,       // z
         // this is the normal for the single face 1065353216 == 1.0f encoded is i32
-        0,
-        1065353216,
-        0,
-        0,
-        1065353216,
-        0,
-        0,
-        1065353216,
-        0,
+        0, 1065353216, 0,
+        0, 1065353216, 0,
+        0, 1065353216, 0,
     ])
+
 }

nodes/max/plantarium/vec3/src/lib.rs

@@ -1,17 +1,13 @@
 use nodarium_macros::nodarium_definition_file;
 use nodarium_macros::nodarium_execute;
-use nodarium_utils::concat_args;
-use nodarium_utils::log;
-use nodarium_utils::read_i32_slice;
+use nodarium_utils::{concat_args, log, split_args};
 
 nodarium_definition_file!("src/input.json");
 
 #[nodarium_execute]
-pub fn execute(x: (i32, i32), y: (i32, i32), z: (i32, i32)) -> Vec<i32> {
-    log!("vec3 x: {:?}", x);
-    concat_args(vec![
-        read_i32_slice(x).as_slice(),
-        read_i32_slice(y).as_slice(),
-        read_i32_slice(z).as_slice(),
-    ])
+pub fn execute(input: &[i32]) -> Vec<i32> {
+    let args = split_args(input);
+    log!("vec3 input: {:?}", input);
+    log!("vec3 args: {:?}", args);
+    concat_args(args)
 }

package.json

@@ -1,7 +1,7 @@
 {
   "version": "0.0.4",
   "scripts": {
-    "postinstall": "pnpm run -r --filter 'ui' build",
+    "_postinstall": "pnpm run -r --filter 'ui' build && pnpm run -r --filter 'planty' build",
     "lint": "pnpm run -r --parallel lint",
     "qa": "pnpm lint && pnpm check && pnpm test",
     "format": "pnpm dprint fmt",
@@ -9,7 +9,7 @@
     "test": "pnpm run -r --parallel test",
     "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",
+    "build:app": "BASE_PATH=/ui pnpm -r --filter 'ui' build && pnpm -r --filter 'app'... build",
     "build:nodes": "cargo build --workspace --target wasm32-unknown-unknown --release && rm -rf ./app/static/nodes/max/plantarium/ && mkdir -p ./app/static/nodes/max/plantarium/ && cp -R ./target/wasm32-unknown-unknown/release/*.wasm ./app/static/nodes/max/plantarium/",
     "dev:nodes": "chokidar './nodes/**' --initial -i '/pkg/' -c 'pnpm build:nodes'",
     "dev:app_ui": "pnpm -r --parallel --filter 'app' --filter './packages/ui' dev",

packages/macros/src/lib.rs

@@ -6,202 +6,96 @@ use std::env;
 use std::fs;
 use std::path::Path;
 use syn::parse_macro_input;
-use syn::spanned::Spanned;
 
 fn add_line_numbers(input: String) -> String {
-    input
+    return input
         .split('\n')
         .enumerate()
         .map(|(i, line)| format!("{:2}: {}", i + 1, line))
         .collect::<Vec<String>>()
-        .join("\n")
-}
-
-fn read_node_definition(file_path: &Path) -> NodeDefinition {
-    let project_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
-    let full_path = Path::new(&project_dir).join(file_path);
-    let json_content = fs::read_to_string(&full_path).unwrap_or_else(|err| {
-        panic!(
-            "Failed to read JSON file at '{}/{}': {}",
-            project_dir,
-            file_path.to_string_lossy(),
-            err
-        )
-    });
-    serde_json::from_str(&json_content).unwrap_or_else(|err| {
-        panic!(
-            "JSON file contains invalid JSON: \n{} \n{}",
-            err,
-            add_line_numbers(json_content.clone())
-        )
-    })
+        .join("\n");
 }
 
 #[proc_macro_attribute]
 pub fn nodarium_execute(_attr: TokenStream, item: TokenStream) -> TokenStream {
     let input_fn = parse_macro_input!(item as syn::ItemFn);
-    let fn_name = &input_fn.sig.ident;
-    let fn_vis = &input_fn.vis;
+    let _fn_name = &input_fn.sig.ident;
+    let _fn_vis = &input_fn.vis;
     let fn_body = &input_fn.block;
-    let inner_fn_name = syn::Ident::new(&format!("__nodarium_inner_{}", fn_name), fn_name.span());
 
-    let def: NodeDefinition = read_node_definition(Path::new("src/input.json"));
-
-    let input_count = def.inputs.as_ref().map(|i| i.len()).unwrap_or(0);
-
-    validate_signature(&input_fn.sig, input_count, &def);
-
-    let input_param_names: Vec<_> = input_fn
-        .sig
-        .inputs
-        .iter()
-        .filter_map(|arg| {
-            if let syn::FnArg::Typed(pat_type) = arg {
+    let first_arg_ident = if let Some(syn::FnArg::Typed(pat_type)) = input_fn.sig.inputs.first() {
         if let syn::Pat::Ident(pat_ident) = &*pat_type.pat {
-                    Some(pat_ident.ident.clone())
+            &pat_ident.ident
         } else {
-                    None
+            panic!("Expected a simple identifier for the first argument");
         }
     } else {
-                None
-            }
-        })
-        .collect();
-
-    let param_count = input_fn.sig.inputs.len();
-    let total_c_params = param_count * 2;
-
-    let arg_names: Vec<_> = (0..total_c_params)
-        .map(|i| syn::Ident::new(&format!("arg{i}"), input_fn.sig.span()))
-        .collect();
-
-    let mut tuple_args = Vec::new();
-    for i in 0..param_count {
-        let start_name = &arg_names[i * 2];
-        let end_name = &arg_names[i * 2 + 1];
-        let tuple_arg = quote! {
-            (#start_name, #end_name)
+        panic!("The execute function must have at least one argument (the input slice)");
     };
-        tuple_args.push(tuple_arg);
-    }
 
+    // We create a wrapper that handles the C ABI and pointer math
     let expanded = quote! {
-
         extern "C" {
-            fn __nodarium_log(ptr: *const u8, len: usize);
+            fn host_log_panic(ptr: *const u8, len: usize);
+            fn host_log(ptr: *const u8, len: usize);
         }
 
-        #[cfg(target_arch = "wasm32")]
-        fn init_panic_hook() {
-            std::panic::set_hook(Box::new(|_info| {
-                unsafe {
-                    __nodarium_log(b"PANIC\0".as_ptr(), 5);
-                }
+        fn setup_panic_hook() {
+            static SET_HOOK: std::sync::Once = std::sync::Once::new();
+            SET_HOOK.call_once(|| {
+                std::panic::set_hook(Box::new(|info| {
+                    let msg = info.to_string();
+                    unsafe { host_log_panic(msg.as_ptr(), msg.len()); }
                 }));
+            });
         }
         
         #[no_mangle]
-        pub extern "C" fn init_allocator() {
-            nodarium_utils::allocator::ALLOCATOR.init();
-        }
-
-        #fn_vis fn #inner_fn_name(#( #input_param_names: (i32, i32) ),*) -> Vec<i32> {
-            #fn_body
+        pub extern "C" fn __alloc(len: usize) -> *mut i32 {
+            let mut buf = Vec::with_capacity(len);
+            let ptr = buf.as_mut_ptr();
+            std::mem::forget(buf);
+            ptr
         }
 
         #[no_mangle]
-        #fn_vis extern "C" fn execute(output_pos: i32, #( #arg_names: i32 ),*) -> i32 {
-
-            nodarium_utils::allocator::ALLOCATOR.init();
-            #[cfg(target_arch = "wasm32")]
-            init_panic_hook();
-            nodarium_utils::log!("before_fn");
-            let result = #inner_fn_name(
-                #( #tuple_args ),*
-            );
-            nodarium_utils::log!("after_fn: result_len={}", result.len());
-
-            let len_bytes = result.len() * 4;
+        pub extern "C" fn __free(ptr: *mut i32, len: usize) {
             unsafe {
-                let src = result.as_ptr() as *const u8;
-                let dst = output_pos as *mut u8;
-                nodarium_utils::log!("writing output_pos={:?} src={:?} len_bytes={:?}", output_pos, src, len_bytes);
-                dst.copy_from_nonoverlapping(src, len_bytes);
+                let _ = Vec::from_raw_parts(ptr, 0, len);
+            }
         }
 
-            len_bytes as i32
+        static mut OUTPUT_BUFFER: Vec<i32> = Vec::new();
+
+        #[no_mangle]
+        pub extern "C" fn execute(ptr: *const i32, len: usize) -> *mut i32 {
+            setup_panic_hook();
+            // 1. Convert raw pointer to slice
+            let input = unsafe { core::slice::from_raw_parts(ptr, len) };
+
+            // 2. Call the logic (which we define below)
+            let result_data: Vec<i32> = internal_logic(input);
+
+            // 3. Use the static buffer for the result
+            let result_len = result_data.len();
+            unsafe {
+                OUTPUT_BUFFER.clear();
+                OUTPUT_BUFFER.reserve(result_len + 1);
+                OUTPUT_BUFFER.push(result_len as i32);
+                OUTPUT_BUFFER.extend(result_data);
+                
+                OUTPUT_BUFFER.as_mut_ptr()
+            }
+        }
+
+        fn internal_logic(#first_arg_ident: &[i32]) -> Vec<i32> {
+            #fn_body
         }
     };
 
     TokenStream::from(expanded)
 }
 
-fn validate_signature(fn_sig: &syn::Signature, expected_inputs: usize, def: &NodeDefinition) {
-    let param_count = fn_sig.inputs.len();
-    let expected_params = expected_inputs;
-
-    if param_count != expected_params {
-        panic!(
-            "Execute function has {} parameters but definition has {} inputs\n\
-             Definition inputs: {:?}\n\
-             Expected signature:\n\
-             pub fn execute({}) -> Vec<i32>",
-            param_count,
-            expected_inputs,
-            def.inputs
-                .as_ref()
-                .map(|i| i.keys().collect::<Vec<_>>())
-                .unwrap_or_default(),
-            (0..expected_inputs)
-                .map(|i| format!("arg{i}: (i32, i32)"))
-                .collect::<Vec<_>>()
-                .join(", ")
-        );
-    }
-
-    for (i, arg) in fn_sig.inputs.iter().enumerate() {
-        match arg {
-            syn::FnArg::Typed(pat_type) => {
-                let type_str = quote! { #pat_type.ty }.to_string();
-                let clean_type = type_str
-                    .trim()
-                    .trim_start_matches("_")
-                    .trim_end_matches(".ty")
-                    .trim()
-                    .to_string();
-                if !clean_type.contains("(") && !clean_type.contains(",") {
-                    panic!(
-                        "Parameter {i} has type '{clean_type}' but should be a tuple (i32, i32) representing (start, end) positions in memory",
-                    );
-                }
-            }
-            syn::FnArg::Receiver(_) => {
-                panic!("Execute function cannot have 'self' parameter");
-            }
-        }
-    }
-
-    match &fn_sig.output {
-        syn::ReturnType::Type(_, ty) => {
-            let is_vec = match &**ty {
-                syn::Type::Path(tp) => tp
-                    .path
-                    .segments
-                    .first()
-                    .map(|seg| seg.ident == "Vec")
-                    .unwrap_or(false),
-                _ => false,
-            };
-            if !is_vec {
-                panic!("Execute function must return Vec<i32>");
-            }
-        }
-        syn::ReturnType::Default => {
-            panic!("Execute function must return Vec<i32>");
-        }
-    }
-}
-
 #[proc_macro]
 pub fn nodarium_definition_file(input: TokenStream) -> TokenStream {
     let path_lit = syn::parse_macro_input!(input as syn::LitStr);
@@ -211,23 +105,30 @@ pub fn nodarium_definition_file(input: TokenStream) -> TokenStream {
     let full_path = Path::new(&project_dir).join(&file_path);
 
     let json_content = fs::read_to_string(&full_path).unwrap_or_else(|err| {
-        panic!("Failed to read JSON file at '{project_dir}/{file_path}': {err}",)
+        panic!("Failed to read JSON file at '{}/{}': {}", project_dir, file_path, err)
     });
 
     let _: NodeDefinition = serde_json::from_str(&json_content).unwrap_or_else(|err| {
-        panic!(
-            "JSON file contains invalid JSON: \n{} \n{}",
-            err,
-            add_line_numbers(json_content.clone())
-        )
+        panic!("JSON file contains invalid JSON: \n{} \n{}", err, add_line_numbers(json_content.clone()))
     });
 
+    // We use the span from the input path literal
     let bytes = syn::LitByteStr::new(json_content.as_bytes(), path_lit.span());
     let len = json_content.len();
 
     let expanded = quote! {
         #[link_section = "nodarium_definition"]
         static DEFINITION_DATA: [u8; #len] = *#bytes;
+        
+        #[no_mangle]
+        pub extern "C" fn get_definition_ptr() -> *const u8 {
+            DEFINITION_DATA.as_ptr()
+        }
+
+        #[no_mangle]
+        pub extern "C" fn get_definition_len() -> usize {
+            DEFINITION_DATA.len()
+        }
     };
 
     TokenStream::from(expanded)

packages/planty/.gitignore

@@ -0,0 +1,24 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+/dist
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+!.env.test
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

packages/planty/README.md

@@ -0,0 +1,65 @@
+# Svelte library
+
+Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+
+Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project in the current directory
+npx sv create
+
+# create a new project in my-app
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+pnpm dlx sv@0.15.1 create --template library --types ts --add prettier eslint tailwindcss="plugins:none" --install pnpm planty
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+
+## Building
+
+To build your library:
+
+```sh
+npm pack
+```
+
+To create a production version of your showcase app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+
+## Publishing
+
+Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+
+To publish your library to [npm](https://www.npmjs.com):
+
+```sh
+npm publish
+```

packages/planty/eslint.config.js

@@ -0,0 +1,44 @@
+import { includeIgnoreFile } from '@eslint/compat';
+import js from '@eslint/js';
+import prettier from 'eslint-config-prettier';
+import svelte from 'eslint-plugin-svelte';
+import { defineConfig } from 'eslint/config';
+import globals from 'globals';
+import path from 'node:path';
+import ts from 'typescript-eslint';
+import svelteConfig from './svelte.config.js';
+
+const gitignorePath = path.resolve(import.meta.dirname, '.gitignore');
+
+export default defineConfig(
+  includeIgnoreFile(gitignorePath),
+  js.configs.recommended,
+  ts.configs.recommended,
+  svelte.configs.recommended,
+  prettier,
+  svelte.configs.prettier,
+  {
+    languageOptions: { globals: { ...globals.browser, ...globals.node } },
+    rules: {
+      // typescript-eslint strongly recommend that you do not use the no-undef lint rule on TypeScript projects.
+      // see: https://typescript-eslint.io/troubleshooting/faqs/eslint/#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors
+      'no-undef': 'off'
+    }
+  },
+  {
+    files: ['**/*.svelte', '**/*.svelte.ts', '**/*.svelte.js'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        extraFileExtensions: ['.svelte'],
+        parser: ts.parser,
+        svelteConfig
+      }
+    }
+  },
+  {
+    // Override or add rule settings here, such as:
+    // 'svelte/button-has-type': 'error'
+    rules: {}
+  }
+);

packages/planty/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@nodarium/planty",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "prepack": "svelte-kit sync && svelte-package && publint",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "lint": "eslint .",
+    "format": "dprint fmt -c '../.dprint.jsonc' .",
+    "format:check": "dprint check -c '../.dprint.jsonc' ."
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./src/lib/index.ts",
+  "types": "./src/lib/index.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/lib/index.ts",
+      "svelte": "./src/lib/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@nodarium/ui": "workspace:*",
+    "@eslint/compat": "^2.0.4",
+    "@eslint/js": "^10.0.1",
+    "@sveltejs/adapter-auto": "^7.0.1",
+    "@sveltejs/kit": "^2.57.0",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@tailwindcss/vite": "^4.2.2",
+    "@types/node": "^24",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-svelte": "^3.17.0",
+    "globals": "^17.4.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-svelte": "^3.5.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "publint": "^0.3.18",
+    "svelte": "^5.55.2",
+    "svelte-check": "^4.4.6",
+    "tailwindcss": "^4.2.2",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
+    "vite": "^8.0.7"
+  },
+  "keywords": [
+    "svelte"
+  ]
+}

packages/planty/src/app.d.ts

@@ -0,0 +1,13 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+declare global {
+  namespace App {
+    // interface Error {}
+    // interface Locals {}
+    // interface PageData {}
+    // interface PageState {}
+    // interface Platform {}
+  }
+}
+
+export {};

packages/planty/src/app.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en" class="theme-dark">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" href="%sveltekit.assets%/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="text-scale" content="scale" />
+    %sveltekit.head%
+  </head>
+  <body data-sveltekit-preload-data="hover">
+    <div style="display: contents">%sveltekit.body%</div>
+  </body>
+</html>

packages/planty/src/lib/components/Highlight.svelte

@@ -0,0 +1,111 @@
+<script lang="ts">
+  import type { PlantyHook } from '../types.js';
+
+  interface Props {
+    selector?: string;
+    hookName?: string;
+    hooks?: Record<string, PlantyHook>;
+  }
+
+  let { selector, hookName, hooks = {} }: Props = $props();
+
+  let rect = $state<{ top: number; left: number; width: number; height: number } | null>(null);
+
+  $effect(() => {
+    let el: Element | null = null;
+    let ro: ResizeObserver | null = null;
+    let mo: MutationObserver | null = null;
+
+    function resolveEl(): Element | null {
+      if (selector) return document.querySelector(selector);
+      if (hookName && hooks[hookName]) {
+        const result = hooks[hookName]();
+        if (result instanceof Element) return result;
+      }
+      return null;
+    }
+
+    function updateRect() {
+      if (!el) {
+        rect = null;
+        return;
+      }
+      const raw = el.getBoundingClientRect();
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      const p = 4;
+      const top = Math.max(p, raw.top - p);
+      const left = Math.max(p, raw.left - p);
+      const right = Math.min(vw - p, raw.right + p);
+      const bottom = Math.min(vh - p, raw.bottom + p);
+      if (right <= left || bottom <= top) {
+        rect = null;
+        return;
+      }
+      rect = { top, left, width: right - left, height: bottom - top };
+    }
+
+    function attachEl(newEl: Element | null) {
+      if (newEl === el) return;
+      ro?.disconnect();
+      el = newEl;
+      if (!el) {
+        rect = null;
+        return;
+      }
+      updateRect();
+      ro = new ResizeObserver(updateRect);
+      ro.observe(el);
+    }
+
+    attachEl(resolveEl());
+
+    window.addEventListener('scroll', updateRect, { passive: true, capture: true });
+    window.addEventListener('resize', updateRect, { passive: true });
+
+    // For hook-based highlights, watch the DOM so we catch dynamically added elements
+    if (hookName) {
+      mo = new MutationObserver(() => attachEl(resolveEl()));
+      mo.observe(document.body, { childList: true, subtree: true });
+    }
+
+    return () => {
+      ro?.disconnect();
+      mo?.disconnect();
+      window.removeEventListener('scroll', updateRect, true);
+      window.removeEventListener('resize', updateRect);
+    };
+  });
+</script>
+
+{#if rect}
+  <div
+    class="highlight pointer-events-none fixed z-99999 rounded-md"
+    style:top="{rect.top}px"
+    style:left="{rect.left}px"
+    style:width="{rect.width}px"
+    style:height="{rect.height}px"
+  >
+  </div>
+{/if}
+
+<style>
+  @keyframes pulse {
+  	0%,
+  	100% {
+  		box-shadow:
+  			0 0 0 9999px rgba(0, 0, 0, 0.45),
+  			0 0 0 2px rgba(255, 255, 255, 0.9),
+  			0 0 16px rgba(255, 255, 255, 0.3);
+  	}
+  	50% {
+  		box-shadow:
+  			0 0 0 9999px rgba(0, 0, 0, 0.45),
+  			0 0 0 2px rgba(255, 255, 255, 1),
+  			0 0 28px rgba(255, 255, 255, 0.6);
+  	}
+  }
+  .highlight {
+  	animation: pulse 1.8s ease-in-out infinite;
+  }
+</style>

packages/planty/src/lib/components/Planty.svelte

@@ -0,0 +1,221 @@
+<script lang="ts">
+  import { DialogRunner } from '../dialog-runner.js';
+  import type { AvatarPosition, DialogNode, PlantyConfig, PlantyHook } from '../types.js';
+  import Highlight from './Highlight.svelte';
+  import PlantyAvatar from './PlantyAvatar.svelte';
+  import type { Mood } from './PlantyAvatar.svelte';
+  import SpeechBubble from './SpeechBubble.svelte';
+
+  interface Props {
+    config: PlantyConfig;
+    hooks?: Record<string, PlantyHook>;
+    actions?: Record<string, PlantyHook>;
+    onStepChange?: (nodeId: string, node: DialogNode) => void;
+    onComplete?: () => void;
+  }
+
+  let { config, actions = {}, hooks = {}, onStepChange, onComplete }: Props = $props();
+
+  const AVATAR_SIZE = 80;
+  const SCREEN_PADDING = 20;
+
+  // ── State ────────────────────────────────────────────────────────────
+  let isActive = $state(false);
+  let currentNodeId = $state<string | null>(null);
+  let bubbleVisible = $state(false);
+  let avatar = $state<PlantyAvatar>(null!);
+  let avatarX = $state(0);
+  let avatarY = $state(0);
+  let mood = $state<Mood>('idle');
+  let autoAdvanceTimer: ReturnType<typeof setTimeout> | null = null;
+  let actionCleanup: (() => void) | null = null;
+
+  // ── Derived ──────────────────────────────────────────────────────────
+  const runner = $derived(new DialogRunner(config));
+  const nextNode = $derived(
+    runner.getNextNode(currentNodeId ?? '')
+  );
+  const mainPath = $derived(runner.getMainPath());
+  const currentNode = $derived<DialogNode | null>(
+    currentNodeId ? runner.getNode(currentNodeId) : null
+  );
+  const showBubble = $derived(
+    isActive && bubbleVisible && currentNode !== null && !!currentNode.text
+  );
+  const highlight = $derived(currentNode?.highlight ?? null);
+  const stepIndex = $derived(currentNodeId ? mainPath.indexOf(currentNodeId) : -1);
+  const totalSteps = $derived(mainPath.length);
+
+  // ── Position helpers ─────────────────────────────────────────────────
+  function anchorToCoords(anchor: string): { x: number; y: number } {
+    const w = window.innerWidth;
+    const h = window.innerHeight;
+    switch (anchor) {
+      case 'top-left':
+        return { x: SCREEN_PADDING, y: SCREEN_PADDING };
+      case 'top-right':
+        return { x: w - AVATAR_SIZE - SCREEN_PADDING, y: SCREEN_PADDING };
+      case 'bottom-left':
+        return { x: SCREEN_PADDING, y: h - AVATAR_SIZE - SCREEN_PADDING };
+      case 'center':
+        return { x: (w - AVATAR_SIZE) / 2, y: (h - AVATAR_SIZE) / 2 };
+      case 'right':
+        return { x: w - AVATAR_SIZE - SCREEN_PADDING, y: (h - AVATAR_SIZE) / 2 };
+      case 'bottom-right':
+      default:
+        return { x: w - AVATAR_SIZE - SCREEN_PADDING, y: h - AVATAR_SIZE - SCREEN_PADDING };
+    }
+  }
+
+  function resolvePosition(pos: AvatarPosition): { x: number; y: number } {
+    return typeof pos === 'string' ? anchorToCoords(pos) : pos;
+  }
+
+  // ── Public API (exposed via bind:this) ───────────────────────────────
+  export function start() {
+    const defaultPos = config.avatar?.defaultPosition ?? 'bottom-right';
+    const pos = resolvePosition(defaultPos);
+    avatarX = pos.x;
+    avatarY = pos.y;
+    isActive = true;
+
+    const start = runner.getStartNode();
+    if (start) _enterNode(start.id, start.node);
+  }
+
+  export function stop() {
+    _clearAutoAdvance();
+    isActive = false;
+    bubbleVisible = false;
+    currentNodeId = null;
+    mood = 'idle';
+    onComplete?.();
+  }
+
+  export async function next() {
+    if (!currentNodeId) return;
+    await _runAfter(currentNodeId, currentNode);
+    const next = runner.getNextNode(currentNodeId);
+    if (next) _enterNode(next.id, next.node);
+    else stop();
+  }
+
+  export function registerHook(name: string, fn: PlantyHook) {
+    hooks = { ...hooks, [name]: fn };
+  }
+
+  // ── Internal ─────────────────────────────────────────────────────────
+
+  async function _runAfter(nodeId: string, node: DialogNode | null) {
+    if (!node) return;
+    if (actionCleanup) {
+      actionCleanup();
+      actionCleanup = null;
+    }
+    await node.after?.(nodeId, node);
+    await hooks[`after:${nodeId}`]?.(nodeId, node);
+  }
+
+  async function _enterNode(id: string, node: DialogNode) {
+    _clearAutoAdvance();
+    bubbleVisible = false;
+    currentNodeId = id;
+    onStepChange?.(id, node);
+
+    // Before hooks — run before movement starts
+    await node.before?.(id, node);
+    await hooks[`before:${id}`]?.(id, node);
+
+    // Fly to position first, then talk
+    if (node.position) {
+      mood = 'moving';
+      const pos = resolvePosition(node.position);
+      const hasChanges = pos.x !== avatarX || pos.y !== avatarY;
+      avatarX = pos.x;
+      avatarY = pos.y;
+      if (hasChanges) await _wait(900);
+    }
+
+    mood = 'talking';
+    bubbleVisible = true;
+
+    // App hook
+    if (node.action && actions[node.action]) {
+      const result = await actions[node.action]();
+      if (typeof result === 'function') actionCleanup = result as () => void;
+    }
+
+    const actionHook = hooks[`action:${id}`];
+    if (actionHook) {
+      const advance = () => {
+        avatar.flash('happy', 2000);
+        next();
+      };
+      const result = await actionHook(advance);
+      if (typeof result === 'function') actionCleanup = result as () => void;
+    }
+
+    if (!node.choices && !node.next) {
+      setTimeout(() => stop(), 3000);
+    }
+
+    // Stay in talking mood until the typewriter finishes (26 ms/char + buffer)
+    const talkMs = (node.text?.length ?? 0) * 26 + 200;
+    setTimeout(() => {
+      mood = 'idle';
+    }, talkMs);
+  }
+
+  function _wait(ms: number) {
+    return new Promise<void>((r) => setTimeout(r, ms));
+  }
+
+  function _clearAutoAdvance() {
+    if (autoAdvanceTimer !== null) {
+      clearTimeout(autoAdvanceTimer);
+      autoAdvanceTimer = null;
+    }
+  }
+</script>
+
+{#if isActive}
+  <div class="pointer-events-none fixed inset-0 z-99999">
+    {#if highlight}
+      <Highlight selector={highlight.selector} hookName={highlight.hookName} {hooks} />
+    {/if}
+
+    <PlantyAvatar bind:this={avatar} bind:x={avatarX} bind:y={avatarY} {mood} />
+
+    {#if showBubble && currentNode}
+      <SpeechBubble
+        text={currentNode.text ?? ''}
+        {avatarX}
+        {avatarY}
+        choices={currentNode.choices || []}
+        showNext={nextNode !== null}
+        {stepIndex}
+        {totalSteps}
+        onNext={next}
+        onClose={stop}
+        onChoose={async (choice) => {
+          await _runAfter(currentNodeId!, currentNode);
+          if (choice && choice.action) {
+            if (choice.action in actions) {
+              actions[choice.action]();
+            } else {
+              console.warn(`Planty: No action found for ${choice.action}`);
+            }
+            return;
+          }
+          if (!choice.next) {
+            stop();
+            return;
+          }
+          const n = runner.followChoice(choice);
+          if (n) _enterNode(n.id, n.node);
+          else stop();
+        }}
+      />
+    {/if}
+  </div>
+{/if}

packages/planty/src/lib/components/PlantyAvatar.svelte

@@ -0,0 +1,435 @@
+<script lang="ts">
+  import { scale } from 'svelte/transition';
+  export type Mood = 'idle' | 'talking' | 'happy' | 'thinking' | 'moving';
+
+  interface Props {
+    x: number;
+    y: number;
+    mood?: Mood;
+  }
+
+  let { x = $bindable(0), y = $bindable(0), mood = 'idle' }: Props = $props();
+
+  // ── Drag ─────────────────────────────────────────────────────────────
+  let dragging = $state(false);
+  let dragOffsetX = 0;
+  let dragOffsetY = 0;
+
+  function onPointerDown(e: PointerEvent) {
+    if (e.button !== 0) return;
+    dragging = true;
+    dragOffsetX = e.clientX - x;
+    dragOffsetY = e.clientY - y;
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    e.preventDefault();
+    e.stopPropagation();
+  }
+
+  function onPointerMove(e: PointerEvent) {
+    if (!dragging) return;
+    x = Math.max(Math.min(e.clientX - dragOffsetX, window.innerWidth - 45), 5);
+    y = Math.max(Math.min(e.clientY - dragOffsetY, window.innerHeight - 75), 5);
+  }
+
+  function onPointerUp() {
+    dragging = false;
+  }
+
+  const displayMood = $derived(dragging ? 'moving' : mood);
+
+  let mouthOpen = $state(false);
+
+  $effect(() => {
+    if (displayMood !== 'talking') {
+      mouthOpen = false;
+      return;
+    }
+    const id = setInterval(() => {
+      mouthOpen = !mouthOpen;
+    }, 180);
+    return () => clearInterval(id);
+  });
+
+  const MOUTH_DOWN =
+    'M29.5 55L28 63L23 68.5L14 70.5L6.5 66L4 58.5L10.5 29L15 24H24L28 29.5L28.5 34L23 58L16.5 61.5L10.5 59.5L8.5 53.5';
+  const MOUTH_UP =
+    'M29.5 55L28 63L23 68.5L14 70.5L6.5 66L4 58.5L10.5 29L15 24H24L28 29.5L28.5 34L24 56.5L17.5 60L11.5 58L9.5 52';
+
+  const bodyPath = $derived(
+    (displayMood === 'talking' && mouthOpen) || displayMood === 'happy' ? MOUTH_DOWN : MOUTH_UP
+  );
+
+  // ── Cursor-tracking pupils ────────────────────────────────────────────
+  // Avatar screen positions of each eye centre (SVG natural size 46×74)
+  let cursorX = $state(-9999);
+  let cursorY = $state(-9999);
+
+  function onMouseMove(e: MouseEvent) {
+    cursorX = e.clientX;
+    cursorY = e.clientY;
+  }
+
+  export function flash(flashMood: Mood, duration = 500) {
+    const prev = displayMood;
+    mood = flashMood;
+    setTimeout(() => (mood = prev), duration);
+  }
+
+  function pupilOffset(cx: number, cy: number, eyeSvgX: number, eyeSvgY: number, maxPx = 2.8) {
+    const ex = x + eyeSvgX;
+    const ey = y + eyeSvgY;
+    const dx = cx - ex;
+    const dy = cy - ey;
+    const dist = Math.sqrt(dx * dx + dy * dy);
+    if (dist < 1) return { px: 0, py: 0 };
+    // Ramp up to full offset over 120px of distance
+    const t = Math.min(dist, 120) / 120;
+    return { px: (dx / dist) * maxPx * t, py: (dy / dist) * maxPx * t };
+  }
+
+  const left = $derived(
+    displayMood === 'talking' ? { px: 0, py: 0 } : pupilOffset(cursorX, cursorY, 9.5, 30.5)
+  );
+  const right = $derived(
+    displayMood === 'talking' ? { px: 0, py: 0 } : pupilOffset(cursorX, cursorY, 31.5, 35.5)
+  );
+</script>
+
+<svelte:window onmousemove={onMouseMove} />
+
+<div
+  class="avatar"
+  role="button"
+  tabindex="0"
+  in:scale={{ duration: 400, delay: 300 }}
+  class:mood-idle={displayMood === 'idle'}
+  class:mood-thinking={displayMood === 'thinking'}
+  class:mood-talking={displayMood === 'talking'}
+  class:mood-happy={displayMood === 'happy'}
+  class:mood-moving={displayMood === 'moving'}
+  class:dragging
+  style:left="{x}px"
+  style:top="{y}px"
+  onpointerdown={onPointerDown}
+  onpointermove={onPointerMove}
+  onpointerup={onPointerUp}
+>
+  <svg
+    width="46"
+    height="74"
+    viewBox="0 0 46 74"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    overflow="visible"
+  >
+    <!--
+			Leaf hinge points (transform-box: fill-box):
+			  leave-right  →  origin 0% 100%   (bottom-left of bbox)
+			  leave-left   →  origin 100% 100% (bottom-right of bbox)
+		-->
+    <g class="leave-right">
+      <path
+        d="M26.9781 16.5596L22.013 23.2368L22.8082 25.306L35.2985 25.3849L43.7783 20.6393L45.8723 14.8213L35.7374 14.0864L26.9781 16.5596Z"
+        fill="#4F7B41"
+      />
+      <path
+        d="M27 16.5L22.013 23.2368L22.8082 25.306L29 21L36.5 17L45.8723 14.8213L36 14L27 16.5Z"
+        fill="#406634"
+      />
+    </g>
+
+    <g class="leave-left">
+      <path
+        d="M11.3107 19.2204L17.7636 24.7215L20.3207 25.3703L22.8257 13.0024L19.0993 2.99176L12.5794 1.95314e-05L10.0997 9.77364L11.3107 19.2204Z"
+        fill="#4F7B41"
+      />
+      <path
+        d="M11.3107 19.2204L17.7636 24.7215L20.3207 25.3703L16 17L13.5 8L12.5794 1.95314e-05L10.0997 9.77364L11.3107 19.2204Z"
+        fill="#5E8751"
+      />
+    </g>
+
+    <path class="body" d={bodyPath} stroke="#4F7B41" stroke-width="3" />
+
+    <!-- Left eye — pupils translated toward cursor -->
+    <g class="eye-left">
+      <circle cx="9.5" cy="30.5" r="9.5" fill="white" />
+      <g transform="translate({left.px} {left.py})">
+        <circle class="pupil" cx="9.5" cy="30.5" r="6.5" fill="black" />
+        <circle cx="10.5" cy="27.5" r="2.5" fill="white" />
+      </g>
+    </g>
+
+    <!-- Right eye — pupils translated toward cursor -->
+    <g class="eye-right">
+      <circle cx="31.5" cy="35.5" r="9.5" fill="white" />
+      <g transform="translate({right.px} {right.py})">
+        <circle class="pupil" cx="30.5" cy="34.5" r="6.5" fill="black" />
+        <circle cx="30.5" cy="31.5" r="2.5" fill="white" />
+      </g>
+    </g>
+  </svg>
+</div>
+
+<style>
+  /* ── Wrapper ─────────────────────────────────────────────────────── */
+  .avatar {
+  	position: absolute;
+  	cursor: grab;
+  	user-select: none;
+  	pointer-events: auto;
+  	filter: drop-shadow(0px 0px 10px black);
+  	transition:
+  		left 0.85s cubic-bezier(0.33, 1, 0.68, 1),
+  		top 0.85s cubic-bezier(0.33, 1, 0.68, 1);
+  }
+
+  .dragging {
+  	cursor: grabbing;
+  	transition: none;
+  }
+
+  /* idle: steady vertical bob */
+  @keyframes bob {
+  	0%,
+  	100% {
+  		transform: translateY(0);
+  	}
+  	50% {
+  		transform: translateY(-5px);
+  	}
+  }
+  .mood-idle {
+  	animation: bob 2.6s ease-in-out infinite;
+  }
+  .mood-happy {
+  	animation: bob 1.8s ease-in-out infinite;
+  }
+
+  /* thinking: head tilted to the side — clearly different from idle */
+  @keyframes think {
+  	0%,
+  	100% {
+  		transform: rotate(-12deg) translateY(0);
+  	}
+  	50% {
+  		transform: rotate(-12deg) translateY(-3px);
+  	}
+  }
+  .mood-thinking {
+  	animation: think 2.8s ease-in-out infinite;
+  }
+
+  /* talking: subtle head waggle */
+  @keyframes waggle {
+  	0%,
+  	100% {
+  		transform: rotate(0deg);
+  	}
+  	25% {
+  		transform: rotate(-2deg) translateY(-1px);
+  	}
+  	75% {
+  		transform: rotate(2deg) translateY(1px);
+  	}
+  }
+  .mood-talking {
+  	animation: waggle 0.3s ease-in-out infinite;
+  }
+
+  /* moving: forward-lean glide */
+  @keyframes glide {
+  	0%,
+  	100% {
+  		transform: translateY(0) rotate(-6deg);
+  	}
+  	50% {
+  		transform: translateY(-8px) rotate(-4deg);
+  	}
+  }
+  .mood-moving {
+  	animation: glide 0.4s ease-in-out infinite;
+  }
+
+  /* ── Drop shadows ────────────────────────────────────────────────── */
+  .body {
+  	filter: drop-shadow(1px 1px 0 rgba(0, 0, 0, 0.5));
+  	transition: d 0.12s ease-in-out;
+  }
+  .eye-left,
+  .eye-right {
+  	filter: drop-shadow(1px 1px 0 rgba(0, 0, 0, 0.5));
+  }
+
+  .mood-talking {
+  	.eye-left,
+  	.eye-right {
+  		> g {
+  			transition: transform 0.5s ease-in-out;
+  		}
+  	}
+  }
+
+  /* ── Leaves ──────────────────────────────────────────────────────── */
+  .leave-right {
+  	transform-box: fill-box;
+  	transform-origin: 0% 100%;
+  }
+  .leave-left {
+  	transform-box: fill-box;
+  	transform-origin: 100% 100%;
+  }
+
+  /* idle: slow gentle breathing wave */
+  @keyframes idle-right {
+  	0%,
+  	100% {
+  		transform: rotate(0deg);
+  	}
+  	50% {
+  		transform: rotate(-9deg);
+  	}
+  }
+  @keyframes idle-left {
+  	0%,
+  	100% {
+  		transform: rotate(0deg);
+  	}
+  	50% {
+  		transform: rotate(7deg);
+  	}
+  }
+  .mood-idle .leave-right {
+  	animation: idle-right 3s ease-in-out infinite;
+  }
+  .mood-idle .leave-left {
+  	animation: idle-left 3s ease-in-out infinite 0.15s;
+  }
+
+  /* thinking: wings held raised, minimal drift */
+  @keyframes think-right {
+  	0%,
+  	100% {
+  		transform: rotate(-14deg);
+  	}
+  	50% {
+  		transform: rotate(-10deg);
+  	}
+  }
+  @keyframes think-left {
+  	0%,
+  	100% {
+  		transform: rotate(10deg);
+  	}
+  	50% {
+  		transform: rotate(7deg);
+  	}
+  }
+  .mood-thinking .leave-right {
+  	animation: think-right 4s ease-in-out infinite;
+  }
+  .mood-thinking .leave-left {
+  	animation: think-left 4s ease-in-out infinite 0.3s;
+  }
+
+  /* talking: nearly still — tiny passive counter-sway */
+  @keyframes talk-right {
+  	0%,
+  	100% {
+  		transform: rotate(-2deg);
+  	}
+  	50% {
+  		transform: rotate(2deg);
+  	}
+  }
+  @keyframes talk-left {
+  	0%,
+  	100% {
+  		transform: rotate(2deg);
+  	}
+  	50% {
+  		transform: rotate(-2deg);
+  	}
+  }
+  .mood-talking .leave-right {
+  	animation: talk-right 0.6s ease-in-out infinite;
+  }
+  .mood-talking .leave-left {
+  	animation: talk-left 0.6s ease-in-out infinite 0.1s;
+  }
+
+  /* happy: light casual flap */
+  @keyframes happy-right {
+  	0%,
+  	100% {
+  		transform: rotate(0deg);
+  	}
+  	50% {
+  		transform: rotate(-18deg);
+  	}
+  }
+  @keyframes happy-left {
+  	0%,
+  	100% {
+  		transform: rotate(0deg);
+  	}
+  	50% {
+  		transform: rotate(13deg);
+  	}
+  }
+  .mood-happy .leave-right {
+  	animation: happy-right 1.4s ease-in-out infinite;
+  }
+  .mood-happy .leave-left {
+  	animation: happy-left 1.4s ease-in-out infinite 0.1s;
+  }
+
+  /* moving: vigorous wing flap — full range, fast */
+  @keyframes flap-right {
+  	0%,
+  	100% {
+  		transform: rotate(0deg);
+  	}
+  	40% {
+  		transform: rotate(-40deg);
+  	}
+  }
+  @keyframes flap-left {
+  	0%,
+  	100% {
+  		transform: rotate(0deg);
+  	}
+  	40% {
+  		transform: rotate(26deg);
+  	}
+  }
+  .mood-moving .leave-right {
+  	animation: flap-right 0.34s ease-in-out infinite;
+  }
+  .mood-moving .leave-left {
+  	animation: flap-left 0.34s ease-in-out infinite 0.04s;
+  }
+
+  /* ── Eye blink (on pupil so it doesn't fight cursor translate) ───── */
+  @keyframes blink {
+  	0%,
+  	93%,
+  	100% {
+  		transform: scaleY(1);
+  	}
+  	96% {
+  		transform: scaleY(0.05);
+  	}
+  }
+  .pupil {
+  	transform-box: fill-box;
+  	transform-origin: center;
+  	animation: blink 4s ease-in-out infinite;
+  }
+  .eye-left .pupil {
+  	animation-delay: 0s;
+  }
+  .eye-right .pupil {
+  	animation-delay: 0.07s;
+  }
+</style>

packages/planty/src/lib/components/SpeechBubble.svelte

@@ -0,0 +1,172 @@
+<script lang="ts">
+  import { fade } from 'svelte/transition';
+  import type { Choice } from '../types.js';
+
+  interface Props {
+    text: string;
+    avatarX: number;
+    avatarY: number;
+    choices?: Choice[];
+    showNext?: boolean;
+    stepIndex?: number;
+    totalSteps?: number;
+    onNext?: () => void;
+    onClose?: () => void;
+    onChoose?: (choice: Choice) => void;
+  }
+
+  let {
+    text,
+    avatarX,
+    avatarY,
+    choices = [],
+    showNext = false,
+    stepIndex = -1,
+    totalSteps = 0,
+    onNext,
+    onClose,
+    onChoose
+  }: Props = $props();
+
+  const showProgress = $derived(stepIndex >= 0 && totalSteps > 0);
+
+  const BUBBLE_WIDTH = 268;
+  const AVATAR_SIZE = 80;
+  const GAP = 10;
+
+  const isAvatarNearTop = $derived(avatarY < BUBBLE_WIDTH + GAP + 8);
+
+  const left = $derived(Math.max(8, Math.min(avatarX, window.innerWidth - BUBBLE_WIDTH - 8)));
+  const bottom = $derived(isAvatarNearTop ? null : `${window.innerHeight - avatarY + GAP}px`);
+  const top = $derived(isAvatarNearTop ? `${avatarY + AVATAR_SIZE + GAP}px` : null);
+
+  // Typewriter
+  let displayed = $state('');
+  const finished = $derived(displayed.length === text.length);
+  let typeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function renderMarkdown(raw: string): string {
+    return raw
+      .replaceAll(/^# (.+)$/gm, '<strong class="block text-sm font-bold mb-1">$1</strong>')
+      .replaceAll(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+      .replaceAll(/\*(.+?)\*/g, '<em>$1</em>')
+      .replaceAll(
+        /`(.+?)`/g,
+        '<code class="text-[11px] rounded px-1 font-mono" style="background: var(--color-layer-3); color: var(--color-text);">$1</code>'
+      )
+      .replaceAll(/\*/g, '')
+      .replaceAll(/_/g, '')
+      .replaceAll(/\n+/g, '<br>');
+  }
+
+  $effect(() => {
+    // Track only `text` as a dependency.
+    // Never read `displayed` inside the effect — += would add it as a dep
+    // and cause an infinite loop. Use slice(0, i) for pure writes instead.
+    const target = text;
+
+    displayed = '';
+    if (typeTimer) clearTimeout(typeTimer);
+
+    let i = 0;
+    function tick() {
+      if (i < target.length) {
+        displayed = target.slice(0, ++i);
+        typeTimer = setTimeout(tick, 26);
+      }
+    }
+    // Defer first tick so no reads happen during the synchronous effect body
+    typeTimer = setTimeout(tick, 0);
+
+    return () => {
+      if (typeTimer) clearTimeout(typeTimer);
+    };
+  });
+</script>
+
+<div
+  class="pointer-events-auto fixed z-99999 rounded-md border p-2"
+  style:width="{BUBBLE_WIDTH}px"
+  style:left="{left}px"
+  style:bottom
+  style:top
+  style:background="var(--color-layer-0)"
+  style:border-color="var(--color-outline)"
+>
+  {#if isAvatarNearTop}
+    <!-- Tail pointing up toward avatar -->
+    <div
+      class="absolute -top-2 h-3.5 w-3.5 rotate-45 border-t border-l"
+      style:left="{Math.min(
+				Math.max(avatarX - left + AVATAR_SIZE / 2 - 25, 12),
+				BUBBLE_WIDTH - 28
+			)}px"
+      style:background="var(--color-layer-0)"
+      style:border-color="var(--color-outline)"
+    >
+    </div>
+  {:else}
+    <!-- Tail pointing down toward avatar -->
+    <div
+      class="absolute -bottom-2 h-3.5 w-3.5 rotate-45 border-r border-b"
+      style:left="{Math.min(
+				Math.max(avatarX - left + AVATAR_SIZE / 2 - 25, 12),
+				BUBBLE_WIDTH - 28
+			)}px"
+      style:background="var(--color-layer-0)"
+      style:border-color="var(--color-outline)"
+    >
+    </div>
+  {/if}
+
+  <div class="mb-2 min-h-[1.4em] text-sm leading-relaxed" style="color: var(--color-text)">
+    <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+    {@html renderMarkdown(displayed)}
+  </div>
+
+  {#if choices.length > 0}
+    <div class="flex flex-col gap-1.5">
+      {#each choices as choice, i (choice.label)}
+        {#if finished}
+          <button
+            in:fade={{ duration: 200, delay: i * 250 }}
+            class="cursor-pointer rounded-lg px-3 py-1.5 text-left text-sm font-medium transition-colors"
+            style:background="var(--color-layer-1)"
+            style:border-color="var(--color-outline)"
+            style:color="var(--color-text)"
+            onclick={() => onChoose?.(choice)}
+          >
+            {choice.label}
+          </button>
+        {/if}
+      {/each}
+    </div>
+  {/if}
+
+  <div class="mt-2 flex items-center justify-between gap-2">
+    <button
+      class="cursor-pointer text-xs transition-colors"
+      style="color: var(--color-outline)"
+      onclick={onClose}
+    >
+      ✕ close
+    </button>
+    <div class="flex items-center gap-2">
+      {#if showProgress}
+        <span class="text-xs tabular-nums" style="color: var(--color-outline)">
+          {stepIndex + 1} / {totalSteps}
+        </span>
+      {/if}
+      {#if showNext && finished}
+        <button
+          class="cursor-pointer rounded-lg px-3 py-1 text-xs font-semibold transition-colors"
+          style:background="var(--color-outline)"
+          style:color="var(--color-layer-0)"
+          onclick={onNext}
+        >
+          Next →
+        </button>
+      {/if}
+    </div>
+  </div>
+</div>

packages/planty/src/lib/dialog-runner.ts

@@ -0,0 +1,52 @@
+import type { Choice, DialogNode, PlantyConfig } from './types.js';
+
+export class DialogRunner {
+  private config: PlantyConfig;
+
+  constructor(config: PlantyConfig) {
+    this.config = config;
+  }
+
+  getNode(id: string): DialogNode | null {
+    return this.config.nodes[id] ?? null;
+  }
+
+  getStartNode(): { id: string; node: DialogNode } | null {
+    const node = this.getNode(this.config.start);
+    if (!node) return null;
+    return { id: this.config.start, node };
+  }
+
+  getNextNode(currentId: string): { id: string; node: DialogNode } | null {
+    const current = this.getNode(currentId);
+    if (!current) return null;
+    if (!current.next) return null;
+    const next = this.getNode(current.next);
+    if (!next) return null;
+    return { id: current.next, node: next };
+  }
+
+  followChoice(choice: Choice): { id: string; node: DialogNode } | null {
+    if (!choice.next) return null;
+    const node = this.getNode(choice.next);
+    if (!node) return null;
+    return { id: choice.next, node };
+  }
+
+  /** Walk the main path (first choice for choice nodes) and return all node IDs. */
+  getMainPath(): string[] {
+    const path: string[] = [];
+    const visited = new Set<string>();
+    let id: string | null = this.config.start;
+    while (id && !visited.has(id)) {
+      visited.add(id);
+      path.push(id);
+      const node = this.getNode(id);
+      if (!node) break;
+      const next = node.choices?.[0]?.next ?? node.next;
+      if (next) id = next;
+      else break;
+    }
+    return path;
+  }
+}

packages/planty/src/lib/index.ts

@@ -0,0 +1,11 @@
+export { default as Planty } from './components/Planty.svelte';
+export type {
+  AvatarAnchor,
+  AvatarPosition,
+  Choice,
+  DialogNode,
+  HighlightTarget,
+  PlantyConfig,
+  PlantyHook,
+  StepCallback
+} from './types.js';

packages/planty/src/lib/planty-steps.ts

@@ -0,0 +1,66 @@
+import type { DialogNode, StepCallback } from './types.js';
+
+/**
+ * Cross-module step hook registry.
+ *
+ * Create one shared instance and import it wherever you need to react to
+ * Planty steps — no reference to the <Planty> component required.
+ *
+ * @example
+ * // tutorial-steps.ts
+ * export const steps = createPlantySteps();
+ *
+ * // graph-editor.ts
+ * steps.before('highlight_graph', () => graphEditor.setHighlight(true));
+ * steps.after ('highlight_graph', () => graphEditor.setHighlight(false));
+ *
+ * // +page.svelte
+ * <Planty {config} {steps} />
+ */
+export class PlantySteps {
+  private _before = new Map<string, StepCallback[]>();
+  private _after = new Map<string, StepCallback[]>();
+
+  /** Register a handler to run before `nodeId` becomes active. Chainable. */
+  before(nodeId: string, fn: StepCallback): this {
+    const list = this._before.get(nodeId) ?? [];
+    this._before.set(nodeId, [...list, fn]);
+    return this;
+  }
+
+  /** Register a handler to run after the user leaves `nodeId`. Chainable. */
+  after(nodeId: string, fn: StepCallback): this {
+    const list = this._after.get(nodeId) ?? [];
+    this._after.set(nodeId, [...list, fn]);
+    return this;
+  }
+
+  /** Remove all handlers for a node (or all nodes if omitted). */
+  clear(nodeId?: string) {
+    if (nodeId) {
+      this._before.delete(nodeId);
+      this._after.delete(nodeId);
+    } else {
+      this._before.clear();
+      this._after.clear();
+    }
+  }
+
+  /** @internal — called by Planty */
+  async runBefore(nodeId: string, node: DialogNode): Promise<void> {
+    for (const fn of this._before.get(nodeId) ?? []) {
+      await fn(nodeId, node);
+    }
+  }
+
+  /** @internal — called by Planty */
+  async runAfter(nodeId: string, node: DialogNode): Promise<void> {
+    for (const fn of this._after.get(nodeId) ?? []) {
+      await fn(nodeId, node);
+    }
+  }
+}
+
+export function createPlantySteps(): PlantySteps {
+  return new PlantySteps();
+}

packages/planty/src/lib/types.ts

@@ -0,0 +1,55 @@
+export type AvatarAnchor =
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'center'
+  | 'right';
+
+export type AvatarPosition = { x: number; y: number } | AvatarAnchor;
+
+export interface HighlightTarget {
+  /** CSS selector for the element to highlight */
+  selector?: string;
+  /** Name of an app-registered hook that returns Element | null */
+  hookName?: string;
+  /** Extra space around the element in px */
+  padding?: number;
+}
+
+export interface DialogNode {
+  text?: string;
+  position?: AvatarPosition;
+  highlight?: HighlightTarget;
+  /** App hook to call on entering this node */
+  action?: string;
+  next?: string | null;
+  choices?: Choice[];
+  /** Called (and awaited) just before the avatar starts moving to this node */
+  before?: StepCallback;
+  /** Called (and awaited) just before the user leaves this node */
+  after?: StepCallback;
+}
+
+export interface Choice {
+  label: string;
+  next?: string | null;
+  action?: string;
+}
+
+export interface PlantyConfig {
+  id: string;
+  avatar?: {
+    name?: string;
+    defaultPosition?: AvatarPosition;
+  };
+  start: string;
+  nodes: Record<string, DialogNode>;
+}
+
+export type PlantyHook = (
+  ...args: unknown[]
+) => void | Element | null | Promise<void> | (() => void);
+
+/** Called before/after a node becomes active. Async-safe. */
+export type StepCallback = (nodeId: string, node: DialogNode) => void | Promise<void>;

packages/planty/src/routes/+layout.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+  import '@nodarium/ui/app.css';
+  import './layout.css';
+  const { children } = $props();
+</script>
+
+{@render children()}

packages/planty/src/routes/+page.svelte

@@ -0,0 +1,147 @@
+<script lang="ts">
+  import Planty from '$lib/components/Planty.svelte';
+  import PlantyAvatar, { type Mood } from '$lib/components/PlantyAvatar.svelte';
+  import type { PlantyConfig } from '$lib/types.js';
+  import { onMount } from 'svelte';
+  import ThemeSelector from './ThemeSelector.svelte';
+
+  let plantyConfig = $state<PlantyConfig | null>(null);
+  let planty: ReturnType<typeof Planty> | undefined = $state();
+  let started = $state(false);
+
+  // Avatar preview state
+  const moods: Mood[] = ['idle', 'talking', 'happy', 'thinking', 'moving'];
+  let previewMood = $state<Mood>('idle');
+
+  onMount(async () => {
+    const res = await fetch('/demo-tutorial.json');
+    plantyConfig = await res.json();
+  });
+
+  function startTour() {
+    planty?.start();
+    started = true;
+  }
+</script>
+
+<svelte:head>
+  <title>Planty — Demo</title>
+</svelte:head>
+
+<div
+  class="grid min-h-screen grid-rows-[auto_1fr]"
+  style="background-color: var(--color-layer-0); color: var(--color-text);"
+>
+  <!-- Header -->
+  <header
+    class="flex h-12 items-center gap-4 px-8 py-5"
+    style="border-color: var(--color-outline);"
+  >
+    <h1 class="text-xl font-semibold">🌿 Planty</h1>
+    <span
+      class="rounded-full px-2 py-0.5 text-xs font-bold"
+      style="background: var(--color-layer-3); color: var(--color-layer-0);"
+    >demo</span>
+
+    <ThemeSelector />
+
+    <button
+      class="ml-auto rounded-xl px-5 py-2 text-sm font-bold transition hover:scale-95 active:scale-95"
+      style="background: var(--color-layer-3); color: var(--color-layer-0);"
+      onclick={startTour}
+      disabled={started || !plantyConfig}
+    >
+      {started ? 'Tour running…' : 'Start tutorial'}
+    </button>
+  </header>
+
+  <!-- App layout -->
+  <main class="grid grid-cols-[1fr_280px]">
+    <!-- Graph canvas -->
+    <div
+      id="graph-canvas"
+      class="relative flex min-h-125 items-center justify-center"
+      style="background-color: var(--color-layer-1); background-image: radial-gradient(circle, var(--color-outline) 1px, transparent 1px); background-size: 24px 24px;"
+    >
+      <p class="text-center text-sm" style="color: var(--color-outline);">
+        Node graph canvas<br />
+        <span style="opacity: 0.6;">(click "Start tutorial" above)</span>
+      </p>
+
+      <!-- Avatar mood preview (bottom of canvas) -->
+      <div class="absolute bottom-6 left-1/2 flex -translate-x-1/2 flex-col items-center gap-4">
+        <!-- Static preview at fixed position inside the canvas -->
+        <div class="relative h-20 w-12">
+          <PlantyAvatar x={0} y={0} mood={previewMood} />
+        </div>
+        <div class="flex gap-2">
+          {#each moods as m (m)}
+            <button
+              class="rounded-lg border px-3 py-1 text-xs transition"
+              onclick={() => (previewMood = m)}
+              style="border-color: {previewMood === m
+  ? 'var(--color-selected)'
+  : 'var(--color-outline)'}; color: {previewMood === m
+  ? 'var(--color-selected)'
+  : 'var(--color-text)'}; background: {previewMood === m
+  ? 'var(--color-layer-2)'
+  : 'transparent'};"
+            >
+              {m}
+            </button>
+          {/each}
+        </div>
+      </div>
+    </div>
+
+    <!-- Sidebar -->
+    <aside
+      id="sidebar"
+      class="flex flex-col gap-3 p-5"
+      style="border-color: var(--color-outline); background-color: var(--color-layer-0);"
+    >
+      <span
+        class="text-xs font-semibold tracking-widest uppercase"
+        style="color: var(--color-outline);"
+      >Parameters</span>
+      <div
+        class="rounded-lg px-3 py-2 text-sm"
+        style="background: var(--color-layer-1); color: var(--color-text);"
+      >
+        Branch length: 1.0
+      </div>
+      <div
+        class="rounded-lg px-3 py-2 text-sm"
+        style="background: var(--color-layer-1); color: var(--color-text);"
+      >
+        Segments: 8
+      </div>
+      <div
+        class="rounded-lg px-3 py-2 text-sm"
+        style="background: var(--color-layer-1); color: var(--color-text);"
+      >
+        Leaf density: 0.6
+      </div>
+      <span
+        class="mt-2 text-xs font-semibold tracking-widest uppercase"
+        style="color: var(--color-outline);"
+      >Export</span>
+      <div
+        class="rounded-lg px-3 py-2 text-sm"
+        style="background: var(--color-layer-1); color: var(--color-text);"
+      >
+        .obj / .glb
+      </div>
+    </aside>
+  </main>
+</div>
+
+{#if plantyConfig}
+  <Planty
+    bind:this={planty}
+    config={plantyConfig}
+    onComplete={() => {
+      started = false;
+    }}
+  />
+{/if}

packages/planty/src/routes/ThemeSelector.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  import { InputSelect } from '@nodarium/ui';
+  const themes = [
+    'dark',
+    'light',
+    'solarized',
+    'catppuccin',
+    'high-contrast',
+    'high-contrast-light',
+    'nord',
+    'dracula',
+    'custom'
+  ];
+
+  let themeIndex = $state(0);
+  $effect(() => {
+    const classList = document.documentElement.classList;
+    for (const c of classList) {
+      if (c.startsWith('theme-')) document.documentElement.classList.remove(c);
+    }
+    document.documentElement.classList.add(`theme-${themes[themeIndex]}`);
+  });
+</script>
+
+<InputSelect bind:value={themeIndex} options={themes}></InputSelect>

packages/planty/src/routes/layout.css

@@ -0,0 +1,7 @@
+@import 'tailwindcss';
+
+body {
+	color: var(--color-text);
+	background-color: var(--color-layer-0);
+	margin: 0;
+}

packages/planty/static/demo-tutorial.json

@@ -0,0 +1,87 @@
+{
+  "id": "demo-tutorial",
+  "avatar": {
+    "name": "Planty",
+    "defaultPosition": "bottom-right"
+  },
+  "start": "welcome",
+  "nodes": {
+    "welcome": {
+      "type": "choice",
+      "position": "bottom-right",
+      "text": "👋 Hey! I'm Planty — your guide to this app. How would you like me to explain things?",
+      "choices": [
+        { "label": "🤓 Technical — give me the details", "next": "intro_nerd" },
+        { "label": "🌱 Simple — keep it friendly", "next": "intro_simple" },
+        { "label": "No thanks, skip the tour", "next": null }
+      ]
+    },
+
+    "intro_nerd": {
+      "type": "step",
+      "position": "bottom-right",
+      "text": "This is a WebAssembly-powered node graph. Each node is a compiled .wasm module executed in a sandboxed runtime.",
+      "next": "highlight_graph_nerd"
+    },
+    "intro_simple": {
+      "type": "step",
+      "position": "bottom-right",
+      "text": "Think of this like a recipe card — each block does one thing, and you connect them to build a plant!",
+      "next": "highlight_graph_simple"
+    },
+
+    "highlight_graph_nerd": {
+      "type": "step",
+      "position": "bottom-left",
+      "highlight": { "selector": "#graph-canvas", "padding": 12 },
+      "text": "The graph canvas renders edges as Bézier curves. Node execution is topologically sorted before each WASM call.",
+      "next": "highlight_sidebar_nerd"
+    },
+    "highlight_graph_simple": {
+      "type": "step",
+      "position": "bottom-left",
+      "highlight": { "selector": "#graph-canvas", "padding": 12 },
+      "text": "This is the main canvas — drag nodes around and connect them to create your plant!",
+      "next": "highlight_sidebar_simple"
+    },
+
+    "highlight_sidebar_nerd": {
+      "type": "step",
+      "position": "bottom-right",
+      "highlight": { "selector": "#sidebar", "padding": 8 },
+      "text": "The sidebar exposes node parameters, export settings, and the raw graph JSON for debugging.",
+      "next": "tip_nerd"
+    },
+    "highlight_sidebar_simple": {
+      "type": "step",
+      "position": "bottom-right",
+      "highlight": { "selector": "#sidebar", "padding": 8 },
+      "text": "The sidebar lets you tweak settings and export your creation.",
+      "next": "tip_simple"
+    },
+
+    "tip_nerd": {
+      "type": "step",
+      "position": "center",
+      "text": "Press Space or double-click the canvas to open node search. Nodes are fetched from the WASM registry at runtime.",
+      "next": "done_nerd"
+    },
+    "tip_simple": {
+      "type": "step",
+      "position": "center",
+      "text": "Press Space anywhere on the canvas to add a new block — try it!",
+      "next": "done_simple"
+    },
+
+    "done_nerd": {
+      "type": "end",
+      "position": "bottom-right",
+      "text": "You're all set. Check the docs for the full NodeDefinition interface. Happy hacking! 🌿"
+    },
+    "done_simple": {
+      "type": "end",
+      "position": "bottom-right",
+      "text": "That's the tour! Have fun building your plant. 🌱"
+    }
+  }
+}

packages/planty/static/favicon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="107" height="128" viewBox="0 0 107 128">
+  <title>svelte-logo</title><path
+    d="M94.157 22.819c-10.4-14.885-30.94-19.297-45.792-9.835L22.282 29.608A29.92 29.92 0 0 0 8.764 49.65a31.5 31.5 0 0 0 3.108 20.231 30 30 0 0 0-4.477 11.183 31.9 31.9 0 0 0 5.448 24.116c10.402 14.887 30.942 19.297 45.791 9.835l26.083-16.624A29.92 29.92 0 0 0 98.235 78.35a31.53 31.53 0 0 0-3.105-20.232 30 30 0 0 0 4.474-11.182 31.88 31.88 0 0 0-5.447-24.116"
+    style="fill:#ff3e00"
+  /><path
+    d="M45.817 106.582a20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.503 18 18 0 0 1 .624-2.435l.49-1.498 1.337.981a33.6 33.6 0 0 0 10.203 5.098l.97.294-.09.968a5.85 5.85 0 0 0 1.052 3.878 6.24 6.24 0 0 0 6.695 2.485 5.8 5.8 0 0 0 1.603-.704L69.27 76.28a5.43 5.43 0 0 0 2.45-3.631 5.8 5.8 0 0 0-.987-4.371 6.24 6.24 0 0 0-6.698-2.487 5.7 5.7 0 0 0-1.6.704l-9.953 6.345a19 19 0 0 1-5.296 2.326 20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.502 17.99 17.99 0 0 1 8.13-12.052l26.081-16.623a19 19 0 0 1 5.3-2.329 20.72 20.72 0 0 1 22.237 8.243 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-.624 2.435l-.49 1.498-1.337-.98a33.6 33.6 0 0 0-10.203-5.1l-.97-.294.09-.968a5.86 5.86 0 0 0-1.052-3.878 6.24 6.24 0 0 0-6.696-2.485 5.8 5.8 0 0 0-1.602.704L37.73 51.72a5.42 5.42 0 0 0-2.449 3.63 5.79 5.79 0 0 0 .986 4.372 6.24 6.24 0 0 0 6.698 2.486 5.8 5.8 0 0 0 1.602-.704l9.952-6.342a19 19 0 0 1 5.295-2.328 20.72 20.72 0 0 1 22.237 8.242 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-8.13 12.053l-26.081 16.622a19 19 0 0 1-5.3 2.328"
+    style="fill:#fff"
+  />
+</svg>

packages/planty/svelte.config.js

@@ -0,0 +1,17 @@
+import adapter from '@sveltejs/adapter-auto';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  compilerOptions: {
+    // Force runes mode for the project, except for libraries. Can be removed in svelte 6.
+    runes: ({ filename }) => (filename.split(/[/\\]/).includes('node_modules') ? undefined : true)
+  },
+  kit: {
+    // adapter-auto only supports some environments, see https://svelte.dev/docs/kit/adapter-auto for a list.
+    // If your environment is not supported, or you settled on a specific environment, switch out the adapter.
+    // See https://svelte.dev/docs/kit/adapters for more information about adapters.
+    adapter: adapter()
+  }
+};
+
+export default config;

packages/planty/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./.svelte-kit/tsconfig.json",
+  "compilerOptions": {
+    "rewriteRelativeImportExtensions": true,
+    "allowJs": true,
+    "checkJs": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "module": "NodeNext",
+    "moduleResolution": "bundler"
+  }
+}

packages/planty/vite.config.ts

@@ -0,0 +1,5 @@
+import { sveltekit } from '@sveltejs/kit/vite';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [tailwindcss(), sveltekit()] });

packages/types/package.json

@@ -2,6 +2,7 @@
   "name": "@nodarium/types",
   "version": "0.0.5",
   "description": "",
+  "type": "module",
   "main": "src/index.ts",
   "scripts": {
     "format": "dprint fmt -c '../../.dprint.jsonc' .",

packages/types/src/index.ts

@@ -4,7 +4,9 @@ export type {
   Box,
   Edge,
   Graph,
+  GroupSocket,
   NodeDefinition,
+  NodeGroupDefinition,
   NodeId,
   NodeInstance,
   SerializedNode,

packages/types/src/inputs.ts

@@ -9,7 +9,6 @@ const DefaultOptionsSchema = z.object({
   accepts: z
     .array(
       z.union([
-        z.literal('*'),
         z.literal('float'),
         z.literal('integer'),
         z.literal('boolean'),

packages/types/src/types.ts

@@ -21,7 +21,7 @@ export type NodeRuntimeState = {
   parents?: NodeInstance[];
   children?: NodeInstance[];
   inputNodes?: Record<string, NodeInstance>;
-  type?: NodeDefinition; // we should probably remove this and rely on registry.getNode(nodeType)
+  type?: NodeDefinition;
   downX?: number;
   downY?: number;
   x?: number;
@@ -51,7 +51,7 @@ export const NodeSchema = z.object({
   id: z.number(),
   type: NodeIdSchema,
   props: z
-    .record(z.string(), z.union([z.number(), z.array(z.number())]))
+    .record(z.string(), z.union([z.number(), z.array(z.number()), z.string()]))
     .optional(),
   meta: z
     .object({
@@ -65,7 +65,7 @@ export const NodeSchema = z.object({
 export type SerializedNode = z.infer<typeof NodeSchema>;
 
 export type NodeDefinition = z.infer<typeof NodeDefinitionSchema> & {
-  execute(outputPos: number, args: number[]): number;
+  execute(input: Int32Array): Int32Array;
 };
 
 export type Socket = {
@@ -76,6 +76,33 @@ export type Socket = {
 
 export type Edge = [NodeInstance, number, NodeInstance, string];
 
+export type GroupSocket = {
+  name: string;
+  type: string;
+};
+
+export type NodeGroupDefinition = {
+  id: string;
+  name: string;
+  inputs: GroupSocket[];
+  outputs: GroupSocket[];
+  graph: {
+    nodes: SerializedNode[];
+    edges: [number, number, number, string][];
+  };
+};
+
+const NodeGroupDefinitionSchema: z.ZodType<NodeGroupDefinition> = z.object({
+  id: z.string(),
+  name: z.string(),
+  inputs: z.array(z.object({ name: z.string(), type: z.string() })),
+  outputs: z.array(z.object({ name: z.string(), type: z.string() })),
+  graph: z.object({
+    nodes: z.array(NodeSchema),
+    edges: z.array(z.tuple([z.number(), z.number(), z.number(), z.string()]))
+  })
+});
+
 export const GraphSchema = z.object({
   id: z.number(),
   meta: z
@@ -86,7 +113,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.record(z.string(), NodeGroupDefinitionSchema).optional()
 });
 
 export type Graph = z.infer<typeof GraphSchema>;