@aardworx/wombat.rendering 0.1.0

package/src/resources/shaderDiagnostics.ts

@@ -0,0 +1,52 @@
+// Shader-compile error reporting. WebGPU's `createShaderModule`
+// is synchronous and never throws on parse errors; the errors
+// surface only via `module.getCompilationInfo()`, which is async.
+// We fire-and-forget that call after creation and log structured
+// messages including the originating TS source location decoded
+// from the supplied source map.
+
+import type { SourceMap } from "@aardworx/wombat.shader/ir";
+import { decodeLine } from "./sourceMapDecoder.js";
+
+export interface ShaderDiagnosticsOptions {
+  /** Human-friendly tag prefixed to log messages. */
+  readonly label?: string;
+  /** Source map produced by wombat.shader for this stage. */
+  readonly sourceMap?: SourceMap | null;
+  /** Optional override for the logger. Default: console. */
+  readonly logger?: { error(...args: unknown[]): void; warn(...args: unknown[]): void };
+}
+
+export function installShaderDiagnostics(
+  module: GPUShaderModule,
+  source: string,
+  opts: ShaderDiagnosticsOptions = {},
+): void {
+  // getCompilationInfo is part of the WebGPU spec; some test mocks
+  // may not implement it. Detect and skip silently.
+  const info = (module as { getCompilationInfo?: () => Promise<GPUCompilationInfo> }).getCompilationInfo;
+  if (typeof info !== "function") return;
+  const log = opts.logger ?? console;
+  const tag = opts.label ?? "shader";
+
+  info.call(module).then((compInfo) => {
+    if (compInfo.messages.length === 0) return;
+    const map = opts.sourceMap ?? null;
+    for (const m of compInfo.messages) {
+      const lineText = source.split("\n")[Math.max(0, m.lineNum - 1)] ?? "";
+      const head = `[${tag}] ${m.type} ${m.lineNum}:${m.linePos}: ${m.message}`;
+      const body = lineText.length > 0 ? `\n  ${lineText.trim()}` : "";
+      const decoded = map ? decodeLine(map, m.lineNum) : null;
+      const origin = decoded
+        ? `\n  → ${decoded.file}:${decoded.line}:${decoded.column}`
+        : (map && map.sources.length > 0
+          ? `\n  (originated in ${map.sources.join(", ")})`
+          : "");
+      const line = `${head}${body}${origin}`;
+      if (m.type === "error") log.error(line);
+      else log.warn(line);
+    }
+  }).catch(() => {
+    // Mock environments / older browsers may reject; silent swallow.
+  });
+}

package/src/resources/sourceMapDecoder.ts

@@ -0,0 +1,133 @@
+// Decoder for v3 source maps. Supports both line-granular maps
+// (one segment per generated line at col 0) and multi-segment
+// lines (per-Expr granularity). Segments encode
+// (genColDelta, sourceIdxDelta, sourceLineDelta, sourceColDelta)
+// as base64-VLQ, with deltas accumulating across the whole map
+// except for genCol which resets at every `;` line boundary.
+//
+// `decodeLine(map, line)` returns the position for the *first*
+// segment on the line; `decodePosition(map, line, col)` picks the
+// closest preceding segment. Both fall back to the most recent
+// mapped line if the queried line is unmapped, which is what
+// `installShaderDiagnostics` wants for "go to source" navigation.
+
+import type { SourceMap } from "@aardworx/wombat.shader/ir";
+
+const VLQ_INDEX = new Map<string, number>();
+{
+  const a = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  for (let i = 0; i < a.length; i++) VLQ_INDEX.set(a.charAt(i), i);
+}
+
+function vlqDecode(s: string): number[] {
+  const out: number[] = [];
+  let value = 0;
+  let shift = 0;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s.charAt(i);
+    const digit = VLQ_INDEX.get(ch);
+    if (digit === undefined) throw new Error(`bad VLQ char: ${ch}`);
+    const cont = (digit & 0b100000) !== 0;
+    value |= (digit & 0b11111) << shift;
+    if (cont) {
+      shift += 5;
+    } else {
+      const negative = (value & 1) === 1;
+      const magnitude = value >>> 1;
+      out.push(negative ? -magnitude : magnitude);
+      value = 0;
+      shift = 0;
+    }
+  }
+  return out;
+}
+
+export interface DecodedPosition {
+  /** Source file as listed in `SourceMap.sources`. */
+  readonly file: string;
+  /** 1-based line in the original source. */
+  readonly line: number;
+  /** 1-based column in the original source. */
+  readonly column: number;
+}
+
+interface DecodedSegment {
+  readonly genCol: number;
+  readonly idx: number;
+  readonly line: number;
+  readonly col: number;
+}
+
+/** Walk the map up to (and including) `targetLine`, returning each line's segments. */
+function segmentsUpTo(map: SourceMap, targetLine: number): DecodedSegment[][] {
+  const lines = map.mappings.split(";");
+  const out: DecodedSegment[][] = [];
+  let srcIdx = 0;
+  let srcLine = 0;
+  let srcCol = 0;
+  for (let i = 0; i <= targetLine && i < lines.length; i++) {
+    const segs = (lines[i] ?? "").split(",").filter(s => s.length > 0);
+    let prevGenCol = 0;
+    const lineOut: DecodedSegment[] = [];
+    for (const sStr of segs) {
+      const fields = vlqDecode(sStr);
+      if (fields.length < 4) continue;
+      const genCol = prevGenCol + fields[0]!;
+      srcIdx += fields[1]!;
+      srcLine += fields[2]!;
+      srcCol += fields[3]!;
+      lineOut.push({ genCol, idx: srcIdx, line: srcLine, col: srcCol });
+      prevGenCol = genCol;
+    }
+    out.push(lineOut);
+  }
+  return out;
+}
+
+function makePosition(map: SourceMap, s: DecodedSegment): DecodedPosition | null {
+  const file = map.sources[s.idx];
+  if (file === undefined) return null;
+  return { file, line: s.line + 1, column: s.col + 1 };
+}
+
+/**
+ * Closest-preceding-segment lookup. Given a 1-based generated
+ * `line` + 0-based generated `col`, returns the originating source
+ * position. Falls back to the last segment on a previous mapped
+ * line if `line` itself has no segments.
+ */
+export function decodePosition(
+  map: SourceMap,
+  generatedLine: number,
+  generatedCol = 0,
+): DecodedPosition | null {
+  const target = generatedLine - 1;
+  if (target < 0) return null;
+  const allLines = segmentsUpTo(map, target);
+  // Prefer a segment on the target line at or before generatedCol.
+  const onTarget = allLines[target];
+  if (onTarget && onTarget.length > 0) {
+    let pick: DecodedSegment | undefined;
+    for (const s of onTarget) {
+      if (s.genCol <= generatedCol) pick = s;
+      else break;
+    }
+    if (pick) return makePosition(map, pick);
+    return makePosition(map, onTarget[0]!);
+  }
+  // Fallback: last segment on the most recent mapped line.
+  for (let i = target - 1; i >= 0; i--) {
+    const segs = allLines[i];
+    if (segs && segs.length > 0) return makePosition(map, segs[segs.length - 1]!);
+  }
+  return null;
+}
+
+/**
+ * Backwards-compatible line-only decoder: returns the *first*
+ * segment of `generatedLine`, or the most recent mapped line for
+ * unmapped lines. Equivalent to `decodePosition(map, line, 0)`.
+ */
+export function decodeLine(map: SourceMap, generatedLine: number): DecodedPosition | null {
+  return decodePosition(map, generatedLine, 0);
+}

package/src/resources/uniformBuffer.ts

@@ -0,0 +1,170 @@
+// prepareUniformBuffer — pack a name-keyed bag of `aval<unknown>`
+// uniforms into a single UBO described by a `UniformBlockInfo`
+// (from wombat.shader's ProgramInterface).
+//
+// The layout dictates byte offsets + sizes per field; this packer
+// trusts those numbers and just encodes values into a Float32-
+// addressable scratch buffer, then uploads via `queue.writeBuffer`
+// on each change.
+//
+// Value encoding by type:
+//   - `number`             → 1 × f32 at offset
+//   - `Float32Array`       → memcpy floats
+//   - `Int32Array`/`Uint32Array` → memcpy as-is (also valid for f32 storage)
+//   - any object with `_data: Float32Array | Int32Array | Uint32Array`
+//     (V2f/V3f/V4f/M44f/M33f/M22f, etc. from wombat.base) → memcpy `_data`
+//
+// Missing inputs (a layout field with no corresponding entry in
+// the bag) are left zero-initialised. Extras in the bag are
+// silently ignored — same "pull, don't push" semantics as the
+// rest of the renderer.
+
+import {
+  AdaptiveResource,
+  tryAcquire,
+  tryRelease,
+  type UniformBlockInfo,
+} from "../core/index.js";
+import {
+  type AdaptiveToken,
+  type aval,
+  type HashMap,
+} from "@aardworx/wombat.adaptive";
+import { BufferUsage } from "./webgpuFlags.js";
+
+export interface PackedView {
+  readonly bytes: ArrayBuffer;
+  readonly f32: Float32Array;
+  readonly i32: Int32Array;
+  readonly u32: Uint32Array;
+}
+
+export function makePackedView(byteSize: number): PackedView {
+  const bytes = new ArrayBuffer(roundUp4(byteSize));
+  return {
+    bytes,
+    f32: new Float32Array(bytes),
+    i32: new Int32Array(bytes),
+    u32: new Uint32Array(bytes),
+  };
+}
+
+class UniformBufferResource extends AdaptiveResource<GPUBuffer> {
+  private _gpu: GPUBuffer | undefined;
+  private readonly _scratch: PackedView;
+
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly layout: UniformBlockInfo,
+    private readonly inputs: HashMap<string, aval<unknown>>,
+    private readonly label: string | undefined,
+  ) {
+    super();
+    const bytes = new ArrayBuffer(roundUp4(layout.size));
+    this._scratch = {
+      bytes,
+      f32: new Float32Array(bytes),
+      i32: new Int32Array(bytes),
+      u32: new Uint32Array(bytes),
+    };
+  }
+
+  protected create(): void {
+    for (const f of this.layout.fields) {
+      const av = this.inputs.tryFind(f.name);
+      if (av !== undefined) tryAcquire(av);
+    }
+  }
+
+  protected destroy(): void {
+    if (this._gpu !== undefined) {
+      this._gpu.destroy();
+      this._gpu = undefined;
+    }
+    for (const f of this.layout.fields) {
+      const av = this.inputs.tryFind(f.name);
+      if (av !== undefined) tryRelease(av);
+    }
+  }
+
+  override compute(token: AdaptiveToken): GPUBuffer {
+    // Pack scratch.
+    new Uint8Array(this._scratch.bytes).fill(0);
+    for (const field of this.layout.fields) {
+      const av = this.inputs.tryFind(field.name);
+      if (av === undefined) continue;
+      writeField(this._scratch, field.offset, av.getValue(token));
+    }
+    if (this._gpu === undefined) {
+      const desc: GPUBufferDescriptor = {
+        size: this._scratch.bytes.byteLength,
+        usage: BufferUsage.UNIFORM | BufferUsage.COPY_DST,
+        ...(this.label !== undefined ? { label: this.label } : {}),
+      };
+      this._gpu = this.device.createBuffer(desc);
+    }
+    this.device.queue.writeBuffer(this._gpu, 0, this._scratch.bytes);
+    return this._gpu;
+  }
+}
+
+/**
+ * Write a value into a UBO scratch buffer at the given byte offset.
+ * `fieldType`, when supplied, disambiguates a bare `number`:
+ *   - Int (signed)    → i32
+ *   - Int (unsigned)  → u32
+ *   - Float (default) → f32
+ * Without it, numbers are assumed to be f32.
+ */
+export function writeField(
+  view: PackedView,
+  offset: number,
+  value: unknown,
+  fieldType?: import("../core/index.js").UniformFieldInfo["type"],
+): void {
+  if (typeof value === "number") {
+    if (fieldType?.kind === "Int") {
+      if (fieldType.signed) view.i32[offset >> 2] = value;
+      else view.u32[offset >> 2] = value;
+    } else {
+      view.f32[offset >> 2] = value;
+    }
+    return;
+  }
+  if (value instanceof Float32Array) {
+    view.f32.set(value, offset >> 2);
+    return;
+  }
+  if (value instanceof Int32Array) {
+    view.i32.set(value, offset >> 2);
+    return;
+  }
+  if (value instanceof Uint32Array) {
+    view.u32.set(value, offset >> 2);
+    return;
+  }
+  if (value !== null && typeof value === "object" && "_data" in (value as object)) {
+    const data = (value as { _data: unknown })._data;
+    if (data instanceof Float32Array) { view.f32.set(data, offset >> 2); return; }
+    if (data instanceof Int32Array)   { view.i32.set(data, offset >> 2); return; }
+    if (data instanceof Uint32Array)  { view.u32.set(data, offset >> 2); return; }
+  }
+  throw new Error(`prepareUniformBuffer: unsupported uniform value at offset ${offset}: ${String(value)}`);
+}
+
+function roundUp4(n: number): number {
+  return (n + 3) & ~3;
+}
+
+export interface PrepareUniformBufferOptions {
+  readonly label?: string;
+}
+
+export function prepareUniformBuffer(
+  device: GPUDevice,
+  layout: UniformBlockInfo,
+  inputs: HashMap<string, aval<unknown>>,
+  opts: PrepareUniformBufferOptions = {},
+): AdaptiveResource<GPUBuffer> {
+  return new UniformBufferResource(device, layout, inputs, opts.label);
+}

package/src/resources/webgpuFlags.ts

@@ -0,0 +1,43 @@
+// `GPUBufferUsage` / `GPUTextureUsage` / `GPUMapMode` etc. are
+// runtime-provided in the browser and Dawn-Node, but `@webgpu/types`
+// is a types-only package — the constants don't exist when running
+// under plain Node (vitest). Vendor the flag values here so the
+// resource layer can compose usage flags portably.
+//
+// Numbers are taken from the WebGPU spec. They are part of the
+// stable API surface.
+
+export const BufferUsage = {
+  MAP_READ: 0x0001,
+  MAP_WRITE: 0x0002,
+  COPY_SRC: 0x0004,
+  COPY_DST: 0x0008,
+  INDEX: 0x0010,
+  VERTEX: 0x0020,
+  UNIFORM: 0x0040,
+  STORAGE: 0x0080,
+  INDIRECT: 0x0100,
+  QUERY_RESOLVE: 0x0200,
+} as const;
+
+export const TextureUsage = {
+  COPY_SRC: 0x01,
+  COPY_DST: 0x02,
+  TEXTURE_BINDING: 0x04,
+  STORAGE_BINDING: 0x08,
+  RENDER_ATTACHMENT: 0x10,
+} as const;
+
+export const ShaderStage = {
+  VERTEX: 0x1,
+  FRAGMENT: 0x2,
+  COMPUTE: 0x4,
+} as const;
+
+export const ColorWrite = {
+  RED: 0x1,
+  GREEN: 0x2,
+  BLUE: 0x4,
+  ALPHA: 0x8,
+  ALL: 0xf,
+} as const;

package/src/runtime/copy.ts

@@ -0,0 +1,13 @@
+// copy(cmd, spec) — encode a buffer↔buffer or texture↔texture
+// transfer described by a `CopySpec`.
+
+import type { CopySpec } from "../core/index.js";
+
+export function copy(cmd: GPUCommandEncoder, spec: CopySpec): void {
+  if (spec.kind === "buffer") {
+    const range = spec.range ?? { srcOffset: 0, dstOffset: 0, size: spec.src.size };
+    cmd.copyBufferToBuffer(spec.src, range.srcOffset, spec.dst, range.dstOffset, range.size);
+  } else {
+    cmd.copyTextureToTexture(spec.src, spec.dst, spec.size);
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,24 @@
+// Public API of @aardworx/wombat.rendering-runtime.
+
+export {
+  Runtime,
+  type RuntimeOptions,
+} from "./runtime.js";
+
+export {
+  compileRenderTask,
+  type RuntimeContext,
+} from "./renderTask.js";
+
+export { copy } from "./copy.js";
+
+export {
+  renderTo,
+  type RenderToOptions,
+  type RenderToResult,
+} from "./renderTo.js";
+
+export {
+  ScenePass,
+  type WalkerStats,
+} from "./scenePass.js";

package/src/runtime/renderTask.ts

@@ -0,0 +1,137 @@
+// RenderTask — compile an `alist<Command>` into a runnable
+// IRenderTask.
+//
+// Per `Render` command we lazily build a `ScenePass` that holds a
+// stateful tree-walker subscribed to the dynamic subtrees
+// (`Adaptive` / `OrderedFromList` / `UnorderedFromSet`). Each frame:
+//   - The walker pulls deltas from its readers (O(deltas) work).
+//   - It produces the ordered list of `PreparedRenderObject`s.
+//   - We open the render pass and call `record(pass, token)` per leaf.
+//
+// The previous per-frame `collectLeaves` recursion through the tree
+// is gone. Static subtrees prep their leaves once at construction;
+// dynamic subtrees splice on delta — see scenePass.ts.
+
+import {
+  RenderContext,
+  type ClearValues,
+  type Command,
+  type CompiledEffect,
+  type Effect,
+  type IFramebuffer,
+  type IRenderTask,
+  type RenderTree,
+} from "../core/index.js";
+import { beginPassDescriptor, clear } from "../commands/index.js";
+import { AdaptiveToken, type alist, type aval } from "@aardworx/wombat.adaptive";
+import { copy } from "./copy.js";
+import { ScenePass } from "./scenePass.js";
+
+export interface RuntimeContext {
+  readonly device: GPUDevice;
+  readonly compileEffect: (effect: Effect) => CompiledEffect;
+}
+
+class RenderTask implements IRenderTask {
+  /**
+   * Cache of `ScenePass`es keyed on the `Render` command itself.
+   * Holding ScenePass per command means the same `RenderTree`
+   * reused across frames keeps its incrementally-maintained
+   * walker state.
+   */
+  private readonly _scenes = new Map<unknown, ScenePass>();
+  private _disposed = false;
+
+  constructor(
+    private readonly ctx: RuntimeContext,
+    private readonly commands: alist<Command>,
+  ) {}
+
+  run(token: AdaptiveToken): void {
+    if (this._disposed) throw new Error("RenderTask: run after dispose");
+    const enc = this.ctx.device.createCommandEncoder();
+    this.encode(enc, token);
+    this.ctx.device.queue.submit([enc.finish()]);
+  }
+
+  encode(enc: GPUCommandEncoder, token: AdaptiveToken): void {
+    if (this._disposed) throw new Error("RenderTask: encode after dispose");
+    RenderContext.withEncoder(enc, () => {
+      const arr: Command[] = [];
+      for (const c of this.commands.content.getValue(token)) arr.push(c);
+      for (let i = 0; i < arr.length; i++) {
+        const c = arr[i]!;
+        if (c.kind === "Clear") {
+          const next = arr[i + 1];
+          if (next !== undefined && next.kind === "Render" && next.output === c.output) {
+            this.encodeRenderCommand(enc, next, token, c.values);
+            i++;
+            continue;
+          }
+        }
+        this.encodeCommand(enc, c, token);
+      }
+    });
+  }
+
+  dispose(): void {
+    if (this._disposed) return;
+    for (const s of this._scenes.values()) s.dispose();
+    this._scenes.clear();
+    this._disposed = true;
+  }
+
+  private encodeCommand(enc: GPUCommandEncoder, c: Command, token: AdaptiveToken): void {
+    switch (c.kind) {
+      case "Clear":  clear(enc, c.output.getValue(token), c.values); return;
+      case "Copy":   copy(enc, c.copy); return;
+      case "Custom": c.encode(enc); return;
+      case "Render": this.encodeRenderCommand(enc, c, token); return;
+    }
+  }
+
+  private encodeRenderCommand(
+    enc: GPUCommandEncoder,
+    cmd: Extract<Command, { kind: "Render" }>,
+    token: AdaptiveToken,
+    clearValues?: ClearValues,
+  ): void {
+    const output = cmd.output.getValue(token);
+    const scene = this.sceneFor(cmd, output, cmd.tree);
+    const leaves = scene.resolve(token);
+    if (leaves.length === 0 && clearValues === undefined) return;
+    // Either we have draws or we need to clear — open a single pass.
+    const pass = enc.beginRenderPass(beginPassDescriptor(output, clearValues));
+    for (const leaf of leaves) leaf.record(pass, token);
+    pass.end();
+  }
+
+  private sceneFor(
+    cmd: Extract<Command, { kind: "Render" }>,
+    output: IFramebuffer,
+    tree: RenderTree,
+  ): ScenePass {
+    let s = this._scenes.get(cmd);
+    if (s === undefined) {
+      s = new ScenePass(this.ctx.device, output.signature, tree, this.ctx.compileEffect);
+      this._scenes.set(cmd, s);
+    }
+    return s;
+    // Note: `output.signature` is read here only to seed the
+    // ScenePass; subsequent frames continue to use this signature
+    // even if the framebuffer aval emits a different sig. That
+    // matches the `(RenderObject, signature)` cache invariant —
+    // changing signature requires a fresh Render command.
+  }
+}
+
+export function compileRenderTask(ctx: RuntimeContext, commands: alist<Command>): IRenderTask & {
+  encode(enc: GPUCommandEncoder, token: AdaptiveToken): void;
+} {
+  return new RenderTask(ctx, commands);
+}
+
+// `RenderTree` carries an `aval<RenderTree>` inside its `Adaptive`
+// variant; this `void` reference keeps the `aval` import live.
+const _avalGuard: ((x: aval<unknown>) => void) | undefined = undefined;
+void _avalGuard;