@aardworx/wombat.rendering 0.9.17 → 0.9.19

package/dist/runtime/index.js

@@ -21,5 +21,7 @@ export { PipelineCache, encodeModeKey, decodeModeKey, MAX_ATTACHMENTS, DEFAULT_D
 export { ModeKeyTracker, snapshotDescriptor, } from "./derivedModes/modeKeyCpu.js";
 export { SlotTable, } from "./derivedModes/slotTable.js";
 export { partitionCPU, PARTITION_HISTOGRAM_WGSL, PARTITION_SCATTER_WGSL, MAX_SLOTS_PER_BUCKET, } from "./derivedModes/partition.js";
-export { derivedMode, isDerivedModeRule, flipCull, } from "./derivedModes/rule.js";
+export { derivedMode, isDerivedModeRule, flipCull, gpuFlipCullByDeterminant, } from "./derivedModes/rule.js";
+export { GpuDerivedModesScene } from "./derivedModes/gpuDispatcher.js";
+export { GPU_FLIP_CULL_BY_DET_WGSL, CULL_TO_U32, U32_TO_CULL, } from "./derivedModes/gpuKernel.js";
 //# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,OAAO,EACL,OAAO,GAER,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,QAAQ,GAGT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,GAEV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,GAOf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,uFAAuF;AACvF,OAAO,EACL,cAAc,EAAE,WAAW,EAC3B,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAE7C,sBAAsB,EAAE,qBAAqB,GAC9C,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,kBAAkB,GAGnB,MAAM,kBAAkB,CAAC;AAE1B,uEAAuE;AACvE,OAAO,EACL,SAAS,EACT,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,cAAc,EACd,KAAK,IAAI,mBAAmB,EAC5B,OAAO,IAAI,qBAAqB,EAChC,KAAK,IAAI,mBAAmB,EAC5B,SAAS,IAAI,uBAAuB,EACpC,MAAM,IAAI,oBAAoB,EAC9B,UAAU,IAAI,wBAAwB,EACtC,UAAU,IAAI,wBAAwB,GACvC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,SAAS,EACT,eAAe,EACf,aAAa,EACb,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,GAKjB,MAAM,6BAA6B,CAAC;AAErC,sEAAsE;AACtE,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,GAWjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,cAAc,EACd,kBAAkB,GACnB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,SAAS,GAEV,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,GAGrB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,QAAQ,GAKT,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,OAAO,EACL,OAAO,GAER,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,QAAQ,GAGT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,GAEV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,GAOf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,uFAAuF;AACvF,OAAO,EACL,cAAc,EAAE,WAAW,EAC3B,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAE7C,sBAAsB,EAAE,qBAAqB,GAC9C,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,kBAAkB,GAGnB,MAAM,kBAAkB,CAAC;AAE1B,uEAAuE;AACvE,OAAO,EACL,SAAS,EACT,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,cAAc,EACd,KAAK,IAAI,mBAAmB,EAC5B,OAAO,IAAI,qBAAqB,EAChC,KAAK,IAAI,mBAAmB,EAC5B,SAAS,IAAI,uBAAuB,EACpC,MAAM,IAAI,oBAAoB,EAC9B,UAAU,IAAI,wBAAwB,EACtC,UAAU,IAAI,wBAAwB,GACvC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,SAAS,EACT,eAAe,EACf,aAAa,EACb,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,GAKjB,MAAM,6BAA6B,CAAC;AAErC,sEAAsE;AACtE,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,GAWjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,cAAc,EACd,kBAAkB,GACnB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,SAAS,GAEV,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,GAGrB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,wBAAwB,GAMzB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EACL,yBAAyB,EACzB,WAAW,EACX,WAAW,GACZ,MAAM,6BAA6B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aardworx/wombat.rendering",
-  "version": "0.9.17",
+  "version": "0.9.19",
   "description": "WebGPU rendering layer for the Wombat TypeScript stack — RenderObject/RenderTask/runtime + window glue, port of Aardvark.Rendering's lower layers on top of WebGPU and wombat.shader.",
   "license": "MIT",
   "author": "krauthaufen",

package/src/core/renderObject.ts

@@ -67,4 +67,23 @@ export interface RenderObject {
   /** Index buffer for indexed draws. */
   readonly indices?: BufferView;
   readonly drawCall: aval<DrawCall>;
+  /**
+   * Per-axis derived-mode rules — `(u, declared) => modeValue`
+   * closures evaluated against this RO's uniforms at scene-build
+   * (and on reactive marks). See
+   * `@aardworx/wombat.rendering/runtime` — `derivedMode(...)`.
+   *
+   * A rule overrides the corresponding `pipelineState.rasterizer.*`
+   * (or `pipelineState.depth.*`) aval value. v1 evaluates rules
+   * CPU-side; v2 (deferred) lowers them to a GPU compute kernel.
+   * See `docs/derived-modes.md`.
+   */
+  readonly modeRules?: {
+    readonly cull?:           import("../runtime/derivedModes/rule.js").DerivedModeRule<"cull">;
+    readonly frontFace?:      import("../runtime/derivedModes/rule.js").DerivedModeRule<"frontFace">;
+    readonly topology?:       import("../runtime/derivedModes/rule.js").DerivedModeRule<"topology">;
+    readonly depthCompare?:   import("../runtime/derivedModes/rule.js").DerivedModeRule<"depthCompare">;
+    readonly depthWrite?:     import("../runtime/derivedModes/rule.js").DerivedModeRule<"depthWrite">;
+    readonly alphaToCoverage?: import("../runtime/derivedModes/rule.js").DerivedModeRule<"alphaToCoverage">;
+  };
 }

package/src/runtime/derivedModes/gpuDispatcher.ts

@@ -0,0 +1,190 @@
+// Scene-level dispatcher for the v1 GPU-evaluated derived-mode rule
+// (flip-cull-by-determinant; see ./gpuKernel.ts).
+//
+// Lifecycle
+// =========
+//
+//   - Construct once per heap scene with the device.
+//   - registerRo(drawId, modelRef, declaredCull): register an RO that
+//     has the GPU flip-cull rule. modelRef = byte offset into the
+//     arena where the RO's ModelTrafo mat4 lives.
+//   - deregisterRo(drawId): unregister on removeDraw.
+//   - markDirty(): caller hints that an input changed; the next
+//     `dispatch()` will run the kernel.
+//   - dispatch(arenaBuf, enc): if dirty, encode the compute pass into
+//     `enc`. Always copies the output buffer into a staging buffer for
+//     CPU readback.
+//   - finish(): mapAsync the staging buffer and resolve with the
+//     per-RO output array. The scene calls this AFTER submit and
+//     before deciding rebuckets. The promise resolves on the next
+//     microtask after the GPU completes the copy.
+//
+// The buffers grow lazily (pow2) as ROs are added.
+
+import { GPU_FLIP_CULL_BY_DET_WGSL, CULL_TO_U32 } from "./gpuKernel.js";
+import type { CullMode } from "../pipelineCache/index.js";
+
+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;
+}
+
+const WG_SIZE = 64;
+const POW2 = (n: number): number => { let p = 1; while (p < n) p <<= 1; return Math.max(64, p); };
+
+export class GpuDerivedModesScene {
+  readonly device: GPUDevice;
+
+  private readonly entries: (RoEntry | undefined)[] = [];
+  private liveCount = 0;
+  private dirty = false;
+
+  // GPU resources — lazily allocated on first registerRo.
+  private inputBuf:   GPUBuffer | null = null;
+  private outputBuf:  GPUBuffer | null = null;
+  private stagingBuf: GPUBuffer | null = null;
+  private paramsBuf:  GPUBuffer | null = null;
+  private pipeline:   GPUComputePipeline | null = null;
+  private bindGroup:  GPUBindGroup | null = null;
+  private layout:     GPUBindGroupLayout | null = null;
+  /** Capacity in number of u32 entries (= numROs the buffers can hold). */
+  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;
+
+  /** Per-RO last-known output. CPU mirror, populated by finish(). */
+  readonly lastOutput: Uint32Array;
+
+  constructor(device: GPUDevice) {
+    this.device = device;
+    this.lastOutput = new Uint32Array(0);
+  }
+
+  get registered(): number { return this.liveCount; }
+
+  registerRo(drawId: number, modelRef: number, declared: CullMode): void {
+    this.entries[drawId] = { modelRef, declaredU32: CULL_TO_U32[declared] };
+    this.liveCount++;
+    this.dirty = true;
+    this.declared = CULL_TO_U32[declared];
+  }
+
+  deregisterRo(drawId: number): void {
+    if (this.entries[drawId] === undefined) return;
+    this.entries[drawId] = undefined;
+    this.liveCount--;
+    this.dirty = true;
+  }
+
+  markDirty(): void { this.dirty = true; }
+  consumeDirty(): boolean { const was = this.dirty; this.dirty = false; return was; }
+
+  private ensureResources(arenaBuf: GPUBuffer, numROs: number): void {
+    const needCap = POW2(Math.max(1, numROs));
+    if (this.outputBuf === null || needCap > this.capacity) {
+      this.inputBuf  ?.destroy();
+      this.outputBuf ?.destroy();
+      this.stagingBuf?.destroy();
+      const bytes = needCap * 4;
+      this.inputBuf   = this.device.createBuffer({ size: bytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/in" });
+      this.outputBuf  = this.device.createBuffer({ size: bytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/out" });
+      this.stagingBuf = this.device.createBuffer({ size: bytes, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/staging" });
+      (this as { lastOutput: Uint32Array }).lastOutput = new Uint32Array(needCap);
+      this.capacity = needCap;
+      this.bindGroup = null;
+    }
+    if (this.paramsBuf === null) {
+      this.paramsBuf = this.device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, label: "gpuDerivedModes/params" });
+    }
+    if (this.layout === null) {
+      this.layout = this.device.createBindGroupLayout({
+        label: "gpuDerivedModes/bgl",
+        entries: [
+          { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+          { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+          { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+          { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+        ],
+      });
+    }
+    if (this.pipeline === null) {
+      const module = this.device.createShaderModule({ code: GPU_FLIP_CULL_BY_DET_WGSL, label: "gpuDerivedModes/module" });
+      this.pipeline = this.device.createComputePipeline({
+        label: "gpuDerivedModes/pipeline",
+        layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.layout] }),
+        compute: { module, entryPoint: "evaluate" },
+      });
+    }
+    if (this.bindGroup === null || this.arenaBuf !== arenaBuf) {
+      this.bindGroup = this.device.createBindGroup({
+        label: "gpuDerivedModes/bindGroup",
+        layout: this.layout,
+        entries: [
+          { binding: 0, resource: { buffer: arenaBuf } },
+          { binding: 1, resource: { buffer: this.inputBuf!  } },
+          { binding: 2, resource: { buffer: this.outputBuf! } },
+          { binding: 3, resource: { buffer: this.paramsBuf! } },
+        ],
+      });
+      this.arenaBuf = arenaBuf;
+    }
+  }
+
+  /** Upload current per-RO input refs + params; called when dirty. */
+  private uploadInputs(numROs: number): void {
+    const refs = new Uint32Array(this.capacity).fill(NO_RULE);
+    for (let i = 0; i < numROs; i++) {
+      const e = this.entries[i];
+      if (e !== undefined) refs[i] = e.modelRef;
+    }
+    this.device.queue.writeBuffer(this.inputBuf!, 0, refs.buffer, refs.byteOffset, refs.byteLength);
+    const params = new Uint32Array([numROs, this.declared, 0, 0]);
+    this.device.queue.writeBuffer(this.paramsBuf!, 0, params.buffer, params.byteOffset, params.byteLength);
+  }
+
+  /**
+   * Encode the compute dispatch + the staging copy into `enc`. Caller
+   * is responsible for `device.queue.submit([enc.finish()])`. Returns
+   * the number of ROs the kernel was dispatched against.
+   */
+  dispatch(arenaBuf: GPUBuffer, numROs: number, enc: GPUCommandEncoder): number {
+    this.ensureResources(arenaBuf, numROs);
+    this.uploadInputs(numROs);
+    const pass = enc.beginComputePass({ label: "gpuDerivedModes/pass" });
+    pass.setPipeline(this.pipeline!);
+    pass.setBindGroup(0, this.bindGroup!);
+    pass.dispatchWorkgroups(Math.ceil(numROs / WG_SIZE));
+    pass.end();
+    const bytes = numROs * 4;
+    enc.copyBufferToBuffer(this.outputBuf!, 0, this.stagingBuf!, 0, bytes);
+    return numROs;
+  }
+
+  /**
+   * mapAsync the staging buffer + copy values into `lastOutput`.
+   * Resolves on the GPU finishing the copy. Caller diffs lastOutput
+   * against its own cached values to find changed ROs.
+   */
+  async finish(numROs: number): Promise<void> {
+    if (this.stagingBuf === null || numROs === 0) return;
+    const bytes = numROs * 4;
+    await this.stagingBuf.mapAsync(GPUMapMode.READ, 0, bytes);
+    const view = new Uint32Array(this.stagingBuf.getMappedRange(0, bytes).slice(0));
+    this.stagingBuf.unmap();
+    (this as { lastOutput: Uint32Array }).lastOutput.set(view, 0);
+  }
+
+  dispose(): void {
+    this.inputBuf  ?.destroy();
+    this.outputBuf ?.destroy();
+    this.stagingBuf?.destroy();
+    this.paramsBuf ?.destroy();
+  }
+}

package/src/runtime/derivedModes/gpuKernel.ts

@@ -0,0 +1,98 @@
+// GPU-evaluated derived-mode rules — minimum viable kernel.
+//
+// CPU eval (Task 2 Phase 1-3, 0.9.17) runs rule closures in JS. For
+// rules whose inputs live GPU-side (per-RO trafos, etc.) JS evaluation
+// fans out CPU work that's wasted: the trafo bytes are right there in
+// the arena. This module runs the rule on the GPU instead, in one
+// dispatch over all dirty ROs per frame.
+//
+// v1 scope is deliberately narrow: ONE hard-coded WGSL kernel for
+// "flip cullMode by sign of det(upper3x3 of an arena mat4)". Picked
+// because it's the motivating case from docs/derived-modes.md and
+// proves the GPU-eval path end-to-end. Generalizes via a traced IR
+// builder in v2 (see derived-mode-rules-plan.md Phase 5).
+//
+// Architecture
+// ============
+//
+//   - One **module-wide** `GpuDerivedModesScene` per heap scene. Holds:
+//       * `roOutputBuf`  — `array<u32>` sized to scene.numROs.
+//                          Each entry = the rule's modeKey contribution.
+//       * `roInputBuf`   — `array<u32>` (one ref-into-arena per RO)
+//                          telling the kernel where to read the input.
+//       * `stagingBuf`   — MAP_READ + COPY_DST mirror of roOutputBuf,
+//                          for the per-frame readback.
+//   - Dispatch each frame in `update()`, ONLY when something dirty.
+//   - `mapAsync(staging)` resolves on a microtask; the CPU diffs the
+//     buffer against `roLastKey[]`. Any change → mark drawId dirty;
+//     the existing rebucket flow does the rest.
+//
+// The dirty gate keeps steady-state cost ≈ 0 — when no input aval
+// marks AND no RO add/remove, we skip the dispatch + readback.
+
+export const GPU_FLIP_CULL_BY_DET_WGSL = /* wgsl */ `
+// Per-RO record. Index i corresponds to drawId i in the scene's
+// flat RO table.
+struct GpuRuleParams {
+  numROs:     u32,
+  declared:   u32,   // 0 = none, 1 = front, 2 = back  (must match CULL_MODE[] order in bitfield.ts)
+  _pad0:      u32,
+  _pad1:      u32,
+};
+
+@group(0) @binding(0) var<storage, read>       arena:        array<u32>;
+// One per-RO entry: byte offset within the arena of the ROs ModelTrafo
+// allocation header. Data is at offset + 16 (ALLOC_HEADER_PAD_TO).
+// 0xFFFFFFFFu means "this RO does NOT have a flip-cull-by-det rule".
+@group(0) @binding(1) var<storage, read>       roInputRefs:  array<u32>;
+@group(0) @binding(2) var<storage, read_write> roOutputs:    array<u32>;
+@group(0) @binding(3) var<uniform>             uIn:          GpuRuleParams;
+
+// Read a row-major mat4 from the arena at byte offset \`refBytes + 16\`
+// (header is 16 bytes wide due to ALLOC_HEADER_PAD_TO). Returns the
+// 3×3 upper-left in row-major order: [m00,m01,m02, m10,m11,m12, m20,m21,m22].
+fn loadUpper3x3(refBytes: u32) -> array<f32, 9> {
+  let baseU32 = (refBytes + 16u) >> 2u;
+  // The arena is a Float32 storage of mat4 in row-major, 16 floats.
+  // Read 9 of them.
+  return array<f32, 9>(
+    bitcast<f32>(arena[baseU32 + 0u]),  bitcast<f32>(arena[baseU32 + 1u]),  bitcast<f32>(arena[baseU32 + 2u]),
+    bitcast<f32>(arena[baseU32 + 4u]),  bitcast<f32>(arena[baseU32 + 5u]),  bitcast<f32>(arena[baseU32 + 6u]),
+    bitcast<f32>(arena[baseU32 + 8u]),  bitcast<f32>(arena[baseU32 + 9u]),  bitcast<f32>(arena[baseU32 + 10u]),
+  );
+}
+
+fn det3x3(m: array<f32, 9>) -> f32 {
+  return m[0] * (m[4] * m[8] - m[5] * m[7])
+       - m[1] * (m[3] * m[8] - m[5] * m[6])
+       + m[2] * (m[3] * m[7] - m[4] * m[6]);
+}
+
+// Mirror of bitfield.ts CULL_MODE[] order: 0=none, 1=front, 2=back.
+fn flipCull(c: u32) -> u32 {
+  if (c == 1u) { return 2u; } // front -> back
+  if (c == 2u) { return 1u; } // back  -> front
+  return c;                   // none
+}
+
+@compute @workgroup_size(64)
+fn evaluate(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let i = gid.x;
+  if (i >= uIn.numROs) { return; }
+  let ref = roInputRefs[i];
+  if (ref == 0xFFFFFFFFu) {
+    // No rule on this RO; leave existing output untouched. Allows a
+    // single kernel dispatch to skip non-participating ROs.
+    return;
+  }
+  let m = loadUpper3x3(ref);
+  let d = det3x3(m);
+  let declared = uIn.declared;
+  let outVal = select(declared, flipCull(declared), d < 0.0);
+  roOutputs[i] = outVal;
+}
+`;
+
+/** Map between bitfield.ts's CULL_MODE order and the kernel's u32 enum. */
+export const CULL_TO_U32 = { "none": 0, "front": 1, "back": 2 } as const;
+export const U32_TO_CULL = ["none", "front", "back"] as const;

package/src/runtime/derivedModes/rule.ts

@@ -54,10 +54,29 @@ export type DerivedModeBuilder<A extends ModeAxis> = (
   declared: ModeValue<A>,
 ) => ModeValue<A>;
 
+/**
+ * Opt-in GPU evaluation marker. When present on a rule, the heap
+ * scene runs a hard-coded WGSL kernel (see `./gpuKernel.ts`) instead
+ * of the CPU closure. The closure is retained for fallback (e.g.
+ * MockGPU tests, devices without compute, or before frame 0).
+ *
+ * v1 supports one kernel: `"flipCullByDeterminant"`. v2 generalizes
+ * via a traced IR builder.
+ */
+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>;
+}
+
 export interface DerivedModeRule<A extends ModeAxis = ModeAxis> {
   readonly __derivedModeRule: true;
   readonly axis:    A;
   readonly evaluate: DerivedModeBuilder<A>;
+  /** Opt-in GPU evaluation. Absent → CPU closure path. */
+  readonly gpu?:    GpuRuleSpec<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
@@ -108,3 +127,46 @@ export function isDerivedModeRule(x: unknown): x is DerivedModeRule {
 export function flipCull(c: CullMode): CullMode {
   return c === "back" ? "front" : c === "front" ? "back" : "none";
 }
+
+/**
+ * Construct a derived-mode rule that flips cullMode based on the sign
+ * of `det(upperLeft3x3(u.<inputUniform>))`. Runs on the GPU when
+ * heapScene's compute path is available; the same logic is mirrored
+ * in the CPU closure for tests and fallback.
+ *
+ *   const rule = gpuFlipCullByDeterminant("ModelTrafo", "back");
+ *   spec.modeRules = { cull: rule };
+ *
+ * Useful for mirrored geometry: scenes that animate a per-RO trafo
+ * with potentially-negative scale don't pay CPU per-RO determinant
+ * cost — the kernel walks the arena once per frame for ALL ROs that
+ * carry this rule.
+ */
+export function gpuFlipCullByDeterminant(
+  inputUniform: string,
+  declared: CullMode = "back",
+): DerivedModeRule<"cull"> {
+  return {
+    __derivedModeRule: true,
+    axis: "cull",
+    domain: ["back", "front", "none"],
+    gpu: { kernel: "flipCullByDeterminant", inputUniform, declared },
+    evaluate: (u, declaredFromCtx) => {
+      const m = u[inputUniform] as { forward?: { _data?: Float64Array | Float32Array } } | { _data?: Float64Array | Float32Array };
+      // Accept Trafo3d ({forward: M44d}), M44 ({_data}), or row-major
+      // Float32Array. Reads upper-left 3x3.
+      const data: ArrayLike<number> | undefined =
+        (m as { forward?: { _data?: ArrayLike<number> } }).forward?._data ??
+        (m as { _data?: ArrayLike<number> })._data ??
+        (m as unknown as ArrayLike<number>);
+      if (data === undefined) return declaredFromCtx;
+      const m00 = data[0]!, m01 = data[1]!, m02 = data[2]!;
+      const m10 = data[4]!, m11 = data[5]!, m12 = data[6]!;
+      const m20 = data[8]!, m21 = data[9]!, m22 = data[10]!;
+      const det = m00 * (m11 * m22 - m12 * m21)
+                - m01 * (m10 * m22 - m12 * m20)
+                + m02 * (m10 * m21 - m11 * m20);
+      return det < 0 ? flipCull(declaredFromCtx) : declaredFromCtx;
+    },
+  };
+}

package/src/runtime/heapAdapter.ts

@@ -349,5 +349,6 @@ export function renderObjectToHeapSpec(
     ...(dc.instanceCount > 1 ? { instanceCount: dc.instanceCount } : {}),
     indices,
     ...(textures !== undefined ? { textures } : {}),
+    ...(ro.modeRules !== undefined ? { modeRules: ro.modeRules } : {}),
   };
 }

package/src/runtime/heapScene.ts

@@ -94,6 +94,8 @@ import {
 } from "./heapScene/pools.js";
 import { encodeModeKey, type PipelineStateDescriptor } from "./pipelineCache/index.js";
 import { snapshotDescriptor, ModeKeyTracker } from "./derivedModes/modeKeyCpu.js";
+import { GpuDerivedModesScene } from "./derivedModes/gpuDispatcher.js";
+import { U32_TO_CULL } from "./derivedModes/gpuKernel.js";
 import { addMarkingCallback } from "@aardworx/wombat.adaptive";
 
 // GrowBuffer + ALIGN16 + MIN_BUFFER_BYTES + POW2 live in ./heapScene/growBuffer.
@@ -887,6 +889,14 @@ export function buildHeapScene(
    *  Drained on removeDraw to release slots + records. */
   const derivedByDrawId = new Map<number, RoRegistration>();
 
+  // ─── GPU-eval mode rules (Task 2 Phase 5, narrow) ─────────────────
+  // Lazily allocated on first registration; one dispatcher per scene.
+  let gpuModesScene: GpuDerivedModesScene | undefined;
+  /** Last per-RO GPU output we routed to a bucket. Diff against
+   *  newly-readback values to decide rebuckets without re-bucketing
+   *  un-changed ROs. */
+  const gpuModesLastKey = new Map<number, number>();
+
   /** The derived-uniform rule for a uniform binding on this RO, if any: an explicit
    *  `derivedUniform(...)` value in `spec.inputs`, or a standard trafo recipe by name
    *  (recipes apply only when their base-trafo leaves are actually bound on this RO —
@@ -2076,6 +2086,21 @@ export function buildHeapScene(
     drawIdToModeTracker[drawId] = tracker;
     tracker.forEachLeaf((av) => subscribeModeLeaf(av, drawId));
 
+    // ─── GPU-eval mode rule registration (Task 2 Phase 5) ────────────
+    // If spec.modeRules.cull is GPU-flavoured, register the RO with
+    // the scene-wide dispatcher. Provide the arena byte offset of the
+    // RO's input uniform so the kernel reads from the right slot.
+    {
+      const gpuRule = spec.modeRules?.cull?.gpu;
+      if (gpuRule !== undefined && gpuRule.kernel === "flipCullByDeterminant") {
+        const inputRef = perDrawRefs.get(gpuRule.inputUniform);
+        if (inputRef !== undefined) {
+          if (gpuModesScene === undefined) gpuModesScene = new GpuDerivedModesScene(device);
+          gpuModesScene.registerRo(drawId, inputRef, gpuRule.declared);
+        }
+      }
+    }
+
     // ─── §7 derived-uniforms registration ────────────────────────────
     // A uniform binding on this RO is either a value (aval/constant) or a rule —
     // collect the rules (explicit `derivedUniform(...)` values + standard trafo
@@ -2236,6 +2261,10 @@ export function buildHeapScene(
     }
     drawIdToModeTracker[drawId] = undefined;
     dirtyModeKeyDrawIds.delete(drawId);
+    if (gpuModesScene !== undefined) {
+      gpuModesScene.deregisterRo(drawId);
+      gpuModesLastKey.delete(drawId);
+    }
 
     stats.totalDraws--;
     stats.geometryBytes = arenaBytes(arena);
@@ -2560,6 +2589,52 @@ export function buildHeapScene(
    * we just swap the bind group + dispatch shape per bucket.
    */
   function encodeComputePrep(enc: GPUCommandEncoder, token: AdaptiveToken): void {
+    // GPU-eval derived-mode rules (Task 2 Phase 5): dispatch the
+    // hardcoded determinant-flip-cull kernel + start readback.
+    // 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) {
+      const numROs = nextDrawId; // upper bound; sparse entries are skipped via 0xFFFFFFFF sentinel
+      gpuModesScene.dispatch(arena.attrs.buffer, numROs, enc);
+      // mapAsync the staging buffer in the background. When it
+      // resolves, diff against gpuModesLastKey to schedule rebuckets.
+      gpuModesScene.finish(numROs).then(() => {
+        const out = gpuModesScene!.lastOutput;
+        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;
+          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.
+          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);
+        }
+      }).catch((e) => {
+        // mapAsync can reject if the device was lost or the scene was
+        // disposed mid-readback. Log but don't crash the frame.
+        console.warn("gpuModesScene readback failed:", e);
+      });
+    }
+
     // §7: derived-uniforms dispatch first — writes into per-bucket
     // drawHeap regions before the scan reads anything. One dispatcher
     // per bucket; constituents are shared so dirty state propagates
@@ -2687,6 +2762,7 @@ export function buildHeapScene(
     arena.attrs.destroy();
     arena.indices.destroy();
     for (const b of buckets) destroyBucketResources(b);
+    gpuModesScene?.dispose();
   }
 
   // Test-only escape hatch for inspecting megacall bucket state. Not

package/src/runtime/index.ts

@@ -131,8 +131,17 @@ export {
   derivedMode,
   isDerivedModeRule,
   flipCull,
+  gpuFlipCullByDeterminant,
   type DerivedModeRule,
   type DerivedModeBuilder,
+  type GpuRuleSpec,
   type ModeAxis,
   type ModeValue,
 } from "./derivedModes/rule.js";
+
+export { GpuDerivedModesScene } from "./derivedModes/gpuDispatcher.js";
+export {
+  GPU_FLIP_CULL_BY_DET_WGSL,
+  CULL_TO_U32,
+  U32_TO_CULL,
+} from "./derivedModes/gpuKernel.js";