animader-cli 0.0.0-stage → 0.1.0

package/toolchain/prepare.mjs

@@ -0,0 +1,446 @@
+// One-time prepare adapter: fills the ignored demo/vendor/ bundle from the
+// workspace's actual built producers and writes the ignored fixture WAV.
+// It records every copied JS/WASM file's content sha256, its source path and
+// the producer's package version. Revision labels are supplementary; the
+// content rows and their digest are the proof.
+//
+// Roots: the content root is the repository root that owns this package's
+// checkout (npm/cli/toolchain → three levels up). Sibling checkouts are two
+// levels above it, and ANIMADER_PNGINE / ANIMADER_PACER / PNGINE override
+// them using the checkout convention. `$HOME/Dev` is not consulted.
+//
+// This module is the contributor workspace's prepare; the installed package
+// resolves the same artifacts through Node module resolution instead
+// (src/toolchain.mjs, stage 2 of the installed-toolchain plan).
+
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { DemoError } from '../lib/errors.mjs';
+import { createTestTone } from '../lib/wav.mjs';
+import {
+  VENDOR_FILE,
+  VENDOR_FORMAT,
+  makeProvenance,
+  provenanceLines,
+  validateProvenance,
+} from '../lib/vendor.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export function defaultContentRoot() {
+  return resolve(HERE, '..', '..', '..');
+}
+
+export function resolveRoots({ contentRoot = defaultContentRoot(), env = process.env } = {}) {
+  const absoluteContent = resolve(contentRoot);
+  const workspaceRoot = resolve(absoluteContent, '..', '..');
+  const pngineRoot = resolve(env.ANIMADER_PNGINE || join(workspaceRoot, 'pngine'));
+  const pacerRoot = resolve(env.ANIMADER_PACER || join(workspaceRoot, 'pacer'));
+  const pngineCli = resolve(env.PNGINE || join(pngineRoot, 'zig-out', 'bin', 'pngine'));
+  return { contentRoot: absoluteContent, workspaceRoot, pngineRoot, pacerRoot, pngineCli };
+}
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+async function readJsonIfPresent(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+
+async function listJs(root, producer, remedy) {
+  let names;
+  try {
+    names = await readdir(root);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+      throw new DemoError('missing_producer_input', `${producer} source directory is missing: ${root}`, { remedy });
+    }
+    throw error;
+  }
+  return names.filter((name) => name.endsWith('.js')).sort();
+}
+
+/** The vendor plan: every runtime file the contributor bundle (and the
+ *  release manifest's runtime rows — scripts/release-runtime.mjs) carries,
+ *  as destination → producer-source pairs. The whole producer subtrees,
+ *  not an import closure: the dir-mode mount serves these by containment,
+ *  so any narrower derivation could drift from what it serves. */
+export async function planSources(roots) {
+  const sources = [];
+  const add = (producer, dest, source, remedy) => sources.push({ producer, dest, source, remedy });
+
+  add(
+    'animader',
+    'animader/animader.wasm',
+    join(roots.contentRoot, 'zig-out', 'bin', 'animader.wasm'),
+    "Build it with 'zig build wasm' from the content root, or point the demo at a built wasm artifact.",
+  );
+  for (const name of await listJs(
+    join(roots.contentRoot, 'npm', 'animader', 'src'),
+    'animader npm',
+    'The animader JS glue is part of this checkout; restore npm/animader/src before preparing the demo.',
+  )) {
+    add('animader', `animader/${name}`, join(roots.contentRoot, 'npm', 'animader', 'src', name), 'Restore the animader npm/animader/src tree.');
+  }
+
+  add(
+    'pngine',
+    'pngine.mjs',
+    join(roots.pngineRoot, 'npm', 'pngine', 'dist', 'viewer.mjs'),
+    "Build pngine's npm viewer, or set ANIMADER_PNGINE to the pngine checkout root.",
+  );
+
+  for (const name of await listJs(
+    join(roots.pacerRoot, 'npm', 'pacer', 'src'),
+    'pacer npm',
+    'Set ANIMADER_PACER to the pacer checkout root, or restore its npm/pacer/src tree.',
+  )) {
+    add('pacer', `pacer/${name}`, join(roots.pacerRoot, 'npm', 'pacer', 'src', name), 'Set ANIMADER_PACER to the pacer checkout root, or restore its npm/pacer/src tree.');
+  }
+  add(
+    'pacer',
+    'pacer/pacer.wasm',
+    join(roots.pacerRoot, 'npm', 'pacer', 'pacer.wasm'),
+    "Build pacer.wasm, or set ANIMADER_PACER to the pacer checkout root.",
+  );
+  add(
+    'pacer',
+    'pacer/pacer-rt.wasm',
+    join(roots.pacerRoot, 'npm', 'pacer', 'pacer-rt.wasm'),
+    "Build pacer-rt.wasm with 'zig build wasm-rt', or set ANIMADER_PACER to the pacer checkout root.",
+  );
+
+  const pnginePackage = await readJsonIfPresent(join(roots.pngineRoot, 'npm', 'pngine', 'package.json'));
+  const pacerPackage = await readJsonIfPresent(join(roots.pacerRoot, 'npm', 'pacer', 'package.json'));
+  return {
+    sources: sources.sort((a, b) => (a.dest < b.dest ? -1 : a.dest > b.dest ? 1 : 0)),
+    producers: {
+      animader: { contentRoot: roots.contentRoot },
+      pngine: { root: roots.pngineRoot, packageVersion: pnginePackage?.version ?? null },
+      pacer: { root: roots.pacerRoot, packageVersion: pacerPackage?.version ?? null },
+    },
+  };
+}
+
+async function readSource(entry) {
+  let info;
+  try {
+    info = await stat(entry.source);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new DemoError('missing_producer_input', `${entry.producer} input is missing: ${entry.source}`, {
+        remedy: entry.remedy,
+      });
+    }
+    throw error;
+  }
+  if (!info.isFile() || info.size === 0) {
+    throw new DemoError('missing_producer_input', `${entry.producer} input is not a non-empty file: ${entry.source}`, {
+      remedy: entry.remedy,
+    });
+  }
+  return readFile(entry.source);
+}
+
+/**
+ * Copy the planned runtime into vendorRoot with a fresh provenance document.
+ * All sources are checked before the live bundle is touched.
+ *
+ * @param {{contentRoot: string, pngineRoot: string, pacerRoot: string, vendorRoot: string}} roots
+ */
+export async function prepareVendor(roots) {
+  const plan = await planSources(roots);
+  const staged = [];
+  for (const entry of plan.sources) {
+    const bytes = await readSource(entry);
+    staged.push({ entry, bytes });
+  }
+
+  const staging = `${roots.vendorRoot}.next`;
+  let committed = false;
+  try {
+    await rm(staging, { recursive: true, force: true });
+    for (const { entry, bytes } of staged) {
+      const destination = join(staging, entry.dest);
+      await mkdir(dirname(destination), { recursive: true });
+      await writeFile(destination, bytes);
+    }
+
+    const files = [];
+    for (const { entry } of staged) {
+      const bytes = await readFile(join(staging, entry.dest));
+      files.push({
+        path: entry.dest,
+        source: entry.source,
+        sha256: sha256(bytes),
+        bytes: bytes.byteLength,
+      });
+    }
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const digest = sha256(provenanceLines(files));
+    const provenance = makeProvenance({ producers: plan.producers, files, digest });
+    await writeFile(join(staging, VENDOR_FILE), `${JSON.stringify(provenance, null, 2)}\n`);
+
+    await rm(roots.vendorRoot, { recursive: true, force: true });
+    await rename(staging, roots.vendorRoot);
+    committed = true;
+    return { vendorRoot: roots.vendorRoot, provenance };
+  } finally {
+    if (!committed) await rm(staging, { recursive: true, force: true });
+  }
+}
+
+async function walkFiles(root, prefix = '') {
+  const entries = await readdir(join(root, prefix), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const relative = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) files.push(...await walkFiles(root, relative));
+    else files.push({ path: relative, kind: entry.isFile() ? 'file' : 'other' });
+  }
+  return files;
+}
+
+/**
+ * Read and validate a bundle's provenance document, including its content
+ * digest. Missing or malformed documents are named distinctly from content
+ * drift so a caller can report the right remedy.
+ *
+ * @param {string} vendorRoot
+ */
+async function loadProvenance(vendorRoot) {
+  let text;
+  try {
+    text = await readFile(join(vendorRoot, VENDOR_FILE), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new DemoError('vendor_missing', `the runtime bundle is missing: ${join(vendorRoot, VENDOR_FILE)}`, {
+        remedy: 'Run the one-time prepare: node demo/prepare.mjs',
+      });
+    }
+    throw error;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new DemoError('bad_vendor_provenance', `${VENDOR_FILE} is not JSON: ${error.message}`, {
+      remedy: 'Regenerate the bundle with: node demo/prepare.mjs',
+    });
+  }
+  const provenance = validateProvenance(parsed);
+  const digest = sha256(provenanceLines(provenance.files));
+  if (parsed.digest !== digest) {
+    throw new DemoError('vendor_provenance_digest', `${VENDOR_FILE} digest does not match its content rows`, {
+      remedy: 'Regenerate the bundle with: node demo/prepare.mjs',
+    });
+  }
+  return { provenance, digest };
+}
+
+/** The producer roots recorded in the bundle, keyed by provenance name. */
+function recordedProducerRoots(producers) {
+  const roots = {};
+  if (typeof producers?.animader?.contentRoot === 'string') roots.animader = producers.animader.contentRoot;
+  if (typeof producers?.pngine?.root === 'string') roots.pngine = producers.pngine.root;
+  if (typeof producers?.pacer?.root === 'string') roots.pacer = producers.pacer.root;
+  return roots;
+}
+
+/** The current root for a producer, preferring an explicitly resolved root. */
+function currentProducerRoot(name, resolvedRoots, recordedRoot) {
+  if (!resolvedRoots) return recordedRoot;
+  const current = {
+    animader: resolvedRoots.contentRoot,
+    pngine: resolvedRoots.pngineRoot,
+    pacer: resolvedRoots.pacerRoot,
+  }[name];
+  return current ?? recordedRoot;
+}
+
+/**
+ * Match a recorded absolute source against the recorded producer roots and
+ * return the producer-relative path. Longest root wins so a nested checkout
+ * cannot steal a file from its parent. Returns null when no root contains it.
+ */
+function locateProducerSource(source, roots) {
+  let match = null;
+  for (const [name, root] of Object.entries(roots)) {
+    const rel = relative(resolve(root), resolve(source));
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) continue;
+    if (match === null || root.length > match.root.length) match = { name, root, relative: rel };
+  }
+  return match;
+}
+
+/**
+ * Close the post-prepare blind spot: compare every vendored file with the
+ * current bytes of the producer file its provenance says it came from. A
+ * bundle that agrees with its own record can still be stale against a
+ * producer that has moved since prepare.
+ *
+ * @param {{vendorRoot: string, roots?: Object}} options
+ */
+export async function verifyProducerFreshness({ vendorRoot, roots = null }) {
+  const { provenance } = await loadProvenance(vendorRoot);
+  const recorded = recordedProducerRoots(provenance.producers);
+  let checked = 0;
+
+  for (const entry of provenance.files) {
+    const located = locateProducerSource(entry.source, recorded);
+    if (located === null) {
+      throw new DemoError(
+        'bad_vendor_provenance',
+        `${entry.path} records no source under a known producer root: ${entry.source}`,
+        { remedy: 'Regenerate the bundle with: node demo/prepare.mjs' },
+      );
+    }
+    const root = currentProducerRoot(located.name, roots, located.root);
+    const producerPath = join(root, located.relative);
+
+    let info;
+    try {
+      info = await stat(producerPath);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new DemoError(
+          'missing_producer_input',
+          `${located.name} input is missing: ${producerPath}`,
+          { remedy: `Restore ${producerPath}, or re-sync with the current producer roots.` },
+        );
+      }
+      throw error;
+    }
+    if (!info.isFile() || info.size === 0) {
+      throw new DemoError(
+        'missing_producer_input',
+        `${located.name} input is not a non-empty file: ${producerPath}`,
+        { remedy: `Restore ${producerPath}, or re-sync with the current producer roots.` },
+      );
+    }
+
+    let vendoredBytes;
+    try {
+      vendoredBytes = await readFile(join(vendorRoot, entry.path));
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new DemoError('vendor_missing_file', `the runtime bundle is missing ${entry.path}`, {
+          remedy: 'Run the one-time prepare: node demo/prepare.mjs',
+        });
+      }
+      throw error;
+    }
+
+    const producerBytes = await readFile(producerPath);
+    if (!vendoredBytes.equals(producerBytes)) {
+      throw new DemoError(
+        'vendor_stale_producer',
+        `the vendored ${entry.path} is stale against ${located.name}'s ${producerPath}: ` +
+          `sha256 ${sha256(vendoredBytes)} vs ${sha256(producerBytes)}`,
+        {
+          remedy:
+            'Re-sync the bundle: ANIMADER_PACER=<pacer checkout> ANIMADER_PNGINE=<pngine checkout> ' +
+            'node demo/prepare.mjs, then node demo/prepare.mjs --verify',
+        },
+      );
+    }
+    checked++;
+  }
+
+  return { files: checked, producers: provenance.producers };
+}
+
+/**
+ * Verify the prepared bundle against its own content manifest. This catches
+ * a missing or stale file, a stale extra file, and any byte drift.
+ *
+ * @param {{vendorRoot: string}} options
+ */
+export async function verifyVendor({ vendorRoot }) {
+  const { provenance, digest } = await loadProvenance(vendorRoot);
+  const actual = await walkFiles(vendorRoot);
+  const actualPaths = new Set(actual.map((entry) => entry.path));
+  const expectedPaths = new Set(provenance.files.map((entry) => entry.path));
+  for (const entry of provenance.files) {
+    if (!actualPaths.has(entry.path)) {
+      throw new DemoError('vendor_missing_file', `the runtime bundle is missing ${entry.path}`, {
+        remedy: 'Run the one-time prepare: node demo/prepare.mjs',
+      });
+    }
+    const bytes = await readFile(join(vendorRoot, entry.path));
+    if (bytes.byteLength !== entry.bytes || sha256(bytes) !== entry.sha256) {
+      throw new DemoError('vendor_content_drift', `${entry.path} does not match its recorded content`, {
+        remedy: 'Run the one-time prepare: node demo/prepare.mjs',
+      });
+    }
+  }
+  for (const entry of actual) {
+    if (entry.path === VENDOR_FILE) continue;
+    if (entry.kind !== 'file' || !expectedPaths.has(entry.path)) {
+      throw new DemoError('vendor_stale', `the runtime bundle carries an unrecorded entry: ${entry.path}`, {
+        remedy: 'Run the one-time prepare: node demo/prepare.mjs',
+      });
+    }
+  }
+
+  return {
+    format: VENDOR_FORMAT,
+    producers: provenance.producers,
+    files: provenance.files,
+    digest,
+    vendorRoot,
+  };
+}
+
+/**
+ * Write the ignored fixture soundtrack. The bytes come from the deterministic
+ * helper, never from the network or a captured artifact.
+ *
+ * @param {{fixtureRoot: string}} options
+ */
+export async function writeFixtureTone({ fixtureRoot }) {
+  const bytes = createTestTone();
+  await mkdir(fixtureRoot, { recursive: true });
+  const path = join(fixtureRoot, 'soundtrack.wav');
+  await writeFile(path, bytes);
+  return { path, bytes: bytes.byteLength, sha256: sha256(bytes) };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const roots = resolveRoots();
+  if (argv.includes('--verify')) {
+    const vendorRoot = join(roots.contentRoot, 'demo', 'vendor');
+    const verified = await verifyVendor({ vendorRoot });
+    const fresh = await verifyProducerFreshness({ vendorRoot, roots });
+    console.log(`vendor: ok (${verified.files.length} files, digest ${verified.digest})`);
+    console.log(`producer: ok (${fresh.files} files match their current producer bytes)`);
+    return;
+  }
+  const prepared = await prepareVendor({ ...roots, vendorRoot: join(roots.contentRoot, 'demo', 'vendor') });
+  const tone = await writeFixtureTone({ fixtureRoot: join(roots.contentRoot, 'demo', 'fixture') });
+  console.log(`vendor: ${prepared.vendorRoot}`);
+  console.log(`provenance: ${join(prepared.vendorRoot, VENDOR_FILE)}`);
+  console.log(`runtime digest: ${prepared.provenance.digest}`);
+  console.log(`runtime files: ${prepared.provenance.files.length}`);
+  console.log(`soundtrack: ${tone.path} (${tone.bytes} bytes, sha256 ${tone.sha256})`);
+  console.log('next: node demo/show.mjs demo/fixture --seconds 8 --no-open');
+}
+
+const invoked = process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url;
+if (invoked) {
+  main().catch((error) => {
+    console.error(`error: ${error.message}`);
+    if (error.remedy) console.error(`remedy: ${error.remedy}`);
+    process.exitCode = error.exitCode ?? 1;
+  });
+}

package/toolchain/uniform-type-name.js

@@ -0,0 +1,184 @@
+// setUniform's value → bytes conversion: the UniformType tag table and the
+// per-type packers.
+//
+// Split out of gpu.js (Phase 4 of the js-runtime-hardening plan) because it is
+// the one part of that file with no GPU in it — pure, module-scoped, already
+// unit-tested on its own, and coupled instead to the WIRE format: the UT_* tags
+// must match uniform_table.zig, which tests/npm/uniform-type-lanes.test.js pins
+// by parsing THIS file. gpu.js keeps a re-export so `import { uniformToTypedArray }
+// from "./gpu.js"` still resolves.
+//
+// ## Invariants
+// - A tag this runtime doesn't recognize is packed as f32 rather than dropped:
+//   255 (unreflectable) is a legitimate wire value, and an unknown one means the
+//   payload is newer than the runtime. Best-effort beats a blank frame.
+// - Array fields expand at the WIRE stride (size / elemCount), not packed —
+//   WGSL uniform-space array strides are 16-byte multiples.
+
+// Build flag — see gpu.js. Guarded so this module is importable raw.
+if (typeof DEBUG === "undefined") globalThis.DEBUG = false;
+
+// UniformType enum values (must match uniform_table.zig — the coupling is
+// gated by tests/npm/uniform-type-lanes.test.js)
+const UT_F32 = 0, UT_I32 = 1, UT_U32 = 2;
+const UT_VEC2F = 3, UT_VEC3F = 4, UT_VEC4F = 5;
+const UT_MAT3X3F = 6, UT_MAT4X4F = 7;
+const UT_VEC2I = 8, UT_VEC3I = 9, UT_VEC4I = 10;
+const UT_VEC2U = 11, UT_VEC3U = 12, UT_VEC4U = 13;
+const UT_UNKNOWN = 255; // unreflectable field type — best-effort f32 by design
+// Input lanes (JS numbers) per single value of each type — used to slice a
+// flat array into per-element chunks for array uniforms. Scalars and unknown
+// tags fall back to 1 (matches convertOne's f32 best-effort default).
+const UT_LANES = {
+  [UT_VEC2F]: 2, [UT_VEC2I]: 2, [UT_VEC2U]: 2,
+  [UT_VEC3F]: 3, [UT_VEC3I]: 3, [UT_VEC3U]: 3,
+  [UT_VEC4F]: 4, [UT_VEC4I]: 4, [UT_VEC4U]: 4,
+  [UT_MAT3X3F]: 9, // row-major input, padded to 48B on convert
+  [UT_MAT4X4F]: 16,
+};
+// The tags by name, as WGSL spells them and uniform_table.zig's enum names
+// them — what getUniforms reports and what a refusal message says. Indexed
+// by tag: the enum is contiguous from 0, and uniform-type-lanes.test.js holds
+// this order to the Zig file. A tag past the table — 255, the word the
+// compiler writes for a type it could not reflect, or one newer than this
+// runtime — reads as "unknown".
+const UT_NAMES = "f32 i32 u32 vec2f vec3f vec4f mat3x3f mat4x4f vec2i vec3i vec4i vec2u vec3u vec4u".split(" ");
+
+/**
+ * A wire type tag's WGSL name.
+ * @param {number} tag - UniformType enum value
+ * @returns {string}
+ */
+export function uniformTypeName(tag) {
+  return UT_NAMES[tag] ?? "unknown";
+}
+
+/**
+ * The public description of a reflected uniform table — what getUniforms
+ * resolves to. The wire map carries a dispatcher buffer id and a type tag,
+ * neither of which anything public accepts; the description carries the
+ * buffer's `(buffer :name …)` — the name writeBuffer and getBuffers speak —
+ * and the type's WGSL name. A pool's members are consecutive ids from the
+ * block's base. `buffer` is null when the payload names nothing: one minted
+ * before the buffer-name block (3.0.1 and earlier), or a buffer the block
+ * does not list.
+ * @param {Map<string, {bufferId: number, offset: number, size: number, type: number, elemCount: number}>} uniforms
+ * @param {Map<string, {id: number, pool?: number}>} buffers - the buffer-name block
+ * @returns {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number}>}
+ */
+export function describeUniforms(uniforms, buffers) {
+  const nameOf = (id) => {
+    for (const [name, b] of buffers) if (id >= b.id && id < b.id + (b.pool || 1)) return name;
+    return null;
+  };
+  /** @type {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number}>} */
+  const out = {};
+  for (const [name, info] of uniforms) {
+    out[name] = { type: uniformTypeName(info.type), size: info.size, buffer: nameOf(info.bufferId), offset: info.offset, elemCount: info.elemCount };
+  }
+  return out;
+}
+
+/**
+ * Convert JS value to a TypedArray-backed byte view based on UniformType.
+ * For array fields (elemCount > 0) the value is expanded per-element at the
+ * wire-implied stride (size / elemCount — WGSL uniform-space array strides
+ * are 16-byte multiples, so elements are padded, not packed). Accepts flat
+ * ([1,2,3,4,5,6]) or nested ([[1,2,3],[4,5,6]]) input; missing trailing
+ * elements stay zero. Exported for tests/npm/gpu-uniform-arrays.test.js.
+ * @param {number|number[]|number[][]} value
+ * @param {number} uniformType - UniformType enum value (the ELEMENT type for arrays)
+ * @param {number} size - Expected byte size (TOTAL array bytes for arrays)
+ * @param {number} [elemCount] - Array element count; 0/undefined = not an array
+ * @returns {Uint8Array|null}
+ */
+export function uniformToTypedArray(value, uniformType, size, elemCount) {
+  const arr = Array.isArray(value) ? value : [value];
+  if (!elemCount) return convertOne(/** @type {number[]} */ (arr), uniformType, size); // not an array field
+  const stride = Math.floor(size / elemCount);
+  if (stride === 0) return convertOne(/** @type {number[]} */ (arr), uniformType, size); // degenerate wire data
+  const lanes = UT_LANES[uniformType] || 1;
+  const out = new Uint8Array(size);
+  // `nested` picks which of the two shapes `arr` actually is; the two views
+  // below just name that invariant so each branch reads as the shape it needs.
+  const nested = Array.isArray(arr[0]);
+  const rows = /** @type {number[][]} */ (arr);
+  const flat = /** @type {number[]} */ (arr);
+  for (let i = 0; i < elemCount; i++) {
+    const elem = nested ? rows[i] : flat.slice(i * lanes, (i + 1) * lanes);
+    if (!elem || elem.length === 0) break; // short input: rest stays zero
+    const chunk = convertOne(elem, uniformType, stride);
+    if (!chunk) return null;
+    out.set(chunk.subarray(0, Math.min(chunk.length, stride)), i * stride);
+  }
+  return out;
+}
+
+/**
+ * Convert ONE value (a normalized number[]) to bytes for a single element of
+ * the given UniformType; `size` clamps the output byte length.
+ * @param {number[]} arr
+ * @param {number} uniformType - UniformType enum value
+ * @param {number} size - Expected byte size
+ * @returns {Uint8Array|null}
+ */
+function convertOne(arr, uniformType, size) {
+  switch (uniformType) {
+    case UT_F32:
+    case UT_VEC2F:
+    case UT_VEC3F:
+    case UT_VEC4F: {
+      const f32 = new Float32Array(arr);
+      return new Uint8Array(f32.buffer, 0, Math.min(f32.byteLength, size));
+    }
+
+    case UT_I32:
+    case UT_VEC2I:
+    case UT_VEC3I:
+    case UT_VEC4I: {
+      const i32 = new Int32Array(arr);
+      return new Uint8Array(i32.buffer, 0, Math.min(i32.byteLength, size));
+    }
+
+    case UT_U32:
+    case UT_VEC2U:
+    case UT_VEC3U:
+    case UT_VEC4U: {
+      const u32 = new Uint32Array(arr);
+      return new Uint8Array(u32.buffer, 0, Math.min(u32.byteLength, size));
+    }
+
+    case UT_MAT3X3F: {
+      // mat3x3 in WGSL is 3 vec4 columns (48 bytes with padding)
+      // Input: 9 floats (row-major), output: 3 vec4 columns (column-major with padding)
+      const f32 = new Float32Array(12); // 3 columns × 4 floats
+      if (arr.length >= 9) {
+        // Column 0
+        f32[0] = arr[0]; f32[1] = arr[3]; f32[2] = arr[6]; f32[3] = 0;
+        // Column 1
+        f32[4] = arr[1]; f32[5] = arr[4]; f32[6] = arr[7]; f32[7] = 0;
+        // Column 2
+        f32[8] = arr[2]; f32[9] = arr[5]; f32[10] = arr[8]; f32[11] = 0;
+      }
+      return new Uint8Array(f32.buffer, 0, Math.min(48, size));
+    }
+
+    case UT_MAT4X4F: {
+      // mat4x4 in WGSL is 4 vec4 columns (64 bytes)
+      // Assume input is column-major (WebGPU convention)
+      const f32 = new Float32Array(arr.length >= 16 ? arr : [...arr, ...Array(16 - arr.length).fill(0)]);
+      return new Uint8Array(f32.buffer, 0, Math.min(64, size));
+    }
+
+    default: {
+      // 255 (unknown) is a legitimate wire tag for unreflectable field types —
+      // best-effort f32 is the designed path there. Any OTHER tag means this
+      // runtime predates the tag (version skew): say so, then still try f32.
+      if (uniformType !== UT_UNKNOWN) {
+        DEBUG && console.warn(`[GPU] setUniform: unrecognized UniformType tag ${uniformType} — treating as f32 (runtime older than payload?)`);
+      }
+      const f32 = new Float32Array(arr);
+      return new Uint8Array(f32.buffer, 0, Math.min(f32.byteLength, size));
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.