@aardworx/wombat.rendering 0.19.25 → 0.20.1

package/src/runtime/heapEffect.ts

@@ -75,6 +75,10 @@ export interface HeapEffectSchema {
   readonly fragmentOutputs: readonly { readonly name: string; readonly location: number; readonly wgslType: string }[];
   readonly textures: readonly HeapTextureBinding[];
   readonly samplers: readonly HeapSamplerBinding[];
+  /** User-declared storage buffers (the OIT node pool & co) — bound at
+   *  bucket level from scene-shared avals (`HeapDrawSpec.storageBuffers`).
+   *  Absent/empty for ordinary effects. */
+  readonly storageBuffers?: readonly { readonly name: string; readonly access: "read" | "read_write" }[];
 }
 
 export interface CompiledHeapEffect {
@@ -104,7 +108,7 @@ export interface FragmentOutputLayout {
 // and on quota; every failure simply degrades to "recompute".
 
 /** Cache-generation stamp for the persistent (localStorage) tier. */
-export const HEAP_PERSIST_VERSION = "h4"; // h4: inline PickId drawHeader read (was h3: packed decode arms)
+export const HEAP_PERSIST_VERSION = "h7"; // h7: OIT resolve early-exit
 
 /**
  * Uniforms whose drawHeader word IS the u32 value (no arena
@@ -275,7 +279,11 @@ function buildSchema(iface: ProgramInterface): HeapEffectSchema {
     name: s.name, wgslType: isComparison(s.type) ? "sampler_comparison" : "sampler",
     ...(s.state !== undefined ? { state: s.state } : {}),
   }));
-  return { attributes, uniforms, varyings, fragmentOutputs, textures, samplers };
+  const storageBuffers = iface.storageBuffers.map(sb => ({ name: sb.name, access: sb.access }));
+  return {
+    attributes, uniforms, varyings, fragmentOutputs, textures, samplers,
+    ...(storageBuffers.length > 0 ? { storageBuffers } : {}),
+  };
 }
 
 function irTypeToWgsl(t: IrType): string {
@@ -389,6 +397,15 @@ export interface BucketLayout {
    * `atlasSample(...)` helper for these names only.
    */
   readonly atlasTextureBindings: ReadonlySet<string>;
+  /**
+   * User storage-buffer bindings (allocated from
+   * HEAP_USER_STORAGE_BINDING_BASE, above the atlas range). Bound at
+   * bucket level from `HeapDrawSpec.storageBuffers` — every RO in the
+   * bucket shares the same buffers (they are scene-level injections
+   * like the OIT node pool). FRAGMENT visibility only (WebGPU forbids
+   * writable storage in vertex stages).
+   */
+  readonly storageBindings: readonly { readonly name: string; readonly access: "read" | "read_write"; readonly binding: number }[];
 }
 
 /**
@@ -412,6 +429,8 @@ export const ATLAS_LINEAR_BINDING_BASE = 11;
 export const ATLAS_SRGB_BINDING_BASE = ATLAS_LINEAR_BINDING_BASE + ATLAS_ARRAY_SIZE;
 /** Atlas sampler binding (= linear base + 2N). */
 export const ATLAS_SAMPLER_BINDING = ATLAS_LINEAR_BINDING_BASE + 2 * ATLAS_ARRAY_SIZE;
+/** First user storage-buffer binding (above the whole atlas range). */
+export const HEAP_USER_STORAGE_BINDING_BASE = ATLAS_SAMPLER_BINDING + 1;
 
 export function buildBucketLayout(
   schema: HeapEffectSchema,
@@ -536,10 +555,18 @@ export function buildBucketLayout(
     isAtlasBucket,
   );
 
+  // User storage buffers: deterministic order (by name) starting above
+  // the atlas binding range.
+  let nextStorageBinding = HEAP_USER_STORAGE_BINDING_BASE;
+  const storageBindings = [...(schema.storageBuffers ?? [])]
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .map(sb => ({ name: sb.name, access: sb.access, binding: nextStorageBinding++ }));
+
   const base = {
     drawHeaderFields, drawHeaderBytes, preludeWgsl, strideU32,
     perInstanceUniforms, perInstanceAttributes,
     textureBindings, samplerBindings, atlasTextureBindings,
+    storageBindings,
   };
   return { id: bucketLayoutId(base), ...base };
 }
@@ -567,6 +594,7 @@ export function bucketLayoutId(l: Omit<BucketLayout, "id">): string {
   parts.push("PIA:" + [...l.perInstanceAttributes].sort().join(","));
   for (const t of l.textureBindings) parts.push(`T:${t.name}|${t.wgslType}|${t.binding}`);
   for (const s of l.samplerBindings) parts.push(`S:${s.name}|${s.wgslType}|${s.binding}`);
+  for (const sb of l.storageBindings) parts.push(`SB:${sb.name}|${sb.access}|${sb.binding}`);
   parts.push("ATB:" + [...l.atlasTextureBindings].sort().join(","));
   // The prelude is derived from the above, but fold its hash in too —
   // cheap insurance against any generator path the field list misses.

package/src/runtime/heapEffectIR.ts

@@ -20,7 +20,8 @@
 import { compileModule, stage as makeStage, effect as makeEffect } from "@aardworx/wombat.shader";
 import { isInlineHeaderField } from "./heapEffect.js";
 import type { Effect, CompileOptions } from "@aardworx/wombat.shader";
-import { substituteInputsInStage, readInputs, mapExpr, mapStmt, liftReturns, uniformsToInputs } from "@aardworx/wombat.shader/passes";
+import { substituteInputsInStage, readInputs, mapExpr, mapStmt, liftReturns, uniformsToInputs, resolveHoles } from "@aardworx/wombat.shader/passes";
+import type { HoleValue } from "@aardworx/wombat.shader/passes";
 import { synthesizeHeapDecoderModule } from "./heapDecoder.js";
 import {
   type Module, type Expr, type Stmt, type Type, type ValueDef,
@@ -1020,6 +1021,22 @@ function compileHeapEffectIRViaDecoder(
   // from the carrier varyings the decoder wrote).
   combined = rewriteFsAtlasTexturesViaCarrier(combined, layout);
 
+  // 6b. USER storage buffers (the OIT node pool & co): pin each to the
+  // slot the bucket's BGL committed to. `keep: true` makes the emitter
+  // use it verbatim (and stops `reduceUniforms` dropping an unreferenced
+  // one). Without this the emitter auto-assigns sequentially and collides
+  // with the heap's own reserved bindings.
+  if (layout.storageBindings.length > 0) {
+    const userStorageSlot = new Map(layout.storageBindings.map(b => [b.name, b.binding]));
+    combined = {
+      ...combined,
+      values: combined.values.map(v =>
+        v.kind === "StorageBuffer" && userStorageSlot.has(v.name)
+          ? { ...v, binding: { group: 0, slot: userStorageSlot.get(v.name)! }, keep: true }
+          : v),
+    };
+  }
+
   // 7. Compile.
   const compiled = compileModule(combined, compileOptions);
   if ((globalThis as { __HEAP_DEBUG_FULL__?: boolean }).__HEAP_DEBUG_FULL__) {
@@ -1566,7 +1583,24 @@ function mergeStages(eff: Effect): Module {
   // Combine all stages' templates into one module by concatenating
   // their values + types arrays. The compile pipeline's composeStages
   // pass will fuse same-stage entries afterwards.
+  //
+  // Closure holes are resolved here (per stage, with that stage's
+  // getters) — Effect.compile does this on the classic path, but the
+  // heap pipeline compiles the raw templates directly, and an
+  // unresolved `ReadInput("Closure", …)` emits as a bare identifier
+  // ("unresolved value" at pipeline compile). Constant captures like
+  // an OIT writer's node-pool capacity are the norm in composed
+  // effects.
   const types = eff.stages.flatMap(s => [...s.template.types]);
-  const values = eff.stages.flatMap(s => [...s.template.values]);
+  const values = eff.stages.flatMap(s => {
+    let hasHoles = false;
+    const sampled: Record<string, HoleValue> = {};
+    for (const [name, getter] of Object.entries(s.holes ?? {})) {
+      sampled[name] = getter();
+      hasHoles = true;
+    }
+    const filled = hasHoles ? resolveHoles(s.template, sampled) : s.template;
+    return [...filled.values];
+  });
   return { types, values };
 }

package/src/runtime/heapScene.ts

@@ -350,6 +350,14 @@ interface Bucket {
   readonly slots: BucketSlot[];
   /** Repointed by `rebuildBindGroups` whenever any backing GrowBuffer reallocates. */
   bindGroup: GPUBindGroup;
+  /** Scene-shared user storage buffers (layout.storageBindings), set on the
+   *  first addDraw that supplies them. */
+  storageBuffers: ReadonlyMap<string, aval<IBuffer>> | undefined;
+  /** Set when a storage aval marks (e.g. the OIT head buffer reallocating on
+   *  resize) — update() rebuilds this bucket's slot bind groups. */
+  storageDirty: boolean;
+  /** Disposers for the storage avals' marking subscriptions. */
+  storageSubs: (() => void)[];
 
   // Per-bucket buffers
   readonly drawHeap: DrawHeap;
@@ -579,6 +587,14 @@ export interface HeapDrawSpec {
    * alongside the effect id.
    */
   readonly textures?: HeapTextureSet;
+  /**
+   * Scene-shared storage buffers for effects that declare
+   * `var<storage>` bindings (e.g. the OIT node pool injected by the
+   * transparency task). Bound ONCE at bucket level — every RO in a
+   * bucket must supply the SAME avals (they are scene-level by
+   * construction). Buffers must be GPU-backed IBuffers.
+   */
+  readonly storageBuffers?: ReadonlyMap<string, aval<IBuffer>>;
   /**
    * Optional pipeline state (rasterizer / depth / blend). Two specs
    * sharing the SAME `PipelineState` object share a bucket; distinct
@@ -1516,6 +1532,19 @@ export function buildHeapScene(
   // that don't yet point at an allocated AtlasPage. WebGPU rejects
   // bind-group entries with `undefined` resources, so every slot in
   // the N-wide ladder must hold a valid view at all times.
+  // 4-byte placeholder storage buffer — binds user-storage slots on the
+  // seed bind group built before the first addDraw delivers the real
+  // buffers (rebuilt immediately after).
+  let storagePlaceholder: GPUBuffer | undefined;
+  function getStoragePlaceholder(): GPUBuffer {
+    if (storagePlaceholder === undefined) {
+      storagePlaceholder = device.createBuffer({
+        label: "heapScene/storagePlaceholder", size: 4, usage: GPUBufferUsage.STORAGE,
+      });
+    }
+    return storagePlaceholder;
+  }
+
   let atlasPlaceholders: Map<AtlasPageFormat, GPUTextureView> | undefined;
   function getAtlasPlaceholder(format: AtlasPageFormat): GPUTextureView {
     if (atlasPlaceholders === undefined) {
@@ -1546,6 +1575,7 @@ export function buildHeapScene(
     const key =
       `t${layout.textureBindings.map(t => t.wgslType).join(",")}` +
       `|s${layout.samplerBindings.map(s => s.wgslType).join(",")}` +
+      `|sb${layout.storageBindings.map(b => `${b.binding}${b.access === "read_write" ? "w" : "r"}`).join(",")}` +
       `|a${withAtlasArrays ? 1 : 0}`;
     let e = bglCache.get(key);
     if (e !== undefined) return e;
@@ -1576,6 +1606,14 @@ export function buildHeapScene(
         sampler: { type: s.wgslType === "sampler_comparison" ? "comparison" : "filtering" },
       });
     }
+    for (const sb of layout.storageBindings) {
+      // FRAGMENT only: WebGPU forbids writable storage in vertex stages,
+      // and the OIT writers are fragment-side anyway.
+      entries.push({
+        binding: sb.binding, visibility: GPUShaderStage.FRAGMENT,
+        buffer: { type: sb.access === "read_write" ? "storage" : "read-only-storage" },
+      });
+    }
     if (withAtlasArrays) {
       // 2N + 1 entries: N linear textures, N srgb textures, 1 sampler.
       for (let i = 0; i < ATLAS_ARRAY_SIZE; i++) {
@@ -1688,11 +1726,31 @@ export function buildHeapScene(
     const cached = pipelineByModeKey.get(cacheKey);
     if (cached !== undefined) return cached;
     const { pipelineLayout } = getBgl(layout, isAtlasBucket);
+    // Per-descriptor color targets: blend + write mask come from the RO's
+    // PipelineState (`desc.attachments`, ordered by signature colorNames —
+    // the same values the modeKey encodes). Using the bare scene-level
+    // `colorTargets` here silently dropped blends/write-masks from every
+    // heap pipeline: transparent heap leaves painted opaque, and the OIT
+    // pick passes' write-mask-0 "Colors" leaked color onto the composite.
+    const targets: GPUColorTargetState[] = colorTargets.map((t, i) => {
+      const a = desc.attachments[i];
+      if (a === undefined) return { format: t.format };
+      return {
+        format: t.format,
+        writeMask: a.writeMask,
+        ...(a.enabled
+          ? { blend: {
+                color: { operation: a.color.operation, srcFactor: a.color.srcFactor, dstFactor: a.color.dstFactor },
+                alpha: { operation: a.alpha.operation, srcFactor: a.alpha.srcFactor, dstFactor: a.alpha.dstFactor },
+              } }
+          : {}),
+      };
+    });
     const pipeline = device.createRenderPipeline({
       label: `heapScene/cached/${cacheKey}`,
       layout: pipelineLayout,
       vertex:   { module: fam.vsModule, entryPoint: fam.vsEntryName, buffers: [] },
-      fragment: { module: fam.fsModule, entryPoint: fam.fsEntryName, targets: colorTargets },
+      fragment: { module: fam.fsModule, entryPoint: fam.fsEntryName, targets },
       primitive: { topology: desc.topology, cullMode: desc.cullMode, frontFace: desc.frontFace },
       ...(depthFormat !== undefined && desc.depth !== undefined
         ? { depthStencil: { format: depthFormat, depthWriteEnabled: desc.depth.write, depthCompare: desc.depth.compare } }
@@ -2066,6 +2124,23 @@ export function buildHeapScene(
       // here — the atlas slots come from the per-format page tracking
       // below.
     }
+    for (const sb of bucket.layout.storageBindings) {
+      const av = bucket.storageBuffers?.get(sb.name);
+      if (av === undefined) {
+        // Buffers arrive with the first addDraw; the seed slot built at
+        // bucket creation is rebuilt right after they land. Bind a
+        // 4-byte placeholder so the seed bind group validates.
+        entries.push({ binding: sb.binding, resource: { buffer: getStoragePlaceholder() } });
+        continue;
+      }
+      const ib = av.force(/* allow-force */);
+      if (ib.kind !== "gpu") {
+        throw new Error(
+          `heapScene: user storage buffer '${sb.name}' must be a GPU-backed IBuffer`,
+        );
+      }
+      entries.push({ binding: sb.binding, resource: { buffer: ib.buffer } });
+    }
     if (bucket.isAtlasBucket) {
       if (atlasPool === undefined) {
         throw new Error(
@@ -3008,6 +3083,7 @@ export function buildHeapScene(
     layout.drawHeaderFields.forEach((f, i) => fieldIdx.set(f.name, i));
     const bucket: Bucket = {
       label: bk, textures: undefined, layout, chunkIdx,
+      storageBuffers: undefined, storageDirty: false, storageSubs: [],
       slots: [],  // populated lazily by ensureSlot per modeKey
       bindGroup: null as unknown as GPUBindGroup,  // legacy field; slot.bindGroup is the real one
       drawHeap,
@@ -3334,6 +3410,28 @@ export function buildHeapScene(
             : arena.attrs.openPage();
     }
     const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState, chunkIdx, precomputedDescriptor);
+    // User storage buffers (layout.storageBindings): bucket-level, set once.
+    if (bucket.layout.storageBindings.length > 0 && bucket.storageBuffers === undefined) {
+      if (spec.storageBuffers === undefined) {
+        throw new Error(
+          `heapScene: bucket '${bucket.label}' needs storage buffers ` +
+          `(${bucket.layout.storageBindings.map(b => b.name).join(", ")}) but spec.storageBuffers is undefined`,
+        );
+      }
+      bucket.storageBuffers = spec.storageBuffers;
+      // A storage aval marking (e.g. the OIT head buffer reallocating on a
+      // canvas resize) invalidates every slot bind group of this bucket.
+      for (const av of spec.storageBuffers.values()) {
+        const disposer = (av as unknown as { addMarkingCallback?: (cb: () => void) => () => void })
+          .addMarkingCallback?.(() => { bucket.storageDirty = true; });
+        if (disposer !== undefined) bucket.storageSubs.push(disposer);
+      }
+      // Slots seeded before the buffers were known carry incomplete bind
+      // groups — rebuild them now.
+      for (let i = 0; i < bucket.slots.length; i++) {
+        bucket.slots[i]!.bindGroup = buildBucketBindGroup(bucket, i);
+      }
+    }
     // Phase 5c.3 — every RO carrying a derived-mode rule is registered
     // on the bucket (lazy-promoting it to GPU-routed on the first
     // call). ROs may carry DIFFERENT rules even when they share the
@@ -4239,6 +4337,16 @@ export function buildHeapScene(
     sceneObj.evaluateAlways(token, (tok) => {
       drainAsetWith(tok);
 
+      // User storage buffers that marked (e.g. the OIT head buffer
+      // reallocating on a resize) invalidate the bucket's bind groups.
+      for (const b of buckets) {
+        if (!b.storageDirty) continue;
+        b.storageDirty = false;
+        for (let i = 0; i < b.slots.length; i++) {
+          b.slots[i]!.bindGroup = buildBucketBindGroup(b, i);
+        }
+      }
+
       // 0. Reactive rebucket: any RO whose PipelineState modeKey
       //    changed since last frame moves to its new bucket.
       //    `dirtyModeKeyDrawIds` was populated by ModeKeyTracker's

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 {
@@ -259,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 ──────────────────────
@@ -269,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 {

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) —