@aardworx/wombat.rendering 0.8.1 → 0.9.1

package/src/runtime/textureAtlas/packer.ts

@@ -0,0 +1,429 @@
+// TexturePacking — incremental immutable MaxRects-style 2D rectangle
+// packer over `BvhTree2d`.
+//
+// Port of `Aardvark.Geometry.TexturePacking<'a>` from
+// `aardvark.base/src/Aardvark.Geometry/TexturePacking.fs`. Algorithm:
+//   - Atlas is described by a set of free MaxRects (contained in a
+//     `BvhTree2d` keyed on the rect itself for O(log N) queries).
+//   - tryAdd picks the free rect with the smallest waste that fits the
+//     incoming size (with optional 90° rotation), splits the chosen
+//     rect into the placed sub-rect plus residual MaxRects.
+//   - Remove restores a sub-rect and merges with adjacent free rects
+//     using the F# `merge` routine, which incrementally maintains
+//     non-overlapping MaxRects covering the released region + neighbours.
+//
+// The wombat port keys the BVH on `Box2i` value-objects. We use a
+// stable string key (`"minX,minY,maxX,maxY"`) so identical rectangles
+// share a Map slot — Box2i instances themselves are reference types in
+// JS and would not collide otherwise.
+
+import { Box2d, Box2i, V2d, V2i } from "@aardworx/wombat.base";
+import { BvhTree2d } from "./bvhTree2d.js";
+
+// ─── Box2i helpers (mirroring the F# helpers in this module) ───────
+
+const boxKey = (b: Box2i): string => {
+  const mn = b.min, mx = b.max;
+  return `${mn.x},${mn.y},${mx.x},${mx.y}`;
+};
+
+const sizeOf = (b: Box2i): V2i => {
+  const mn = b.min, mx = b.max;
+  return new V2i(mx.x - mn.x + 1, mx.y - mn.y + 1);
+};
+
+const isValid2i = (b: Box2i): boolean => {
+  const mn = b.min, mx = b.max;
+  return mn.x <= mx.x && mn.y <= mx.y;
+};
+
+const intersects2i = (a: Box2i, b: Box2i): boolean => {
+  const amin = a.min, amax = a.max, bmin = b.min, bmax = b.max;
+  return amin.x <= bmax.x && amax.x >= bmin.x && amin.y <= bmax.y && amax.y >= bmin.y;
+};
+
+const intersectsTouching2i = (a: Box2i, b: Box2i): boolean => {
+  // Mirror F# `intersects` inside `maxRects`: a 1-unit halo so adjacent
+  // rectangles count as overlapping (used to detect contact).
+  const amin = a.min, amax = a.max, bmin = b.min, bmax = b.max;
+  return amin.x <= bmax.x + 1 && amax.x >= bmin.x - 1 && amin.y <= bmax.y + 1 && amax.y >= bmin.y - 1;
+};
+
+const contains2i = (outer: Box2i, inner: Box2i): boolean => {
+  const omin = outer.min, omax = outer.max, imin = inner.min, imax = inner.max;
+  return omin.x <= imin.x && omin.y <= imin.y && omax.x >= imax.x && omax.y >= imax.y;
+};
+
+const equals2i = (a: Box2i, b: Box2i): boolean => {
+  const amin = a.min, amax = a.max, bmin = b.min, bmax = b.max;
+  return amin.x === bmin.x && amin.y === bmin.y && amax.x === bmax.x && amax.y === bmax.y;
+};
+
+const mkBox = (minX: number, minY: number, maxX: number, maxY: number): Box2i =>
+  new Box2i(minX, minY, maxX, maxY);
+
+// `createBox`: half-pixel padded Box2d for BVH key. Exact mirror of
+// F#'s `createBox`.
+const createBox = (b: Box2i): Box2d => {
+  const mn = b.min, mx = b.max;
+  return Box2d.fromMinMax(
+    new V2d(mn.x - 0.5, mn.y - 0.5),
+    new V2d(mx.x + 0.5, mx.y + 0.5),
+  );
+};
+
+// Subtract `b` from `a` (the placed rect from a free rect) and produce
+// up to four residual MaxRects strips. Mirrors F#'s `split`.
+const splitRects = (a: Box2i, b: Box2i): Box2i[] => {
+  const cands: Box2i[] = [
+    mkBox(b.max.x + 1, a.min.y, a.max.x, a.max.y),
+    mkBox(a.min.x, a.min.y, b.min.x - 1, a.max.y),
+    mkBox(a.min.x, b.max.y + 1, a.max.x, a.max.y),
+    mkBox(a.min.x, a.min.y, a.max.x, b.min.y - 1),
+  ];
+  return cands.filter(isValid2i);
+};
+
+// MaxRects union/cleanup. Direct port of F#'s `maxRects`.
+const maxRectsCombine = (a: Box2i, b: Box2i): Box2i[] => {
+  if (intersectsTouching2i(a, b)) {
+    if (contains2i(a, b)) return [a];
+    if (contains2i(b, a)) return [b];
+    const ax0 = a.min.x, ax1 = a.max.x, ay0 = a.min.y, ay1 = a.max.y;
+    const bx0 = b.min.x, bx1 = b.max.x, by0 = b.min.y, by1 = b.max.y;
+
+    // RangeX of a contains RangeX of b: ax0<=bx0 && ax1>=bx1
+    const abx = ax0 <= bx0 && ax1 >= bx1;
+    const bax = bx0 <= ax0 && bx1 >= ax1;
+    const aby = ay0 <= by0 && ay1 >= by1;
+    const bay = by0 <= ay0 && by1 >= ay1;
+
+    if (abx && bax) {
+      // identical X — Y-union
+      return [mkBox(ax0, Math.min(ay0, by0), ax1, Math.max(ay1, by1))];
+    }
+    if (aby && bay) {
+      return [mkBox(Math.min(ax0, bx0), ay0, Math.max(ax1, bx1), ay1)];
+    }
+    if (abx) {
+      return [mkBox(bx0, Math.min(ay0, by0), bx1, Math.max(ay1, by1)), a];
+    }
+    if (bax) {
+      return [mkBox(ax0, Math.min(ay0, by0), ax1, Math.max(ay1, by1)), b];
+    }
+    if (aby) {
+      return [mkBox(Math.min(ax0, bx0), by0, Math.max(ax1, bx1), by1), a];
+    }
+    if (bay) {
+      return [mkBox(Math.min(ax0, bx0), ay0, Math.max(ax1, bx1), ay1), b];
+    }
+    // Cross case: produce the two orthogonal strips of each rect's
+    // overlap with the other, plus both originals; filter invalid.
+    const out: Box2i[] = [
+      mkBox(Math.min(ax0, bx0), Math.max(ay0, by0), Math.max(ax1, bx1), Math.min(ay1, by1)),
+      mkBox(Math.max(ax0, bx0), Math.min(ay0, by0), Math.min(ax1, bx1), Math.max(ay1, by1)),
+      a,
+      b,
+    ];
+    return out.filter(isValid2i);
+  }
+  return [a, b];
+};
+
+// Merge a freshly-released rect `n` with already-known adjacent free
+// rects, producing the new MaxRects covering the union. Direct port
+// of F#'s `merge`.
+const merge = (n: Box2i, boxes: Iterable<Box2i>): Box2i[] => {
+  const boxArr = [...boxes];
+  if (boxArr.length === 0) return [n];
+
+  type FreeT = BvhTree2d<string, Box2i>;
+  let free: FreeT = BvhTree2d.empty<string, Box2i>();
+
+  const addOne = (b: Box2i): void => {
+    const q = mkBox(b.min.x - 1, b.min.y - 1, b.max.x + 1, b.max.y + 1);
+    const touching: Box2i[] = [];
+    for (const [, val] of free.getIntersecting(createBox(q))) {
+      if (intersectsTouching2i(val, q)) touching.push(val);
+    }
+    if (touching.length === 0) {
+      free = free.add(boxKey(b), createBox(b), b);
+      return;
+    }
+    for (const o of touching) {
+      free = free.remove(boxKey(o));
+      for (const r of maxRectsCombine(o, b)) {
+        // skip if any existing free rect already contains r
+        let contained = false;
+        for (const [, val] of free.getContaining(createBox(r))) {
+          if (contains2i(val, r)) { contained = true; break; }
+        }
+        if (!contained) {
+          // remove any free rect r contains
+          const containedKeys: string[] = [];
+          for (const [k, val] of free.getContained(createBox(r))) {
+            if (contains2i(r, val)) containedKeys.push(k);
+            void val;
+          }
+          for (const k of containedKeys) free = free.remove(k);
+          free = free.add(boxKey(r), createBox(r), r);
+        }
+      }
+    }
+  };
+
+  addOne(n);
+  for (const b of boxArr) addOne(b);
+
+  return [...free.toSeq()].map(([, , v]) => v);
+};
+
+// Add a free rect into the tree iff no existing rect already contains
+// it. Mirror of F#'s `addFree`.
+const addFree = (b: Box2i, free: BvhTree2d<string, Box2i>): BvhTree2d<string, Box2i> => {
+  if (!isValid2i(b)) return free;
+  let containing = false;
+  for (const [, v] of free.getContaining(createBox(b))) {
+    if (contains2i(v, b)) { containing = true; break; }
+  }
+  if (containing) return free;
+  return free.add(boxKey(b), createBox(b), b);
+};
+
+/**
+ * Immutable 2D atlas. Generic over `K` (entry key — anything that's a
+ * valid `Map` key works; we recommend strings or numbers).
+ */
+export class TexturePacking<K> {
+  private constructor(
+    public readonly size: V2i,
+    public readonly allowRotate: boolean,
+    private readonly free: BvhTree2d<string, Box2i>,
+    /** Used rects keyed on the user's K. */
+    public readonly used: ReadonlyMap<K, Box2i>,
+  ) {}
+
+  static empty<K>(size: V2i, allowRotate: boolean = true): TexturePacking<K> {
+    if (size.x <= 0 || size.y <= 0) {
+      return new TexturePacking<K>(new V2i(0, 0), allowRotate, BvhTree2d.empty<string, Box2i>(), new Map());
+    }
+    const bb = mkBox(0, 0, size.x - 1, size.y - 1);
+    const tree = BvhTree2d.empty<string, Box2i>().add(boxKey(bb), createBox(bb), bb);
+    return new TexturePacking<K>(size, allowRotate, tree, new Map());
+  }
+
+  static create<K>(size: V2i, allowRotate: boolean = true): TexturePacking<K> {
+    return TexturePacking.empty<K>(size, allowRotate);
+  }
+
+  get count(): number {
+    return this.used.size;
+  }
+
+  get isEmpty(): boolean {
+    return this.used.size === 0;
+  }
+
+  /** All free MaxRects. */
+  get freeRects(): Iterable<Box2i> {
+    return [...this.free.toSeq()].map(([, , v]) => v);
+  }
+
+  get occupancy(): number {
+    let area = 0;
+    for (const [, b] of this.used) {
+      const s = sizeOf(b);
+      area += s.x * s.y;
+    }
+    const total = this.size.x * this.size.y;
+    return total > 0 ? area / total : 0;
+  }
+
+  /**
+   * Try to insert one entry. Returns the new packing on success, or
+   * `null` if no free rect (with optional rotation) can accommodate
+   * `size`.
+   *
+   * If `id` is already present:
+   *   - same size → returns `this` (no-op).
+   *   - different size → removes then re-adds.
+   */
+  tryAdd(id: K, size: V2i): TexturePacking<K> | null;
+  /** Atomic batch insert: returns null if any element would not fit. */
+  tryAdd(many: Iterable<readonly [K, V2i]>): TexturePacking<K> | null;
+  tryAdd(a: K | Iterable<readonly [K, V2i]>, b?: V2i): TexturePacking<K> | null {
+    if (b === undefined) {
+      let cur: TexturePacking<K> | null = this;
+      for (const [id, sz] of a as Iterable<readonly [K, V2i]>) {
+        if (cur === null) return null;
+        cur = cur.tryAddOne(id, sz);
+      }
+      return cur;
+    }
+    return this.tryAddOne(a as K, b);
+  }
+
+  private tryAddOne(id: K, size: V2i): TexturePacking<K> | null {
+    if (size.x <= 0 || size.y <= 0) return this;
+    const ex = this.used.get(id);
+    if (ex !== undefined) {
+      const s = sizeOf(ex);
+      if (s.x === size.x && s.y === size.y) return this;
+      const removed = this.remove(id);
+      return removed.tryAddOne(id, size);
+    }
+
+    // Score each free rect; pick the smallest waste that fits.
+    let best: { rect: Box2i; upright: boolean; score: number } | undefined;
+    for (const [, , rect] of this.free.toSeq()) {
+      const sh = sizeOf(rect);
+      const f0 = sh.x >= size.x && sh.y >= size.y;
+      const f1 = this.allowRotate ? sh.x >= size.y && sh.y >= size.x : false;
+      const w0 = (sh.x - size.x) * (sh.y - size.y);
+      const w1 = (sh.x - size.y) * (sh.y - size.x);
+      let cand: { score: number; upright: boolean } | undefined;
+      if (f0 && f1) {
+        if (w0 < w1) cand = { score: w0, upright: true };
+        else cand = { score: w1, upright: false };
+      } else if (f0) cand = { score: w0, upright: true };
+      else if (f1) cand = { score: w1, upright: false };
+      if (cand !== undefined && (best === undefined || cand.score < best.score)) {
+        best = { rect, upright: cand.upright, score: cand.score };
+      }
+    }
+
+    if (best === undefined) return null;
+
+    const placedSize = best.upright ? size : new V2i(size.y, size.x);
+    const fitting = best.rect;
+
+    // Two slabs left of `fitting` after placement: right strip + top
+    // strip. Mirror F# layout.
+    const r0 = mkBox(fitting.min.x + placedSize.x, fitting.min.y, fitting.max.x, fitting.max.y);
+    const r1 = mkBox(fitting.min.x, fitting.min.y + placedSize.y, fitting.max.x, fitting.max.y);
+    const rect = mkBox(
+      fitting.min.x,
+      fitting.min.y,
+      fitting.min.x + placedSize.x - 1,
+      fitting.min.y + placedSize.y - 1,
+    );
+
+    let free = this.free.remove(boxKey(fitting));
+    free = addFree(r0, free);
+    free = addFree(r1, free);
+
+    // For every other free rect intersecting `rect`, replace with
+    // `splitRects(other, rect)`.
+    const intersecting: Array<[string, Box2i]> = [];
+    for (const [, , v] of free.toSeq()) {
+      if (intersects2i(v, rect)) intersecting.push([boxKey(v), v]);
+    }
+    for (const [k, other] of intersecting) {
+      free = free.remove(k);
+      for (const p of splitRects(other, rect)) free = addFree(p, free);
+    }
+
+    const newUsed = new Map(this.used);
+    newUsed.set(id, rect);
+    return new TexturePacking<K>(this.size, this.allowRotate, free, newUsed);
+  }
+
+  /** Remove `id` (no-op if absent). */
+  remove(id: K): TexturePacking<K> {
+    const rect = this.used.get(id);
+    if (rect === undefined) return this;
+    const newUsed = new Map(this.used);
+    newUsed.delete(id);
+
+    const qi = mkBox(rect.min.x - 1, rect.min.y - 1, rect.max.x + 1, rect.max.y + 1);
+    const adjacent: Box2i[] = [];
+    for (const [, , v] of [...this.free.getIntersecting(createBox(qi))].map(
+      ([k, vv]) => [k, vv, vv] as const,
+    )) {
+      if (
+        v.min.x === qi.max.x ||
+        v.max.x === qi.min.x ||
+        v.min.y === qi.max.y ||
+        v.max.y === qi.min.y
+      ) {
+        adjacent.push(v);
+      }
+    }
+    let free = this.free;
+    for (const a of adjacent) free = free.remove(boxKey(a));
+    for (const m of merge(rect, adjacent)) free = addFree(m, free);
+    return new TexturePacking<K>(this.size, this.allowRotate, free, newUsed);
+  }
+}
+
+// ─── Module-level helpers (matching the F# `module TexturePacking`) ─
+
+export const empty = <K>(size: V2i): TexturePacking<K> => TexturePacking.empty<K>(size);
+export const isEmpty = <K>(p: TexturePacking<K>): boolean => p.isEmpty;
+export const count = <K>(p: TexturePacking<K>): number => p.count;
+export const occupancy = <K>(p: TexturePacking<K>): number => p.occupancy;
+export const tryAdd = <K>(id: K, size: V2i, p: TexturePacking<K>): TexturePacking<K> | null =>
+  p.tryAdd(id, size);
+
+/** Sort-then-tryAdd helper. Sorting by descending max-extent matches the F# heuristic. */
+export const tryAddMany = <K>(
+  elements: Iterable<readonly [K, V2i]>,
+  p: TexturePacking<K>,
+): TexturePacking<K> | null => {
+  const arr = [...elements];
+  arr.sort((a, b) => Math.max(b[1].x, b[1].y) - Math.max(a[1].x, a[1].y));
+  return p.tryAdd(arr);
+};
+
+export const tryOfArray = <K>(
+  size: V2i,
+  elements: ReadonlyArray<readonly [K, V2i]>,
+): TexturePacking<K> | null => tryAddMany(elements, empty<K>(size));
+
+/**
+ * Build an optimal-square packing for the given elements, doubling
+ * the side until everything fits then binary-searching down. Mirrors
+ * F#'s `TexturePacking.square`.
+ */
+export const square = <K>(elements: ReadonlyArray<readonly [K, V2i]>): TexturePacking<K> => {
+  const arr = [...elements];
+  arr.sort((a, b) => Math.max(b[1].x, b[1].y) - Math.max(a[1].x, a[1].y));
+  if (arr.length === 0) return empty<K>(new V2i(0, 0));
+  if (arr.length === 1) {
+    const [id, sz] = arr[0]!;
+    const s = Math.max(sz.x, sz.y);
+    return empty<K>(new V2i(s, s)).tryAdd(id, sz)!;
+  }
+  let area = 0;
+  for (const [, sz] of arr) area += sz.x * sz.y;
+  let lo = Math.floor(Math.sqrt(area));
+  let hi = nextPow2(lo);
+  let best = tryOfArray(new V2i(hi, hi), arr);
+  while (best === null) {
+    lo = hi;
+    hi = hi * 2;
+    best = tryOfArray(new V2i(hi, hi), arr);
+  }
+  let bestPacking = best;
+  while (hi > lo + 1) {
+    const m = (hi + lo) >> 1;
+    const p = tryOfArray(new V2i(m, m), arr);
+    if (p !== null) {
+      bestPacking = p;
+      hi = m;
+    } else {
+      lo = m;
+    }
+  }
+  return bestPacking;
+};
+
+function nextPow2(n: number): number {
+  if (n <= 1) return 1;
+  let p = 1;
+  while (p < n) p *= 2;
+  return p;
+}
+
+// silence unused-helper warning at export-time tooling
+void equals2i;

package/src/window/loop.ts

@@ -39,6 +39,20 @@ export interface RunFrameOptions {
    * behavior.
    */
   readonly onAfterFrame?: () => void;
+  /**
+   * Frame pacer. When provided, runFrame awaits this promise after
+   * each frame's eval and BEFORE invoking `onAfterFrame` / scheduling
+   * the next rAF. Caps the JS encode rate to whatever the pacer
+   * resolves at — typically `() => device.queue.onSubmittedWorkDone()`
+   * to keep the GPU queue at depth 1 instead of letting submit-
+   * returns-immediately balloon the queue under load.
+   *
+   * Without a pacer, JS happily encodes 60 frames/s into a GPU that's
+   * actually running at 10 fps — the compositor then drops frames
+   * silently and the perceived rate has nothing to do with rAF rate.
+   * Always supply a pacer for continuous-redraw scenes.
+   */
+  readonly pacer?: () => Promise<void>;
 }
 
 export type FrameCallback = (token: AdaptiveToken, info: FrameInfo) => void;
@@ -79,6 +93,17 @@ export function runFrame(
     return frameNo;
   });
 
+  const finalizeFrame = (): void => {
+    if (stopped) return;
+    if (opts.onAfterFrame !== undefined) {
+      transact(opts.onAfterFrame);
+    }
+    if (opts.maxFrames !== undefined && frameNo >= opts.maxFrames) {
+      stopped = true;
+      sub.dispose();
+    }
+  };
+
   const tick = (): void => {
     if (stopped) return;
     pending = false;
@@ -93,12 +118,13 @@ export function runFrame(
     // Inside the eval the same mark would race the
     // `outOfDate=false` reset and animation would stall after one
     // frame.
-    if (opts.onAfterFrame !== undefined) {
-      transact(opts.onAfterFrame);
-    }
-    if (opts.maxFrames !== undefined && frameNo >= opts.maxFrames) {
-      stopped = true;
-      sub.dispose();
+    if (opts.pacer !== undefined) {
+      opts.pacer().then(finalizeFrame, (e) => {
+        stopped = true;
+        console.error("runFrame: pacer rejected", e);
+      });
+    } else {
+      finalizeFrame();
     }
   };
 

package/dist/runtime/heapShader.d.ts

@@ -1,12 +0,0 @@
-import type { Effect } from "@aardworx/wombat.shader";
-/**
- * Compile a wombat.shader fragment `Effect` into a WGSL string
- * usable as a `buildHeapScene` `fragmentShaders` value.
- *
- * The effect's fragment input field names must match the
- * heap-scene `VsOut` fields: `worldPos`, `normal`, `color`,
- * `lightLoc`. The fragment output must be a single `vec4<f32>`
- * field (any name).
- */
-export declare function compileHeapFragment(effect: Effect): string;
-//# sourceMappingURL=heapShader.d.ts.map

package/dist/runtime/heapShader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"heapShader.d.ts","sourceRoot":"","sources":["../../src/runtime/heapShader.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAO1D"}

package/dist/runtime/heapShader.js

@@ -1,157 +0,0 @@
-// heapShader — bridge from wombat.shader effects to heap-scene
-// fragment WGSL.
-//
-// `buildHeapScene` requires a fragment-stage WGSL string per group
-// key (see runtime/heapScene.ts). Writing those strings by hand
-// works but is the wrong long-term shape — users want to write the
-// FS in the wombat.shader DSL and get the same effect-composition,
-// type-checking, and DCE the per-RO path enjoys.
-//
-// `compileHeapFragment(effect)` runs wombat.shader's emit on a
-// fragment Effect and rewrites the resulting WGSL to plug into the
-// heap-scene's `VsOut` shape:
-//
-//   ┌─ heap-scene's VsOut          ┌─ DSL fragment input must use
-//   │ worldPos: vec3<f32>          │ matching field names:
-//   │ normal:   vec3<f32>          │   worldPos, normal, color,
-//   │ color:    vec4<f32>          │   lightLoc
-//   │ lightLoc: vec3<f32>          │
-//   └─                             └─
-//
-// The DSL effect's fragment OUTPUT must be a single field; its name
-// is irrelevant (the adapter rewraps to bare `@location(0) vec4<f32>`).
-// `uniform.X` references inside the fragment body are redirected to
-// `in.X` — the contract is that any uniform the FS reads must have
-// been thread through the VS into the corresponding VsOut field.
-//
-// What this DOES NOT do: rewrite the vertex stage. The heap-scene's
-// VS is fixed (storage-buffer uniform reads, vertex pulling from
-// position/normal slabs); user effects only contribute the fragment.
-/**
- * Compile a wombat.shader fragment `Effect` into a WGSL string
- * usable as a `buildHeapScene` `fragmentShaders` value.
- *
- * The effect's fragment input field names must match the
- * heap-scene `VsOut` fields: `worldPos`, `normal`, `color`,
- * `lightLoc`. The fragment output must be a single `vec4<f32>`
- * field (any name).
- */
-export function compileHeapFragment(effect) {
-    const compiled = effect.compile({ target: "wgsl" });
-    const fs = compiled.stages.find(s => s.stage === "fragment");
-    if (fs === undefined) {
-        throw new Error("compileHeapFragment: effect has no fragment stage");
-    }
-    return rewriteFragment(fs.source);
-}
-function rewriteFragment(wgsl) {
-    let s = wgsl;
-    // 1. Drop the auto-emitted UBO struct + binding. Heap-scene FS
-    //    doesn't bind a UBO at all (uniforms ride on VsOut from VS).
-    s = s.replace(/struct\s+_UB_uniform\s*\{[\s\S]*?\};?\s*/g, "");
-    s = s.replace(/@group\(\d+\)\s*@binding\(\d+\)\s*var<uniform>\s+_w_uniform\s*:\s*_UB_uniform\s*;?\s*/g, "");
-    // 2. Redirect uniform reads to inter-stage. _w_uniform.LightLocation
-    //    → in.lightLoc.
-    s = s.replace(/_w_uniform\.(\w+)/g, (_m, name) => "in." + uniformToVsOut(name));
-    // 3. Locate the @fragment function signature; capture the input
-    //    struct name + output struct name from the signature itself.
-    //    Two emit shapes seen in practice:
-    //      - inline-marker: `wombat_fragment_<hash>` + `Wombat_fragment_<hash>{Input,Output}`
-    //      - direct stage(): `<fnName>` + `<FnName>{Input,Output}`
-    //    Detecting from the signature works for both.
-    const fnSigMatch = s.match(/@fragment\s+fn\s+(\w+)\s*\(\s*(\w+)\s*:\s*(\w+)\s*\)\s*->\s*(\w+)\s*\{/);
-    if (fnSigMatch === null) {
-        throw new Error("compileHeapFragment: emitted WGSL has no @fragment function header");
-    }
-    const fnHeader = fnSigMatch[0];
-    const paramName = fnSigMatch[2];
-    const inputStructName = fnSigMatch[3];
-    const outputStructName = fnSigMatch[4];
-    // 4. Drop the input struct.
-    const inputStructRe = new RegExp(`struct\\s+${escapeRegExp(inputStructName)}\\s*\\{[\\s\\S]*?\\};?`);
-    s = s.replace(inputStructRe, "");
-    // 5. Capture + drop the output struct, recording its (single) field name.
-    const outputStructRe = new RegExp(`struct\\s+${escapeRegExp(outputStructName)}\\s*\\{([\\s\\S]*?)\\};?`);
-    const outputMatch = s.match(outputStructRe);
-    if (outputMatch === null) {
-        throw new Error(`compileHeapFragment: cannot locate output struct '${outputStructName}'`);
-    }
-    const outputBody = outputMatch[1];
-    const fieldRe = /@location\(0\)\s+(\w+)\s*:\s*vec4<f32>\s*,?/g;
-    const fieldMatches = [...outputBody.matchAll(fieldRe)];
-    if (fieldMatches.length !== 1) {
-        throw new Error(`compileHeapFragment: fragment output must be a single @location(0) vec4<f32> field; got ${fieldMatches.length} field(s)`);
-    }
-    const outputFieldName = fieldMatches[0][1];
-    s = s.replace(outputMatch[0], "");
-    // 6. Rewrite the function header to the heap-scene shape. Any parameter
-    //    name (in, input, …) is renormalised to `in` so the user shader's
-    //    field references work uniformly downstream.
-    s = s.replace(fnHeader, "@fragment\nfn fs(in: VsOut) -> @location(0) vec4<f32> {");
-    if (paramName !== "in") {
-        // Rewrite `paramName.X` references to `in.X`.
-        const paramRe = new RegExp(`\\b${escapeRegExp(paramName)}\\.`, "g");
-        s = s.replace(paramRe, "in.");
-    }
-    // 7. Rewrite the body's `out: <Output>; ... out.<field> = expr; return out;` to
-    //    return expr directly. wombat.shader's emit always uses this pattern; we
-    //    transform it via two passes (capture the assignment, drop the var/return).
-    const fieldRef = `out\\.${escapeRegExp(outputFieldName)}`;
-    const assignRe = new RegExp(`var\\s+out\\s*:\\s*${escapeRegExp(outputStructName)}\\s*;([\\s\\S]*?)${fieldRef}\\s*=\\s*([\\s\\S]*?);([\\s\\S]*?)return\\s+out\\s*;`);
-    const assignMatch = s.match(assignRe);
-    if (assignMatch === null) {
-        // Fall back: if user wrote a more exotic body we surface a clear error.
-        throw new Error("compileHeapFragment: emitted body doesn't follow the var-out / out." + outputFieldName +
-            " = ... / return out pattern (got unsupported emit shape)");
-    }
-    const beforeAssign = assignMatch[1]; // statements between var-out decl and the field assignment
-    const expr = assignMatch[2];
-    const afterAssign = assignMatch[3]; // statements between the assignment and the return
-    s = s.replace(assignMatch[0], beforeAssign + afterAssign + `return ${expr};`);
-    // 8. Map references `in.<DslField>` to the corresponding heap VsOut
-    //    field name (a 1:1 mapping when the user's input struct uses
-    //    the canonical field names; identity otherwise).
-    s = s.replace(/in\.(\w+)/g, (_m, name) => "in." + dslFieldToVsOut(name));
-    // 9. Tidy: collapse 3+ blank lines to one.
-    s = s.replace(/\n{3,}/g, "\n\n").trimStart();
-    return s;
-}
-// Map a DSL uniform name to the heap-scene VsOut field that carries
-// it. Today only `LightLocation` rides on VsOut; everything else
-// would need to be added to the VS prelude in heapScene.ts.
-function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function uniformToVsOut(name) {
-    switch (name) {
-        case "LightLocation": return "lightLoc";
-        default:
-            throw new Error(`compileHeapFragment: uniform '${name}' is not carried on VsOut. Either thread it through the VS or use a fragment that doesn't read it.`);
-    }
-}
-// Map an inter-stage name from the DSL convention (PascalCase, e.g.
-// 'Normals', 'WorldPositions') or our preferred direct names
-// ('normal', 'worldPos') to the canonical VsOut field name.
-function dslFieldToVsOut(name) {
-    switch (name) {
-        // canonical heap-scene names — pass through.
-        case "worldPos":
-        case "normal":
-        case "color":
-        case "lightLoc":
-            return name;
-        // legacy PascalCase from the wombat.dom convention — auto-translate
-        // so users can copy DSL effects from the per-RO path with minimal edits.
-        case "WorldPositions": return "worldPos";
-        case "WorldPosition": return "worldPos";
-        case "Normals": return "normal";
-        case "Normal": return "normal";
-        case "Colors": return "color";
-        case "Color": return "color";
-        case "LightLocation": return "lightLoc";
-        default:
-            throw new Error(`compileHeapFragment: input field '${name}' has no mapping to VsOut. ` +
-                `Use one of: worldPos, normal, color, lightLoc.`);
-    }
-}
-//# sourceMappingURL=heapShader.js.map

package/dist/runtime/heapShader.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"heapShader.js","sourceRoot":"","sources":["../../src/runtime/heapShader.ts"],"names":[],"mappings":"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"}