@aardworx/wombat.rendering 0.9.14 → 0.9.15

package/src/runtime/heapScene/packers.ts

@@ -0,0 +1,127 @@
+// WGSL-type → JS-value packers used by heapScene to write per-draw
+// uniforms into the arena's Float32Array staging mirror.
+//
+// One packer per supported WGSL type. The `pack` callback takes the
+// aval's `.getValue(tok)` result and writes its bytes to `dst` at
+// float offset `off`. Coerces between Trafo3d / M44d / V4f / V3d /
+// V3f / number as needed.
+//
+// Integer scalar / vector packers go through a same-buffer Uint32/
+// Int32 view to avoid the lossy i32 → f32 coercion you'd get from a
+// direct `dst[off] = ...` assignment.
+
+import type { M44d, V4f } from "@aardworx/wombat.base";
+
+export interface WgslPacker {
+  /** Tightly-packed size in bytes of one value (mat4 = 64, vec3 = 12, …). */
+  readonly dataBytes: number;
+  readonly typeId: number;
+  /**
+   * Pack `val` (the aval's `.getValue(tok)` result) into `dst` at
+   * float offset `off`.
+   */
+  readonly pack: (val: unknown, dst: Float32Array, off: number) => void;
+}
+
+function packMat44(m: M44d, dst: Float32Array, off: number): void {
+  // Zero-alloc flat copy (row-major) straight into the f32 staging
+  // buffer — `copyTo` does `dst.set(m._data, off)` which narrows f64→f32
+  // on store, no throwaway `number[]` per call.
+  m.copyTo(dst, off);
+}
+
+export const PACKER_MAT4: WgslPacker = {
+  dataBytes: 64, typeId: 0,
+  pack: (val, dst, off) => {
+    // Accept Trafo3d (uses .forward) or M44d directly.
+    const m = (val as { forward?: M44d }).forward !== undefined
+      ? (val as { forward: M44d }).forward
+      : (val as M44d);
+    packMat44(m, dst, off);
+  },
+};
+
+export const PACKER_VEC4: WgslPacker = {
+  dataBytes: 16, typeId: 0,
+  pack: (val, dst, off) => {
+    const v = val as V4f;
+    dst[off + 0] = v.x; dst[off + 1] = v.y;
+    dst[off + 2] = v.z; dst[off + 3] = v.w;
+  },
+};
+
+export const PACKER_VEC3: WgslPacker = {
+  dataBytes: 12, typeId: 0,
+  pack: (val, dst, off) => {
+    // V3f or V3d both expose .x/.y/.z; cast through a common shape.
+    const v = val as { x: number; y: number; z: number };
+    dst[off + 0] = v.x; dst[off + 1] = v.y; dst[off + 2] = v.z;
+  },
+};
+
+export const PACKER_VEC2: WgslPacker = {
+  dataBytes: 8, typeId: 0,
+  pack: (val, dst, off) => {
+    const v = val as { x: number; y: number };
+    dst[off + 0] = v.x; dst[off + 1] = v.y;
+  },
+};
+
+export const PACKER_F32: WgslPacker = {
+  dataBytes: 4, typeId: 0,
+  pack: (val, dst, off) => { dst[off] = val as number; },
+};
+
+function makeIntPacker(
+  ctor: typeof Uint32Array | typeof Int32Array,
+  dim: 1 | 2 | 3 | 4,
+): WgslPacker {
+  const bytes = dim * 4;
+  if (dim === 1) {
+    return {
+      dataBytes: bytes, typeId: 0,
+      pack: (val, dst, off) => {
+        new ctor(dst.buffer as ArrayBuffer, dst.byteOffset + off * 4, 1)[0] = val as number;
+      },
+    };
+  }
+  return {
+    dataBytes: bytes, typeId: 0,
+    pack: (val, dst, off) => {
+      const view = new ctor(dst.buffer as ArrayBuffer, dst.byteOffset + off * 4, dim);
+      const v = val as { x: number; y: number; z?: number; w?: number };
+      view[0] = v.x; view[1] = v.y;
+      if (dim >= 3) view[2] = v.z!;
+      if (dim >= 4) view[3] = v.w!;
+    },
+  };
+}
+
+export const PACKER_U32     = makeIntPacker(Uint32Array, 1);
+export const PACKER_UVEC2   = makeIntPacker(Uint32Array, 2);
+export const PACKER_UVEC3   = makeIntPacker(Uint32Array, 3);
+export const PACKER_UVEC4   = makeIntPacker(Uint32Array, 4);
+export const PACKER_I32     = makeIntPacker(Int32Array, 1);
+export const PACKER_IVEC2   = makeIntPacker(Int32Array, 2);
+export const PACKER_IVEC3   = makeIntPacker(Int32Array, 3);
+export const PACKER_IVEC4   = makeIntPacker(Int32Array, 4);
+
+export function packerForWgslType(wgslType: string): WgslPacker {
+  switch (wgslType) {
+    case "mat4x4<f32>": return PACKER_MAT4;
+    case "vec4<f32>":   return PACKER_VEC4;
+    case "vec3<f32>":   return PACKER_VEC3;
+    case "vec2<f32>":   return PACKER_VEC2;
+    case "f32":         return PACKER_F32;
+    case "u32":         return PACKER_U32;
+    case "vec2<u32>":   return PACKER_UVEC2;
+    case "vec3<u32>":   return PACKER_UVEC3;
+    case "vec4<u32>":   return PACKER_UVEC4;
+    case "i32":         return PACKER_I32;
+    case "vec2<i32>":   return PACKER_IVEC2;
+    case "vec3<i32>":   return PACKER_IVEC3;
+    case "vec4<i32>":   return PACKER_IVEC4;
+    default:
+      throw new Error(`heapScene: no JS-side packer for WGSL type '${wgslType}'`);
+  }
+}

package/src/runtime/heapScene/pools.ts

@@ -0,0 +1,492 @@
+// Arena + pool allocators that back the heap renderer's per-RO
+// storage. Pulled out of heapScene.ts as a unit because the five
+// classes here are tightly interleaved:
+//
+//   AttributeArena    — byte-bump over a STORAGE GrowBuffer
+//   IndexAllocator    — element-bump over an INDEX GrowBuffer
+//   DrawHeap          — slot-indexed allocator over a STORAGE GrowBuffer
+//                       (one slot per RO drawHeader)
+//   UniformPool       — aval-keyed refcounted alloc on top of AttributeArena
+//   IndexPool         — aval-keyed refcounted alloc on top of IndexAllocator,
+//                       with value-tuple dedup for constant avals (§5b).
+//
+// Plus the per-allocation header constants used by all of them and
+// the `buildArenaState` / `arenaBytes` / `writeAttribute` / `asAval`
+// / `isBufferView` / `asFloat32` helpers that the heap-scene factory
+// uses to assemble the arena.
+
+import { AVal } from "@aardworx/wombat.adaptive";
+import type { aval, IDisposable } from "@aardworx/wombat.adaptive";
+import type { BufferView } from "../../core/bufferView.js";
+import type { HostBufferSource } from "../../core/buffer.js";
+import { GrowBuffer, ALIGN16 } from "./growBuffer.js";
+
+// ─── Per-allocation header layout ──────────────────────────────────────
+
+/** Per-allocation header: (u32 typeId, u32 length). Data follows
+ *  the header aligned up to 16 bytes (so positions/normals/etc. line
+ *  up for future vec4 reads). */
+export const ALLOC_HEADER_BYTES   = 8;
+export const ALLOC_HEADER_PAD_TO  = 16;
+
+/** Encoding-tag enum (low 16 bits of typeId). */
+export const ENC_V3F_TIGHT = 1; // tightly-packed array of vec3<f32> (12 B/elt)
+
+/** Semantic-tag enum (high 16 bits of typeId). Optional metadata —
+ *  the shader doesn't branch on this. */
+export const SEM_POSITIONS = 1;
+export const SEM_NORMALS   = 2;
+
+// ─── UniformPool ───────────────────────────────────────────────────────
+
+interface PoolEntry {
+  /** Byte offset into the arena. Data starts at ref + ALLOC_HEADER_PAD_TO. */
+  readonly ref: number;
+  readonly dataBytes: number;
+  readonly typeId: number;
+  /** Packer used to refresh the data region on aval marks. */
+  readonly pack: (val: unknown, dst: Float32Array, off: number) => void;
+  refcount: number;
+}
+
+/**
+ * Aval-keyed pool of arena allocations. One allocation per unique
+ * aval (object identity). Two draws referencing the same aval share
+ * the allocation; their DrawHeaders carry the same u32 ref. Holds
+ * uniforms (fixed-size scalars/vectors/matrices) AND attribute arrays
+ * (variable-size). The caller decides `dataBytes` + `length` per
+ * acquisition — the pool just keys on aval identity and refcounts.
+ *
+ * Sharing emerges from aval identity — no separate "frequency"
+ * declaration needed. A `cval` shared by all draws → 1 alloc.
+ * A static positions array shared across instanced draws → 1 alloc.
+ * Same code path either way.
+ */
+export class UniformPool {
+  // Keyed by `aval<unknown>` *by reference* (a plain JS `Map`). These
+  // keys are overwhelmingly reactive `cval`s (per-object trafos,
+  // colours, …) and the hot path is `acquire`/`release` ~once per
+  // drawHeader field per RO.
+  private readonly byAval = new Map<aval<unknown>, PoolEntry>();
+
+  has(av: aval<unknown>): boolean { return this.byAval.has(av); }
+  entry(av: aval<unknown>): PoolEntry | undefined { return this.byAval.get(av); }
+
+  /**
+   * Acquire (or share) an allocation for `aval`. Caller passes the
+   * pre-read `value` (so the pool doesn't need a token) plus the
+   * (`dataBytes`, `typeId`, `length`, `pack`) describing how to lay
+   * it out. If a new allocation is made, the value is packed and
+   * uploaded immediately.
+   */
+  acquire(
+    device: GPUDevice,
+    arena: AttributeArena,
+    av: aval<unknown>,
+    value: unknown,
+    dataBytes: number,
+    typeId: number,
+    length: number,
+    pack: (val: unknown, dst: Float32Array, off: number) => void,
+  ): number {
+    const existing = this.byAval.get(av);
+    if (existing !== undefined) {
+      existing.refcount++;
+      return existing.ref;
+    }
+    const ref = arena.alloc(dataBytes);
+    const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
+    const buf = new ArrayBuffer(allocBytes);
+    const u32 = new Uint32Array(buf);
+    const f32 = new Float32Array(buf);
+    u32[0] = typeId;
+    u32[1] = length;
+    // stride_bytes (offset 8): bytes per element. Lets the VS decode
+    // pick V3- vs V4-tight load expressions for vec4 attributes.
+    u32[2] = length > 0 ? Math.floor(dataBytes / length) : 0;
+    pack(value, f32, ALLOC_HEADER_PAD_TO / 4);
+    arena.write(ref, new Uint8Array(buf));
+    void device;
+    this.byAval.set(av, { ref, dataBytes, typeId, pack, refcount: 1 });
+    return ref;
+  }
+
+  /** Decrement refcount; if zero, free the arena allocation. */
+  release(arena: AttributeArena, av: aval<unknown>): void {
+    const e = this.byAval.get(av);
+    if (e === undefined) return;
+    e.refcount--;
+    if (e.refcount > 0) return;
+    arena.release(e.ref, ALIGN16(ALLOC_HEADER_PAD_TO + e.dataBytes));
+    this.byAval.delete(av);
+  }
+
+  /** Re-pack one entry's data region into the arena's CPU shadow. */
+  repack(device: GPUDevice, arena: AttributeArena, av: aval<unknown>, val: unknown): void {
+    const e = this.byAval.get(av);
+    if (e === undefined) return;
+    const dst = new Float32Array(e.dataBytes / 4);
+    e.pack(val, dst, 0);
+    arena.write(
+      e.ref + ALLOC_HEADER_PAD_TO,
+      new Uint8Array(dst.buffer, dst.byteOffset, e.dataBytes),
+    );
+    void device;
+  }
+}
+
+// ─── IndexPool ─────────────────────────────────────────────────────────
+
+/**
+ * Aval-keyed pool over the `IndexAllocator`. Two draws referencing
+ * the same `Uint32Array` (or aval thereof) share an index range —
+ * 19K instanced clones of the same mesh share one allocation, one
+ * upload.
+ *
+ * **Value-equality dedup for constant avals (§5b):** when an
+ * incoming aval has `isConstant === true`, the pool also keys by
+ * the underlying `ArrayBuffer` tuple `(buffer, byteOffset,
+ * byteLength)`. Two distinct constant avals wrapping the same
+ * `Uint32Array` view collapse to one allocation.
+ */
+export class IndexPool {
+  private readonly byAval = new Map<
+    aval<Uint32Array>,
+    { entry: IndexPoolEntry; perAvalCount: number }
+  >();
+  private readonly byValueKey = new Map<string, IndexPoolEntry>();
+  private readonly bufferIds = new WeakMap<ArrayBufferLike, number>();
+  private nextBufferId = 1;
+  private bufferIdOf(buf: ArrayBufferLike): number {
+    let id = this.bufferIds.get(buf);
+    if (id === undefined) {
+      id = this.nextBufferId++;
+      this.bufferIds.set(buf, id);
+    }
+    return id;
+  }
+
+  acquire(
+    device: GPUDevice,
+    indices: IndexAllocator,
+    av: aval<Uint32Array>,
+    arr: Uint32Array,
+  ): { firstIndex: number; count: number } {
+    const bound = this.byAval.get(av);
+    if (bound !== undefined) {
+      bound.perAvalCount++;
+      bound.entry.totalRefcount++;
+      return { firstIndex: bound.entry.firstIndex, count: bound.entry.count };
+    }
+    let valueKey: string | undefined;
+    if (av.isConstant) {
+      valueKey = `${this.bufferIdOf(arr.buffer)}:${arr.byteOffset}:${arr.byteLength}`;
+      const shared = this.byValueKey.get(valueKey);
+      if (shared !== undefined) {
+        shared.totalRefcount++;
+        this.byAval.set(av, { entry: shared, perAvalCount: 1 });
+        return { firstIndex: shared.firstIndex, count: shared.count };
+      }
+    }
+    const firstIndex = indices.alloc(arr.length);
+    indices.write(
+      firstIndex * 4,
+      new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength),
+    );
+    void device;
+    const entry: IndexPoolEntry = { firstIndex, count: arr.length, totalRefcount: 1, valueKey };
+    this.byAval.set(av, { entry, perAvalCount: 1 });
+    if (valueKey !== undefined) this.byValueKey.set(valueKey, entry);
+    return { firstIndex, count: arr.length };
+  }
+
+  release(indices: IndexAllocator, av: aval<Uint32Array>): void {
+    const bound = this.byAval.get(av);
+    if (bound === undefined) return;
+    bound.perAvalCount--;
+    bound.entry.totalRefcount--;
+    if (bound.perAvalCount === 0) this.byAval.delete(av);
+    if (bound.entry.totalRefcount > 0) return;
+    indices.release(bound.entry.firstIndex, bound.entry.count);
+    if (bound.entry.valueKey !== undefined) {
+      this.byValueKey.delete(bound.entry.valueKey);
+    }
+  }
+}
+
+interface IndexPoolEntry {
+  firstIndex: number;
+  count: number;
+  totalRefcount: number;
+  valueKey: string | undefined;
+}
+
+// ─── DrawHeap (slot-indexed) ───────────────────────────────────────────
+
+/**
+ * Slot-indexed allocator over a GrowBuffer. `slotBytes` is set per-
+ * instance — each bucket sizes its DrawHeader from its effect's
+ * schema, so a bucket whose layout is e.g. 96 B / slot uses a
+ * DrawHeap with `slotBytes=96`.
+ */
+export class DrawHeap {
+  private free: number[] = [];
+  private nextSlot = 0;
+  constructor(private readonly buf: GrowBuffer, private readonly slotBytes: number) {}
+  get buffer(): GPUBuffer { return this.buf.buffer; }
+  /** Bytes per slot — caller multiplies by slot index for byte offsets. */
+  get bytesPerSlot(): number { return this.slotBytes; }
+  /** High-water mark in bytes (used to size bind-group entry on rebuild). */
+  get usedBytes(): number { return this.nextSlot * this.slotBytes; }
+  alloc(): number {
+    const slot = this.free.length > 0 ? this.free.pop()! : this.nextSlot++;
+    this.buf.ensureCapacity((slot + 1) * this.slotBytes);
+    this.buf.setUsed(Math.max(this.buf.usedBytes, (slot + 1) * this.slotBytes));
+    return slot;
+  }
+  release(slot: number): void { this.free.push(slot); }
+  onResize(cb: () => void): IDisposable { return this.buf.onResize(cb); }
+  destroy(): void { this.buf.destroy(); }
+}
+
+// ─── AttributeArena (byte-bump) ────────────────────────────────────────
+
+/**
+ * Byte-bump allocator over a GrowBuffer for variable-size attribute
+ * allocations. Each allocation gets a 16-byte aligned start (8-byte
+ * (typeId, length) header at the start, data 16 bytes in). Frees go
+ * onto a sorted free list with coalesce on insert.
+ */
+export class AttributeArena {
+  private cursor = 0;
+  private freeList: { off: number; size: number }[] = [];
+  /** CPU shadow of the entire GPU buffer; writes go here first then
+   *  flush() emits one writeBuffer per dirty contiguous range. */
+  private shadow: Uint8Array;
+  private dirtyMin = Infinity;
+  private dirtyMax = 0;
+  constructor(private readonly buf: GrowBuffer) {
+    this.shadow = new Uint8Array(buf.capacity);
+    buf.onResize(() => {
+      const grown = new Uint8Array(buf.capacity);
+      grown.set(this.shadow);
+      this.shadow = grown;
+    });
+  }
+  get buffer(): GPUBuffer { return this.buf.buffer; }
+  get capacity(): number { return this.buf.capacity; }
+  get usedBytes(): number { return this.cursor; }
+  write(dst: number, data: Uint8Array): void {
+    this.shadow.set(data, dst);
+    if (dst < this.dirtyMin) this.dirtyMin = dst;
+    const end = dst + data.byteLength;
+    if (end > this.dirtyMax) this.dirtyMax = end;
+  }
+  flush(device: GPUDevice): void {
+    if (this.dirtyMax <= this.dirtyMin) return;
+    device.queue.writeBuffer(
+      this.buf.buffer, this.dirtyMin,
+      this.shadow.buffer, this.shadow.byteOffset + this.dirtyMin,
+      this.dirtyMax - this.dirtyMin,
+    );
+    this.dirtyMin = Infinity;
+    this.dirtyMax = 0;
+  }
+  /**
+   * Allocate space for one attribute. Returns the byte ref (offset
+   * to the header — data lives at ref + 16).
+   */
+  alloc(dataBytes: number): number {
+    const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
+    // First-fit reuse from free list.
+    for (let i = 0; i < this.freeList.length; i++) {
+      const f = this.freeList[i]!;
+      if (f.size >= allocBytes) {
+        const ref = f.off;
+        if (f.size === allocBytes) this.freeList.splice(i, 1);
+        else { f.off += allocBytes; f.size -= allocBytes; }
+        return ref;
+      }
+    }
+    const ref = this.cursor;
+    this.cursor += allocBytes;
+    this.buf.ensureCapacity(this.cursor);
+    this.buf.setUsed(this.cursor);
+    return ref;
+  }
+  release(ref: number, dataBytes: number): void {
+    const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
+    insertSortedFreeBlock(this.freeList, ref, allocBytes);
+  }
+  onResize(cb: () => void): IDisposable { return this.buf.onResize(cb); }
+  destroy(): void { this.buf.destroy(); }
+}
+
+/**
+ * Insert `{off, size}` into a free-list kept sorted by `off`, then
+ * coalesce with the two immediate neighbours.
+ */
+export function insertSortedFreeBlock(
+  freeList: { off: number; size: number }[],
+  off: number,
+  size: number,
+): void {
+  let lo = 0, hi = freeList.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (freeList[mid]!.off <= off) lo = mid + 1;
+    else hi = mid;
+  }
+  const prev = lo > 0 ? freeList[lo - 1] : undefined;
+  if (prev !== undefined && prev.off + prev.size === off) {
+    prev.size += size;
+    const next = freeList[lo];
+    if (next !== undefined && prev.off + prev.size === next.off) {
+      prev.size += next.size;
+      freeList.splice(lo, 1);
+    }
+    return;
+  }
+  const next = freeList[lo];
+  if (next !== undefined && off + size === next.off) {
+    next.off = off;
+    next.size += size;
+    return;
+  }
+  freeList.splice(lo, 0, { off, size });
+}
+
+// ─── IndexAllocator (element-bump) ─────────────────────────────────────
+
+/**
+ * Element-bump allocator over an index GrowBuffer (units = u32). Each
+ * draw's index range is allocated as one block; on release the block
+ * is returned to a free list and can be reused first-fit.
+ */
+export class IndexAllocator {
+  private cursor = 0;     // in u32s, not bytes
+  private freeList: { off: number; size: number }[] = [];
+  private shadow: Uint8Array;
+  private dirtyMin = Infinity;
+  private dirtyMax = 0;
+  constructor(private readonly buf: GrowBuffer) {
+    this.shadow = new Uint8Array(buf.capacity);
+    buf.onResize(() => {
+      const grown = new Uint8Array(buf.capacity);
+      grown.set(this.shadow);
+      this.shadow = grown;
+    });
+  }
+  get buffer(): GPUBuffer { return this.buf.buffer; }
+  get usedElements(): number { return this.cursor; }
+  write(dstByteOffset: number, data: Uint8Array): void {
+    this.shadow.set(data, dstByteOffset);
+    if (dstByteOffset < this.dirtyMin) this.dirtyMin = dstByteOffset;
+    const end = dstByteOffset + data.byteLength;
+    if (end > this.dirtyMax) this.dirtyMax = end;
+  }
+  flush(device: GPUDevice): void {
+    if (this.dirtyMax <= this.dirtyMin) return;
+    device.queue.writeBuffer(
+      this.buf.buffer, this.dirtyMin,
+      this.shadow.buffer, this.shadow.byteOffset + this.dirtyMin,
+      this.dirtyMax - this.dirtyMin,
+    );
+    this.dirtyMin = Infinity;
+    this.dirtyMax = 0;
+  }
+  alloc(elements: number): number {
+    for (let i = 0; i < this.freeList.length; i++) {
+      const f = this.freeList[i]!;
+      if (f.size >= elements) {
+        const off = f.off;
+        if (f.size === elements) this.freeList.splice(i, 1);
+        else { f.off += elements; f.size -= elements; }
+        return off;
+      }
+    }
+    const off = this.cursor;
+    this.cursor += elements;
+    this.buf.ensureCapacity(this.cursor * 4);
+    this.buf.setUsed(this.cursor * 4);
+    return off;
+  }
+  release(off: number, elements: number): void {
+    insertSortedFreeBlock(this.freeList, off, elements);
+  }
+  onResize(cb: () => void): IDisposable { return this.buf.onResize(cb); }
+  destroy(): void { this.buf.destroy(); }
+}
+
+// ─── ArenaState + helpers ──────────────────────────────────────────────
+
+/**
+ * Global arena state: attribute / uniform data lives in `attrs`
+ * (multi-typed-view storage); indices live in `indices` (separate
+ * INDEX-usage buffer).
+ */
+export interface ArenaState {
+  readonly attrs:    AttributeArena;
+  readonly indices:  IndexAllocator;
+}
+
+export function buildArenaState(
+  device: GPUDevice,
+  attrBytesHint: number,
+  idxBytesHint: number,
+  label: string,
+  idxExtraUsage: GPUBufferUsageFlags = 0,
+): ArenaState {
+  const attrs = new AttributeArena(new GrowBuffer(
+    device, `${label}/attrs`, GPUBufferUsage.STORAGE,
+    attrBytesHint,
+  ));
+  const indices = new IndexAllocator(new GrowBuffer(
+    device, `${label}/idx`, GPUBufferUsage.INDEX | idxExtraUsage,
+    idxBytesHint,
+  ));
+  return { attrs, indices };
+}
+
+export function arenaBytes(arena: ArenaState): number {
+  return arena.attrs.usedBytes + arena.indices.usedElements * 4;
+}
+
+/** Upload a single attribute — header (typeId, length) + data — into the arena at byte offset `ref`. */
+export function writeAttribute(
+  device: GPUDevice, buf: GPUBuffer, ref: number, typeId: number, length: number, data: Float32Array,
+): void {
+  const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + data.byteLength);
+  const staging = new ArrayBuffer(allocBytes);
+  const u32 = new Uint32Array(staging);
+  const f32 = new Float32Array(staging);
+  u32[0] = typeId;
+  u32[1] = length;
+  f32.set(data, ALLOC_HEADER_PAD_TO / 4);
+  device.queue.writeBuffer(buf, ref, staging, 0, allocBytes);
+}
+
+export function asAval<T>(v: aval<T> | T): aval<T> {
+  return (typeof v === "object" && v !== null && typeof (v as { getValue?: unknown }).getValue === "function")
+    ? (v as aval<T>)
+    : AVal.constant(v as T);
+}
+
+/** Heuristic predicate — BufferView has `buffer: aval<IBuffer>` + elementType. */
+export function isBufferView(v: unknown): v is BufferView {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as { buffer?: unknown; elementType?: unknown };
+  return typeof o.buffer === "object" && o.buffer !== null
+      && typeof (o.buffer as { getValue?: unknown }).getValue === "function"
+      && typeof o.elementType === "object" && o.elementType !== null;
+}
+
+/** Float32 view over a host-side buffer source. Used by the BufferView
+ *  packer to hand the pool a typed array it can `set()` from. */
+export function asFloat32(data: HostBufferSource): Float32Array {
+  if (data instanceof Float32Array) return data;
+  if (ArrayBuffer.isView(data)) {
+    return new Float32Array(data.buffer, data.byteOffset, data.byteLength / 4);
+  }
+  return new Float32Array(data); // ArrayBuffer
+}