@aardworx/wombat.rendering 0.8.1 → 0.9.1

package/src/runtime/hybridScene.ts

@@ -0,0 +1,310 @@
+// hybridScene — composes the heap-bucket fast path with the legacy
+// per-RO path into a single render-pass renderer.
+//
+// Pipeline:
+//   1. `flattenRenderTree(tree)` → `aset<RenderObject>` (drops intra-
+//      pass ordering by contract).
+//   2. `partitionA(aset, isHeapEligible)` → (heapAset, legacyAset).
+//      Reactive: an RO migrates when its eligibility predicate marks
+//      (e.g. an `aval<IBuffer>` flips host↔gpu).
+//   3. `heapAset.map(renderObjectToHeapSpec)` → `aset<HeapDrawSpec>`,
+//      fed to `buildHeapScene`. The adapter is memoized per-RO so
+//      the same RO always maps to the same spec object — needed for
+//      delta-driven removal to identify the right entry.
+//   4. `legacyAset` wrapped as `RenderTree.unorderedFromSet(map(leaf))`
+//      and fed to `ScenePass`. Same NodeWalker machinery that the
+//      legacy `RenderTask` uses.
+//
+// Per-frame:
+//   - `update(token)` runs both backends' update phases (CPU work
+//     only — pool repacks, RO preparation).
+//   - `encodeIntoPass(passEnc, token)` runs both backends' draw
+//     emission into the caller-managed render pass.
+//
+// Order between the two batches inside the pass is irrelevant by
+// the aset contract — the framebuffer's depth/blend ops resolve any
+// apparent ordering. State changes between batches are limited to
+// pipeline + bind-group switches at the boundary; both batches retain
+// their internal amortization.
+
+import {
+  ASet, AVal, AdaptiveToken, type aset, type aval, type AdaptiveToken as _T,
+} from "@aardworx/wombat.adaptive";
+import type { CompiledEffect, Effect } from "../core/shader.js";
+import type { FramebufferSignature } from "../core/framebufferSignature.js";
+import { RenderTree } from "../core/renderTree.js";
+import type { RenderObject } from "../core/renderObject.js";
+import { ScenePass } from "./scenePass.js";
+import { flattenRenderTree } from "./flattenTree.js";
+import { isHeapEligible } from "./heapEligibility.js";
+import { renderObjectToHeapSpec } from "./heapAdapter.js";
+import { buildHeapScene, type HeapDrawSpec, type HeapScene } from "./heapScene.js";
+import type { FragmentOutputLayout } from "./heapEffect.js";
+import { AtlasPool } from "./textureAtlas/atlasPool.js";
+
+void (null as AdaptiveToken | _T | null);
+
+export interface CompileHybridSceneOptions {
+  /**
+   * Maps each fragment-output name an effect emits to its framebuffer
+   * attachment location. Used by both backends — the heap path uses
+   * it during effect introspection, the legacy path passes it to
+   * `Effect.compile`. Omitted ⇒ derive from `signature.colorNames`
+   * by index.
+   */
+  readonly fragmentOutputLayout?: FragmentOutputLayout;
+  /**
+   * Override `Effect → CompiledEffect`. Defaults to
+   * `effect.compile({ target: "wgsl", fragmentOutputLayout })` with
+   * the `fragmentOutputLayout` resolved as above. Used only by the
+   * legacy path; the heap path calls `compileHeapEffect` itself.
+   */
+  readonly compileEffect?: (e: Effect, sig: FramebufferSignature) => CompiledEffect;
+  /**
+   * Global on/off switch for the heap fast path. When `false`, every
+   * `RenderObject` routes through the legacy per-RO path regardless
+   * of its own eligibility — equivalent to forcing `isHeapEligible`
+   * to `false` for the whole scene. Reactive: flipping it migrates
+   * ROs between subsets via the existing `filterA` partition.
+   *
+   * Use cases:
+   *  - A/B perf comparisons (heap vs legacy on identical scenes).
+   *  - Quick fallback if a heap-path bug shows up on a specific
+   *    workload — flip the cval, ship.
+   *
+   * Default: `AVal.constant(true)` (heap path on for eligible ROs).
+   */
+  readonly heapEnabled?: aval<boolean>;
+  /**
+   * §6 family-merge opt-in — pass-through to `BuildHeapSceneOptions`.
+   * When true, all effects collapse into one bucket per pipelineState.
+   * Default false (per-effect buckets).
+   */
+  readonly enableFamilyMerge?: boolean;
+  /**
+   * §7 derived-uniforms opt-in — pass-through to `BuildHeapSceneOptions`.
+   */
+  readonly enableDerivedUniforms?: boolean;
+}
+
+export interface HybridScene {
+  /**
+   * Run both backends' CPU-side update phases. Idempotent within a
+   * frame. Call before opening the render pass.
+   */
+  update(token: AdaptiveToken): void;
+  /**
+   * Encode pre-pass compute work the heap path needs (drawTable GPU
+   * prefix-sum). Must be called BEFORE `beginRenderPass`. No-op when
+   * the heap path has no buckets or none are dirty.
+   */
+  encodeComputePrep(enc: GPUCommandEncoder, token: AdaptiveToken): void;
+  /**
+   * Encode draws from both backends into the caller-managed render
+   * pass. Heap batch first, legacy batch second — order is contract-
+   * irrelevant inside one pass.
+   */
+  encodeIntoPass(passEnc: GPURenderPassEncoder, token: AdaptiveToken): void;
+  /**
+   * Cheap check for "is there anything to draw?". Lets the caller
+   * skip opening the render pass entirely when both backends are
+   * empty AND no clear is requested. Must be called after `update`.
+   */
+  hasDraws(): boolean;
+  /**
+   * Number of GPU buckets the heap path is currently emitting. With
+   * §6 family-merge in v1 this typically collapses to 1 per
+   * pipelineState. Useful for status / dev-overlay text.
+   */
+  heapBucketCount(): number;
+  /** Per-frame breakdown of §7 derived-uniforms work (CPU). */
+  heapDerivedTimings(): {
+    pullMs: number; uploadMs: number; encodeMs: number; records: number;
+  };
+  /** Diagnostic: download heap state and verify drawHeader refs land in
+   *  arena, drawTable rows reference valid indices, prefix sum is
+   *  consistent, attribute alloc headers (typeId/length) are sane and
+   *  data is finite. Returns issue strings + counts. */
+  validateHeap(): Promise<{
+    arenaBytes: number; issues: string[];
+    okRefs: number; badRefs: number;
+    drawTableRows: number; drawTableErrs: number; prefixSumErrs: number;
+    attrAllocsChecked: number; attrAllocsBad: number;
+    tilesChecked: number; tilesBad: number;
+    vidChecks: number; vidBad: number;
+    indicesHash: string;
+  }>;
+  /** Per-emit CPU draw simulator — samples the global emit space,
+   *  reproduces the binary-search + (slot, _local, instId, vid)
+   *  recovery, and verifies every storage-buffer read address is
+   *  in-bounds and reads finite data. Reports any out-of-bounds. */
+  simulateDraws(samples?: number): Promise<{
+    emitsChecked: number; oob: number; issues: string[];
+  }>;
+  /** GPU-side binary-search probe — dispatches a kernel mirroring the
+   *  render VS preamble; for each sampled emit, compares GPU-resolved
+   *  slot to CPU-resolved slot. Mismatches indicate the search loop
+   *  (or one of its inputs as seen by the kernel) miscomputes. */
+  probeBinarySearch(samples?: number): Promise<{
+    emitsChecked: number; gpuMismatches: number; issues: string[];
+  }>;
+  /** Triangle-level coherence check — for each sampled triangle base,
+   *  verifies all three of its emits resolve to the same slot. */
+  checkTriangleCoherence(samples?: number): Promise<{
+    trianglesChecked: number; crossSlot: number; issues: string[];
+  }>;
+  dispose(): void;
+}
+
+function defaultFragmentOutputLayout(sig: FramebufferSignature): FragmentOutputLayout {
+  const locations = new Map<string, number>();
+  sig.colorNames.forEach((name, i) => locations.set(name, i));
+  return { locations };
+}
+
+export function compileHybridScene(
+  device: GPUDevice,
+  signature: FramebufferSignature,
+  tree: RenderTree,
+  opts: CompileHybridSceneOptions = {},
+): HybridScene {
+  const fragmentOutputLayout =
+    opts.fragmentOutputLayout ?? defaultFragmentOutputLayout(signature);
+  const compileEffect =
+    opts.compileEffect ?? ((e: Effect, _sig: FramebufferSignature) =>
+      e.compile({ target: "wgsl", fragmentOutputLayout }));
+
+  // ─── Partition ───────────────────────────────────────────────────
+  // Memoize the eligibility predicate per-RO so the two filterA calls
+  // share one underlying observation. Without this, both calls would
+  // build independent custom-avals with overlapping subscriptions.
+  // The per-RO eligibility is ANDed with the global `heapEnabled`
+  // toggle — flipping that off forces every RO to legacy.
+  const heapEnabled = opts.heapEnabled ?? AVal.constant(true);
+  const eligCache = 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));
+      eligCache.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));
+
+  // ─── Atlas pool ──────────────────────────────────────────────────
+  // Per-scene Tier-S atlas pool. Owned by this hybrid scene; disposed
+  // alongside the heap path. The adapter consults it to classify
+  // textures into Tier S (atlas-packed) vs Tier L (standalone). MVP:
+  // the adapter currently always returns Tier L (see heapAdapter
+  // comments) — the pool is wired here so the next PR can add Tier-S
+  // classification without touching this file.
+  const atlasPool = new AtlasPool(device);
+
+  // ─── Heap subset → HeapDrawSpec aset ─────────────────────────────
+  // Memoize the adapter: aset removal must identify the SAME spec
+  // object that addition produced; the underlying HashSet uses
+  // identity/equality and HeapDrawSpec is plain (no structural hash).
+  // WeakMap keyed by RO ensures the same RO always maps to the same
+  // spec instance, even if the RO migrates out and back in.
+  const specCache = new WeakMap<RenderObject, HeapDrawSpec>();
+  const heapSpecAset = heapAset.map((ro: RenderObject) => {
+    let spec = specCache.get(ro);
+    if (spec === undefined) {
+      spec = renderObjectToHeapSpec(ro, AdaptiveToken.top, atlasPool);
+      specCache.set(ro, spec);
+    }
+    return spec;
+  });
+
+  const heapScene: HeapScene = buildHeapScene(device, signature, heapSpecAset, {
+    fragmentOutputLayout,
+    atlasPool,
+    ...(opts.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
+    ...(opts.enableDerivedUniforms === true ? { enableDerivedUniforms: true } : {}),
+  });
+
+  // ─── Legacy subset → RenderTree → ScenePass ──────────────────────
+  // The unordered-from-set wrapper drops index/order info; the legacy
+  // path inherits the same "no order inside a pass" contract. Re-using
+  // the existing NodeWalker machinery means RO preparation, caching,
+  // and resource ref-counting all behave exactly as the master path.
+  const legacyTree: RenderTree =
+    RenderTree.unorderedFromSet(legacyAset.map(ro => RenderTree.leaf(ro)));
+  const scenePass = new ScenePass(device, signature, legacyTree, compileEffect);
+
+  return {
+    update(token: AdaptiveToken): void {
+      heapScene.update(token);
+      scenePass.update(token);
+    },
+    encodeComputePrep(enc: GPUCommandEncoder, token: AdaptiveToken): void {
+      heapScene.encodeComputePrep(enc, token);
+    },
+    encodeIntoPass(passEnc: GPURenderPassEncoder, token: AdaptiveToken): void {
+      heapScene.encodeIntoPass(passEnc);
+      scenePass.encodeIntoPass(passEnc, token);
+    },
+    hasDraws(): boolean {
+      // Heap path tracks count in stats; legacy path's leaf count is
+      // a cheap walker-tree scan when empty (collect into a fresh
+      // array). The sentinel here is "both empty" — caller decides
+      // whether a clear-only pass is still worth opening.
+      if (heapScene.stats.totalDraws > 0) return true;
+      return scenePass.collect().length > 0;
+    },
+    heapBucketCount(): number {
+      return heapScene.stats.groups;
+    },
+    heapDerivedTimings() {
+      const s = heapScene.stats;
+      return {
+        pullMs:   s.derivedPullMs,
+        uploadMs: s.derivedUploadMs,
+        encodeMs: s.derivedEncodeMs,
+        records:  s.derivedRecords,
+      };
+    },
+    validateHeap() {
+      return (heapScene as unknown as { _debug: { validateHeap(): Promise<{
+        arenaBytes: number; issues: string[];
+        okRefs: number; badRefs: number;
+        drawTableRows: number; drawTableErrs: number; prefixSumErrs: number;
+        attrAllocsChecked: number; attrAllocsBad: number;
+        tilesChecked: number; tilesBad: number;
+        vidChecks: number; vidBad: number;
+        indicesHash: string;
+      }> } })._debug.validateHeap();
+    },
+    simulateDraws(samples?: number) {
+      return (heapScene as unknown as { _debug: { simulateDraws(s?: number): Promise<{
+        emitsChecked: number; oob: number; issues: string[];
+      }> } })._debug.simulateDraws(samples);
+    },
+    probeBinarySearch(samples?: number) {
+      return (heapScene as unknown as { _debug: { probeBinarySearch(s?: number): Promise<{
+        emitsChecked: number; gpuMismatches: number; issues: string[];
+      }> } })._debug.probeBinarySearch(samples);
+    },
+    checkTriangleCoherence(samples?: number) {
+      return (heapScene as unknown as { _debug: { checkTriangleCoherence(s?: number): Promise<{
+        trianglesChecked: number; crossSlot: number; issues: string[];
+      }> } })._debug.checkTriangleCoherence(samples);
+    },
+    dispose(): void {
+      heapScene.dispose();
+      scenePass.dispose();
+      atlasPool.dispose();
+    },
+  };
+}
+
+// `aset` reference keeps the import live for documentation comments.
+const _asetTypeGuard: aset<unknown> | undefined = undefined;
+void _asetTypeGuard;
+// Same for ASet: re-exported here as a hint (the helper uses ASet.* internally).
+void ASet;

package/src/runtime/index.ts

@@ -33,4 +33,48 @@ export {
   type BuildHeapSceneOptions,
 } from "./heapScene.js";
 
-export { compileHeapFragment } from "./heapShader.js";
+export {
+  compileHeapEffect,
+  type CompiledHeapEffect,
+  type FragmentOutputLayout,
+} from "./heapEffect.js";
+
+export { flattenRenderTree } from "./flattenTree.js";
+export { isHeapEligible } from "./heapEligibility.js";
+export { renderObjectToHeapSpec } from "./heapAdapter.js";
+
+export {
+  compileHybridScene,
+  type CompileHybridSceneOptions,
+  type HybridScene,
+} from "./hybridScene.js";
+
+// ─── Texture atlas (heap path Tier-S texture sharing) ───────────────
+export {
+  BvhTree2d,
+  SPLIT_LIMIT_DEFAULT,
+} from "./textureAtlas/bvhTree2d.js";
+
+export {
+  TexturePacking,
+  empty as emptyTexturePacking,
+  isEmpty as isEmptyTexturePacking,
+  count as countTexturePacking,
+  occupancy as texturePackingOccupancy,
+  square as squareTexturePacking,
+  tryAddMany as texturePackingTryAddMany,
+  tryOfArray as texturePackingTryOfArray,
+} from "./textureAtlas/packer.js";
+
+export {
+  AtlasPool,
+  ATLAS_PAGE_SIZE,
+  ATLAS_MAX_DIM,
+  ATLAS_MAX_PAGES_PER_FORMAT,
+  ATLAS_PAGE_FORMATS,
+  atlasFormatIndex,
+  type AtlasPage,
+  type AtlasPageFormat,
+  type AtlasAcquisition,
+  type AtlasSource,
+} from "./textureAtlas/atlasPool.js";

package/src/runtime/renderTask.ts

@@ -26,7 +26,7 @@ import {
 import { beginPassDescriptor, clear } from "../commands/index.js";
 import { AdaptiveToken, type alist, type aval } from "@aardworx/wombat.adaptive";
 import { copy } from "./copy.js";
-import { ScenePass } from "./scenePass.js";
+import { compileHybridScene, type HybridScene } from "./hybridScene.js";
 
 export interface RuntimeContext {
   readonly device: GPUDevice;
@@ -37,50 +37,177 @@ export interface RuntimeContext {
    * `linkFragmentOutputs` pass uses it to re-pin and DCE outputs.
    */
   readonly compileEffect: (effect: Effect, signature: FramebufferSignature) => CompiledEffect;
+  /**
+   * Global heap on/off toggle propagated to every `HybridScene`
+   * compiled against this context. Flipping it causes every RO to
+   * migrate between the heap subset and the legacy subset.
+   * Useful for A/B perf comparisons.
+   */
+  readonly heapEnabled?: aval<boolean>;
+  /**
+   * §6 family-merge opt-in — propagated to every HybridScene
+   * compiled against this context. Default: merge off.
+   */
+  readonly enableFamilyMerge?: boolean;
+  /**
+   * §7 derived-uniforms opt-in — propagated to every HybridScene
+   * compiled against this context.
+   */
+  readonly enableDerivedUniforms?: boolean;
 }
 
 class RenderTask implements IRenderTask {
   /**
-   * Cache of `ScenePass`es keyed on the `Render` command itself.
-   * Holding ScenePass per command means the same `RenderTree`
-   * reused across frames keeps its incrementally-maintained
-   * walker state.
+   * Cache of `HybridScene`s keyed on the `Render` command itself.
+   * Each command compiles to a hybrid scene composing the heap-
+   * bucket fast path with the legacy per-RO path; reuse across
+   * frames preserves both backends' incremental state.
    */
-  private readonly _scenes = new Map<unknown, ScenePass>();
+  private readonly _scenes = new Map<unknown, HybridScene>();
   private _disposed = false;
 
   constructor(
     private readonly ctx: RuntimeContext,
+    readonly signature: FramebufferSignature,
     private readonly commands: alist<Command>,
   ) {}
 
-  run(token: AdaptiveToken): void {
+  run(framebuffer: IFramebuffer, token: AdaptiveToken): void {
     if (this._disposed) throw new Error("RenderTask: run after dispose");
     const enc = this.ctx.device.createCommandEncoder();
-    this.encode(enc, token);
+    this.encode(enc, framebuffer, token);
     this.ctx.device.queue.submit([enc.finish()]);
   }
 
-  encode(enc: GPUCommandEncoder, token: AdaptiveToken): void {
+  encode(enc: GPUCommandEncoder, framebuffer: IFramebuffer, token: AdaptiveToken): void {
     if (this._disposed) throw new Error("RenderTask: encode after dispose");
     RenderContext.withEncoder(enc, () => {
       const arr: Command[] = [];
       for (const c of this.commands.content.getValue(token)) arr.push(c);
       for (let i = 0; i < arr.length; i++) {
         const c = arr[i]!;
+        // Coalesce a Clear immediately followed by a Render: both
+        // share the run-arg framebuffer now (no per-cmd output to
+        // disambiguate), so the merge is unconditional when the
+        // pair is adjacent.
         if (c.kind === "Clear") {
           const next = arr[i + 1];
-          if (next !== undefined && next.kind === "Render" && next.output === c.output) {
-            this.encodeRenderCommand(enc, next, token, c.values);
+          if (next !== undefined && next.kind === "Render") {
+            this.encodeRenderCommand(enc, next, framebuffer, token, c.values);
             i++;
             continue;
           }
         }
-        this.encodeCommand(enc, c, token);
+        this.encodeCommand(enc, c, framebuffer, token);
       }
     });
   }
 
+  heapBucketCount(): number {
+    let total = 0;
+    for (const s of this._scenes.values()) total += s.heapBucketCount();
+    return total;
+  }
+
+  heapDerivedTimings(): {
+    pullMs: number; uploadMs: number; encodeMs: number; records: number;
+  } {
+    let pullMs = 0, uploadMs = 0, encodeMs = 0, records = 0;
+    for (const s of this._scenes.values()) {
+      const t = s.heapDerivedTimings();
+      pullMs   += t.pullMs;
+      uploadMs += t.uploadMs;
+      encodeMs += t.encodeMs;
+      records  += t.records;
+    }
+    return { pullMs, uploadMs, encodeMs, records };
+  }
+
+  async validateHeap(): Promise<{
+    arenaBytes: number; issues: string[];
+    okRefs: number; badRefs: number;
+    drawTableRows: number; drawTableErrs: number; prefixSumErrs: number;
+    attrAllocsChecked: number; attrAllocsBad: number;
+    tilesChecked: number; tilesBad: number;
+    vidChecks: number; vidBad: number;
+    indicesHash: string;
+  }> {
+    let arenaBytes = 0, okRefs = 0, badRefs = 0;
+    let drawTableRows = 0, drawTableErrs = 0, prefixSumErrs = 0;
+    let attrAllocsChecked = 0, attrAllocsBad = 0;
+    let tilesChecked = 0, tilesBad = 0;
+    let vidChecks = 0, vidBad = 0;
+    const indicesHashes: string[] = [];
+    const issues: string[] = [];
+    for (const s of this._scenes.values()) {
+      const r = await s.validateHeap();
+      arenaBytes += r.arenaBytes;
+      okRefs += r.okRefs;
+      badRefs += r.badRefs;
+      drawTableRows += r.drawTableRows;
+      drawTableErrs += r.drawTableErrs;
+      prefixSumErrs += r.prefixSumErrs;
+      attrAllocsChecked += r.attrAllocsChecked;
+      attrAllocsBad += r.attrAllocsBad;
+      tilesChecked += r.tilesChecked;
+      tilesBad += r.tilesBad;
+      vidChecks += r.vidChecks;
+      vidBad += r.vidBad;
+      indicesHashes.push(r.indicesHash);
+      for (const i of r.issues) issues.push(i);
+    }
+    return {
+      arenaBytes, issues, okRefs, badRefs,
+      drawTableRows, drawTableErrs, prefixSumErrs,
+      attrAllocsChecked, attrAllocsBad,
+      tilesChecked, tilesBad,
+      vidChecks, vidBad,
+      indicesHash: indicesHashes.join(","),
+    };
+  }
+
+  async simulateDraws(samples?: number): Promise<{
+    emitsChecked: number; oob: number; issues: string[];
+  }> {
+    let emitsChecked = 0, oob = 0;
+    const issues: string[] = [];
+    for (const s of this._scenes.values()) {
+      const r = await s.simulateDraws(samples);
+      emitsChecked += r.emitsChecked;
+      oob += r.oob;
+      for (const i of r.issues) issues.push(i);
+    }
+    return { emitsChecked, oob, issues };
+  }
+
+  async probeBinarySearch(samples?: number): Promise<{
+    emitsChecked: number; gpuMismatches: number; issues: string[];
+  }> {
+    let emitsChecked = 0, gpuMismatches = 0;
+    const issues: string[] = [];
+    for (const s of this._scenes.values()) {
+      const r = await s.probeBinarySearch(samples);
+      emitsChecked += r.emitsChecked;
+      gpuMismatches += r.gpuMismatches;
+      for (const i of r.issues) issues.push(i);
+    }
+    return { emitsChecked, gpuMismatches, issues };
+  }
+
+  async checkTriangleCoherence(samples?: number): Promise<{
+    trianglesChecked: number; crossSlot: number; issues: string[];
+  }> {
+    let trianglesChecked = 0, crossSlot = 0;
+    const issues: string[] = [];
+    for (const s of this._scenes.values()) {
+      const r = await s.checkTriangleCoherence(samples);
+      trianglesChecked += r.trianglesChecked;
+      crossSlot += r.crossSlot;
+      for (const i of r.issues) issues.push(i);
+    }
+    return { trianglesChecked, crossSlot, issues };
+  }
+
   dispose(): void {
     if (this._disposed) return;
     for (const s of this._scenes.values()) s.dispose();
@@ -88,54 +215,62 @@ class RenderTask implements IRenderTask {
     this._disposed = true;
   }
 
-  private encodeCommand(enc: GPUCommandEncoder, c: Command, token: AdaptiveToken): void {
+  private encodeCommand(
+    enc: GPUCommandEncoder, c: Command, framebuffer: IFramebuffer, token: AdaptiveToken,
+  ): void {
     switch (c.kind) {
-      case "Clear":  clear(enc, c.output.getValue(token), c.values); return;
+      case "Clear":  clear(enc, framebuffer, c.values); return;
       case "Copy":   copy(enc, c.copy); return;
       case "Custom": c.encode(enc); return;
-      case "Render": this.encodeRenderCommand(enc, c, token); return;
+      case "Render": this.encodeRenderCommand(enc, c, framebuffer, token); return;
     }
   }
 
   private encodeRenderCommand(
     enc: GPUCommandEncoder,
     cmd: Extract<Command, { kind: "Render" }>,
+    framebuffer: IFramebuffer,
     token: AdaptiveToken,
     clearValues?: ClearValues,
   ): void {
-    const output = cmd.output.getValue(token);
-    const scene = this.sceneFor(cmd, output, cmd.tree);
-    const leaves = scene.resolve(token);
-    if (leaves.length === 0 && clearValues === undefined) return;
+    const scene = this.sceneFor(cmd, cmd.tree);
+    scene.update(token);
+    if (!scene.hasDraws() && clearValues === undefined) return;
+    // Compute prep (drawTable prefix-sum) must happen outside any
+    // render pass — encode it before we open the pass.
+    scene.encodeComputePrep(enc, token);
     // Either we have draws or we need to clear — open a single pass.
-    const pass = enc.beginRenderPass(beginPassDescriptor(output, clearValues));
-    for (const leaf of leaves) leaf.record(pass, token);
+    const pass = enc.beginRenderPass(beginPassDescriptor(framebuffer, clearValues));
+    scene.encodeIntoPass(pass, token);
     pass.end();
   }
 
   private sceneFor(
     cmd: Extract<Command, { kind: "Render" }>,
-    output: IFramebuffer,
     tree: RenderTree,
-  ): ScenePass {
+  ): HybridScene {
     let s = this._scenes.get(cmd);
     if (s === undefined) {
-      s = new ScenePass(this.ctx.device, output.signature, tree, this.ctx.compileEffect);
+      s = compileHybridScene(this.ctx.device, this.signature, tree, {
+        compileEffect: this.ctx.compileEffect,
+        ...(this.ctx.heapEnabled !== undefined ? { heapEnabled: this.ctx.heapEnabled } : {}),
+        ...(this.ctx.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
+        ...(this.ctx.enableDerivedUniforms === true ? { enableDerivedUniforms: true } : {}),
+      });
       this._scenes.set(cmd, s);
     }
     return s;
-    // Note: `output.signature` is read here only to seed the
-    // ScenePass; subsequent frames continue to use this signature
-    // even if the framebuffer aval emits a different sig. That
-    // matches the `(RenderObject, signature)` cache invariant —
-    // changing signature requires a fresh Render command.
   }
 }
 
-export function compileRenderTask(ctx: RuntimeContext, commands: alist<Command>): IRenderTask & {
-  encode(enc: GPUCommandEncoder, token: AdaptiveToken): void;
+export function compileRenderTask(
+  ctx: RuntimeContext,
+  signature: FramebufferSignature,
+  commands: alist<Command>,
+): IRenderTask & {
+  encode(enc: GPUCommandEncoder, framebuffer: IFramebuffer, token: AdaptiveToken): void;
 } {
-  return new RenderTask(ctx, commands);
+  return new RenderTask(ctx, signature, commands);
 }
 
 // `RenderTree` carries an `aval<RenderTree>` inside its `Adaptive`