archetype-ecs 1.4.2 → 1.5.0

package/README.md

@@ -51,7 +51,7 @@ em.forEach([Position, Velocity], (arch) => {
 ### Why archetype-ecs?
 
 <table>
-<tr><td><strong>Fast iteration</strong></td><td>1.7 ms/frame over 1M entities. Faster than bitecs, wolf-ecs, harmony-ecs — see <a href="#benchmarks">benchmarks</a>.</td></tr>
+<tr><td><strong>Fast iteration</strong></td><td>0.5 ms/frame over 1M entities with auto-detected <a href="#wasm-simd">WASM SIMD</a>. Faster than bitecs, wolf-ecs, harmony-ecs — see <a href="#benchmarks">benchmarks</a>.</td></tr>
 <tr><td><strong>Low memory</strong></td><td>86 MB for 1M entities. Sparse-array ECS libraries use up to 2.4x more.</td></tr>
 <tr><td><strong>No allocations</strong></td><td><code>get</code>, <code>set</code>, and <code>forEach</code> don't allocate.</td></tr>
 <tr><td><strong>Typed</strong></td><td>TypeScript generics throughout. Field names autocomplete, wrong fields don't compile.</td></tr>
@@ -228,8 +228,8 @@ A functional API is also available:
 import { createSystem } from 'archetype-ecs'
 
 const deathSystem = createSystem(em, (sys) => {
-  sys.onAdded(Health, (id: EntityId) => console.log(`${id} spawned`))
-  sys.onRemoved(Health, (id: EntityId) => console.log(`${id} died`))
+  sys.onAdded(Health, (id) => console.log(`${id} spawned`))
+  sys.onRemoved(Health, (id) => console.log(`${id} died`))
 })
 
 em.flushHooks()
@@ -254,6 +254,47 @@ em.deserialize(JSON.parse(json), { Position, Velocity, Health })
 
 Supports stripping components, skipping entities, and custom serializers.
 
+### WASM SIMD
+
+When WebAssembly SIMD is available (all modern browsers and Node.js 16+), archetype-ecs automatically allocates numeric TypedArrays on a shared `WebAssembly.Memory`. This enables SIMD-accelerated batch operations like `fieldAdd()` — no manual WASM code needed.
+
+```ts
+em.forEach([Position, Velocity], (arch) => {
+  arch.fieldAdd(Position.x, Velocity.vx)  // px[i] += vx[i], SIMD-accelerated
+  arch.fieldAdd(Position.y, Velocity.vy)  // py[i] += vy[i], SIMD-accelerated
+})
+```
+
+`fieldAdd(target, source)` dispatches to a `f32x4.add` SIMD kernel (4 floats per instruction) when available, and falls back to a scalar JS loop otherwise. Your system code stays identical either way — no feature detection needed.
+
+To disable WASM mode (e.g. for testing or environments without WebAssembly):
+
+```ts
+const em = createEntityManager({ wasm: false })
+```
+
+For advanced use cases, you can write your own WASM modules and use `fieldOffset()` + `em.wasmMemory` to operate directly on the raw memory:
+
+```ts
+import { instantiateKernels } from 'archetype-ecs'
+
+const kernels = await instantiateKernels(em.wasmMemory!)
+
+em.forEach([Position, Velocity], (arch) => {
+  kernels.iterate_simd(
+    arch.fieldOffset(Position.x), arch.fieldOffset(Position.y),
+    arch.fieldOffset(Velocity.vx), arch.fieldOffset(Velocity.vy),
+    arch.count,
+  )
+})
+```
+
+**Details:**
+- The arena reserves 128 MB virtual address space (lazily committed — no physical RAM cost on most OSes)
+- String fields always fall back to regular JS arrays
+- `fieldAdd` uses SIMD for `Float32Array` fields; other types fall back to scalar
+- The bump allocator doesn't reclaim memory — frequent archetype churn may waste space
+
 ---
 
 ## TypeScript
@@ -261,7 +302,7 @@ Supports stripping components, skipping entities, and custom serializers.
 Component types are inferred from their definition. Field names autocomplete, wrong fields are compile errors.
 
 ```ts
-// Fields are typed as FieldRef — Position becomes ComponentDef & { x: FieldRef; y: FieldRef }
+// Schema is inferred — Position becomes ComponentDef<'x' | 'y'>
 const Position = component('Position', 'f32', ['x', 'y'])
 
 Position.x                // FieldRef — autocompletes to .x and .y
@@ -298,9 +339,9 @@ Schema component with mixed field types.
 const Item = component('Item', { name: 'string', weight: 'f32', armor: 'u8' })
 ```
 
-### `createEntityManager()`
+### `createEntityManager(options?)`
 
-Returns an entity manager with the following methods:
+Returns an entity manager. WASM SIMD is auto-detected and enabled by default. Pass `{ wasm: false }` to force JS-only mode.
 
 | Method | Description |
 |---|---|
@@ -321,6 +362,21 @@ Returns an entity manager with the following methods:
 | `flushHooks()` | Collect pending add/remove events for registered hooks |
 | `serialize(symbolToName, strip?, skip?, opts?)` | Serialize world to JSON-friendly object |
 | `deserialize(data, nameToSymbol, opts?)` | Restore world from serialized data |
+| `wasmMemory` | `WebAssembly.Memory \| null` — the underlying memory (WASM mode only) |
+
+The `forEach` callback receives an `ArchetypeView` with:
+
+| Method | Description |
+|---|---|
+| `field(ref)` | Get the backing TypedArray for a field |
+| `fieldStride(ref)` | Elements per entity (1 for scalars, N for arrays) |
+| `fieldOffset(ref)` | Byte offset in `wasmMemory` (-1 if not in WASM mode) |
+| `fieldAdd(target, source)` | `target[i] += source[i]` — uses SIMD in WASM mode, scalar loop otherwise |
+| `snapshot(ref)` | Get the snapshot TypedArray (change tracking) |
+
+### `instantiateKernels(memory)`
+
+Loads the built-in WASM SIMD module onto the given `WebAssembly.Memory`. Returns `{ iterate_scalar, iterate_simd }` — both take `(pxOffset, pyOffset, vxOffset, vyOffset, count)` as byte offsets.
 
 ### `System`
 
@@ -349,16 +405,16 @@ Creates a pipeline from an array of class-based (`System` subclasses) and/or fun
 
 1M entities, Position += Velocity, 5 runs (median), Node.js:
 
-| | archetype-ecs | [bitecs](https://github.com/NateTheGreatt/bitECS) | [wolf-ecs](https://github.com/EnderShadow8/wolf-ecs) | [harmony-ecs](https://github.com/3mcd/harmony-ecs) | [miniplex](https://github.com/hmans/miniplex) |
-|---|---:|---:|---:|---:|---:|
-| **Iteration** (ms/frame) | **1.7** | 2.2 | 2.2 | 1.8 | 32.5 |
-| **Entity creation** (ms) | 401 | 366 | **106** | 248 | 265 |
-| **Memory** (MB) | 86 | 204 | 60 | **31** | 166 |
+| | archetype-ecs | archetype-ecs (WASM SIMD) | [bitecs](https://github.com/NateTheGreatt/bitECS) | [wolf-ecs](https://github.com/EnderShadow8/wolf-ecs) | [harmony-ecs](https://github.com/3mcd/harmony-ecs) | [miniplex](https://github.com/hmans/miniplex) |
+|---|---:|---:|---:|---:|---:|---:|
+| **Iteration** (ms/frame) | 1.5 | **0.5** | 2.2 | 2.2 | 1.8 | 32.5 |
+| **Entity creation** (ms) | 401 | 401 | 366 | **106** | 248 | 265 |
+| **Memory** (MB) | 86 | 86+128 | 204 | 60 | **31** | 166 |
 
 Each library runs the same test — iterate 1M entities over 500 frames:
 
 ```ts
-// archetype-ecs
+// archetype-ecs (default) — manual loop
 em.forEach([Position, Velocity], (arch) => {
   const px = arch.field(Position.x)   // Float32Array, dense
   const py = arch.field(Position.y)
@@ -369,14 +425,22 @@ em.forEach([Position, Velocity], (arch) => {
     py[i] += vy[i]
   }
 })
+
+// archetype-ecs (WASM SIMD) — same code, 2.5x faster
+const em = createEntityManager({ wasm: true })
+em.forEach([Position, Velocity], (arch) => {
+  arch.fieldAdd(Position.x, Velocity.vx)
+  arch.fieldAdd(Position.y, Velocity.vy)
+})
 ```
 
-archetype-ecs is fastest at iteration. Harmony-ecs and wolf-ecs are close; miniplex is ~20x slower due to object-based storage.
+The WASM SIMD kernel processes 4 floats per instruction (`f32x4.add`) and avoids V8's `f32→f64→f32` conversion overhead.
 
 Run them yourself:
 
 ```bash
-npm run bench
+npm run bench                                            # vs other ECS libraries
+node --expose-gc bench/wasm-iteration-bench.js           # WASM SIMD benchmark
 ```
 
 ---
@@ -389,6 +453,7 @@ Compared against other JS ECS libraries:
 
 | Feature | archetype-ecs | bitecs | wolf-ecs | harmony-ecs | miniplex |
 |---|:---:|:---:|:---:|:---:|:---:|
+| WASM SIMD iteration (opt-in) | ✓ | — | — | — | — |
 | String SoA storage | ✓ | — | — | — | — |
 | Mixed string + numeric components | ✓ | — | — | — | — |
 | `forEach` with dense TypedArray field access | ✓ | — | — | — | — |

package/bench/allocations-1m.js

@@ -4,7 +4,7 @@
 import {
   createWorld, addEntity, addComponent, removeEntity, query
 } from 'bitecs';
-import { createEntityManager, component } from '../dist/src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const RUNS = 5;

package/bench/component-churn-bench.js

@@ -0,0 +1,193 @@
+// Component Churn Benchmark: 1M entities, component add/remove over 500 frames
+// Vergelijkt runtime van code gecompileerd met tsc (JS) vs tsgo (Go)
+// Run met: node --expose-gc bench/component-churn-bench.js
+// Of via: bash bench/run-js-vs-go-ts.sh
+
+import { createEntityManager, component } from '../dist/index.js';
+
+const COUNT = 1_000_000;
+const FRAMES = 500;
+const CHURN_BATCH = 1_000;
+const RUNS = 5;
+
+// ── Utilities ────────────────────────────────────────────────────────────────
+
+const median = (arr) => {
+  const s = [...arr].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length & 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+};
+
+const memMB = () => {
+  if (globalThis.gc) globalThis.gc();
+  return process.memoryUsage().heapUsed / 1024 / 1024;
+};
+
+// ── Components ───────────────────────────────────────────────────────────────
+
+const Position = component('ChurnPos', { x: 'f32', y: 'f32' });
+const Velocity = component('ChurnVel', { vx: 'f32', vy: 'f32' });
+const Active   = component('ChurnActive', { frame: 'i32' });
+
+// ── Benchmark: iteration only (baseline) ─────────────────────────────────────
+
+function benchIterationOnly() {
+  const em = createEntityManager();
+  for (let i = 0; i < COUNT; i++) {
+    em.createEntityWith(
+      Position, { x: i * 0.1, y: i * 0.1 },
+      Velocity, { vx: 1, vy: 1 },
+    );
+  }
+
+  // Warmup
+  for (let f = 0; f < 10; f++) {
+    em.forEach([Position, Velocity], (arch) => {
+      const px = arch.field(Position.x);
+      const py = arch.field(Position.y);
+      const vx = arch.field(Velocity.vx);
+      const vy = arch.field(Velocity.vy);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i];
+        py[i] += vy[i];
+      }
+    });
+  }
+
+  const t0 = performance.now();
+  for (let f = 0; f < FRAMES; f++) {
+    em.forEach([Position, Velocity], (arch) => {
+      const px = arch.field(Position.x);
+      const py = arch.field(Position.y);
+      const vx = arch.field(Velocity.vx);
+      const vy = arch.field(Velocity.vy);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i];
+        py[i] += vy[i];
+      }
+    });
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+// ── Benchmark: iteration + component churn ───────────────────────────────────
+
+function benchComponentChurn() {
+  const em = createEntityManager();
+
+  const entityIds = new Array(COUNT);
+  for (let i = 0; i < COUNT; i++) {
+    entityIds[i] = em.createEntityWith(
+      Position, { x: i * 0.1, y: i * 0.1 },
+      Velocity, { vx: 1, vy: 1 },
+    );
+  }
+
+  let activeIds = [];
+
+  // Warmup
+  for (let f = 0; f < 10; f++) {
+    em.forEach([Position, Velocity], (arch) => {
+      const px = arch.field(Position.x);
+      const py = arch.field(Position.y);
+      const vx = arch.field(Velocity.vx);
+      const vy = arch.field(Velocity.vy);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i];
+        py[i] += vy[i];
+      }
+    });
+  }
+
+  const t0 = performance.now();
+  for (let f = 0; f < FRAMES; f++) {
+    // 1. Movement system: iterate all entities with Position + Velocity
+    em.forEach([Position, Velocity], (arch) => {
+      const px = arch.field(Position.x);
+      const py = arch.field(Position.y);
+      const vx = arch.field(Velocity.vx);
+      const vy = arch.field(Velocity.vy);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i];
+        py[i] += vy[i];
+      }
+    });
+
+    // 2. Remove Active from previous batch (archetype migration)
+    for (const id of activeIds) {
+      em.removeComponent(id, Active);
+    }
+
+    // 3. Add Active to new batch (archetype migration, rotating through entities)
+    activeIds = [];
+    const base = (f * CHURN_BATCH) % (COUNT - CHURN_BATCH);
+    for (let i = 0; i < CHURN_BATCH; i++) {
+      const id = entityIds[base + i];
+      em.addComponent(id, Active, { frame: f });
+      activeIds.push(id);
+    }
+
+    // 4. Process Active entities (small set, tests multi-archetype iteration)
+    em.forEach([Position, Active], (arch) => {
+      const px = arch.field(Position.x);
+      const frame = arch.field(Active.frame);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += frame[i] * 0.001;
+      }
+    });
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+function main() {
+  const compiler = process.env.TS_COMPILER || 'unknown';
+
+  console.log(`=== Component Churn Benchmark ===`);
+  console.log(`    ${(COUNT / 1e6).toFixed(0)}M entities | ${FRAMES} frames | ${CHURN_BATCH} churn/frame | ${RUNS} runs`);
+  console.log(`    Compiler: ${compiler}`);
+  console.log();
+
+  const memBefore = memMB();
+
+  // ── Baseline: iteration only ──────────────────────────────────────────────
+  console.log('  [1/2] Iteration only (baseline)');
+  const iterResults = [];
+  for (let r = 0; r < RUNS; r++) {
+    process.stdout.write(`        Run ${r + 1}/${RUNS}...`);
+    const ms = benchIterationOnly();
+    iterResults.push(ms);
+    console.log(` ${ms.toFixed(2)} ms/frame`);
+  }
+  const iterMedian = median(iterResults);
+
+  // ── Component churn ───────────────────────────────────────────────────────
+  console.log('  [2/2] Iteration + component churn');
+  const churnResults = [];
+  for (let r = 0; r < RUNS; r++) {
+    process.stdout.write(`        Run ${r + 1}/${RUNS}...`);
+    const ms = benchComponentChurn();
+    churnResults.push(ms);
+    console.log(` ${ms.toFixed(2)} ms/frame`);
+  }
+  const churnMedian = median(churnResults);
+
+  const memAfter = memMB();
+  const churnOverhead = ((churnMedian / iterMedian - 1) * 100).toFixed(1);
+
+  // ── Resultaten ────────────────────────────────────────────────────────────
+  console.log();
+  console.log(`  Resultaten (${compiler}):`);
+  console.log(`    Iteratie baseline:  ${iterMedian.toFixed(2)} ms/frame`);
+  console.log(`    Met component churn: ${churnMedian.toFixed(2)} ms/frame`);
+  console.log(`    Churn overhead:     +${churnOverhead}%`);
+  console.log(`    Geheugen (heap):    ~${(memAfter - memBefore).toFixed(0)} MB`);
+  console.log();
+
+  // Machine-readable output voor runner script
+  console.log(`__ITER__=${iterMedian.toFixed(4)}`);
+  console.log(`__CHURN__=${churnMedian.toFixed(4)}`);
+}
+
+main();

package/bench/iterate.wat

@@ -0,0 +1,95 @@
+(module
+  (memory (import "env" "memory") 1)
+
+  ;; Scalar loop: px[i] += vx[i]; py[i] += vy[i]
+  ;; params: byte offsets for px, py, vx, vy arrays + element count
+  (func (export "iterate_scalar")
+    (param $px i32) (param $py i32) (param $vx i32) (param $vy i32) (param $count i32)
+    (local $i i32)
+    (local $off i32)
+    (local.set $i (i32.const 0))
+    (block $break
+      (loop $loop
+        (br_if $break (i32.ge_u (local.get $i) (local.get $count)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        ;; px[i] += vx[i]
+        (f32.store
+          (i32.add (local.get $px) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $px) (local.get $off)))
+            (f32.load (i32.add (local.get $vx) (local.get $off)))
+          )
+        )
+        ;; py[i] += vy[i]
+        (f32.store
+          (i32.add (local.get $py) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $py) (local.get $off)))
+            (f32.load (i32.add (local.get $vy) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 1)))
+        (br $loop)
+      )
+    )
+  )
+
+  ;; SIMD loop: processes 4 floats at a time using v128 / f32x4
+  (func (export "iterate_simd")
+    (param $px i32) (param $py i32) (param $vx i32) (param $vy i32) (param $count i32)
+    (local $i i32)
+    (local $off i32)
+    (local $end4 i32)
+    ;; end4 = count & ~3 (round down to multiple of 4)
+    (local.set $end4 (i32.and (local.get $count) (i32.const -4)))
+    ;; SIMD loop: 4 elements per iteration
+    (local.set $i (i32.const 0))
+    (block $break
+      (loop $loop
+        (br_if $break (i32.ge_u (local.get $i) (local.get $end4)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        ;; px[i..i+4] += vx[i..i+4]
+        (v128.store
+          (i32.add (local.get $px) (local.get $off))
+          (f32x4.add
+            (v128.load (i32.add (local.get $px) (local.get $off)))
+            (v128.load (i32.add (local.get $vx) (local.get $off)))
+          )
+        )
+        ;; py[i..i+4] += vy[i..i+4]
+        (v128.store
+          (i32.add (local.get $py) (local.get $off))
+          (f32x4.add
+            (v128.load (i32.add (local.get $py) (local.get $off)))
+            (v128.load (i32.add (local.get $vy) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 4)))
+        (br $loop)
+      )
+    )
+    ;; Scalar remainder
+    (block $break2
+      (loop $loop2
+        (br_if $break2 (i32.ge_u (local.get $i) (local.get $count)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        (f32.store
+          (i32.add (local.get $px) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $px) (local.get $off)))
+            (f32.load (i32.add (local.get $vx) (local.get $off)))
+          )
+        )
+        (f32.store
+          (i32.add (local.get $py) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $py) (local.get $off)))
+            (f32.load (i32.add (local.get $vy) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 1)))
+        (br $loop2)
+      )
+    )
+  )
+)

package/bench/multi-ecs-bench.js

@@ -2,7 +2,7 @@
 // Tests: iteration (Position += Velocity), entity creation, memory usage
 // Run with: node --expose-gc bench/multi-ecs-bench.js
 
-import { createEntityManager, component } from '../dist/src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const FRAMES = 500;

package/bench/run-js-vs-go-ts.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# ── JS TypeScript (tsc) vs Go TypeScript (tsgo) Benchmark Runner ──────────────
+# Compileert archetype-ecs met beide compilers en vergelijkt de runtime.
+#
+# Gebruik:  bash bench/run-js-vs-go-ts.sh
+# Vereist:  npm install @typescript/native-preview
+# ──────────────────────────────────────────────────────────────────────────────
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+BENCH="bench/component-churn-bench.js"
+NODE_FLAGS="--expose-gc"
+
+# Kleuren
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+echo -e "${BOLD}=== archetype-ecs: tsc vs tsgo ===${NC}"
+echo ""
+
+# ── Check of tsgo beschikbaar is ─────────────────────────────────────────────
+
+if ! npx tsgo --version &>/dev/null; then
+  echo -e "${RED}tsgo niet gevonden. Installeer met:${NC}"
+  echo "  npm install -D @typescript/native-preview"
+  exit 1
+fi
+
+TSC_VERSION=$(npx tsc --version 2>/dev/null || echo "unknown")
+TSGO_VERSION=$(npx tsgo --version 2>/dev/null || echo "unknown")
+echo -e "  tsc:  ${CYAN}${TSC_VERSION}${NC}"
+echo -e "  tsgo: ${CYAN}${TSGO_VERSION}${NC}"
+echo ""
+
+# ── Backup bestaande dist ───────────────────────────────────────────────────
+
+DIST_BACKUP=""
+if [ -d dist ]; then
+  DIST_BACKUP=$(mktemp -d)
+  cp -r dist/* "$DIST_BACKUP/" 2>/dev/null || true
+fi
+
+cleanup() {
+  # Herstel originele dist
+  if [ -n "$DIST_BACKUP" ] && [ -d "$DIST_BACKUP" ]; then
+    rm -rf dist
+    mkdir -p dist
+    cp -r "$DIST_BACKUP"/* dist/ 2>/dev/null || true
+    rm -rf "$DIST_BACKUP"
+  fi
+}
+trap cleanup EXIT
+
+# ── 1. Compileer en benchmark met tsc (JS TypeScript) ───────────────────────
+
+echo -e "${BOLD}--- [1/2] tsc (JS TypeScript) ---${NC}"
+rm -rf dist
+
+TSC_START=$(date +%s%N)
+npx tsc
+TSC_END=$(date +%s%N)
+TSC_COMPILE=$(( (TSC_END - TSC_START) / 1000000 ))
+echo -e "  Compile time: ${GREEN}${TSC_COMPILE}ms${NC}"
+echo ""
+
+TSC_OUTPUT=$(TS_COMPILER="tsc (JS)" node $NODE_FLAGS "$BENCH")
+echo "$TSC_OUTPUT"
+
+TSC_ITER=$(echo "$TSC_OUTPUT" | grep '__ITER__=' | cut -d= -f2)
+TSC_CHURN=$(echo "$TSC_OUTPUT" | grep '__CHURN__=' | cut -d= -f2)
+
+echo ""
+
+# ── 2. Compileer en benchmark met tsgo (Go TypeScript) ──────────────────────
+
+echo -e "${BOLD}--- [2/2] tsgo (Go TypeScript) ---${NC}"
+rm -rf dist
+
+TSGO_START=$(date +%s%N)
+npx tsgo
+TSGO_END=$(date +%s%N)
+TSGO_COMPILE=$(( (TSGO_END - TSGO_START) / 1000000 ))
+echo -e "  Compile time: ${GREEN}${TSGO_COMPILE}ms${NC}"
+echo ""
+
+TSGO_OUTPUT=$(TS_COMPILER="tsgo (Go)" node $NODE_FLAGS "$BENCH")
+echo "$TSGO_OUTPUT"
+
+TSGO_ITER=$(echo "$TSGO_OUTPUT" | grep '__ITER__=' | cut -d= -f2)
+TSGO_CHURN=$(echo "$TSGO_OUTPUT" | grep '__CHURN__=' | cut -d= -f2)
+
+echo ""
+
+# ── Samenvatting ─────────────────────────────────────────────────────────────
+
+echo -e "${BOLD}=== Samenvatting ===${NC}"
+echo ""
+
+# Compile time vergelijking
+if [ "$TSGO_COMPILE" -gt 0 ]; then
+  COMPILE_RATIO=$(echo "scale=1; $TSC_COMPILE / $TSGO_COMPILE" | bc 2>/dev/null || echo "?")
+else
+  COMPILE_RATIO="?"
+fi
+
+echo "  Compile time:"
+echo "    tsc  (JS): ${TSC_COMPILE}ms"
+echo "    tsgo (Go): ${TSGO_COMPILE}ms"
+echo -e "    ${GREEN}tsgo is ${COMPILE_RATIO}x sneller${NC}"
+echo ""
+
+# Runtime vergelijking
+echo "  Runtime — iteratie baseline (ms/frame):"
+echo "    tsc  (JS): ${TSC_ITER}"
+echo "    tsgo (Go): ${TSGO_ITER}"
+if [ -n "$TSC_ITER" ] && [ -n "$TSGO_ITER" ]; then
+  ITER_RATIO=$(echo "scale=2; $TSC_ITER / $TSGO_ITER" | bc 2>/dev/null || echo "?")
+  if (( $(echo "$ITER_RATIO > 1.05" | bc -l 2>/dev/null || echo 0) )); then
+    echo -e "    ${GREEN}tsgo is ${ITER_RATIO}x sneller${NC}"
+  elif (( $(echo "$ITER_RATIO < 0.95" | bc -l 2>/dev/null || echo 0) )); then
+    INV=$(echo "scale=2; 1 / $ITER_RATIO" | bc 2>/dev/null || echo "?")
+    echo -e "    ${RED}tsc is ${INV}x sneller${NC}"
+  else
+    echo "    ~gelijk"
+  fi
+fi
+echo ""
+
+echo "  Runtime — component churn (ms/frame):"
+echo "    tsc  (JS): ${TSC_CHURN}"
+echo "    tsgo (Go): ${TSGO_CHURN}"
+if [ -n "$TSC_CHURN" ] && [ -n "$TSGO_CHURN" ]; then
+  CHURN_RATIO=$(echo "scale=2; $TSC_CHURN / $TSGO_CHURN" | bc 2>/dev/null || echo "?")
+  if (( $(echo "$CHURN_RATIO > 1.05" | bc -l 2>/dev/null || echo 0) )); then
+    echo -e "    ${GREEN}tsgo is ${CHURN_RATIO}x sneller${NC}"
+  elif (( $(echo "$CHURN_RATIO < 0.95" | bc -l 2>/dev/null || echo 0) )); then
+    INV=$(echo "scale=2; 1 / $CHURN_RATIO" | bc 2>/dev/null || echo "?")
+    echo -e "    ${RED}tsc is ${INV}x sneller${NC}"
+  else
+    echo "    ~gelijk"
+  fi
+fi
+echo ""

package/bench/typed-vs-bitecs-1m.js

@@ -3,7 +3,7 @@
 import {
   createWorld, addEntity, addComponent, query
 } from 'bitecs';
-import { createEntityManager, component } from '../dist/src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const FRAMES = 500;

package/bench/typed-vs-untyped.js

@@ -1,6 +1,6 @@
 // Benchmark: forEach+field (bulk TypedArray) vs query+get/set (per-entity) vs query+getComponent (allocating)
 
-import { createEntityManager, component } from '../dist/src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const FRAMES = 200;

package/bench/vs-bitecs.js

@@ -1,7 +1,7 @@
 // Benchmark: archetype-ecs vs bitECS
 // Tests: system loop, entity creation, component add/remove churn
 
-import { createEntityManager, component } from '../dist/src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 import {
   createWorld, addEntity,
   addComponent, removeComponent,