@aardworx/wombat.rendering 0.19.24 → 0.20.0

package/src/runtime/heapShaderFamily.ts

@@ -481,6 +481,26 @@ function unionDrawHeaders(
   // descriptor-only purpose of this slice, the per-effect-allocated
   // numbers are retained as-is on each entry.
 
+  // Union user storage-buffer bindings by name (type/access agreement),
+  // keeping the per-effect-allocated binding numbers (all effects allocate
+  // from the same fixed base in the same sorted-by-name order, so shared
+  // names agree; family-merge is disabled in practice anyway).
+  const storageByName = new Map<string, { name: string; access: "read" | "read_write"; binding: number }>();
+  for (const e of sortedEffects) {
+    const layout = perEffectLayout.get(e)!;
+    for (const sb of layout.storageBindings) {
+      const existing = storageByName.get(sb.name);
+      if (existing === undefined) storageByName.set(sb.name, { ...sb });
+      else if (existing.access !== sb.access) {
+        throw new Error(
+          `buildShaderFamily: storage buffer '${sb.name}' has conflicting access ` +
+          `across effects: '${existing.access}' vs '${sb.access}'.`,
+        );
+      }
+    }
+  }
+  const storageBindings = [...storageByName.values()].sort((a, b) => a.binding - b.binding);
+
   const base = {
     drawHeaderFields: fields,
     drawHeaderBytes,
@@ -491,6 +511,7 @@ function unionDrawHeaders(
     textureBindings: orderedTextures,
     samplerBindings: orderedSamplers,
     atlasTextureBindings: atlasUnion,
+    storageBindings,
   };
   return { id: bucketLayoutId(base), ...base };
 }

package/src/runtime/hybridScene.ts

@@ -92,6 +92,12 @@ export interface CompileHybridSceneOptions {
    * massive workloads.
    */
   readonly maxChunkBytes?: number;
+  /** Pre-size heap arena chunks (bytes) — pass-through to `BuildHeapSceneOptions.initialArenaBytes`. */
+  readonly initialArenaBytes?: number;
+  /** Heap arena compaction toggle — pass-through to `BuildHeapSceneOptions.enableCompaction`. */
+  readonly enableCompaction?: boolean;
+  /** Compaction waste floor (bytes) — pass-through to `BuildHeapSceneOptions.compactionWasteFloorBytes`. */
+  readonly compactionWasteFloorBytes?: number;
 }
 
 export interface HybridScene {
@@ -197,19 +203,33 @@ export function compileHybridScene(
   // toggle — flipping that off forces every RO to legacy.
   const heapEnabled = opts.heapEnabled ?? AVal.constant(true);
   const eligCache = new WeakMap<RenderObject, aval<boolean>>();
+  const notEligCache = new WeakMap<RenderObject, aval<boolean>>();
   const elig = (ro: RenderObject): aval<boolean> => {
     let av = eligCache.get(ro);
     if (av === undefined) {
       const perRO = isHeapEligible(ro);
-      av = AVal.custom(t => heapEnabled.getValue(t) && perRO.getValue(t));
+      // Constant collapse (static RO + constant heapEnabled): a plain
+      // constant instead of a custom aval + two subscriptions per RO.
+      av = heapEnabled.isConstant && perRO.isConstant
+        ? AVal.constant(heapEnabled.force(/* allow-force */) && perRO.force(/* allow-force */))
+        : AVal.custom(t => heapEnabled.getValue(t) && perRO.getValue(t));
       eligCache.set(ro, av);
     }
     return av;
   };
+  const notElig = (ro: RenderObject): aval<boolean> => {
+    let av = notEligCache.get(ro);
+    if (av === undefined) {
+      const e = elig(ro);
+      av = e.isConstant ? AVal.constant(!e.force(/* allow-force */)) : e.map(b => !b);
+      notEligCache.set(ro, av);
+    }
+    return av;
+  };
 
   const flat = flattenRenderTree(tree);
   const heapAset   = flat.filterA(ro => elig(ro));
-  const legacyAset = flat.filterA(ro => elig(ro).map(b => !b));
+  const legacyAset = flat.filterA(ro => notElig(ro));
 
   // ─── Atlas pool ──────────────────────────────────────────────────
   // Per-scene Tier-S atlas pool. Owned by this hybrid scene; disposed
@@ -231,7 +251,9 @@ export function compileHybridScene(
   const heapSpecAset = heapAset.map((ro: RenderObject) => {
     let spec = specCache.get(ro);
     if (spec === undefined) {
-      spec = renderObjectToHeapSpec(ro, AdaptiveToken.top, atlasPool);
+      spec = renderObjectToHeapSpec(ro, AdaptiveToken.top, atlasPool, {
+        enableDerivedUniforms: opts.enableDerivedUniforms !== false,
+      });
       specCache.set(ro, spec);
     }
     return spec;
@@ -243,6 +265,9 @@ export function compileHybridScene(
     ...(opts.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
     ...(opts.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
     ...(opts.maxChunkBytes !== undefined ? { maxChunkBytes: opts.maxChunkBytes } : {}),
+    ...(opts.initialArenaBytes !== undefined ? { initialArenaBytes: opts.initialArenaBytes } : {}),
+    ...(opts.enableCompaction !== undefined ? { enableCompaction: opts.enableCompaction } : {}),
+    ...(opts.compactionWasteFloorBytes !== undefined ? { compactionWasteFloorBytes: opts.compactionWasteFloorBytes } : {}),
   });
 
   // ─── Legacy subset → RenderTree → ScenePass ──────────────────────
@@ -253,10 +278,24 @@ export function compileHybridScene(
   const legacyTree: RenderTree =
     RenderTree.unorderedFromSet(legacyAset.map(ro => RenderTree.leaf(ro)));
   const scenePass = new ScenePass(device, signature, legacyTree, compileEffect);
+  // DEBUG registry: per-hybrid-scene live draw counts (heap vs legacy) so
+  // multi-task pipelines (OIT) can be inspected from the console.
+  const dbgEntry = {
+    sig: signature.colorNames.join("+"),
+    heap: () => heapScene.stats.totalDraws,
+    legacy: () => scenePass.collect().length,
+  };
+  const dbgArr = ((globalThis as any).__hybridScenes ??= []) as (typeof dbgEntry)[];
+  dbgArr.push(dbgEntry);
 
   return {
     update(token: AdaptiveToken): void {
+      // Batch all of this frame's atlas uploads (tile ingest during
+      // heapScene.update → pool.acquire) into ONE queue submission —
+      // per-tile submits stall multi-frame when several tiles land at once.
+      atlasPool.beginUploadBatch();
       heapScene.update(token);
+      atlasPool.flushUploadBatch();
       scenePass.update(token);
     },
     encodeComputePrep(enc: GPUCommandEncoder, token: AdaptiveToken): void {
@@ -291,6 +330,7 @@ export function compileHybridScene(
     __legacyCount(): number {
       return scenePass.collect().length;
     },
+
     heapDerivedTimings() {
       const s = heapScene.stats;
       return {

package/src/runtime/index.ts

@@ -25,7 +25,12 @@ export {
 
 export {
   buildHeapScene,
+  createHeapStorage,
+  oct32, c4b,
+  type HeapPackedAttribute,
   type HeapScene,
+  type HeapStorage,
+  type HeapStorageOptions,
   type HeapSceneStats,
   type HeapDrawSpec,
   type HeapGeometry,

package/src/runtime/renderTask.ts

@@ -59,6 +59,12 @@ export interface RuntimeContext {
    * compiled against this context. Default unset → adapter limit.
    */
   readonly maxChunkBytes?: number;
+  /** Pre-size heap arena chunks (bytes) — see `BuildHeapSceneOptions.initialArenaBytes`. */
+  readonly initialArenaBytes?: number;
+  /** Heap arena compaction toggle — see `BuildHeapSceneOptions.enableCompaction`. */
+  readonly enableCompaction?: boolean;
+  /** Compaction waste floor (bytes) — see `BuildHeapSceneOptions.compactionWasteFloorBytes`. */
+  readonly compactionWasteFloorBytes?: number;
 }
 
 class RenderTask implements IRenderTask {
@@ -262,6 +268,9 @@ class RenderTask implements IRenderTask {
         ...(this.ctx.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
         ...(this.ctx.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
         ...(this.ctx.maxChunkBytes !== undefined ? { maxChunkBytes: this.ctx.maxChunkBytes } : {}),
+        ...(this.ctx.initialArenaBytes !== undefined ? { initialArenaBytes: this.ctx.initialArenaBytes } : {}),
+        ...(this.ctx.enableCompaction !== undefined ? { enableCompaction: this.ctx.enableCompaction } : {}),
+        ...(this.ctx.compactionWasteFloorBytes !== undefined ? { compactionWasteFloorBytes: this.ctx.compactionWasteFloorBytes } : {}),
       });
       this._scenes.set(cmd, s);
     }

package/src/runtime/runtime.ts

@@ -47,6 +47,21 @@ export interface RuntimeOptions {
    * from a demo / test to exercise multi-chunk routing.
    */
   readonly maxChunkBytes?: number;
+  /**
+   * Pre-size heap arena chunks (bytes) — threaded into
+   * `BuildHeapSceneOptions.initialArenaBytes`. Streaming apps should pass
+   * their expected working-set size to avoid pow2 grow-copies (full-arena
+   * GPU copy + bind-group rebuilds) mid-navigation.
+   */
+  readonly initialArenaBytes?: number;
+  /**
+   * Heap arena compaction toggle — threaded into
+   * `BuildHeapSceneOptions.enableCompaction`. Streaming apps with steady
+   * churn may prefer `false` to guarantee no mid-frame compaction bounce.
+   */
+  readonly enableCompaction?: boolean;
+  /** Waste floor (bytes) before compaction triggers — see `BuildHeapSceneOptions`. */
+  readonly compactionWasteFloorBytes?: number;
 }
 
 /**
@@ -84,6 +99,9 @@ export class Runtime {
       ...(opts.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
       ...(opts.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
       ...(opts.maxChunkBytes !== undefined ? { maxChunkBytes: opts.maxChunkBytes } : {}),
+      ...(opts.initialArenaBytes !== undefined ? { initialArenaBytes: opts.initialArenaBytes } : {}),
+      ...(opts.enableCompaction !== undefined ? { enableCompaction: opts.enableCompaction } : {}),
+      ...(opts.compactionWasteFloorBytes !== undefined ? { compactionWasteFloorBytes: opts.compactionWasteFloorBytes } : {}),
     };
     // `device.lost` is a real-WebGPU promise; mock devices may not
     // expose it. Treat as "never lost" in that case.

package/src/runtime/textureAtlas/atlasMipGutterKernel.ts

@@ -185,6 +185,44 @@ export interface MipSlot {
   readonly size:   { w: number; h: number };
 }
 
+/**
+ * Shared-encoder batch for atlas uploads: many tiles' mip/gutter kernels
+ * encode into ONE command encoder and submit ONCE — per-tile submits (2 per
+ * tile: the implicit copyExternalImageToTexture + a dedicated kernel submit)
+ * were measured as multi-frame stalls when several tiles land per frame on
+ * mobile GPUs. Resources pushed to `trash`/`trashTextures` are destroyed
+ * once the single submission completes.
+ */
+export interface MipGutterBatch {
+  readonly enc: GPUCommandEncoder;
+  readonly trash: GPUBuffer[];
+  readonly trashTextures: GPUTexture[];
+  /** encoded job count (empty batches skip the submit entirely) */
+  jobs: number;
+}
+
+export function beginMipGutterBatch(device: GPUDevice): MipGutterBatch {
+  return {
+    enc: device.createCommandEncoder({ label: "atlas/mipGutterBatch" }),
+    trash: [], trashTextures: [], jobs: 0,
+  };
+}
+
+export function submitMipGutterBatch(device: GPUDevice, batch: MipGutterBatch): void {
+  if (batch.jobs === 0) {
+    // nothing encoded — still finish the encoder to release it
+    batch.enc.finish();
+    for (const t of batch.trashTextures) t.destroy();
+    for (const b of batch.trash) b.destroy();
+    return;
+  }
+  device.queue.submit([batch.enc.finish()]);
+  void device.queue.onSubmittedWorkDone().then(() => {
+    for (const t of batch.trashTextures) t.destroy();
+    for (const b of batch.trash) b.destroy();
+  });
+}
+
 /** How mip-0's interior pixels get into the scratch buffer. */
 type Mip0Source =
   // The caller already filled the buffer's mip-0 region at creation
@@ -216,12 +254,15 @@ function runMipGutter(
   srcW: number, srcH: number,
   mips: readonly MipSlot[],
   mip0Src: Mip0Source,
+  batch?: MipGutterBatch,
 ): void {
   const k = getKernel(device);
   const bufStrideU32 = rowBytes / 4;
   const mip0 = mips[0]!;
 
-  const enc = device.createCommandEncoder({ label: "atlas/mipGutterKernel" });
+  const enc = batch !== undefined
+    ? batch.enc
+    : device.createCommandEncoder({ label: "atlas/mipGutterKernel" });
 
   const ubos: GPUBuffer[] = [];
   const makeUbo = (
@@ -312,6 +353,12 @@ function runMipGutter(
     { width: boundsW, height: boundsH, depthOrArrayLayers: 1 },
   );
 
+  if (batch !== undefined) {
+    batch.jobs++;
+    batch.trash.push(scratch, ...ubos);
+    return; // caller submits the shared encoder once per frame
+  }
+
   device.queue.submit([enc.finish()]);
 
   // Lifetime: destroy scratch + per-pass UBOs once submitted work is
@@ -348,6 +395,7 @@ export function buildMipsAndGutterOnGpu(
   srcPixels: Uint8Array,
   srcW: number, srcH: number,
   mips: readonly MipSlot[],
+  batch?: MipGutterBatch,
 ): void {
   if (mips.length === 0) return;
   const { rowBytes, bufSize } = scratchGeom(boundsW, boundsH);
@@ -382,7 +430,7 @@ export function buildMipsAndGutterOnGpu(
 
   runMipGutter(
     device, page, subRectX, subRectY, boundsW, boundsH,
-    rowBytes, scratch, srcW, srcH, mips, { kind: "prefilled" },
+    rowBytes, scratch, srcW, srcH, mips, { kind: "prefilled" }, batch,
   );
 }
 
@@ -408,6 +456,7 @@ export function buildMipsAndGutterFromTexture(
   srcTex: GPUTexture,
   srcW: number, srcH: number,
   mips: readonly MipSlot[],
+  batch?: MipGutterBatch,
 ): void {
   if (mips.length === 0) return;
   const { rowBytes, bufSize } = scratchGeom(boundsW, boundsH);
@@ -418,6 +467,6 @@ export function buildMipsAndGutterFromTexture(
   });
   runMipGutter(
     device, page, subRectX, subRectY, boundsW, boundsH,
-    rowBytes, scratch, srcW, srcH, mips, { kind: "texture", tex: srcTex },
+    rowBytes, scratch, srcW, srcH, mips, { kind: "texture", tex: srcTex }, batch,
   );
 }

package/src/runtime/textureAtlas/atlasPool.ts

@@ -33,7 +33,10 @@ import { V2f, V2i } from "@aardworx/wombat.base";
 import { type aval, HashTable } from "@aardworx/wombat.adaptive";
 import type { ITexture, HostTextureSource } from "../../core/texture.js";
 import { TexturePacking } from "./packer.js";
-import { buildMipsAndGutterOnGpu, buildMipsAndGutterFromTexture, type MipSlot } from "./atlasMipGutterKernel.js";
+import {
+  buildMipsAndGutterOnGpu, buildMipsAndGutterFromTexture, type MipSlot,
+  beginMipGutterBatch, submitMipGutterBatch, type MipGutterBatch,
+} from "./atlasMipGutterKernel.js";
 
 export const ATLAS_PAGE_SIZE = 4096;
 /** Tier S/M source-side dimension cap. */
@@ -675,6 +678,27 @@ export class AtlasPool {
     this.lru.clear();
   }
 
+  // ── shared-encoder upload batching ─────────────────────────────────
+  // While a batch is open, per-tile kernel work encodes into ONE encoder
+  // and `flushUploadBatch` submits once — per-tile submits were measured
+  // as multi-frame stalls when several tiles land per frame (mobile GPUs,
+  // large photogrammetry textures). Callers that never open a batch keep
+  // the old immediate-submit behavior.
+  private uploadBatch: MipGutterBatch | null = null;
+
+  /** Open (or keep) a shared upload batch. Pair with `flushUploadBatch`. */
+  beginUploadBatch(): void {
+    if (this.uploadBatch === null) this.uploadBatch = beginMipGutterBatch(this.device);
+  }
+
+  /** Submit all batched uploads in one queue submission. */
+  flushUploadBatch(): void {
+    if (this.uploadBatch !== null) {
+      submitMipGutterBatch(this.device, this.uploadBatch);
+      this.uploadBatch = null;
+    }
+  }
+
   private finalize(
     aval: aval<ITexture>,
     format: AtlasPageFormat,
@@ -804,8 +828,10 @@ export class AtlasPool {
             this.device, page.texture,
             boundsX, boundsY, reservedW, reservedH,
             staging, w, h, slots,
+            this.uploadBatch ?? undefined,
           );
-          void this.device.queue.onSubmittedWorkDone().then(() => staging.destroy());
+          if (this.uploadBatch !== null) this.uploadBatch.trashTextures.push(staging);
+          else void this.device.queue.onSubmittedWorkDone().then(() => staging.destroy());
           return;
         } catch {
           // Source not in a copyable state (e.g. a not-ready video) —

package/src/window/loop.ts

@@ -131,6 +131,8 @@ export function runFrame(
   let lastTime = performance.now();
   let rafId = 0;
   let pending = false;
+  let consecutiveErrors = 0;
+  const MAX_CONSECUTIVE_ERRORS = 30;
   const UNCAPPED = isUncapped();
 
   // Wrap the frame callback in an AVal so the adaptive system tracks
@@ -143,10 +145,34 @@ export function runFrame(
     attachment.markFrame();
     try {
       frame(token, { frame: frameNo, timestampMs: now, deltaMs: delta });
+      consecutiveErrors = 0;
     } catch (e) {
-      stopped = true;
-      console.error("runFrame: error in frame callback", e);
-      throw e;
+      // A throwing frame used to kill the loop for good. That is far too harsh
+      // for a transient fault (a resource disposed mid-frame, a one-off device
+      // hiccup): the page then looks alive — DOM, input and workers all keep
+      // running — while nothing renders again and any animation driven from the
+      // frame callback freezes. Retry instead, and only give up if the fault
+      // repeats every frame (a genuinely broken scene, which would otherwise
+      // spin the error path forever).
+      consecutiveErrors++;
+      console.error(
+        `runFrame: error in frame callback (${consecutiveErrors}/${MAX_CONSECUTIVE_ERRORS})`, e,
+      );
+      if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+        stopped = true;
+        console.error("runFrame: giving up after repeated frame errors — render loop stopped");
+        throw e;
+      }
+      // Keep the loop breathing: schedule the next frame ourselves, since a
+      // frame that died early may not have read the inputs it would be marked
+      // by. Swallow the error rather than rethrowing — an exception escaping
+      // the aval eval leaves the wrapper's dirty state ambiguous, and we have
+      // already reported it.
+      queueMicrotask(() => {
+        if (stopped || pending) return;
+        pending = true;
+        rafId = schedule(tick);
+      });
     }
     frameNo++;
     return frameNo;
@@ -188,8 +214,10 @@ export function runFrame(
     // frame.
     if (opts.pacer !== undefined) {
       opts.pacer().then(finalizeFrame, (e) => {
-        stopped = true;
+        // A rejected pacer (GPU hiccup) must not brick the loop either — the
+        // frame is done as far as we're concerned; carry on.
         console.error("runFrame: pacer rejected", e);
+        finalizeFrame();
       });
     } else {
       finalizeFrame();