@aardworx/wombat.rendering 0.9.32 → 0.18.1

package/src/runtime/derivedModes/rule.ts

@@ -1,35 +1,44 @@
-// `derivedMode(axis, (u, declared) => modeValue)` — author-facing
-// marker for per-RO pipeline-state values that are functions of the
-// RO's uniforms.
+// Derived-mode rule — branded combination of a shader-IR rule
+// expression (from `rule(...)` in wombat.shader) + an axis + the
+// SG-declared aval. The IR is what gets compiled into the partition
+// kernel; the declared aval drives per-frame re-specialisation.
 //
-// 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.
+// Authoring flow (with `@boperators/plugin-vite` + the shader-vite
+// plugin both installed):
 //
-// 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.
+//     declare const u: { ModelTrafo: M44f };
+//     declare const declared: number;
 //
-// 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.
+//     const cullExpr = rule(() => {
+//       const m: M33f = mat3(u.ModelTrafo);
+//       const det = determinant(m);
+//       return det < 0 ? flipCull(declared) : declared;
+//     });
+//
+//     const cullRule = derivedMode("cull", cullExpr, { declared: cullModeC });
+//
+// At runtime, heapScene reads `cullRule.expr.template`, extracts the
+// entry's body Stmt, calls `analyseOutputSet(body)` to obtain the
+// symbolic set, and for each declared-aval value resolves the set
+// via `evaluateSet({"declared": current}, intrinsics)` to size the
+// bucket's slots + codegen the partition kernel.
 
-import type { CullMode, FrontFace, Topology } from "../pipelineCache/index.js";
+import type { RuleExpr } from "@aardworx/wombat.shader";
+import type { aval } from "@aardworx/wombat.adaptive";
+import type { CullMode, FrontFace, Topology, AttachmentBlend } 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";
+  | "alphaToCoverage"
+  /** Per-attachment blend state. The rule's u32 output indexes into
+   *  the `values` array on `DerivedModeOptions` (or the `resolve`
+   *  callback); each entry is a full {@link AttachmentBlend} struct
+   *  with srcFactor / dstFactor / operation / writeMask / enabled
+   *  fields — letting blend rules specify the entire mode object,
+   *  not just an enum index. */
+  | "blend";
 
-/** Output value type per axis. */
 export type ModeValue<A extends ModeAxis> =
   A extends "cull"           ? CullMode :
   A extends "frontFace"      ? FrontFace :
@@ -37,147 +46,59 @@ export type ModeValue<A extends ModeAxis> =
   A extends "depthCompare"   ? GPUCompareFunction :
   A extends "depthWrite"     ? boolean :
   A extends "alphaToCoverage" ? boolean :
+  A extends "blend"          ? AttachmentBlend :
   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>;
-
-/**
- * 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. 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> {
   readonly __derivedModeRule: true;
-  readonly axis:    A;
-  readonly evaluate: DerivedModeBuilder<A>;
-  /** Opt-in GPU evaluation. Absent → CPU closure path. */
-  readonly gpu?:    GpuRuleSpec<A>;
+  readonly axis: A;
+  /** Shader-IR rule body — the entry's return Expr is the rule. For
+   *  axes whose `ModeValue<A>` is a struct (e.g. blend's
+   *  `AttachmentBlend`) the body returns object literals directly;
+   *  the renderer fingerprints distinct returns and auto-assigns
+   *  slot indices. For enum axes (cull etc.) the body returns u32
+   *  enum indices that the renderer maps via the canonical table. */
+  readonly expr: RuleExpr<ModeValue<A> | number>;
   /**
-   * 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.
+   * SG-context value for this axis. Filled in by `<Sg CullMode>` /
+   * `<Sg DepthTest>` / etc. at traversal time — users never write
+   * it. The rule body's `declared` ambient leaf resolves to this;
+   * when the underlying aval marks, heapScene re-specialises +
+   * swaps the cached kernel + pipeline set.
+   *
+   * `undefined` is the initial state right after `derivedMode(...)`;
+   * the SG fills it in before the rule reaches the renderer.
    */
-  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;
+  readonly declared: aval<ModeValue<A>> | ModeValue<A> | undefined;
 }
 
-/** 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";
-}
 
 /**
- * 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.
+ * Brand a `RuleExpr` (the shader-IR artefact emitted by the
+ * `rule(...)` build-time marker) as a derived-mode rule for `axis`.
  *
- *   const rule = gpuFlipCullByDeterminant("ModelTrafo", "back");
- *   spec.modeRules = { cull: rule };
+ * The `declared` option carries the SG-context value the rule reads
+ * via `declare const declared: number` in its body. heapScene
+ * substitutes it (as a Const) before codegen — when `declared` is a
+ * cval, every mark triggers a re-specialise + cached-kernel swap.
  *
- * 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.
+ * `domain` is NOT a parameter: the renderer infers the per-declared
+ * set of possible outputs from the rule's IR via
+ * `analyseOutputSet` + `evaluateSet`.
  */
-export function gpuFlipCullByDeterminant(
-  inputUniform: string,
-  declared:
-    | CullMode
-    | import("@aardworx/wombat.adaptive").aval<CullMode>
-    = "back",
-): DerivedModeRule<"cull"> {
+export function derivedMode<A extends ModeAxis>(
+  axis: A,
+  expr: RuleExpr<ModeValue<A> | number>,
+): DerivedModeRule<A> {
   return {
     __derivedModeRule: true,
-    axis: "cull",
-    domain: ["back", "front", "none"],
-    gpu: { kernel: "flipCullByDeterminant", inputUniform, declared },
-    evaluate: (u, declaredFromCtx) => {
-      // Accept Trafo3d ({forward: M44d}) — the wombat.base shape used
-      // by SG ModelTrafo — or any object with M00..M22 accessors.
-      const raw = u[inputUniform];
-      type M = { M00: number; M01: number; M02: number;
-                 M10: number; M11: number; M12: number;
-                 M20: number; M21: number; M22: number };
-      const m: M | undefined =
-        (raw as { forward?: M }).forward
-        ?? (raw as M);
-      if (m === undefined || typeof m.M00 !== "number") return declaredFromCtx;
-      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(declaredFromCtx) : declaredFromCtx;
-    },
+    axis,
+    expr,
+    declared: undefined,  // SG fills this in at traversal time
   };
 }

package/src/runtime/derivedUniforms/dispatch.ts

@@ -32,12 +32,13 @@ export function uploadConstituentsRange(
   device.queue.writeBuffer(buf, startByte, mirror.buffer, mirror.byteOffset + startByte, endByte - startByte);
 }
 
-/** Live getters for the GPU buffers the kernel binds (scene may grow/replace them). */
+/** Live getters for the scene-wide GPU buffers the kernel binds. The
+ *  main-heap binding is per-dispatch and supplied to `encodeChunk`,
+ *  since one DerivedUniformsScene now serves multiple arena chunks
+ *  (§3) and each chunk has its own main-heap GPUBuffer. */
 export interface DerivedUniformsResources {
   /** `array<vec2<f32>>` — df32 trafo halves (the constituents heap). */
   readonly constituentsBuf: () => GPUBuffer;
-  /** `array<f32>` — the main heap (drawHeaders); written by the kernel. */
-  readonly mainHeapBuf: () => GPUBuffer;
 }
 
 function bglEntries(): GPUBindGroupLayoutEntry[] {
@@ -145,57 +146,83 @@ class UberPipeline {
   }
 }
 
+/** Per-chunk dispatch state: GPU mirror of that chunk's records +
+ *  a cached bind group keyed on (consts, heap, recs). */
+interface ChunkState {
+  readonly gpu: RecordsGpu;
+  cachedBg: GPUBindGroup | undefined;
+  bgKey: [GPUBuffer | undefined, GPUBuffer | undefined, GPUBuffer | undefined];
+}
+
 export class DerivedUniformsDispatcher {
   private readonly device: GPUDevice;
   private readonly resources: DerivedUniformsResources;
-  private readonly gpu: RecordsGpu;
   private readonly pipe: UberPipeline;
-  private cachedBg: GPUBindGroup | undefined;
-  private bgKey: [GPUBuffer | undefined, GPUBuffer | undefined, GPUBuffer | undefined] = [undefined, undefined, undefined];
+  private readonly byChunk = new Map<RecordsBuffer, ChunkState>();
 
   constructor(device: GPUDevice, resources: DerivedUniformsResources) {
     this.device = device;
     this.resources = resources;
-    this.gpu = new RecordsGpu(device);
     this.pipe = new UberPipeline(device);
   }
 
-  /** Open a compute pass and run the uber-kernel. No-ops if there are no records / no rules. */
-  encode(enc: GPUCommandEncoder, registry: DerivedUniformRegistry, records: RecordsBuffer): boolean {
+  /** Run the uber-kernel for ONE chunk's records, binding
+   *  `mainHeapGetter()` as the heap target. No-op if the chunk's
+   *  records buffer is empty or the registry has no rules. */
+  encodeChunk(
+    enc: GPUCommandEncoder,
+    registry: DerivedUniformRegistry,
+    records: RecordsBuffer,
+    mainHeapGetter: () => GPUBuffer,
+  ): boolean {
     if (records.recordCount === 0) return false;
     const pipeline = this.pipe.pipeline(registry, records.strideWords);
     if (pipeline === undefined) return false;
-    this.gpu.sync(records);
+    const state = this.stateFor(records);
+    state.gpu.sync(records);
     const pass = enc.beginComputePass({ label: "derivedUniforms.uber" });
     pass.setPipeline(pipeline);
-    pass.setBindGroup(0, this.bindGroup());
+    pass.setBindGroup(0, this.bindGroup(state, mainHeapGetter()));
     pass.dispatchWorkgroups(Math.ceil(records.recordCount / 64));
     pass.end();
     return true;
   }
 
   dispose(): void {
-    this.gpu.dispose();
+    for (const s of this.byChunk.values()) s.gpu.dispose();
+    this.byChunk.clear();
+  }
+
+  private stateFor(records: RecordsBuffer): ChunkState {
+    let s = this.byChunk.get(records);
+    if (s === undefined) {
+      s = {
+        gpu: new RecordsGpu(this.device),
+        cachedBg: undefined,
+        bgKey: [undefined, undefined, undefined],
+      };
+      this.byChunk.set(records, s);
+    }
+    return s;
   }
 
-  private bindGroup(): GPUBindGroup {
+  private bindGroup(state: ChunkState, heap: GPUBuffer): GPUBindGroup {
     const consts = this.resources.constituentsBuf();
-    const heap = this.resources.mainHeapBuf();
-    const recs = this.gpu.buffer();
-    if (this.cachedBg !== undefined && this.bgKey[0] === consts && this.bgKey[1] === heap && this.bgKey[2] === recs) {
-      return this.cachedBg;
+    const recs = state.gpu.buffer();
+    if (state.cachedBg !== undefined && state.bgKey[0] === consts && state.bgKey[1] === heap && state.bgKey[2] === recs) {
+      return state.cachedBg;
     }
-    this.cachedBg = this.device.createBindGroup({
+    state.cachedBg = this.device.createBindGroup({
       label: "derivedUniforms.uber",
       layout: this.pipe.bgl,
       entries: [
         { binding: 0, resource: { buffer: consts } },
         { binding: 1, resource: { buffer: heap } },
         { binding: 2, resource: { buffer: recs } },
-        { binding: 3, resource: { buffer: this.gpu.countBuf } },
+        { binding: 3, resource: { buffer: state.gpu.countBuf } },
       ],
     });
-    this.bgKey = [consts, heap, recs];
-    return this.cachedBg;
+    state.bgKey = [consts, heap, recs];
+    return state.cachedBg;
   }
 }

package/src/runtime/derivedUniforms/marker.ts

@@ -49,27 +49,79 @@ function intrinsicExpr(name: string, type: Type, args: readonly Expr[]): Expr {
   };
 }
 
-/** A traced expression in a `derivedUniform` builder. */
+/** Convertible-to-DerivedExpr operand. `aardvark-operators` rewrites
+ *  e.g. `det < 0` to `det.lt(0)` — so every binary method accepts a
+ *  raw number and lifts it to a Const matching the receiver's
+ *  numeric type (f32 / u32 / i32). */
+export type DerivedOperand = DerivedExpr | number;
+
+/** True iff `t` is a numeric scalar IR type (Float / Int). */
+function isNumericScalar(t: Type): boolean {
+  return t.kind === "Float" || t.kind === "Int";
+}
+/** Element type for scalar arithmetic: scalar types pass through,
+ *  vector/matrix types unwrap to their element type, anything else
+ *  defaults to f32 (the natural numeric on the GPU side). */
+function scalarLiftType(t: Type): Type {
+  if (isNumericScalar(t)) return t;
+  if (t.kind === "Vector" || t.kind === "Matrix") return t.element;
+  return Tf32;
+}
+function liftConst(value: number, target: Type): Expr {
+  if (target.kind === "Int") {
+    if (target.signed) {
+      return { kind: "Const", type: target, value: { kind: "Int", value: value | 0, signed: true } } as Expr;
+    }
+    return { kind: "Const", type: target, value: { kind: "Int", value: value >>> 0, signed: false } } as Expr;
+  }
+  // Default: f32 const.
+  return { kind: "Const", type: Tf32, value: { kind: "Float", value } } as Expr;
+}
+/** Coerce `DerivedOperand` to a DerivedExpr, lifting raw numbers to a
+ *  Const expression whose type matches the receiver's scalar type. */
+function lift(other: DerivedOperand, receiverType: Type): DerivedExpr {
+  if (other instanceof DerivedExpr) return other;
+  return new DerivedExpr(liftConst(other, scalarLiftType(receiverType)));
+}
+
+/**
+ * A traced expression in a `derivedUniform` / `derivedMode` builder.
+ *
+ * Plays nicely with `boperators` (https://npmjs.com/package/boperators):
+ * the named-static operator methods (`static ["+"]`, `static ["*"]`,
+ * `static ["<"]`, …) make `a + b`, `a * b`, `a < b`, etc. on
+ * DerivedExprs rewrite to those statics at build time. Without the
+ * plugin, the same logic is reachable via the instance methods
+ * (`.add`, `.mul`, `.lt`, …).
+ *
+ * Ternary `a < b ? x : y` isn't rewritten — call `.select` on the
+ * resulting bool DerivedExpr:
+ *
+ *     (det < 0).select(flipped, declared)
+ */
 export class DerivedExpr {
   constructor(readonly ir: Expr) {}
   get type(): Type { return this.ir.type; }
 
   /** Matrix product `this · other` (also matrix·vector / vector·matrix by operand types). */
-  mul(other: DerivedExpr): DerivedExpr {
-    const a = this.ir.type, b = other.ir.type;
+  mul(other: DerivedOperand): DerivedExpr {
+    const o = lift(other, this.ir.type);
+    const a = this.ir.type, b = o.ir.type;
     if (a.kind === "Matrix" && b.kind === "Matrix") {
-      return new DerivedExpr({ kind: "MulMatMat", lhs: this.ir, rhs: other.ir, type: { kind: "Matrix", element: a.element, rows: a.rows, cols: b.cols } });
+      return new DerivedExpr({ kind: "MulMatMat", lhs: this.ir, rhs: o.ir, type: { kind: "Matrix", element: a.element, rows: a.rows, cols: b.cols } });
     }
     if (a.kind === "Matrix" && b.kind === "Vector") {
-      return new DerivedExpr({ kind: "MulMatVec", lhs: this.ir, rhs: other.ir, type: { kind: "Vector", element: b.element, dim: a.rows } });
+      return new DerivedExpr({ kind: "MulMatVec", lhs: this.ir, rhs: o.ir, type: { kind: "Vector", element: b.element, dim: a.rows } });
     }
     if (a.kind === "Vector" && b.kind === "Matrix") {
-      return new DerivedExpr({ kind: "MulVecMat", lhs: this.ir, rhs: other.ir, type: { kind: "Vector", element: a.element, dim: b.cols } });
+      return new DerivedExpr({ kind: "MulVecMat", lhs: this.ir, rhs: o.ir, type: { kind: "Vector", element: a.element, dim: b.cols } });
     }
-    return new DerivedExpr({ kind: "Mul", lhs: this.ir, rhs: other.ir, type: a.kind === "Float" ? b : a });
+    return new DerivedExpr({ kind: "Mul", lhs: this.ir, rhs: o.ir, type: a.kind === "Float" || a.kind === "Int" ? b : a });
   }
-  add(other: DerivedExpr): DerivedExpr { return new DerivedExpr({ kind: "Add", lhs: this.ir, rhs: other.ir, type: this.ir.type }); }
-  sub(other: DerivedExpr): DerivedExpr { return new DerivedExpr({ kind: "Sub", lhs: this.ir, rhs: other.ir, type: this.ir.type }); }
+  add(other: DerivedOperand): DerivedExpr { const o = lift(other, this.ir.type); return new DerivedExpr({ kind: "Add", lhs: this.ir, rhs: o.ir, type: this.ir.type }); }
+  sub(other: DerivedOperand): DerivedExpr { const o = lift(other, this.ir.type); return new DerivedExpr({ kind: "Sub", lhs: this.ir, rhs: o.ir, type: this.ir.type }); }
+  div(other: DerivedOperand): DerivedExpr { const o = lift(other, this.ir.type); return new DerivedExpr({ kind: "Div", lhs: this.ir, rhs: o.ir, type: this.ir.type }); }
+  mod(other: DerivedOperand): DerivedExpr { const o = lift(other, this.ir.type); return new DerivedExpr({ kind: "Mod", lhs: this.ir, rhs: o.ir, type: this.ir.type }); }
   neg(): DerivedExpr { return new DerivedExpr({ kind: "Neg", value: this.ir, type: this.ir.type }); }
 
   /** Inverse (of a constituent trafo this reads its stored backward half; otherwise unsupported in codegen). */
@@ -130,18 +182,160 @@ export class DerivedExpr {
   log2(): DerivedExpr { return this.u1("log2"); }
   sign(): DerivedExpr { return this.u1("sign"); }
   normalize(): DerivedExpr { return this.u1("normalize"); }
-  min(o: DerivedExpr): DerivedExpr { return this.bin("min", o); }
-  max(o: DerivedExpr): DerivedExpr { return this.bin("max", o); }
-  pow(o: DerivedExpr): DerivedExpr { return this.bin("pow", o); }
-  atan2(o: DerivedExpr): DerivedExpr { return this.bin("atan2", o); }
-  step(edge: DerivedExpr): DerivedExpr { return new DerivedExpr(intrinsicExpr("step", this.ir.type, [edge.ir, this.ir])); }
-  clamp(lo: DerivedExpr, hi: DerivedExpr): DerivedExpr { return new DerivedExpr(intrinsicExpr("clamp", this.ir.type, [this.ir, lo.ir, hi.ir])); }
-  mix(o: DerivedExpr, t: DerivedExpr): DerivedExpr { return new DerivedExpr(intrinsicExpr("mix", this.ir.type, [this.ir, o.ir, t.ir])); }
+  min(o: DerivedOperand): DerivedExpr { return this.bin("min", lift(o, this.ir.type)); }
+  max(o: DerivedOperand): DerivedExpr { return this.bin("max", lift(o, this.ir.type)); }
+  pow(o: DerivedOperand): DerivedExpr { return this.bin("pow", lift(o, this.ir.type)); }
+  atan2(o: DerivedOperand): DerivedExpr { return this.bin("atan2", lift(o, this.ir.type)); }
+  step(edge: DerivedOperand): DerivedExpr { const e = lift(edge, this.ir.type); return new DerivedExpr(intrinsicExpr("step", this.ir.type, [e.ir, this.ir])); }
+  clamp(lo: DerivedOperand, hi: DerivedOperand): DerivedExpr { const l = lift(lo, this.ir.type); const h = lift(hi, this.ir.type); return new DerivedExpr(intrinsicExpr("clamp", this.ir.type, [this.ir, l.ir, h.ir])); }
+  mix(o: DerivedOperand, t: DerivedOperand): DerivedExpr { const oo = lift(o, this.ir.type); const tt = lift(t, this.ir.type); return new DerivedExpr(intrinsicExpr("mix", this.ir.type, [this.ir, oo.ir, tt.ir])); }
   dot(o: DerivedExpr): DerivedExpr { return new DerivedExpr(intrinsicExpr("dot", elemOf(this.ir.type), [this.ir, o.ir])); }
   cross(o: DerivedExpr): DerivedExpr { return new DerivedExpr(intrinsicExpr("cross", this.ir.type, [this.ir, o.ir])); }
   length(): DerivedExpr { return new DerivedExpr(intrinsicExpr("length", elemOf(this.ir.type), [this.ir])); }
   distance(o: DerivedExpr): DerivedExpr { return new DerivedExpr(intrinsicExpr("distance", elemOf(this.ir.type), [this.ir, o.ir])); }
   reflect(n: DerivedExpr): DerivedExpr { return new DerivedExpr(intrinsicExpr("reflect", this.ir.type, [this.ir, n.ir])); }
+
+  // ── Comparisons (produce a bool DerivedExpr). Receivers + arg can be
+  //    raw numbers — `aardvark-operators` lifts `a < 2` to `a.lt(2)`,
+  //    and we lift `2` to a const matching the receiver's scalar type. ──
+  private cmp(kind: "Eq" | "Neq" | "Lt" | "Le" | "Gt" | "Ge", other: DerivedOperand): DerivedExpr {
+    const o = lift(other, this.ir.type);
+    const ir = { kind, lhs: this.ir, rhs: o.ir, type: { kind: "Bool" } as Type } as Expr;
+    return new DerivedExpr(ir);
+  }
+  eq(o: DerivedOperand): DerivedExpr { return this.cmp("Eq", o); }
+  ne(o: DerivedOperand): DerivedExpr { return this.cmp("Neq", o); }
+  lt(o: DerivedOperand): DerivedExpr { return this.cmp("Lt", o); }
+  le(o: DerivedOperand): DerivedExpr { return this.cmp("Le", o); }
+  gt(o: DerivedOperand): DerivedExpr { return this.cmp("Gt", o); }
+  ge(o: DerivedOperand): DerivedExpr { return this.cmp("Ge", o); }
+
+  /**
+   * Ternary select. The RECEIVER must be a bool — typically the
+   * result of a comparison — and the args are the then / else
+   * branches:
+   *
+   *     (det < 0).select(flipped, declared)   // det<0 ? flipped : declared
+   *
+   * The result type follows `then` (which must be widening-
+   * compatible with `else`). Raw numbers are lifted using `then`'s
+   * type when `then` is a DerivedExpr, else f32.
+   */
+  select(thenE: DerivedOperand, elseE: DerivedOperand): DerivedExpr {
+    if (this.ir.type.kind !== "Bool") {
+      throw new Error("DerivedExpr.select(then, else): receiver must be a bool (typically a comparison)");
+    }
+    const t = thenE instanceof DerivedExpr ? thenE : lift(thenE, elseE instanceof DerivedExpr ? elseE.ir.type : Tf32);
+    const e = elseE instanceof DerivedExpr ? elseE : lift(elseE, t.ir.type);
+    const ir = { kind: "Conditional", cond: this.ir, ifTrue: t.ir, ifFalse: e.ir, type: t.ir.type } as Expr;
+    return new DerivedExpr(ir);
+  }
+
+  /** Determinant of a square matrix expression — yields a scalar f32. */
+  determinant(): DerivedExpr {
+    if (this.ir.type.kind !== "Matrix") {
+      throw new Error("DerivedExpr.determinant(): receiver must be a matrix expression");
+    }
+    return new DerivedExpr({ kind: "Determinant", value: this.ir, type: Tf32 } as Expr);
+  }
+
+  // ── Static literal builders. Mode rules in particular need u32 constants for enum
+  //    indices (slot lookup). Floats for thresholds (e.g. determinant against zero).
+  static f32(value: number): DerivedExpr {
+    return new DerivedExpr({ kind: "Const", type: Tf32, value: { kind: "Float", value } } as Expr);
+  }
+  static u32(value: number): DerivedExpr {
+    return new DerivedExpr({ kind: "Const", type: Tu32, value: { kind: "Int", value: value >>> 0, signed: false } } as Expr);
+  }
+  static i32(value: number): DerivedExpr {
+    return new DerivedExpr({ kind: "Const", type: Ti32, value: { kind: "Int", value: value | 0, signed: true } } as Expr);
+  }
+
+  // ─── boperators static dispatch ──────────────────────────────────────
+  // `a OP b` (where at least one operand is a DerivedExpr) is rewritten
+  // by the boperators plugin to `DerivedExpr["OP"](a, b)`. Either-order
+  // overloads (`number OP expr`, `expr OP number`) are handled by lifting
+  // the raw number to a Const matching the other operand's scalar type.
+
+  static "+"(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "+"(a: DerivedExpr, b: number): DerivedExpr;
+  static "+"(a: number, b: DerivedExpr): DerivedExpr;
+  static "+"(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.add(b);
+  }
+  static "-"(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "-"(a: DerivedExpr, b: number): DerivedExpr;
+  static "-"(a: number, b: DerivedExpr): DerivedExpr;
+  static "-"(a: DerivedExpr): DerivedExpr; // unary minus
+  static "-"(a: DerivedOperand, b?: DerivedOperand): DerivedExpr {
+    if (b === undefined) return (a as DerivedExpr).neg();
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.sub(b);
+  }
+  static "*"(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "*"(a: DerivedExpr, b: number): DerivedExpr;
+  static "*"(a: number, b: DerivedExpr): DerivedExpr;
+  static "*"(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.mul(b);
+  }
+  static "/"(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "/"(a: DerivedExpr, b: number): DerivedExpr;
+  static "/"(a: number, b: DerivedExpr): DerivedExpr;
+  static "/"(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.div(b);
+  }
+  static "%"(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "%"(a: DerivedExpr, b: number): DerivedExpr;
+  static "%"(a: number, b: DerivedExpr): DerivedExpr;
+  static "%"(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.mod(b);
+  }
+  static "<"(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "<"(a: DerivedExpr, b: number): DerivedExpr;
+  static "<"(a: number, b: DerivedExpr): DerivedExpr;
+  static "<"(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.lt(b);
+  }
+  static "<="(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "<="(a: DerivedExpr, b: number): DerivedExpr;
+  static "<="(a: number, b: DerivedExpr): DerivedExpr;
+  static "<="(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.le(b);
+  }
+  static ">"(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static ">"(a: DerivedExpr, b: number): DerivedExpr;
+  static ">"(a: number, b: DerivedExpr): DerivedExpr;
+  static ">"(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.gt(b);
+  }
+  static ">="(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static ">="(a: DerivedExpr, b: number): DerivedExpr;
+  static ">="(a: number, b: DerivedExpr): DerivedExpr;
+  static ">="(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.ge(b);
+  }
+  static "=="(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "=="(a: DerivedExpr, b: number): DerivedExpr;
+  static "=="(a: number, b: DerivedExpr): DerivedExpr;
+  static "=="(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.eq(b);
+  }
+  static "!="(a: DerivedExpr, b: DerivedExpr): DerivedExpr;
+  static "!="(a: DerivedExpr, b: number): DerivedExpr;
+  static "!="(a: number, b: DerivedExpr): DerivedExpr;
+  static "!="(a: DerivedOperand, b: DerivedOperand): DerivedExpr {
+    const x = a instanceof DerivedExpr ? a : lift(a, (b as DerivedExpr).ir.type);
+    return x.ne(b);
+  }
 }
 
 /** The `u` passed to a `derivedUniform` builder. `u.<Name>` is a uniform leaf — a mat4