@aardworx/wombat.rendering 0.19.24 → 0.19.25

package/src/runtime/flattenTree.ts

@@ -19,6 +19,49 @@ import { AListBridges } from "@aardworx/wombat.adaptive";
 import type { RenderObject } from "../core/renderObject.js";
 import type { RenderTree } from "../core/renderTree.js";
 
+/** True when `tree` contains no reactive nodes — its RenderObjects can
+ *  be enumerated as a plain iterable (no inner aset / reader needed). */
+function isStaticTree(tree: RenderTree): boolean {
+  switch (tree.kind) {
+    case "Empty":
+    case "Leaf":
+      return true;
+    case "Ordered":
+    case "Unordered":
+      return tree.children.every(isStaticTree);
+    default:
+      return false;
+  }
+}
+
+/** Enumerate a static subtree's RenderObjects (pre: `isStaticTree`). */
+function* staticObjects(tree: RenderTree): Iterable<RenderObject> {
+  switch (tree.kind) {
+    case "Empty":
+      return;
+    case "Leaf":
+      yield tree.object;
+      return;
+    case "Ordered":
+    case "Unordered":
+      for (const c of tree.children) yield* staticObjects(c);
+      return;
+    default:
+      throw new Error(`staticObjects: reactive node '${tree.kind}'`);
+  }
+}
+
+/** Flatten a reactive container of subtrees. The static children go
+ *  through `collectSeq` (plain iterables — ONE reader for the whole
+ *  set, instead of a ConstantAset + reader + subscription PER LEAF,
+ *  which at heap scale was megabytes of ballast); reactive children
+ *  keep the full `collect`. */
+function flattenChildSet(children: aset<RenderTree>): aset<RenderObject> {
+  const staticPart = children.filter(isStaticTree).collectSeq(staticObjects);
+  const reactivePart = children.filter(t => !isStaticTree(t)).collect(flattenRenderTree);
+  return ASet.union(staticPart, reactivePart);
+}
+
 export function flattenRenderTree(tree: RenderTree): aset<RenderObject> {
   switch (tree.kind) {
     case "Empty":
@@ -27,6 +70,8 @@ export function flattenRenderTree(tree: RenderTree): aset<RenderObject> {
       return ASet.single(tree.object);
     case "Ordered":
     case "Unordered": {
+      // Fully-static subtree → one constant aset over a plain array.
+      if (isStaticTree(tree)) return ASet.ofArray([...staticObjects(tree)]);
       // N-ary union via `unionMany(aset<aset<T>>)`. The naïve
       // `children.reduce(ASet.union)` builds a 2N-deep nested-union
       // tree; the reader's traversal recurses through it and blows
@@ -39,8 +84,8 @@ export function flattenRenderTree(tree: RenderTree): aset<RenderObject> {
     case "Adaptive":
       return ASet.bind(flattenRenderTree, tree.tree);
     case "OrderedFromList":
-      return ASet.collect(flattenRenderTree, AListBridges.toASet(tree.children));
+      return flattenChildSet(AListBridges.toASet(tree.children));
     case "UnorderedFromSet":
-      return ASet.collect(flattenRenderTree, tree.children);
+      return flattenChildSet(tree.children);
   }
 }

package/src/runtime/heapAdapter.ts

@@ -113,6 +113,8 @@ import type { HeapDrawSpec, HeapTextureSet } from "./heapScene.js";
 import { isBufferView } from "./heapScene/pools.js";
 import { compileHeapEffect } from "./heapEffect.js";
 import { AtlasPool } from "./textureAtlas/atlasPool.js";
+import { STANDARD_DERIVED_RULES, STANDARD_TRAFO_LEAVES } from "./derivedUniforms/recipes.js";
+import { inputsOf } from "./derivedUniforms/flatten.js";
 
 /**
  * View `HostBufferSource` as `Uint32Array`. Index buffers are u32 in
@@ -326,6 +328,7 @@ export function renderObjectToHeapSpec(
   ro: RenderObject,
   token: AdaptiveToken,
   pool?: AtlasPool,
+  opts?: { readonly enableDerivedUniforms?: boolean },
 ): HeapDrawSpec {
   // 1. Inputs map: vertex attributes (BufferView) + uniforms, pulled
   //    SHADER-DRIVEN from the providers. We compile `ro.effect` (cached
@@ -356,12 +359,38 @@ export function renderObjectToHeapSpec(
     const av = uProv.tryGet(name);
     if (av !== undefined) inputs[name] = av;
   };
-  for (const u of schema.uniforms) pullUniform(u.name);
+  // §7-covered derived trafos (ModelViewProjTrafo, NormalMatrix, …) are
+  // GPU-computed from the M/V/P constituents — addDraw never reads their
+  // `spec.inputs` entry when the rule applies. Deferring the pull keeps
+  // the provider from materialising a per-RO derived-aval chain (MapVal +
+  // nested closure contexts + a never-forced lazy constant) that would sit
+  // in `inputs` as pure ballast. Pulled after all as a fallback only when
+  // the recipe's base leaves turn out not to be bound (mirrors
+  // heapScene's `ruleForUniform` applicability test).
+  const deriveOnGpu = opts?.enableDerivedUniforms !== false;
+  const deferredDerived: string[] = [];
+  for (const u of schema.uniforms) {
+    if (deriveOnGpu && STANDARD_DERIVED_RULES.has(u.name)) {
+      deferredDerived.push(u.name);
+      continue;
+    }
+    pullUniform(u.name);
+  }
   // §7 derived-uniforms constituents — cheap (these are the raw
   // `state.model/view/proj` avals, no `compose`/`inverse`) and the
   // compute pre-pass needs them even when the effect itself doesn't
   // declare them. No-ops if the provider doesn't carry them.
   for (const n of ["ModelTrafo", "ViewTrafo", "ProjTrafo"]) pullUniform(n);
+  for (const name of deferredDerived) {
+    const rule = STANDARD_DERIVED_RULES.get(name)!;
+    let leavesBound = true;
+    for (const inp of inputsOf(rule.ir)) {
+      if (inp.name === "Model" && ro.modelChain !== undefined) continue;
+      const specName = STANDARD_TRAFO_LEAVES.get(inp.name) ?? inp.name;
+      if (inputs[specName] === undefined) { leavesBound = false; break; }
+    }
+    if (!leavesBound) pullUniform(name);
+  }
 
   // 1b. Instance attributes — provider is map-backed (user-supplied via
   //     `Sg.instanced({attributes})`), so enumerate its names. Threaded
@@ -399,9 +428,11 @@ export function renderObjectToHeapSpec(
   //    WGSL schema's binding shape doesn't matter at scene time — that
   //    leaves us with two HashMap entries pointing at the same aval.
   //    Dedupe by identity before applying the single-pair rule.
-  const distinctTexAvals = new Set<aval<ITexture>>();
-  ro.textures.iter((_n, av) => { distinctTexAvals.add(av as aval<ITexture>); });
-  const distinctSamplerAvals = new Set<aval<ISampler>>();
+  // `let` + nulled after use: the spec's long-lived closures share
+  // this scope context — a leftover Set here is per-RO ballast.
+  let distinctTexAvals: Set<aval<ITexture>> | undefined = new Set<aval<ITexture>>();
+  ro.textures.iter((_n, av) => { distinctTexAvals!.add(av as aval<ITexture>); });
+  let distinctSamplerAvals: Set<aval<ISampler>> | undefined = new Set<aval<ISampler>>();
   // Shader-defined sampler state (from a `sampler2d { filter …; addressU … }`
   // builder, carried through the IR) overrides the scene's default sampler.
   const stateBinding = schema.samplers.find(b => b.state !== undefined);
@@ -418,7 +449,7 @@ export function renderObjectToHeapSpec(
       AVal.constant(ISampler.fromDescriptor(desc)) as aval<ISampler>,
     );
   } else {
-    ro.samplers.iter((_n, av) => { distinctSamplerAvals.add(av as aval<ISampler>); });
+    ro.samplers.iter((_n, av) => { distinctSamplerAvals!.add(av as aval<ISampler>); });
   }
   let textures: HeapTextureSet | undefined;
   if (distinctTexAvals.size === 1 && distinctSamplerAvals.size === 1) {
@@ -531,6 +562,9 @@ export function renderObjectToHeapSpec(
       `single-pair only in v1 (classifier should have caught this)`,
     );
   }
+  // Drop the dedup scratch — see the `let` note above.
+  distinctTexAvals = undefined;
+  distinctSamplerAvals = undefined;
 
   // 4. DrawCall geometry. Classifier validates fields are heap-
   //    compatible (instanceCount≥1, firstInstance=0, non-indexed firstVertex=0).
@@ -550,6 +584,7 @@ export function renderObjectToHeapSpec(
 
   return {
     effect: ro.effect,
+    ...(ro.pickId !== undefined ? { pickId: ro.pickId } : {}),
     pipelineState: ro.pipelineState,
     inputs,
     ...(instanceAttributes !== undefined ? { instanceAttributes } : {}),

package/src/runtime/heapDecoder.ts

@@ -46,6 +46,7 @@ import {
   Tu32, Tf32,
 } from "@aardworx/wombat.shader/ir";
 import type { BucketLayout, DrawHeaderField } from "./heapEffect.js";
+import { isInlineHeaderField } from "./heapEffect.js";
 import {
   Tvec2, Tvec3, Tvec4, Tmat4, TarrU32,
   constU32, add, mul, div, item, newVec, readScope,
@@ -307,9 +308,13 @@ function addUniformOutput(
   }
   const irType = wgslTypeToIrType(wgslType);
   const refExpr = loadHeaderRef(drawIdxExpr, f.byteOffset, layout.strideU32);
-  const value = layout.perInstanceUniforms.has(f.name)
-    ? loadInstanceByRef(refExpr, instIdExpr, wgslType)
-    : loadUniformByRef(refExpr, wgslType);
+  // Inline fields (PickId, __layoutId family): the header word IS the
+  // u32 value — no arena indirection, no pool entry per draw.
+  const value = isInlineHeaderField(f)
+    ? refExpr
+    : layout.perInstanceUniforms.has(f.name)
+      ? loadInstanceByRef(refExpr, instIdExpr, wgslType)
+      : loadUniformByRef(refExpr, wgslType);
 
   outputs.push({
     name: f.name,

package/src/runtime/heapEffect.ts

@@ -104,7 +104,21 @@ 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 = "h2";
+export const HEAP_PERSIST_VERSION = "h4"; // h4: inline PickId drawHeader read (was h3: packed decode arms)
+
+/**
+ * Uniforms whose drawHeader word IS the u32 value (no arena
+ * indirection, no pool entry, no per-RO aval) — the `__layoutId`
+ * mechanism generalised. Values come from first-class RenderObject
+ * fields (`ro.pickId`), not the uniform provider. Fields must be
+ * u32-typed.
+ */
+export const INLINE_HEADER_UNIFORMS: ReadonlySet<string> = new Set(["PickId"]);
+
+/** True for fields read inline from the drawHeader word. */
+export function isInlineHeaderField(f: { kind: string; name: string }): boolean {
+  return f.kind === "uniform-ref" && (f.name === "__layoutId" || INLINE_HEADER_UNIFORMS.has(f.name));
+}
 export const HEAP_PERSIST_PREFIX = "wbt.heapfx.";
 
 export function persistKey(version: string, kind: string, contentKey: string): string {

package/src/runtime/heapEffectIR.ts

@@ -18,6 +18,7 @@
 // consumes is identical to the one heapScene.ts already builds.
 
 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 { synthesizeHeapDecoderModule } from "./heapDecoder.js";
@@ -278,9 +279,12 @@ function buildVertexUniformMap(layout: BucketLayout): Map<string, Expr> {
   for (const f of layout.drawHeaderFields) {
     if (f.kind !== "uniform-ref") continue;
     const refExpr = loadHeaderRef(drawIdx, f.byteOffset, stride);
-    const value = layout.perInstanceUniforms.has(f.name)
-      ? loadInstanceByRef(refExpr, iidx, f.uniformWgslType ?? "")
-      : loadUniformByRef(refExpr, f.uniformWgslType ?? "");
+    // Inline fields: the header word IS the u32 value.
+    const value = isInlineHeaderField(f)
+      ? refExpr
+      : layout.perInstanceUniforms.has(f.name)
+        ? loadInstanceByRef(refExpr, iidx, f.uniformWgslType ?? "")
+        : loadUniformByRef(refExpr, f.uniformWgslType ?? "");
     out.set(f.name, value);
   }
   return out;
@@ -420,9 +424,11 @@ function rewriteFsUniformsDirect(m: Module, layout: BucketLayout): Module {
     const f = fieldByName.get(name);
     if (f === undefined || f.kind !== "uniform-ref") continue;
     const refExpr = loadHeaderRef(drawIdxExpr, f.byteOffset, layout.strideU32);
-    const value = layout.perInstanceUniforms.has(name)
-      ? loadInstanceByRef(refExpr, instIdExpr, f.uniformWgslType ?? "")
-      : loadUniformByRef(refExpr, f.uniformWgslType ?? "");
+    const value = isInlineHeaderField(f)
+      ? refExpr
+      : layout.perInstanceUniforms.has(name)
+        ? loadInstanceByRef(refExpr, instIdExpr, f.uniformWgslType ?? "")
+        : loadUniformByRef(refExpr, f.uniformWgslType ?? "");
     fsSubst.set(name, value);
   }
   return substituteInputsInStage(m, "fragment", "Uniform", n => fsSubst.get(n));
@@ -541,9 +547,12 @@ function rewriteFsUniforms(m: Module, layout: BucketLayout): Module {
       value: { kind: "Expr", value: refExprWriter },
     });
     const refReadFs = readScope("Input", refParamName, Tu32);
-    const value = layout.perInstanceUniforms.has(name)
-      ? loadInstanceByRef(refReadFs, readScope("Input", "_iidx", Tu32), f.uniformWgslType ?? "")
-      : loadUniformByRef(refReadFs, f.uniformWgslType ?? "");
+    // Inline fields: the threaded varying already carries the value.
+    const value = isInlineHeaderField(f)
+      ? refReadFs
+      : layout.perInstanceUniforms.has(name)
+        ? loadInstanceByRef(refReadFs, readScope("Input", "_iidx", Tu32), f.uniformWgslType ?? "")
+        : loadUniformByRef(refReadFs, f.uniformWgslType ?? "");
     fsSubst.set(name, value);
   }
 

package/src/runtime/heapEligibility.ts

@@ -34,7 +34,7 @@
 // grows feature support each becomes a per-buffer eligibility
 // question instead of a blanket "no".
 
-import { AVal, type aval } from "@aardworx/wombat.adaptive";
+import { AVal, AdaptiveToken, type aval } from "@aardworx/wombat.adaptive";
 import type { IBuffer } from "../core/buffer.js";
 import type { BufferView } from "../core/bufferView.js";
 import type { ITexture } from "../core/texture.js";
@@ -174,14 +174,14 @@ export function isHeapEligible(ro: RenderObject): aval<boolean> {
   // per-RO path, which at scale (thousands of textured ROs ⇒ thousands
   // of draw calls + bind-group switches) is far slower than the heap
   // megacall sampling one shared atlas page.
-  const distinctTextureAvals = new Set<aval<ITexture>>();
-  ro.textures.iter((_n, av) => { distinctTextureAvals.add(av); });
-  if (distinctTextureAvals.size > 1) {
+  // NOTE identity-dedup WITHOUT a Set: the long-lived AVal.custom
+  // closure below shares this function's V8 scope context, so any
+  // temporary Set here would be retained per-RO for the scene's
+  // lifetime (measured: 1 Set/RO of pure ballast at heap scale).
+  if (countDistinct(ro.textures) > 1) {
     return AVal.constant(false);
   }
-  const distinctSamplerAvals = new Set<aval<ISampler>>();
-  ro.samplers.iter((_n, av) => { distinctSamplerAvals.add(av); });
-  if (distinctSamplerAvals.size > 1) {
+  if (countDistinct(ro.samplers) > 1) {
     return AVal.constant(false);
   }
 
@@ -202,11 +202,16 @@ export function isHeapEligible(ro: RenderObject): aval<boolean> {
   const textures = textureAvals(ro);
   const samplers = samplerAvals(ro);
 
-  // Reactive AND-fold over all participating avals. We also subscribe
-  // to drawCall (instanceCount/baseVertex/firstIndex/firstInstance
-  // can flip; if they violate heap constraints the RO routes to the
-  // legacy path that frame).
-  return AVal.custom(token => {
+  // Constant collapse: when every participating aval is constant the
+  // answer can never change — evaluate once and return a plain
+  // constant. This keeps the hybrid partition from holding a custom
+  // aval + subscriptions per static RO (the overwhelmingly common
+  // case at heap scale).
+  let allConstant = ro.drawCall.isConstant;
+  if (allConstant) for (const av of buffers)  { if (!av.isConstant) { allConstant = false; break; } }
+  if (allConstant) for (const av of textures) { if (!av.isConstant) { allConstant = false; break; } }
+  if (allConstant) for (const av of samplers) { if (!av.isConstant) { allConstant = false; break; } }
+  const evaluate = (token: AdaptiveToken): boolean => {
     let payloadBytes = 0;
     for (const av of buffers) {
       const b = av.getValue(token);
@@ -240,5 +245,27 @@ export function isHeapEligible(ro: RenderObject): aval<boolean> {
       if (dc.firstVertex !== 0) return false;
     }
     return true;
+  };
+  if (allConstant) return AVal.constant(evaluate(AdaptiveToken.top));
+  // Reactive AND-fold over all participating avals. We also subscribe
+  // to drawCall (instanceCount/baseVertex/firstIndex/firstInstance
+  // can flip; if they violate heap constraints the RO routes to the
+  // legacy path that frame).
+  return AVal.custom(evaluate);
+}
+
+
+/** Count distinct avals in a name→aval map by identity, allocation-free
+ *  for the 0/1/2-distinct cases that matter (we only compare > 1). */
+function countDistinct(m: { iter(f: (n: string, av: aval<unknown>) => void): void }): number {
+  let first: aval<unknown> | undefined;
+  let second: aval<unknown> | undefined;
+  let n = 0;
+  m.iter((_n, av) => {
+    if (av === first || av === second) return;
+    if (first === undefined) { first = av; n = 1; }
+    else if (second === undefined) { second = av; n = 2; }
+    else n++;
   });
+  return n;
 }

package/src/runtime/heapIrBuilders.ts

@@ -62,6 +62,23 @@ export const shr = (lhs: Expr, rhs: Expr, type: Type): Expr => ({
 export const select = (cond: Expr, ifTrue: Expr, ifFalse: Expr, type: Type): Expr => ({
   kind: "Conditional", cond, ifTrue, ifFalse, type,
 });
+export const bitAnd = (lhs: Expr, rhs: Expr, type: Type): Expr => ({
+  kind: "BitAnd", lhs, rhs, type,
+});
+export const ltF32 = (lhs: Expr, rhs: Expr): Expr => ({ kind: "Lt", lhs, rhs, type: Tbool });
+export const geF32 = (lhs: Expr, rhs: Expr): Expr => ({ kind: "Ge", lhs, rhs, type: Tbool });
+/** u32 → f32 numeric conversion. */
+export const toF32 = (value: Expr): Expr => ({ kind: "Convert", value, type: Tf32 } as Expr);
+/** Pure WGSL/GLSL intrinsic call (same emit name unless glsl differs). */
+const callIntrinsic = (wgsl: string, glsl: string, ret: Type, args: Expr[]): Expr => ({
+  kind: "CallIntrinsic",
+  op: { name: wgsl, returnTypeOf: () => ret, pure: true, emit: { wgsl, glsl } },
+  args, type: ret,
+} as Expr);
+export const absF32 = (e: Expr): Expr => callIntrinsic("abs", "abs", Tf32, [e]);
+export const normalize3 = (e: Expr): Expr => callIntrinsic("normalize", "normalize", Tvec3, [e]);
+export const unpack4x8unorm = (e: Expr): Expr =>
+  callIntrinsic("unpack4x8unorm", "unpackUnorm4x8", Tvec4, [e]);
 export const newVec = (components: Expr[], type: Type): Expr => ({
   kind: "NewVector", components, type,
 });
@@ -174,14 +191,40 @@ export function loadAttributeByRef(refIdent: Expr, idx: Expr, wgslType: string):
     const length = item(heapU32, add(div(refIdent, constU32(4), Tu32), constU32(1), Tu32), Tu32);
     return mul(mod(idx, length, Tu32), constU32(elemSize), Tu32);
   };
+  /** Header typeId (word 0 — same 16-byte cache line as the length the
+   *  broadcast modulo already loads, so the packed-encoding branch costs
+   *  no extra memory round-trip and is warp-coherent per field). */
+  const typeId = item(heapU32, div(refIdent, constU32(4), Tu32), Tu32);
+  /** One u32 element at the cyclic index (packed encodings: 4 B/elt). */
+  const packedWord = (): Expr => add(dataF32Base, cyclic(1), Tu32);
   switch (wgslType) {
     case "vec3<f32>": {
       const base = add(dataF32Base, cyclic(3), Tu32);
-      return newVec([
+      const tight = newVec([
         item(heapF32, base, Tf32),
         item(heapF32, add(base, constU32(1), Tu32), Tf32),
         item(heapF32, add(base, constU32(2), Tu32), Tf32),
       ], Tvec3);
+      // ENC_OCT32 (typeId 2): one u32/element — x = low unorm16, y = high
+      // unorm16, both → [-1,1]; octahedral fold when z<0 (matches
+      // build_vienna.py's oct_pack and the CPU decoder in renderbench).
+      const u = item(heapU32, packedWord(), Tu32);
+      const toSnorm = (word: Expr): Expr =>
+        add(mul(toF32(word), constF32(2 / 65535), Tf32), constF32(-1.0), Tf32);
+      const fx = toSnorm(bitAnd(u, constU32(0xffff), Tu32));
+      const fy = toSnorm(shr(u, constU32(16), Tu32));
+      const z = sub(sub(constF32(1.0), absF32(fx), Tf32), absF32(fy), Tf32);
+      const neg = ltF32(z, constF32(0.0));
+      const signOf = (v: Expr): Expr =>
+        select(geF32(v, constF32(0.0)), constF32(1.0), constF32(-1.0), Tf32);
+      const fold = (a: Expr, b: Expr): Expr =>   // (1-|b|) * sign(a)
+        mul(sub(constF32(1.0), absF32(b), Tf32), signOf(a), Tf32);
+      const oct = normalize3(newVec([
+        select(neg, fold(fx, fy), fx, Tf32),
+        select(neg, fold(fy, fx), fy, Tf32),
+        z,
+      ], Tvec3));
+      return select(eqU32(typeId, constU32(2 /* ENC_OCT32 */)), oct, tight, Tvec3);
     }
     case "vec4<f32>": {
       const strideBytes = item(heapU32, add(div(refIdent, constU32(4), Tu32), constU32(2), Tu32), Tu32);
@@ -190,12 +233,17 @@ export function loadAttributeByRef(refIdent: Expr, idx: Expr, wgslType: string):
       const off = mul(cycled, strideF, Tu32);
       const base = add(dataF32Base, off, Tu32);
       const w = select(eqU32(strideF, constU32(4)), item(heapF32, add(base, constU32(3), Tu32), Tf32), constF32(1.0), Tf32);
-      return newVec([
+      const tight = newVec([
         item(heapF32, base, Tf32),
         item(heapF32, add(base, constU32(1), Tu32), Tf32),
         item(heapF32, add(base, constU32(2), Tu32), Tf32),
         w,
       ], Tvec4);
+      // ENC_C4B (typeId 3): one u32/element, RGBA8 unorm — a single
+      // hardware unpack. (Vienna colours ship as C4b; storing them raw is
+      // 4 B/vertex instead of the 12 B tight-RGB expansion.)
+      const c4b = unpack4x8unorm(item(heapU32, packedWord(), Tu32));
+      return select(eqU32(typeId, constU32(3 /* ENC_C4B */)), c4b, tight, Tvec4);
     }
     case "vec2<f32>": {
       const base = add(dataF32Base, cyclic(2), Tu32);

package/src/runtime/heapScene/chunkedArena.ts

@@ -14,7 +14,7 @@
 
 import type { IDisposable } from "@aardworx/wombat.adaptive";
 import { GrowBuffer, DEFAULT_MAX_BUFFER_BYTES } from "./growBuffer.js";
-import { AttributeArena, IndexAllocator } from "./pools.js";
+import { AttributeArena } from "./pools.js";
 
 /** Address inside a chunked arena. */
 export interface ChunkedRef {
@@ -46,6 +46,15 @@ export class ChunkedAttributeArena {
   get chunks(): ReadonlyArray<AttributeArena> { return this._chunks; }
   chunk(i: number): AttributeArena { return this._chunks[i]!; }
 
+  /** Bump headroom (bytes) of chunk `i` — free space before its cap, used by
+   *  group placement. Out-of-range → 0. */
+  bumpHeadroom(i: number): number {
+    return i >= 0 && i < this._chunks.length ? this._chunks[i]!.bumpHeadroom : 0;
+  }
+  /** Open a fresh empty chunk (page) and return its index. Used by group
+   *  placement when no existing chunk can hold a draw's whole group. */
+  openPage(): number { return this.openChunk(); }
+
   /**
    * Allocate `dataBytes` of attribute storage. Tries the `hint`
    * chunk first when given (caller passes the RO's chunk to keep all
@@ -81,12 +90,12 @@ export class ChunkedAttributeArena {
     c.release(off, dataBytes);
   }
 
-  /** Push the dirty CPU shadow of every chunk to its GPU buffer. */
+  /** No-op (mirror-less arena — writes upload immediately). Kept for API compat. */
   flush(device: GPUDevice): void {
     for (const c of this._chunks) c.flush(device);
   }
 
-  /** Write into a specific chunk's CPU shadow. */
+  /** Write into a specific chunk (immediate GPU upload). */
   write(chunkIdx: number, dst: number, data: Uint8Array): void {
     this._chunks[chunkIdx]!.write(dst, data);
   }
@@ -124,100 +133,25 @@ export class ChunkedAttributeArena {
     return s;
   }
 
-  destroy(): void {
-    for (const c of this._chunks) c.destroy();
-    this._chunks.length = 0;
-  }
-
-  private openChunk(): number {
-    const idx = this._chunks.length;
-    const buf = new GrowBuffer(
-      this.device, `${this.label}/c${idx}`, this.usage,
-      this.initialChunkBytes, this.maxChunkBytes,
-    );
-    this._chunks.push(new AttributeArena(buf));
-    for (const cb of this.onChunkAddedCbs) cb(idx);
-    return idx;
-  }
-}
-
-/** Multi-chunk wrapper around `IndexAllocator`. Element-bump units
- *  are u32. Same chunk-open / hint / fallback semantics as
- *  `ChunkedAttributeArena`. */
-export class ChunkedIndexAllocator {
-  private readonly _chunks: IndexAllocator[] = [];
-  private readonly onChunkAddedCbs = new Set<(chunkIdx: number) => void>();
-
-  constructor(
-    private readonly device: GPUDevice,
-    private readonly label: string,
-    private readonly usage: GPUBufferUsageFlags,
-    private readonly initialChunkBytes: number,
-    private readonly maxChunkBytes: number = DEFAULT_MAX_BUFFER_BYTES,
-  ) {
-    this.openChunk();
-  }
-
-  get chunkCount(): number { return this._chunks.length; }
-  get chunks(): ReadonlyArray<IndexAllocator> { return this._chunks; }
-  chunk(i: number): IndexAllocator { return this._chunks[i]!; }
-
-  alloc(elements: number, hint?: number): ChunkedRef {
-    if (hint !== undefined && hint >= 0 && hint < this._chunks.length) {
-      const off = this._chunks[hint]!.tryAlloc(elements);
-      if (off !== undefined) return { chunkIdx: hint, off };
-    }
-    for (let i = this._chunks.length - 1; i >= 0; i--) {
-      if (i === hint) continue;
-      const off = this._chunks[i]!.tryAlloc(elements);
-      if (off !== undefined) return { chunkIdx: i, off };
-    }
-    const newIdx = this.openChunk();
-    const off = this._chunks[newIdx]!.tryAlloc(elements);
-    if (off === undefined) {
-      throw new Error(
-        `ChunkedIndexAllocator '${this.label}': allocation of ${elements} elements exceeds maxChunkBytes/4 ${this.maxChunkBytes / 4}`,
-      );
-    }
-    return { chunkIdx: newIdx, off };
-  }
-
-  release(chunkIdx: number, off: number, elements: number): void {
-    const c = this._chunks[chunkIdx];
-    if (c === undefined) return;
-    c.release(off, elements);
-  }
-
-  flush(device: GPUDevice): void {
-    for (const c of this._chunks) c.flush(device);
-  }
-
-  write(chunkIdx: number, dst: number, data: Uint8Array): void {
-    this._chunks[chunkIdx]!.write(dst, data);
-  }
-
-  onChunkAdded(cb: (chunkIdx: number) => void): IDisposable {
-    this.onChunkAddedCbs.add(cb);
-    return { dispose: () => { this.onChunkAddedCbs.delete(cb); } };
+  /** Total fragmentation waste across all chunks (diagnostic / trigger). */
+  totalWasteBytes(): number {
+    let s = 0;
+    for (const c of this._chunks) s += c.wasteBytes;
+    return s;
   }
 
-  onAnyResize(cb: (chunkIdx: number) => void): IDisposable {
-    const disposables: IDisposable[] = [];
+  /** Waste-triggered compaction across every chunk. Returns one entry per
+   *  chunk that actually relocated data — `remap` maps OLD→NEW byte offset
+   *  within that chunk. Empty array when nothing was worth compacting. The
+   *  caller must have flushed pending arena writes first (the GPU copy reads
+   *  the live buffers). */
+  compact(device: GPUDevice, wasteFloorBytes: number, force = false): Array<{ chunkIdx: number; remap: Map<number, number> }> {
+    const out: Array<{ chunkIdx: number; remap: Map<number, number> }> = [];
     for (let i = 0; i < this._chunks.length; i++) {
-      const idx = i;
-      disposables.push(this._chunks[i]!.onResize(() => cb(idx)));
+      const remap = this._chunks[i]!.compact(device, wasteFloorBytes, force);
+      if (remap.size > 0) out.push({ chunkIdx: i, remap });
     }
-    disposables.push(this.onChunkAdded((idx) => {
-      disposables.push(this._chunks[idx]!.onResize(() => cb(idx)));
-      cb(idx);
-    }));
-    return { dispose: () => { for (const d of disposables) d.dispose(); } };
-  }
-
-  totalUsedElements(): number {
-    let s = 0;
-    for (const c of this._chunks) s += c.usedElements;
-    return s;
+    return out;
   }
 
   destroy(): void {
@@ -231,8 +165,9 @@ export class ChunkedIndexAllocator {
       this.device, `${this.label}/c${idx}`, this.usage,
       this.initialChunkBytes, this.maxChunkBytes,
     );
-    this._chunks.push(new IndexAllocator(buf));
+    this._chunks.push(new AttributeArena(this.device, buf));
     for (const cb of this.onChunkAddedCbs) cb(idx);
     return idx;
   }
 }
+

package/src/runtime/heapScene/freelist.ts

@@ -1,5 +1,5 @@
-// Freelist — best-fit free-block manager used by AttributeArena and
-// IndexAllocator. Replaces the earlier `{off,size}[]` sorted-by-off
+// Freelist — best-fit free-block manager used by AttributeArena.
+// Replaces the earlier `{off,size}[]` sorted-by-off
 // freelist (whose alloc was O(N) first-fit and release was O(log N)
 // binary-search-then-coalesce).
 //
@@ -94,7 +94,7 @@ export class Freelist {
   /**
    * Take and remove the free block whose end offset is exactly
    * `endOff`, if any exists. Used by `AttributeArena` /
-   * `IndexAllocator` to shrink the bump cursor back when releases
+   * `AttributeArena` to shrink the bump cursor back when releases
    * expose a free tail (§5 — cursor-shrink hygiene for long-lived
    * high-churn scenes).
    */