@aardworx/wombat.rendering 0.9.23 → 0.9.25

package/src/runtime/derivedModes/gpuDispatcher.ts

@@ -23,14 +23,17 @@
 
 import { GPU_FLIP_CULL_BY_DET_WGSL, CULL_TO_U32 } from "./gpuKernel.js";
 import type { CullMode } from "../pipelineCache/index.js";
+import type { aval } from "@aardworx/wombat.adaptive";
+import { AdaptiveToken } from "@aardworx/wombat.adaptive";
 
 const NO_RULE = 0xFFFFFFFF;
 
 interface RoEntry {
   /** Byte offset of the RO's ModelTrafo mat4 in the arena. */
   modelRef: number;
-  /** SG-declared cull mode, encoded as u32 (0=none/1=front/2=back). */
-  declaredU32: number;
+  /** SG-declared cull mode — either a plain value or an aval whose
+   *  current value the dispatcher reads each frame. */
+  declared: CullMode | aval<CullMode>;
 }
 
 const WG_SIZE = 64;
@@ -55,9 +58,6 @@ export class GpuDerivedModesScene {
   private capacity = 0;
   /** Last-known arena buffer, used to detect bind-group invalidation. */
   private arenaBuf: GPUBuffer | null = null;
-  /** Last-known declared (for kernel uniform). Common case: all RO
-   *  rules share the same declared (= the SG scope's value). */
-  private declared: number = CULL_TO_U32.back;
   /** True while the staging buffer's mapAsync is in flight. We must
    *  not enqueue a new copyBufferToBuffer into it until it's been
    *  unmapped (mapAsync resolved + unmap called). */
@@ -73,11 +73,14 @@ export class GpuDerivedModesScene {
 
   get registered(): number { return this.liveCount; }
 
-  registerRo(drawId: number, modelRef: number, declared: CullMode): void {
-    this.entries[drawId] = { modelRef, declaredU32: CULL_TO_U32[declared] };
+  registerRo(
+    drawId: number,
+    modelRef: number,
+    declared: CullMode | aval<CullMode>,
+  ): void {
+    this.entries[drawId] = { modelRef, declared };
     this.liveCount++;
     this.dirty = true;
-    this.declared = CULL_TO_U32[declared];
   }
 
   deregisterRo(drawId: number): void {
@@ -144,12 +147,28 @@ export class GpuDerivedModesScene {
   /** Upload current per-RO input refs + params; called when dirty. */
   private uploadInputs(numROs: number): void {
     const refs = new Uint32Array(this.capacity).fill(NO_RULE);
+    let declaredU32: number = CULL_TO_U32.back;
     for (let i = 0; i < numROs; i++) {
       const e = this.entries[i];
-      if (e !== undefined) refs[i] = e.modelRef;
+      if (e !== undefined) {
+        refs[i] = e.modelRef;
+        // Resolve the declared each dispatch. v1 supports one shared
+        // declared per kernel (single uniform in the WGSL). Last
+        // registered entry's declared wins. For the typical SG shape
+        // where a single `<Sg CullMode={cv}>` wraps every leaf, every
+        // entry's declared is the same aval — so picking the last is
+        // equivalent to picking any. If the user genuinely binds
+        // distinct declareds across the scene, an axis-domain
+        // analyzer would be the correct generalization.
+        const d = e.declared;
+        const v = typeof d === "string"
+          ? d
+          : (d as aval<CullMode>).getValue(AdaptiveToken.top);
+        declaredU32 = CULL_TO_U32[v];
+      }
     }
     this.device.queue.writeBuffer(this.inputBuf!, 0, refs.buffer, refs.byteOffset, refs.byteLength);
-    const params = new Uint32Array([numROs, this.declared, 0, 0]);
+    const params = new Uint32Array([numROs, declaredU32, 0, 0]);
     this.device.queue.writeBuffer(this.paramsBuf!, 0, params.buffer, params.byteOffset, params.byteLength);
   }
 

package/src/runtime/derivedModes/rule.ts

@@ -67,8 +67,16 @@ export interface GpuRuleSpec<A extends ModeAxis = ModeAxis> {
   readonly kernel: "flipCullByDeterminant";
   /** Name of the input uniform the kernel reads (e.g. "ModelTrafo"). */
   readonly inputUniform: string;
-  /** Declared (SG-scope) value the kernel mutates by. */
-  readonly declared: ModeValue<A>;
+  /**
+   * Declared (SG-scope) value the kernel mutates by. Either a plain
+   * mode value (baked at scene-build) or an `aval` for reactive
+   * declared — the dispatcher re-uploads the kernel uniform on each
+   * dispatch from the aval's current value, so flipping it via a UI
+   * cval re-runs the rule with the new declared.
+   */
+  readonly declared:
+    | ModeValue<A>
+    | import("@aardworx/wombat.adaptive").aval<ModeValue<A>>;
 }
 
 export interface DerivedModeRule<A extends ModeAxis = ModeAxis> {
@@ -144,7 +152,10 @@ export function flipCull(c: CullMode): CullMode {
  */
 export function gpuFlipCullByDeterminant(
   inputUniform: string,
-  declared: CullMode = "back",
+  declared:
+    | CullMode
+    | import("@aardworx/wombat.adaptive").aval<CullMode>
+    = "back",
 ): DerivedModeRule<"cull"> {
   return {
     __derivedModeRule: true,

package/src/runtime/heapScene.ts

@@ -637,6 +637,12 @@ export function buildHeapScene(
       modeAvalToDrawIds.set(av, set);
       modeAvalCallbacks.set(av, addMarkingCallback(av, () => {
         for (const id of set!) dirtyModeKeyDrawIds.add(id);
+        // Mark the GPU mode-rules dispatcher dirty too — at least one
+        // of those drawIds may carry a GPU rule whose input changed.
+        // The dispatch path checks consumeDirty() before encoding, so
+        // an unrelated aval mark (e.g. Color change on hover) leaves
+        // the kernel quiet.
+        gpuModesScene?.markDirty();
       }));
     }
     set.add(drawId);
@@ -2097,10 +2103,14 @@ export function buildHeapScene(
         if (inputRef !== undefined) {
           if (gpuModesScene === undefined) gpuModesScene = new GpuDerivedModesScene(device);
           gpuModesScene.registerRo(drawId, inputRef, gpuRule.declared);
+          // If declared is reactive (e.g. a shared cullModeC cval),
+          // subscribe so flipping it marks the dispatcher dirty.
+          // Plain values: no subscription needed.
+          if (typeof gpuRule.declared !== "string") {
+            subscribeModeLeaf(gpuRule.declared as aval<unknown>, drawId);
+          }
           if (drawId < 3 || drawId % 20 === 0) {
-            // Sparse logging so we can confirm registration without
-            // spamming for big scenes.
-            console.debug(`[heapScene] GPU rule registered drawId=${drawId} input='${gpuRule.inputUniform}' ref=${inputRef} declared=${gpuRule.declared}`);
+            console.debug(`[heapScene] GPU rule registered drawId=${drawId} input='${gpuRule.inputUniform}' ref=${inputRef} declared=${typeof gpuRule.declared === "string" ? gpuRule.declared : "<aval>"}`);
           }
         } else {
           console.warn(`[heapScene] GPU rule input '${gpuRule.inputUniform}' not in spec.inputs for drawId=${drawId}; rule disabled`);
@@ -2391,9 +2401,25 @@ export function buildHeapScene(
           arr.push(drawId);
         }
 
+        // Two-phase rebucket: collect all proposed renames first, then
+        // commit them atomically. Avoids the "two buckets swap names"
+        // conflict (e.g. cullModeC flip with both 'back' and 'front'
+        // buckets present — A wants 'front', B wants 'back', they
+        // collide). After phase 1 every fast-path bucket is removed
+        // from bucketByKey, freeing both keys for phase 2's atomic
+        // re-insertion. Slow per-RO rebuckets handle anything that
+        // still conflicts (rare).
+        type Rename = {
+          bucket: Bucket;
+          repId: number;
+          newKey: bigint;
+          newBk: string;
+          oldBk: string;
+        };
+        const renames: Rename[] = [];
+        const slowChanged: number[] = []; // ROs going through per-RO
+
         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];
@@ -2405,61 +2431,73 @@ export function buildHeapScene(
           }
           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 newKey  = repTracker.modeKey;
             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
+            let oldBk: string | undefined;
+            for (const [k, v] of bucketByKey) {
+              if (v === bucket) { oldBk = k; break; }
+            }
+            if (oldBk !== undefined && oldBk !== newBk) {
+              renames.push({ bucket, repId, newKey, newBk, oldBk });
+              continue;
             }
-            // Conflict: another bucket already owns newBk. Fall through
-            // to per-RO rebucket below, which will merge into `existing`.
+            if (oldBk === newBk) continue; // shouldn't happen but safe
           }
-          // 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;
+          // Partial transition: per-RO slow path.
+          for (const c of changed) slowChanged.push(c);
+        }
+
+        if (renames.length > 0) {
+          // Phase 1: remove all old keys. After this, the renames' new
+          // keys are free unless they collide with a NON-rename
+          // bucket's current key.
+          for (const r of renames) bucketByKey.delete(r.oldBk);
+          // Phase 2: assign new keys, building new pipelines. If a
+          // collision still exists after phase 1 (against a stale
+          // bucket that's NOT being renamed), restore old key + fall
+          // back to per-RO for that bucket's records.
+          for (const r of renames) {
+            if (bucketByKey.has(r.newBk)) {
+              // Collision with a stale bucket. Restore + flag for slow.
+              bucketByKey.set(r.oldBk, r.bucket);
+              for (const id of r.bucket.drawSlots) slowChanged.push(id);
+              continue;
+            }
+            bucketByKey.set(r.newBk, r.bucket);
+            const tracker = drawIdToModeTracker[r.repId]!;
+            const sample = drawIdToSpec[r.repId]!;
+            const desc = tracker.descriptor;
+            const { pipelineLayout } = getBgl(r.bucket.layout, r.bucket.isAtlasBucket);
+            const newPipeline = device.createRenderPipeline({
+              label: `heapScene/${r.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 } }
+                  : {}),
+            });
+            (r.bucket.slots[0] as { pipeline: GPURenderPipeline }).pipeline = newPipeline;
           }
         }
+
+        // Slow per-RO rebucket for the leftover cases.
+        for (const drawId of slowChanged) {
+          const spec = drawIdToSpec[drawId];
+          if (spec === undefined) continue;
+          removeDraw(drawId);
+          const newId = addDrawImpl(spec, tok);
+          void newId;
+        }
       }
 
       // 1. Pool: re-pack any aval whose value changed since last frame.
@@ -2601,7 +2639,13 @@ export function buildHeapScene(
     // Resolved on the next frame's update() — one-frame lag for the
     // first appearance of a state transition. CPU fallback runs at
     // addDraw time so the initial bucket assignment is still correct.
-    if (gpuModesScene !== undefined && gpuModesScene.registered > 0) {
+    if (gpuModesScene !== undefined
+        && gpuModesScene.registered > 0
+        && gpuModesScene.consumeDirty()) {
+      // Dirty-gate: skip the kernel + readback when no rule input
+      // changed since the last dispatch. Unrelated avals (Color on
+      // hover, etc.) don't trigger dirty, so steady state has zero
+      // GPU mode-rule work per frame.
       const numROs = nextDrawId; // upper bound; sparse entries are skipped via 0xFFFFFFFF sentinel
       gpuModesScene.dispatch(arena.attrs.buffer, numROs, enc);
       // mapAsync the staging buffer AFTER the caller's submit. The
@@ -2610,39 +2654,36 @@ export function buildHeapScene(
       // submitted the enc. Without this deferral, mapAsync fires
       // before submit and WebGPU rejects the next dispatch's
       // copy-to-staging with "buffer used in submit while mapped".
+      // v1.5: the readback used to PATCH spec.modeRules.cull with the
+      // GPU output as a constant rule, then mark the drawId dirty so
+      // the next update() rebucketed via the patched value. That had
+      // a fatal bug: per-RO rebucket (the slow-path fallback) creates
+      // a NEW tracker that reads the patched (constant) rule —
+      // permanently breaking the rule's reactivity. Second cullModeC
+      // flip → trackers re-evaluate → constant rule returns the same
+      // value → no rebucket. So patching is gone.
+      //
+      // The CPU fallback already routes ROs correctly: its evaluate
+      // is the same algorithm as the kernel (sign(det(upper3x3))), so
+      // CPU and GPU agree. The readback now runs purely as a
+      // verification signal — disagreements indicate a CPU/GPU eval
+      // drift bug. Phase 5c.2 (no-readback design) drops it entirely.
       Promise.resolve().then(() => gpuModesScene!.finish(numROs)).then(() => {
         const out = gpuModesScene!.lastOutput;
-        let changes = 0;
+        let mismatches = 0;
         for (let i = 0; i < numROs; i++) {
           const cur = out[i] ?? 0xFFFFFFFF;
-          const prev = gpuModesLastKey.get(i);
-          if (cur === 0xFFFFFFFF) continue;       // no rule on this RO
-          if (prev === cur) continue;
-          changes++;
-          gpuModesLastKey.set(i, cur);
-          // Project the kernel's u32 enum back to a CullMode value,
-          // store on the tracker's modeRules so the next snapshot
-          // picks it up, then schedule a rebucket.
+          if (cur === 0xFFFFFFFF) continue;
           const tracker = drawIdToModeTracker[i];
-          const spec    = drawIdToSpec[i];
-          if (tracker === undefined || spec === undefined) continue;
-          const cull = U32_TO_CULL[cur];
-          if (cull === undefined) continue;
-          // Inject the GPU result by patching the spec's CPU rule to
-          // return a constant. Slightly hacky but contained: the next
-          // recompute() will read this and route to the right bucket.
-          const patched: typeof spec.modeRules = {
-            ...spec.modeRules,
-            cull: {
-              __derivedModeRule: true, axis: "cull",
-              evaluate: () => cull,
-            },
-          };
-          (spec as { modeRules?: typeof spec.modeRules }).modeRules = patched;
-          dirtyModeKeyDrawIds.add(i);
-        }
-        if (changes > 0) {
-          console.debug(`[heapScene] GPU rule readback: ${changes}/${numROs} ROs changed modeKey`);
+          if (tracker === undefined) continue;
+          // Decode the tracker's current cullMode (CPU result) into the
+          // same u32 enum the kernel emits and compare. Drift logs once.
+          const cpuCull = tracker.descriptor.cullMode;
+          const cpuU32 = cpuCull === "none" ? 0 : cpuCull === "front" ? 1 : 2;
+          if (cpuU32 !== cur && mismatches < 3) {
+            mismatches++;
+            console.warn(`[heapScene] GPU/CPU mode drift drawId=${i} cpu=${cpuCull}(${cpuU32}) gpu=${U32_TO_CULL[cur]}(${cur})`);
+          }
         }
       }).catch((e) => {
         // mapAsync can reject if the device was lost or the scene was