@aardworx/wombat.rendering 0.9.15 → 0.9.17

package/src/runtime/derivedModes/modeKeyCpu.ts

@@ -20,7 +20,7 @@ import type {
 } from "../../core/pipelineState.js";
 import type { FramebufferSignature } from "../../core/framebufferSignature.js";
 import type { aval, IDisposable } from "@aardworx/wombat.adaptive";
-import { addMarkingCallback } from "@aardworx/wombat.adaptive";
+import { addMarkingCallback, AdaptiveToken } from "@aardworx/wombat.adaptive";
 
 import {
   encodeModeKey,
@@ -31,6 +31,42 @@ import {
   type BlendComponent,
   type DepthSlice,
 } from "../pipelineCache/index.js";
+import type { DerivedModeRule } from "./rule.js";
+
+/**
+ * Per-axis derived-mode rules for one RO. Same shape as
+ * `HeapDrawSpec.modeRules`.
+ */
+export interface RoModeRules {
+  readonly cull?:            DerivedModeRule<"cull">;
+  readonly frontFace?:       DerivedModeRule<"frontFace">;
+  readonly topology?:        DerivedModeRule<"topology">;
+  readonly depthCompare?:    DerivedModeRule<"depthCompare">;
+  readonly depthWrite?:      DerivedModeRule<"depthWrite">;
+  readonly alphaToCoverage?: DerivedModeRule<"alphaToCoverage">;
+}
+
+/**
+ * Uniforms accessor exposed to a derived-mode rule's `(u, declared)`
+ * closure. Reads each `u.<Name>` from the supplied aval map at
+ * evaluation time and tracks which avals were accessed so the
+ * `ModeKeyTracker` can subscribe to them.
+ */
+function uniformsProxy(
+  uniformAvals: ReadonlyMap<string, aval<unknown>>,
+  tok: AdaptiveToken,
+  recordDep: ((av: aval<unknown>) => void) | undefined,
+): Record<string, unknown> {
+  return new Proxy({}, {
+    get(_target, prop): unknown {
+      if (typeof prop !== "string") return undefined;
+      const av = uniformAvals.get(prop);
+      if (av === undefined) return undefined;
+      if (recordDep !== undefined) recordDep(av);
+      return av.getValue(tok);
+    },
+  }) as Record<string, unknown>;
+}
 
 /**
  * One-shot snapshot of the current values of every leaf aval in a
@@ -42,9 +78,15 @@ import {
 export function snapshotDescriptor(
   ps: PipelineState | undefined,
   signature: FramebufferSignature,
+  options: {
+    readonly modeRules?: RoModeRules;
+    readonly uniformAvals?: ReadonlyMap<string, aval<unknown>>;
+    readonly token?: AdaptiveToken;
+    readonly recordDep?: (av: aval<unknown>) => void;
+  } = {},
 ): PipelineStateDescriptor {
   if (ps === undefined) {
-    return buildAttachmentsFor(DEFAULT_DESCRIPTOR, signature);
+    return applyRules(buildAttachmentsFor(DEFAULT_DESCRIPTOR, signature), options);
   }
   const r = ps.rasterizer;
   const depth = ps.depth !== undefined ? snapshotDepth(ps.depth, signature) : undefined;
@@ -63,6 +105,52 @@ export function snapshotDescriptor(
     attachments,
     alphaToCoverage: atc,
   };
+  return applyRules(out, options);
+}
+
+function applyRules(
+  d: PipelineStateDescriptor,
+  options: {
+    readonly modeRules?: RoModeRules;
+    readonly uniformAvals?: ReadonlyMap<string, aval<unknown>>;
+    readonly token?: AdaptiveToken;
+    readonly recordDep?: (av: aval<unknown>) => void;
+  },
+): PipelineStateDescriptor {
+  const rules = options.modeRules;
+  if (rules === undefined) return d;
+  const uniforms = options.uniformAvals ?? new Map();
+  const tok = options.token ?? AdaptiveToken.top;
+  const proxy = uniformsProxy(uniforms, tok, options.recordDep);
+  let out = d;
+  if (rules.cull !== undefined) {
+    const v = rules.cull.evaluate(proxy, out.cullMode);
+    if (v !== out.cullMode) out = { ...out, cullMode: v };
+  }
+  if (rules.frontFace !== undefined) {
+    const v = rules.frontFace.evaluate(proxy, out.frontFace);
+    if (v !== out.frontFace) out = { ...out, frontFace: v };
+  }
+  if (rules.topology !== undefined) {
+    const v = rules.topology.evaluate(proxy, out.topology);
+    if (v !== out.topology) out = { ...out, topology: v, stripIndexFormat: stripFormatFor(v) };
+  }
+  if (rules.alphaToCoverage !== undefined) {
+    const v = rules.alphaToCoverage.evaluate(proxy, out.alphaToCoverage);
+    if (v !== out.alphaToCoverage) out = { ...out, alphaToCoverage: v };
+  }
+  if (out.depth !== undefined && (rules.depthCompare !== undefined || rules.depthWrite !== undefined)) {
+    let depthOut = out.depth;
+    if (rules.depthCompare !== undefined) {
+      const v = rules.depthCompare.evaluate(proxy, depthOut.compare);
+      if (v !== depthOut.compare) depthOut = { ...depthOut, compare: v };
+    }
+    if (rules.depthWrite !== undefined) {
+      const v = rules.depthWrite.evaluate(proxy, depthOut.write);
+      if (v !== depthOut.write) depthOut = { ...depthOut, write: v };
+    }
+    if (depthOut !== out.depth) out = { ...out, depth: depthOut };
+  }
   return out;
 }
 
@@ -131,18 +219,81 @@ export class ModeKeyTracker implements IDisposable {
   private readonly subs: IDisposable[] = [];
   private cachedDescriptor: PipelineStateDescriptor;
   private cachedModeKey: bigint;
+  private readonly modeRules: RoModeRules | undefined;
+  private readonly uniformAvals: ReadonlyMap<string, aval<unknown>> | undefined;
+  /** Avals discovered while evaluating rules; merged into the leaf
+   *  set returned by `forEachLeaf` so the heap scene subscribes once. */
+  private readonly ruleDeps = new Set<aval<unknown>>();
 
   constructor(
     ps: PipelineState | undefined,
     signature: FramebufferSignature,
     onDirty: () => void,
+    /**
+     * Skip the per-instance addMarkingCallback subscriptions. The caller
+     * is responsible for invoking `onDirty` (or recomputing directly)
+     * when an input aval marks. Use this when the heap scene shares one
+     * subscription across N tracker instances (the 20k-ROs-share-one-
+     * cullCval case) — saves N subscriptions and N callback dispatches
+     * per mark.
+     */
+    options: {
+      skipSubscribe?: boolean;
+      modeRules?: RoModeRules;
+      uniformAvals?: ReadonlyMap<string, aval<unknown>>;
+    } = {},
   ) {
     this.ps        = ps;
     this.signature = signature;
     this.onDirty   = onDirty;
-    this.cachedDescriptor = snapshotDescriptor(ps, signature);
+    if (options.modeRules    !== undefined) this.modeRules    = options.modeRules;
+    if (options.uniformAvals !== undefined) this.uniformAvals = options.uniformAvals;
+    this.cachedDescriptor = this.snapshot();
     this.cachedModeKey    = encodeModeKey(this.cachedDescriptor);
-    this.subscribeAll();
+    if (options.skipSubscribe !== true) this.subscribeAll();
+  }
+
+  private snapshot(): PipelineStateDescriptor {
+    return snapshotDescriptor(this.ps, this.signature, {
+      ...(this.modeRules    !== undefined ? { modeRules:    this.modeRules    } : {}),
+      ...(this.uniformAvals !== undefined ? { uniformAvals: this.uniformAvals } : {}),
+      recordDep: (av) => { this.ruleDeps.add(av); },
+    });
+  }
+
+  /**
+   * Walk every leaf aval in this tracker's PipelineState and invoke
+   * `visit(aval)`. Used by the heap scene to register ONE
+   * addMarkingCallback per unique aval across many trackers.
+   */
+  forEachLeaf(visit: (a: aval<unknown>) => void): void {
+    const ps = this.ps;
+    if (ps !== undefined) {
+      visit(ps.rasterizer.topology);
+      visit(ps.rasterizer.cullMode);
+      visit(ps.rasterizer.frontFace);
+      if (ps.rasterizer.depthBias !== undefined) visit(ps.rasterizer.depthBias);
+      if (ps.depth !== undefined) {
+        visit(ps.depth.write);
+        visit(ps.depth.compare);
+        if (ps.depth.clamp !== undefined) visit(ps.depth.clamp);
+      }
+      if (ps.blends !== undefined) {
+        visit(ps.blends);
+        const map = ps.blends.force(/* allow-force */);
+        for (const [, bs] of map) {
+          visit(bs.color.srcFactor); visit(bs.color.dstFactor); visit(bs.color.operation);
+          visit(bs.alpha.srcFactor); visit(bs.alpha.dstFactor); visit(bs.alpha.operation);
+          visit(bs.writeMask);
+        }
+      }
+      if (ps.alphaToCoverage !== undefined) visit(ps.alphaToCoverage);
+    }
+    // Rule-input deps discovered on the last evaluation. The set is
+    // refreshed each `recompute()`; callers re-subscribe accordingly.
+    // Surfaced regardless of `ps` because a rule can fire without
+    // any underlying PipelineState aval (e.g. ps === undefined).
+    for (const av of this.ruleDeps) visit(av);
   }
 
   get descriptor(): PipelineStateDescriptor { return this.cachedDescriptor; }
@@ -152,9 +303,15 @@ export class ModeKeyTracker implements IDisposable {
    * Snapshot current aval values and rebuild descriptor + modeKey.
    * Returns true iff the modeKey changed (so the bucket only needs to
    * upload + repartition when something actually moved).
+   *
+   * Also rediscovers rule-input dependencies on every call — a
+   * conditional rule body may read different uniforms in different
+   * branches. New deps surface in `forEachLeaf` so the heap scene's
+   * subscription-dedupe layer picks them up.
    */
   recompute(): boolean {
-    const next = snapshotDescriptor(this.ps, this.signature);
+    this.ruleDeps.clear();
+    const next = this.snapshot();
     const nextKey = encodeModeKey(next);
     if (nextKey === this.cachedModeKey) return false;
     this.cachedDescriptor = next;

package/src/runtime/derivedModes/rule.ts

@@ -0,0 +1,110 @@
+// `derivedMode(axis, (u, declared) => modeValue)` — author-facing
+// marker for per-RO pipeline-state values that are functions of the
+// RO's uniforms.
+//
+// v1 is CPU-evaluated: the user's closure runs in JS each time the
+// rule's inputs mark. That's a good fit for the typical authoring
+// shapes (a uniform-driven enum flip, a determinant-sign cull flip,
+// etc.) and pairs naturally with the bucket-level rebuild fast path
+// shipped in 0.9.16 — only ROs whose inputs actually changed get
+// re-evaluated, and same-key buckets re-bind their pipeline once
+// rather than per-RO.
+//
+// v2 (deferred) lowers rules to a GPU compute kernel via §7's IR
+// machinery — needed only when bulk-animated per-RO inputs become a
+// CPU-side bottleneck. See docs/derived-mode-rules-plan.md.
+//
+// What can be derived (the small-enum axes — cull/blend/depth-compare/
+// topology/etc.) and what stays static (depth bias, blend constant,
+// stencil ref) is covered in docs/derived-modes.md.
+
+import type { CullMode, FrontFace, Topology } from "../pipelineCache/index.js";
+
+/** Discrete pipeline-state axes a `derivedMode` rule can target. v1
+ *  supports cull / frontFace / topology / depthCompare / depthWrite /
+ *  blendEnabled. Stencil + per-attachment blend factor/operation are
+ *  deferred — same carve-outs as `derived-modes.md`. */
+export type ModeAxis =
+  | "cull" | "frontFace" | "topology"
+  | "depthCompare" | "depthWrite"
+  | "alphaToCoverage";
+
+/** Output value type per axis. */
+export type ModeValue<A extends ModeAxis> =
+  A extends "cull"           ? CullMode :
+  A extends "frontFace"      ? FrontFace :
+  A extends "topology"       ? Topology :
+  A extends "depthCompare"   ? GPUCompareFunction :
+  A extends "depthWrite"     ? boolean :
+  A extends "alphaToCoverage" ? boolean :
+  never;
+
+/**
+ * The closure signature a `derivedMode` rule body takes:
+ *   - `u`: a proxy whose properties resolve to the RO's uniform values
+ *     at evaluation time. The proxy is type-erased in v1 — declare the
+ *     uniforms you'll read via `UniformScope` augmentation on the
+ *     wombat.shader side for compile-time safety, or annotate locally.
+ *   - `declared`: the SG-declared value for this axis at this leaf.
+ *     Identity rules `(u, d) => d` are valid and useful for axes that
+ *     want to pass declared through unchanged.
+ */
+export type DerivedModeBuilder<A extends ModeAxis> = (
+  u: Record<string, unknown>,
+  declared: ModeValue<A>,
+) => ModeValue<A>;
+
+export interface DerivedModeRule<A extends ModeAxis = ModeAxis> {
+  readonly __derivedModeRule: true;
+  readonly axis:    A;
+  readonly evaluate: DerivedModeBuilder<A>;
+  /**
+   * Conservative over-approximation of the rule's output set. Used by
+   * the build-time pre-warm in v2 to enumerate the pipelines a scene
+   * could realize. v1 doesn't use it at runtime, but recording it
+   * here keeps the API forward-compatible.
+   */
+  readonly domain?: ReadonlyArray<ModeValue<A>>;
+}
+
+/**
+ * Author a derived mode rule.
+ *
+ *     derivedMode("cull", (u, declared) =>
+ *       u.WindingFlipped ? flipCull(declared) : declared);
+ *
+ *     derivedMode("blend", (u) => u.Premultiplied ? "premul" : "straight");
+ *
+ *     // Determinant-flip-cull (the motivating case):
+ *     derivedMode("cull", (u, declared) => {
+ *       const m = u.ModelTrafo as M44d;
+ *       const det =
+ *         m.M00 * (m.M11 * m.M22 - m.M12 * m.M21) -
+ *         m.M01 * (m.M10 * m.M22 - m.M12 * m.M20) +
+ *         m.M02 * (m.M10 * m.M21 - m.M11 * m.M20);
+ *       return det < 0 ? flipCull(declared) : declared;
+ *     });
+ */
+export function derivedMode<A extends ModeAxis>(
+  axis: A,
+  evaluate: DerivedModeBuilder<A>,
+  options: { readonly domain?: ReadonlyArray<ModeValue<A>> } = {},
+): DerivedModeRule<A> {
+  const out: DerivedModeRule<A> = options.domain !== undefined
+    ? { __derivedModeRule: true, axis, evaluate, domain: options.domain }
+    : { __derivedModeRule: true, axis, evaluate };
+  return out;
+}
+
+/** Brand check — distinguishes a DerivedModeRule from an aval/raw value
+ *  at runtime so PipelineState consumers can route accordingly. */
+export function isDerivedModeRule(x: unknown): x is DerivedModeRule {
+  return typeof x === "object" && x !== null
+      && (x as { __derivedModeRule?: unknown }).__derivedModeRule === true;
+}
+
+/** Convenience: flip 'back' ↔ 'front' (and pass through 'none').
+ *  Useful in `(u, declared) => mirrored ? flipCull(declared) : declared`. */
+export function flipCull(c: CullMode): CullMode {
+  return c === "back" ? "front" : c === "front" ? "back" : "none";
+}

package/src/runtime/heapScene.ts

@@ -92,8 +92,9 @@ import {
   ENC_V3F_TIGHT, SEM_POSITIONS, SEM_NORMALS,
   type ArenaState,
 } from "./heapScene/pools.js";
-import { encodeModeKey } from "./pipelineCache/index.js";
+import { encodeModeKey, type PipelineStateDescriptor } from "./pipelineCache/index.js";
 import { snapshotDescriptor, ModeKeyTracker } from "./derivedModes/modeKeyCpu.js";
+import { addMarkingCallback } from "@aardworx/wombat.adaptive";
 
 // GrowBuffer + ALIGN16 + MIN_BUFFER_BYTES + POW2 live in ./heapScene/growBuffer.
 // Packers (WGSL-type → JS-value → arena bytes) live in ./heapScene/packers.
@@ -340,6 +341,38 @@ export interface HeapDrawSpec {
    * with depth write enabled. Matches the demo's existing visuals.
    */
   readonly pipelineState?: PipelineState;
+  /**
+   * Per-RO derived pipeline-mode rules: per-axis closures
+   * `(u, declared) => modeValue` that compute the effective mode
+   * value as a function of this RO's uniforms (see
+   * `derivedMode(...)` in `runtime/derivedModes/rule.ts`).
+   *
+   * A rule overrides the corresponding `pipelineState.rasterizer.*`
+   * (or `pipelineState.depth.*`) aval value at descriptor-snapshot
+   * time. The rule's closure runs CPU-side with a proxy that
+   * resolves `u.<Name>` against this spec's `inputs[<Name>]`. The
+   * heap renderer auto-discovers the closure's input dependencies on
+   * first run and subscribes the per-RO ModeKeyTracker to each of
+   * them — so a rule that reads `u.ModelTrafo` reactively rebuckets
+   * when ModelTrafo marks.
+   *
+   * Common use cases:
+   *   - cull: flip-by-determinant-sign for mirrored geometry
+   *   - blend: pick a preset based on a boolean uniform
+   *   - depthCompare: lighter passes for transparent overlays
+   *
+   * v1 evaluates rules CPU-side. v2 (deferred) lowers them to a GPU
+   * compute kernel for the bulk-animated-input case. See
+   * `docs/derived-modes.md`.
+   */
+  readonly modeRules?: {
+    readonly cull?:           import("./derivedModes/rule.js").DerivedModeRule<"cull">;
+    readonly frontFace?:      import("./derivedModes/rule.js").DerivedModeRule<"frontFace">;
+    readonly topology?:       import("./derivedModes/rule.js").DerivedModeRule<"topology">;
+    readonly depthCompare?:   import("./derivedModes/rule.js").DerivedModeRule<"depthCompare">;
+    readonly depthWrite?:     import("./derivedModes/rule.js").DerivedModeRule<"depthWrite">;
+    readonly alphaToCoverage?: import("./derivedModes/rule.js").DerivedModeRule<"alphaToCoverage">;
+  };
 }
 
 export interface HeapSceneStats {
@@ -578,11 +611,45 @@ export function buildHeapScene(
    * references.
    */
   const drawIdToSpec:        (HeapDrawSpec | undefined)[] = [];
-  /** Per-draw ModeKeyTracker — subscribes to PS aval marks, recomputes
-   *  the modeKey, schedules a rebucket if it changed. */
+  /** Per-draw ModeKeyTracker — recomputes the modeKey on demand. Does
+   *  NOT install per-instance marking callbacks; subscriptions are
+   *  scene-level (deduped by aval identity below). */
   const drawIdToModeTracker: (ModeKeyTracker | undefined)[] = [];
   /** drawIds whose PS marked since last update; drained by `update`. */
   const dirtyModeKeyDrawIds = new Set<number>();
+  /**
+   * Scene-level mode-aval subscription dedupe. One IDisposable per
+   * unique leaf aval, plus a Set of dependent drawIds. When the aval
+   * marks, all drawIds in the set become dirty in O(1) per RO instead
+   * of installing N separate addMarkingCallbacks. The big win for the
+   * shared-cullCval case (20k ROs subscribing to one cval → 1 callback
+   * instead of 20k).
+   */
+  const modeAvalToDrawIds  = new Map<aval<unknown>, Set<number>>();
+  const modeAvalCallbacks  = new Map<aval<unknown>, IDisposable>();
+
+  function subscribeModeLeaf(av: aval<unknown>, drawId: number): void {
+    let set = modeAvalToDrawIds.get(av);
+    if (set === undefined) {
+      set = new Set<number>();
+      modeAvalToDrawIds.set(av, set);
+      modeAvalCallbacks.set(av, addMarkingCallback(av, () => {
+        for (const id of set!) dirtyModeKeyDrawIds.add(id);
+      }));
+    }
+    set.add(drawId);
+  }
+
+  function unsubscribeModeLeaf(av: aval<unknown>, drawId: number): void {
+    const set = modeAvalToDrawIds.get(av);
+    if (set === undefined) return;
+    set.delete(drawId);
+    if (set.size === 0) {
+      modeAvalToDrawIds.delete(av);
+      const cb = modeAvalCallbacks.get(av);
+      if (cb !== undefined) { cb.dispose(); modeAvalCallbacks.delete(av); }
+    }
+  }
   let nextDrawId = 0;
 
   /**
@@ -1438,6 +1505,13 @@ export function buildHeapScene(
     effect: Effect,
     _textures: HeapTextureSet | undefined,
     pipelineState: PipelineState | undefined,
+    /**
+     * Optional precomputed descriptor. addDrawImpl passes this when
+     * the spec carries `modeRules` so the bucket key reflects the
+     * rule-evaluated value (not the raw PS aval values). When omitted
+     * the descriptor is snapshotted from PS as before.
+     */
+    precomputedDescriptor?: PipelineStateDescriptor,
   ): Bucket {
     if (!familyBuilt) {
       throw new Error("heapScene: findOrCreateBucket called before family build");
@@ -1451,12 +1525,24 @@ export function buildHeapScene(
     // (the actual value-set in the descriptor), so identical-value
     // cvals collapse to ONE bucket. See docs/derived-modes.md and
     // tests/heap-multi-pipeline-bucket.test.ts.
-    const psDescriptor = snapshotDescriptor(pipelineState, sig);
+    const psDescriptor = precomputedDescriptor ?? snapshotDescriptor(pipelineState, sig);
     const psModeKey    = encodeModeKey(psDescriptor);
     const bk = `family#${fam.schema.id}|mk#${psModeKey.toString(16)}`;
     const existing = bucketByKey.get(bk);
     if (existing !== undefined) return existing;
-    const ps = resolvePipelineState(pipelineState);
+    // If a precomputed descriptor is supplied (rule-evaluated path),
+    // use its post-rule axis values so the pipeline reflects what the
+    // RO actually wants. Otherwise fall through to PS-aval forcing.
+    const ps: ResolvedPipelineState = precomputedDescriptor !== undefined
+      ? {
+          topology:  precomputedDescriptor.topology,
+          cullMode:  precomputedDescriptor.cullMode,
+          frontFace: precomputedDescriptor.frontFace,
+          ...(precomputedDescriptor.depth !== undefined
+            ? { depth: { write: precomputedDescriptor.depth.write, compare: precomputedDescriptor.depth.compare } }
+            : {}),
+        }
+      : resolvePipelineState(pipelineState);
 
     const layout: BucketLayout = fam.schema.drawHeaderUnion;
     const isAtlasBucket = layout.atlasTextureBindings.size > 0;
@@ -1765,7 +1851,24 @@ export function buildHeapScene(
     const perInstanceAttributes = spec.instanceAttributes !== undefined
       ? new Set(Object.keys(spec.instanceAttributes))
       : new Set<string>();
-    const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState);
+
+    // If the spec has modeRules, pre-snapshot the rule-evaluated
+    // descriptor so the bucket key + pipeline reflect post-rule
+    // values. Without this, two ROs with identical PS but different
+    // rule outputs would collide on the same bucket.
+    let precomputedDescriptor: PipelineStateDescriptor | undefined;
+    if (spec.modeRules !== undefined) {
+      const uAvals = new Map<string, aval<unknown>>();
+      for (const [name, val] of Object.entries(spec.inputs)) {
+        uAvals.set(name, asAval(val as aval<unknown> | unknown));
+      }
+      precomputedDescriptor = snapshotDescriptor(spec.pipelineState, sig, {
+        modeRules:    spec.modeRules,
+        uniformAvals: uAvals,
+        token:        outerTok,
+      });
+    }
+    const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState, precomputedDescriptor);
     const fam = familyFor(spec.effect);
     const effectFields = fam.fieldsForEffect.get(spec.effect.id)!;
 
@@ -1947,10 +2050,31 @@ export function buildHeapScene(
     // value must move the RO to a different bucket. Without this
     // tracker the cval flip would be silently ignored.
     drawIdToSpec[drawId] = spec;
-    const tracker = new ModeKeyTracker(spec.pipelineState, sig, () => {
-      dirtyModeKeyDrawIds.add(drawId);
-    });
+    // skipSubscribe: this tracker doesn't install its own callbacks.
+    // The scene-level `modeAvalToDrawIds` does it once per unique aval
+    // (the 20k-ROs-share-one-cullCval optimization).
+    // If the spec has modeRules, pre-build a uniforms-aval map the
+    // rule closures will read against; the tracker auto-discovers
+    // which avals each rule reads and surfaces them via forEachLeaf.
+    let uniformAvals: ReadonlyMap<string, aval<unknown>> | undefined;
+    if (spec.modeRules !== undefined) {
+      const m = new Map<string, aval<unknown>>();
+      for (const [name, val] of Object.entries(spec.inputs)) {
+        m.set(name, asAval(val as aval<unknown> | unknown));
+      }
+      uniformAvals = m;
+    }
+    const tracker = new ModeKeyTracker(
+      spec.pipelineState, sig,
+      () => { dirtyModeKeyDrawIds.add(drawId); },
+      {
+        skipSubscribe: true,
+        ...(spec.modeRules  !== undefined ? { modeRules: spec.modeRules } : {}),
+        ...(uniformAvals    !== undefined ? { uniformAvals } : {}),
+      },
+    );
     drawIdToModeTracker[drawId] = tracker;
+    tracker.forEachLeaf((av) => subscribeModeLeaf(av, drawId));
 
     // ─── §7 derived-uniforms registration ────────────────────────────
     // A uniform binding on this RO is either a value (aval/constant) or a rule —
@@ -2106,7 +2230,10 @@ export function buildHeapScene(
     drawIdToIndexAval[drawId] = undefined;
     drawIdToSpec[drawId]      = undefined;
     const oldTracker = drawIdToModeTracker[drawId];
-    if (oldTracker !== undefined) oldTracker.dispose();
+    if (oldTracker !== undefined) {
+      oldTracker.forEachLeaf((av) => unsubscribeModeLeaf(av, drawId));
+      oldTracker.dispose();
+    }
     drawIdToModeTracker[drawId] = undefined;
     dirtyModeKeyDrawIds.delete(drawId);
 
@@ -2212,20 +2339,90 @@ export function buildHeapScene(
       if (dirtyModeKeyDrawIds.size > 0) {
         const dirty = [...dirtyModeKeyDrawIds];
         dirtyModeKeyDrawIds.clear();
+
+        // Bucket-level fast path: group dirty drawIds by bucket. If
+        // ALL of a bucket's ROs are dirty (typical SG case where one
+        // shared aval drives every leaf — e.g. <Sg CullMode={cullC}>
+        // wrapping 20k leaves), the whole bucket transitions together.
+        // Rebuild the bucket's pipeline + rename in bucketByKey,
+        // O(1) work instead of N remove+add cycles.
+        const byBucket = new Map<Bucket, number[]>();
         for (const drawId of dirty) {
-          const tracker = drawIdToModeTracker[drawId];
-          if (tracker === undefined) continue;          // RO removed since mark
-          const oldKey  = tracker.modeKey;
-          if (!tracker.recompute()) continue;            // value unchanged
-          if (tracker.modeKey === oldKey) continue;      // belt + braces
-          const spec    = drawIdToSpec[drawId];
-          if (spec === undefined) continue;
-          removeDraw(drawId);
-          const newId  = addDrawImpl(spec, tok);
-          // The drawId returned by addDraw is a fresh slot; we don't
-          // attempt to preserve the caller's id mapping in v1. v2
-          // could thread the original id through if needed.
-          void newId;
+          const b = drawIdToBucket[drawId];
+          if (b === undefined) continue; // RO removed since mark
+          let arr = byBucket.get(b);
+          if (arr === undefined) { arr = []; byBucket.set(b, arr); }
+          arr.push(drawId);
+        }
+
+        for (const [bucket, ids] of byBucket) {
+          // First recompute every dirty tracker so .modeKey is fresh.
+          // Filter out ones whose value didn't actually change.
+          const changed: number[] = [];
+          for (const drawId of ids) {
+            const tracker = drawIdToModeTracker[drawId];
+            if (tracker === undefined) continue;
+            const oldKey = tracker.modeKey;
+            if (!tracker.recompute()) continue;
+            if (tracker.modeKey === oldKey) continue;
+            changed.push(drawId);
+          }
+          if (changed.length === 0) continue;
+
+          // Try the all-together fast path.
+          const wholeBucket = changed.length === bucket.drawSlots.size;
+          if (wholeBucket) {
+            const repId = changed[0]!;
+            const repTracker = drawIdToModeTracker[repId]!;
+            const newKey  = repTracker.modeKey;
+            // Compute the new bucketByKey string; we need the family.
+            const sample = drawIdToSpec[repId]!;
+            const fam = familyFor(sample.effect);
+            const newBk = `family#${fam.schema.id}|mk#${newKey.toString(16)}`;
+            const existing = bucketByKey.get(newBk);
+            if (existing === undefined) {
+              // No conflict — rename + rebuild pipeline in place.
+              // Find this bucket's current key by linear scan
+              // (buckets ≤ ~100 typically, so this is cheap).
+              let oldBk: string | undefined;
+              for (const [k, v] of bucketByKey) {
+                if (v === bucket) { oldBk = k; break; }
+              }
+              if (oldBk !== undefined) bucketByKey.delete(oldBk);
+              bucketByKey.set(newBk, bucket);
+              // Build the new pipeline with the snapshotted PS.
+              const desc = repTracker.descriptor;
+              const { pipelineLayout } = getBgl(bucket.layout, bucket.isAtlasBucket);
+              const newPipeline = device.createRenderPipeline({
+                label: `heapScene/${newBk}/pipeline`,
+                layout: pipelineLayout,
+                vertex:   { module: familyFor(sample.effect).vsModule, entryPoint: familyFor(sample.effect).vsEntryName, buffers: [] },
+                fragment: { module: familyFor(sample.effect).fsModule, entryPoint: familyFor(sample.effect).fsEntryName, targets: colorTargets },
+                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 } }
+                  : depthFormat !== undefined
+                    ? { depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: "always" as GPUCompareFunction } }
+                    : {}),
+              });
+              // Swap pipeline reference on the bucket's single slot.
+              // (Multi-slot Phase 5c would update one slot at a time.)
+              (bucket.slots[0] as { pipeline: GPURenderPipeline }).pipeline = newPipeline;
+              continue; // done with this bucket
+            }
+            // Conflict: another bucket already owns newBk. Fall through
+            // to per-RO rebucket below, which will merge into `existing`.
+          }
+          // Slow path — per-RO rebucket (used when partial transition
+          // OR when a merge with an existing destination bucket is
+          // required).
+          for (const drawId of changed) {
+            const spec = drawIdToSpec[drawId];
+            if (spec === undefined) continue;
+            removeDraw(drawId);
+            const newId = addDrawImpl(spec, tok);
+            void newId;
+          }
         }
       }
 

package/src/runtime/index.ts

@@ -126,3 +126,13 @@ export {
   type PartitionInput,
   type PartitionResult,
 } from "./derivedModes/partition.js";
+
+export {
+  derivedMode,
+  isDerivedModeRule,
+  flipCull,
+  type DerivedModeRule,
+  type DerivedModeBuilder,
+  type ModeAxis,
+  type ModeValue,
+} from "./derivedModes/rule.js";