animader-cli 0.0.0-stage → 0.1.1

package/adapters/watch.mjs

@@ -0,0 +1,355 @@
+// The recursive project watcher (plan section 5). One native `fs.watch`
+// handle covers the whole project tree (recursive watching is this Node's
+// own), and every event is filtered before it is forwarded: authored input,
+// kernels and nested relative asset directories forward, while the
+// generated `out/` tree, the default release/staging trees (`dist/`,
+// `dist.next/`), the detached `dist.size.json` report, `.git`,
+// `node_modules` and legacy `.animader-export-work-*` debris never do — so
+// a build's own outputs cannot reach the loop. Exports to other output
+// names need matching entries; the defaults cover the plan's named ones
+// only.
+//
+// The watcher PROMPTS; it never decides. Forwarding is unconditional for
+// every filtered event — a creation, a rewrite, a reappearance, a
+// directory change, even a replayed event for a write that predates the
+// watch (macOS fs.watch({recursive:true}) is FSEvents and answers recent
+// history for a newly watched tree). Whether a prompt means a change is
+// the session's to answer, from the filesystem, against snapshots it owns:
+// a platform's event delivery affects only how soon the loop looks, never
+// whether it looks correctly. There is no event baseline, no start
+// timestamp and no per-path record here to drift — which is also why a
+// tree that cannot be walked cannot suppress anything: nothing is walked.
+// The watcher does not coalesce either: one editor save may legitimately
+// answer several events (an atomic save is a temp-file create plus a
+// rename), and coalescing bursts into one build is the build loop's
+// decision.
+//
+// Beside the watcher stands the stat safety net (`createInputSweep`):
+// some platforms keep reporting the OLD vnode after an atomic save, so the
+// path goes silent for the process's life (measured on obs), and network
+// filesystems answer no event at all. The sweep stats the build's own
+// consumed-input rows — the receipt's `inputs.files`, the same input set
+// the build records, so there is no second list to drift — and lists the
+// filtered entries of the directories that hold them, and feeds any
+// difference to the SAME loop entry point a watcher event feeds. Both are
+// prompts; the session judges both the same way.
+//
+// Failures are actionable, never silent: a folder that cannot be watched
+// throws `watch_failed` before anything starts, and a runtime watcher error
+// reaches `onError` with the same identity — the caller decides to report
+// and keep serving. `close()` is final and idempotent.
+
+import { promises as fsp } from 'node:fs';
+import { watch as nodeWatch } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+
+import { serverError } from '../lib/errors.mjs';
+import { LEGACY_WORK_PREFIX, SNAPSHOT_PRUNED_NAMES } from './snapshot.mjs';
+
+/**
+ * Root-relative paths the watcher excludes by default: the generated
+ * `out/` tree, the default release output and its staging directory, and
+ * the detached size report.
+ */
+export const DEFAULT_WATCH_EXCLUDED_PATHS = Object.freeze(['out', 'dist', 'dist.next', 'dist.size.json']);
+
+function watchFailure(cause) {
+  return serverError(
+    'watch_failed',
+    `watching the project failed: ${cause?.message ?? String(cause)}`,
+    'Check that the project folder exists and is readable, then restart animader dev; serving the last successful generation does not need the watcher.',
+  );
+}
+
+/**
+ * The change filter: true when an absolute path is authored input this
+ * dev session must rebuild for. A path is excluded when it leaves the
+ * project root, or when it sits inside (or is) any excluded root-relative
+ * tree or report, at any depth. `.git`, `node_modules` and legacy work
+ * debris are pruned at any depth, exactly like the input snapshot's own
+ * filter.
+ *
+ * @param {{projectRoot: string, excludedPaths?: string[]}} options
+ * @returns {(source: string) => boolean}
+ */
+export function createProjectWatchFilter({ projectRoot, excludedPaths = DEFAULT_WATCH_EXCLUDED_PATHS }) {
+  const excluded = new Set(excludedPaths);
+  return (source) => {
+    const rel = relative(projectRoot, source);
+    if (rel === '') return true;
+    if (rel.startsWith(`..${sep}`) || isAbsolute(rel)) return false;
+    const segments = rel.split(sep);
+    if (segments.some((name) => SNAPSHOT_PRUNED_NAMES.includes(name) || name.startsWith(LEGACY_WORK_PREFIX))) {
+      return false;
+    }
+    // Any excluded root-relative path is a subtree: a file or a deeper
+    // directory under it is excluded with it.
+    for (let depth = 1; depth <= segments.length; depth += 1) {
+      if (excluded.has(segments.slice(0, depth).join('/'))) return false;
+    }
+    return true;
+  };
+}
+
+// ─── the watcher: filtered events forward as prompts ────────────────────────
+
+/**
+ * Watch one project folder recursively. Every filtered event forwards as
+ * one prompt (`onChange` with the changed path); an event that carries no
+ * filename forwards with null — a prompt the session cannot miss, because
+ * a false prompt costs one look at the filesystem while a dropped edit
+ * costs a stale generation. The watcher decides nothing else: no start
+ * clock, no baseline, no per-path record — whether a prompt means a
+ * change is judged downstream, from the filesystem.
+ *
+ * @param {Object} options
+ * @param {string} options.folder the project folder (watched recursively)
+ * @param {(source: string|null) => boolean} options.filter receives the
+ *   absolute changed path (or null when the platform answers no filename)
+ * @param {(source: string|null) => void} options.onChange one filtered
+ *   change, forwarded as a prompt
+ * @param {(error: Error) => void} options.onError a runtime watcher failure
+ * @param {(folder: string, options: Object, handler: Function) => object} [options.watchImpl]
+ * @returns {{close(): void}}
+ */
+export function watchProject({ folder, filter, onChange, onError, watchImpl = nodeWatch }) {
+  let watcher;
+  try {
+    watcher = watchImpl(folder, { recursive: true }, (eventType, filename) => {
+      if (filename === null || filename === undefined) {
+        // No filename to filter on: forward the prompt anyway; the
+        // session's decision is a stat pass, never the event's metadata.
+        onChange(null);
+        return;
+      }
+      const source = join(folder, String(filename));
+      if (!filter(source)) return;
+      onChange(source);
+    });
+  } catch (cause) {
+    throw watchFailure(cause);
+  }
+
+  watcher.on('error', (cause) => {
+    onError(watchFailure(cause));
+  });
+
+  let closed = false;
+  return {
+    close() {
+      if (closed) return;
+      closed = true;
+      watcher.close();
+    },
+  };
+}
+
+// ─── the stat safety net ────────────────────────────────────────────────────
+
+/** The default sweep period: ~1 s, the order the dev session promises. */
+export const DEFAULT_SWEEP_INTERVAL_MS = 1000;
+
+/** Project-relative rows use '/', whatever the host separator is. */
+function rowContainer(row) {
+  const cut = row.lastIndexOf('/');
+  return cut === -1 ? '' : row.slice(0, cut);
+}
+
+/**
+ * One file's cheap identity: size, mtime and inode (where the platform
+ * answers one — a rename-over always changes the inode on the hosts that
+ * have inodes). A row that is gone, replaced by a directory, or currently
+ * unreadable is its own identity, so the change is still reported.
+ */
+function statIdentity(stats) {
+  if (stats === null || stats.isDirectory()) return null;
+  return `${stats.size}:${stats.mtimeMs}:${stats.ino ?? '-'}`;
+}
+
+/**
+ * One path's stat-row identity, shared by the sweep's periodic comparison
+ * and the dev session's publish-time freshness check: `statIdentity`'s
+ * {size, mtimeMs, inode} for a file, null when the path is gone (a clean
+ * ENOENT/ENOTDIR is an answer — a deletion — not an error), and
+ * `unreadable:<code>` when the stat cannot answer at all.
+ */
+export async function statRow(path) {
+  try {
+    return statIdentity(await fsp.stat(path));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    return `unreadable:${error.code ?? 'unknown'}`;
+  }
+}
+
+/**
+ * One directory's cheap identity: the names of its entries that pass the
+ * SAME filter the watcher uses — excluded trees (`out/`, `dist/`, `.git`,
+ * `node_modules`, legacy work debris) are not part of the identity, so a
+ * build's own outputs can never look like a change. A missing directory
+ * is its own identity. Entry names are enough here: a replaced file keeps
+ * its name, and its own row's stat identity is what reports the swap.
+ *
+ * Exported for the dev session's own input snapshots, which compare the
+ * same directory discipline the sweep compares.
+ */
+export async function statDir(dir, filter) {
+  let entries;
+  try {
+    entries = await fsp.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    return `unreadable:${error.code ?? 'unknown'}`;
+  }
+  return entries
+    .filter((entry) => filter(join(dir, entry.name)))
+    .map((entry) => `${entry.isDirectory() ? 'd' : 'f'}:${entry.name}`)
+    .sort()
+    .join('|');
+}
+
+/**
+ * The stat-based safety net beside the watcher: a bounded, periodic
+ * comparison over the project's authored input set — the consumed-input
+ * rows the build's own receipt records (program, timeline, soundtrack and
+ * every authored resource beside them, kernels included) plus the
+ * directories that hold them, so a newly created kernel is noticed. One
+ * sweep is N stats and D directory listings, never a tree walk; a
+ * difference is reported once through the same `onChange` the watcher
+ * feeds, and the baselines move to the observed state, so the same
+ * difference is never reported twice.
+ *
+ * Baseline discipline is what keeps one edit at exactly one build:
+ * `accounted()` re-reads every baseline when a build starts (everything
+ * up to that instant is inside the running build, watcher event or not),
+ * and `inputs()` adopts the finished build's rows WITHOUT resetting the
+ * identities it already holds, so an edit that landed mid-build still
+ * reports on the next sweep. Before the first successful build the row
+ * set is empty and the watcher is the only net; every build then replaces
+ * the set with its own record.
+ *
+ * `close()` is final and idempotent, and leaves no timer behind.
+ *
+ * @param {Object} options
+ * @param {string} options.folder the project folder the rows are relative to
+ * @param {(source: string) => boolean} options.filter the watcher's own
+ *   exclusion filter, applied to directory entries
+ * @param {(reasons: string[]) => void} options.onChange one detected
+ *   difference (the labels name the rows/directories that differ)
+ * @param {number} [options.intervalMs] the sweep period
+ * @returns {{inputs(rows: string[]): void, accounted(): void, close(): void}}
+ */
+export function createInputSweep({ folder, filter, onChange, intervalMs = DEFAULT_SWEEP_INTERVAL_MS }) {
+  if (typeof folder !== 'string' || folder === '') {
+    throw new TypeError('createInputSweep needs the project folder');
+  }
+  if (typeof filter !== 'function' || typeof onChange !== 'function') {
+    throw new TypeError('createInputSweep needs filter and onChange functions');
+  }
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new TypeError('createInputSweep needs a positive intervalMs');
+  }
+
+  let closed = false;
+  let timer = null;
+  // Every read runs through one queue: a sweep never interleaves with an
+  // adoption or an accounting refresh, so a difference is always judged
+  // against baselines that were read atomically.
+  let queue = Promise.resolve();
+  const fileRows = new Map(); // absolute path -> identity
+  const dirRows = new Map(); // absolute directory -> filtered entry key
+
+  const toAbs = (rel) => (rel === '' ? folder : join(folder, ...rel.split('/')));
+  const toLabel = (path) => relative(folder, path).split(sep).join('/');
+
+  async function readRows(paths, directories) {
+    const files = await Promise.all([...paths].map(async (path) => [path, await statRow(path)]));
+    const dirs = await Promise.all([...directories].map(async (dir) => [dir, await statDir(dir, filter)]));
+    return { files, dirs };
+  }
+
+  function store({ files, dirs }) {
+    fileRows.clear();
+    for (const [path, identity] of files) fileRows.set(path, identity);
+    dirRows.clear();
+    for (const [dir, key] of dirs) dirRows.set(dir, key);
+  }
+
+  function enqueue(work) {
+    queue = queue.then(async () => {
+      if (closed) return;
+      await work();
+    });
+    // A programmer error in the sweep must not kill the queue; the next
+    // tick still runs and the difference still reports.
+    queue = queue.catch(() => {});
+    return queue;
+  }
+
+  function sweepOnce() {
+    return enqueue(async () => {
+      const paths = new Set(fileRows.keys());
+      const directories = new Set(dirRows.keys());
+      const current = await readRows(paths, directories);
+      const reasons = [];
+      for (const [path, identity] of current.files) {
+        if (fileRows.get(path) !== identity) reasons.push(toLabel(path));
+      }
+      for (const [dir, key] of current.dirs) {
+        if (dirRows.get(dir) !== key) reasons.push(dir === folder ? '/' : `${toLabel(dir)}/`);
+      }
+      store(current);
+      if (reasons.length > 0) onChange(reasons);
+    });
+  }
+
+  timer = setInterval(() => {
+    sweepOnce();
+  }, intervalMs);
+
+  return {
+    /**
+     * Adopt the build's consumed-input rows (project-relative, '/'
+     * separated). Identities already held are kept — an edit that landed
+     * while the build ran must still report — and new rows are baselined
+     * as they are now, without notifying.
+     *
+     * @param {string[]} rows
+     */
+    inputs(rows) {
+      if (!Array.isArray(rows) || rows.some((row) => typeof row !== 'string' || row === '' || row.startsWith('/') || row.split('/').some((name) => name === '..'))) {
+        throw new TypeError('createInputSweep inputs needs the receipt\'s project-relative row paths');
+      }
+      enqueue(async () => {
+        const paths = new Set(rows.map(toAbs));
+        const directories = new Set(rows.map(rowContainer).map(toAbs));
+        const files = await Promise.all([...paths].map(async (path) => [path, fileRows.has(path) ? fileRows.get(path) : await statRow(path)]));
+        const dirs = await Promise.all([...directories].map(async (dir) => [dir, dirRows.has(dir) ? dirRows.get(dir) : await statDir(dir, filter)]));
+        store({ files, dirs });
+      });
+    },
+
+    /**
+     * Every baseline is re-read now, without notifying: the build that is
+     * starting includes everything up to this instant, so the sweep must
+     * not re-report it. Called at the start of every build, successful or
+     * not — a build that fails has still accounted its inputs, which is
+     * what keeps a persistently failing rebuild from looping.
+     */
+    accounted() {
+      enqueue(async () => {
+        store(await readRows(new Set(fileRows.keys()), new Set(dirRows.keys())));
+      });
+    },
+
+    /** Final: stop sweeping and leave no timer behind. */
+    close() {
+      if (closed) return;
+      closed = true;
+      if (timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+}

package/adapters/webaudio.mjs

@@ -0,0 +1,102 @@
+// The browser WebAudio adapter (M1 slice 2): one port over an injected
+// AudioContext, matching what `createShow`'s transport expects. This is
+// browser-only wiring — no `node:` import, no DOM, and the context
+// itself is injected: the page constructs it (it starts suspended)
+// before decode, so READY needs no gesture; only the Start gesture that
+// calls `show.start()` resumes it. A portable core never owns the
+// platform graph.
+//
+// The graph is the stable QA seam: every started source connects
+// through one AnalyserNode into the context destination, so a real page
+// run can measure a NONZERO signal on the analyser while the show
+// plays instead of trusting the context state alone. Each start is a
+// fresh single-use AudioBufferSourceNode started at the transport's
+// captured origin with its STOP scheduled at origin+seconds — the
+// audio ends itself on time regardless of paint slack.
+//
+// Ownership: the wiring only. Decode, resume/suspend and currentTime
+// belong to the context; the clock policy belongs to lib/show.mjs.
+
+/**
+ * Build the audio port over one AudioContext.
+ *
+ * @param {object} options
+ * @param {AudioContext} options.context
+ *   the page's own context, constructed suspended before decode; only
+ *   the Start gesture resumes it.
+ * @returns {{
+ *   decode: (bytes: ArrayBuffer) => Promise<AudioBuffer>,
+ *   resume: () => Promise<void>,
+ *   suspend: () => Promise<void>,
+ *   now: () => number,
+ *   play: (decoded: AudioBuffer, origin: number, stopAt: number) => AudioBufferSourceNode,
+ *   stop: (source: AudioBufferSourceNode) => void,
+ *   analyser: AnalyserNode,
+ * }}
+ */
+export function createWebAudioPort({ context }) {
+  if (!context
+    || typeof context.decodeAudioData !== 'function'
+    || typeof context.resume !== 'function'
+    || typeof context.suspend !== 'function'
+    || typeof context.createBufferSource !== 'function'
+    || typeof context.createAnalyser !== 'function'
+    || typeof context.destination === 'undefined') {
+    throw new TypeError('createWebAudioPort needs an AudioContext-shaped context');
+  }
+
+  const analyser = context.createAnalyser();
+  analyser.connect(context.destination);
+
+  return {
+    /** The QA measurement point: source -> analyser -> destination. */
+    analyser,
+
+    async decode(bytes) {
+      return await context.decodeAudioData(bytes);
+    },
+
+    async resume() {
+      await context.resume();
+    },
+
+    /** Once this settles, the context clock (below) is frozen. */
+    async suspend() {
+      await context.suspend();
+    },
+
+    now() {
+      return context.currentTime;
+    },
+
+    /**
+     * One fresh single-use source per start, scheduled on the context's
+     * own timeline: begin at `origin`, STOP at `stopAt` (origin+seconds).
+     */
+    play(decoded, origin, stopAt) {
+      const source = context.createBufferSource();
+      source.buffer = decoded;
+      source.connect(analyser);
+      source.start(origin);
+      source.stop(stopAt);
+      return source;
+    },
+
+    /**
+     * End a source now. The platform allows repeated stops (the latest
+     * wins); only stop-before-start throws, and teardown ignores that.
+     */
+    stop(source) {
+      try {
+        source.stop();
+      } catch {
+        // The node never started; there is nothing left to end.
+      }
+      try {
+        source.disconnect();
+      } catch {
+        // A disconnected node is already out of the graph.
+      }
+    },
+  };
+}

package/bin/animader.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// The `animader` executable: the thin process adapter. It parses
+// process.argv.slice(2), dispatches through the router, and maps thrown
+// DemoErrors to their exit codes and the error:/remedy: lines
+// (lib/errors.mjs is the one owner of that vocabulary and format).
+//
+// The whole command layer, its lib and node adapters, the player page, the
+// hello player core and the starters live inside this package
+// (installed-toolchain plan, stage 1): nothing under bin/, src/, lib/,
+// adapters/, player/, hello/, starters/ or toolchain/ imports across the
+// package boundary, so the packed package works without the checkout. The
+// contributor workspace's demo/ entries are compatibility adapters over
+// these modules.
+
+import pkg from '../package.json' with { type: 'json' };
+import { createNodeIo } from '../adapters/node-fs.mjs';
+import { errorLines } from '../lib/errors.mjs';
+import { runRouter } from '../src/router.mjs';
+
+const context = {
+  version: pkg.version,
+  env: process.env,
+  io: createNodeIo(),
+  out: (line) => process.stdout.write(`${line}\n`),
+  err: (line) => process.stderr.write(`${line}\n`),
+};
+
+runRouter(process.argv.slice(2), context).catch((error) => {
+  for (const line of errorLines(error)) context.err(line);
+  process.exitCode = error.exitCode ?? 1;
+});

package/hello/join.js

@@ -0,0 +1,46 @@
+// The hello player's score target join, built from the compiled program's
+// own reflection (step 12's second landing, the seventh ruling's (c)).
+// pngine's `getUniforms` answers the program's reflected fields by name,
+// with the type as WGSL spells it and the array length; registry 0 is that
+// reflection, so a score target the program does not declare is refused by
+// pacer's compile instead of drifting with a hand-written list.
+//
+// The wire target's `ncomp` is 1..4 lanes: a scalar or a vector of at most
+// four. An array field (`elemCount` non-zero) and a matrix are not score
+// targets (a mat3x3f is nine lanes and pacer's target arity is 1..4), and
+// an unknown type is skipped rather than guessed.
+
+/** The lanes one reflected WGSL type contributes to a score target. */
+const LANES = {
+  f32: 1,
+  i32: 1,
+  u32: 1,
+  vec2f: 2,
+  vec2i: 2,
+  vec2u: 2,
+  vec3f: 3,
+  vec3i: 3,
+  vec3u: 3,
+  vec4f: 4,
+  vec4i: 4,
+  vec4u: 4,
+};
+
+/**
+ * One pacer registry from pngine's reflected field table, in the table's
+ * own order (the target_id space).
+ *
+ * @param {Object<string, {type: string, elemCount: number}>} fields
+ *   `getUniforms`'s answer (or its parsed equivalent).
+ * @returns {Array<{name: string, ncomp: number}>}
+ */
+export function buildJoin(fields) {
+  const join = [];
+  for (const [name, field] of Object.entries(fields)) {
+    if (field.elemCount) continue;
+    const ncomp = LANES[field.type];
+    if (ncomp === undefined) continue;
+    join.push({ name, ncomp });
+  }
+  return join;
+}