animader-cli 0.0.0-stage → 0.1.1

package/lib/show.mjs

@@ -0,0 +1,458 @@
+// The demo's portable audio-master transport (M1 slice 2): the finite
+// clock lifecycle around one composed show. The audio context is the
+// master clock (a context-currentTime-style injected reader), the run
+// core is the examples' own `createPlayer` result, and every platform
+// byte — audio graph, wake loop, renderer — is an injected port, so the
+// same decisions run in a page, a headless test or a future host with
+// no `node:` import, no process state and no DOM here.
+//
+// The clock policy (approved): `elapsed = readClock() - origin`, and
+// the origin is captured only AFTER `audio.resume()` resolves — a real
+// context does not sit at zero at a start or restart, and the resume is
+// an async platform settle. The buffer is scheduled at that same origin
+// as a fresh single-use source whose STOP is scheduled at
+// `origin + seconds`, independent of any wake slack: the audio ends
+// itself on time even if paints lag. A stall steps every due tick with
+// no catch-up cap and no rebase (the debt is paid in full); a step
+// draws its own tick and then increments, so the last shown tick is
+// always `tick - 1` (the run core's actual contract). The end bound
+// never overruns the tick grid. A non-finite or backwards clock fails
+// loudly — error state, audio ended, nothing rescheduled — instead of a
+// NaN busy loop; a throwing clock read or step takes that same total
+// failure path instead of escaping the host's wake callback.
+//
+// States: loading, ready, playing, paused, press-to-resume, ended,
+// stopped, error. Commands in the wrong state are ignored (never a
+// duplicate audio start), commands are serialized through one queue so
+// a double start or a pause during a pending resume cannot interleave,
+// and `start`/`pause`/`resume`/`stop`/`restart` return promises so the
+// platform's async settle is observable. `fail()` stays immediate —
+// never queued behind a platform await that may never resolve — and
+// every command continuation re-checks it after its await: the original
+// structured failure is final, keeps its identity, and nothing starts,
+// announces or reschedules over it. `restart` resets the score
+// ticks through the run core's own reset, returns every held control to
+// the document default, and resets the visual feedback state through
+// the renderer's public restart verb — never by patching private
+// workers. `seconds` is a host policy received here (never inferred
+// from the compiled transport) and must be a whole number of ticks on
+// the run core's grid; a score's own `:end loop|hold` stays authored
+// and is not acted on by this transport.
+//
+// Ownership: the state machine, the clock arithmetic, the serialization.
+// The audio graph, the wake source, the renderer and the driver belong
+// to the host adapters.
+
+import { TICKS_PER_SECOND } from '../hello/run.js';
+import { ShowError } from './score.mjs';
+
+/** Every state `createShow` announcements can carry. */
+export const SHOW_STATES = Object.freeze([
+  'loading',
+  'ready',
+  'playing',
+  'paused',
+  'press-to-resume',
+  'ended',
+  'stopped',
+  'error',
+]);
+
+/**
+ * @param {object} options
+ * @param {number} options.seconds
+ *   the host show length; must be positive, finite and a whole number
+ *   of ticks on the tick grid.
+ * @param {() => Promise<{driver: object, player: object, renderer: object}>} options.prepare
+ *   composes the show: renderer ready, score compiled (a `loadShow`
+ *   result wired through `createPlayer`). READY waits for this.
+ * @param {() => Promise<object>} options.decode
+ *   decodes the soundtrack; READY waits for this too, so no show plays
+ *   on audio it has not decoded.
+ * @param {object} options.audio
+ *   the audio port: `resume(): Promise`, `suspend(): Promise` (the
+ *   clock freezes once it settles), `now(): number` (a
+ *   context-currentTime-style reader), `play(decoded, origin, stopAt):
+ *   handle` (a fresh single-use source started at `origin` with its
+ *   STOP scheduled at `stopAt`), `stop(handle)`.
+ * @param {(fn: () => void) => () => void} options.scheduleWake
+ *   schedules one pump (requestAnimationFrame-shaped) and answers a
+ *   cancel function.
+ * @param {() => number} [options.readClock]
+ *   defaults to `audio.now` (ship it as a closure).
+ * @param {(state: string) => void} [options.onState]
+ *   called on every transition, `loading` included.
+ * @param {number} [options.ticksPerSecond]
+ *   defaults to the run core's own `TICKS_PER_SECOND`.
+ */
+export function createShow({
+  seconds,
+  prepare,
+  decode,
+  audio,
+  scheduleWake,
+  readClock,
+  onState = null,
+  ticksPerSecond = TICKS_PER_SECOND,
+}) {
+  if (typeof prepare !== 'function' || typeof decode !== 'function') {
+    throw new TypeError('createShow needs prepare and decode functions (the composed load and the audio decode)');
+  }
+  if (!audio
+    || typeof audio.resume !== 'function'
+    || typeof audio.suspend !== 'function'
+    || typeof audio.now !== 'function'
+    || typeof audio.play !== 'function'
+    || typeof audio.stop !== 'function') {
+    throw new TypeError('createShow needs audio.resume, audio.suspend, audio.now, audio.play and audio.stop');
+  }
+  if (typeof scheduleWake !== 'function') {
+    throw new TypeError('createShow needs a scheduleWake function (requestAnimationFrame-shaped)');
+  }
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) {
+    throw new ShowError('invalid_seconds', `--seconds must be a positive finite number; got ${String(seconds)}`, {
+      stage: 'transport',
+    });
+  }
+  if (!Number.isInteger(seconds * ticksPerSecond)) {
+    throw new ShowError(
+      'seconds_not_representable',
+      `--seconds ${seconds} is not a whole number of ticks on the ${ticksPerSecond}-tick grid; pass a length the grid represents exactly instead of rounding forever`,
+      { stage: 'transport' },
+    );
+  }
+
+  const clock = readClock ?? audio.now;
+  const totalTicks = seconds * ticksPerSecond;
+
+  let state = 'loading';
+  let failure = null;
+  let loaded = null;
+  let origin = null;
+  let handle = null;
+  let lastNow = null;
+  let cancelWake = null;
+  const held = new Set();
+
+  function announce(next) {
+    state = next;
+    if (onState) onState(next);
+  }
+
+  /** End the audio now and cancel any scheduled pump. */
+  function endAudio() {
+    if (handle !== null) {
+      audio.stop(handle);
+      handle = null;
+    }
+    if (cancelWake !== null) {
+      const cancel = cancelWake;
+      cancelWake = null;
+      cancel();
+    }
+  }
+
+  /** Enter the error state: audio ended, nothing rescheduled, cause kept. */
+  function failShow(code, message, detail = {}) {
+    const error = new ShowError(code, message, detail);
+    endAudio();
+    failure = error;
+    announce('error');
+    return error;
+  }
+
+  function schedulePump() {
+    if (cancelWake !== null) return;
+    const cancel = scheduleWake(pump);
+    cancelWake = () => {
+      cancelWake = null;
+      cancel();
+    };
+  }
+
+  /**
+   * One paint: step every tick the clock has passed, bounded by the
+   * grid's end, then schedule the next paint unless the show is over.
+   * Runs only while playing — a stop, an error or a pause is the end of
+   * resumption, not a reason to keep scheduling.
+   */
+  function pump() {
+    cancelWake = null;
+    if (state !== 'playing' || loaded === null) return;
+    try {
+      const now = clock();
+      if (!Number.isFinite(now) || (lastNow !== null && now < lastNow)) {
+        failShow(
+          'clock_invalid',
+          `the master clock is not usable (read ${now} after ${lastNow}); the show refuses to guess time`,
+          { stage: 'clock' },
+        );
+        return;
+      }
+      lastNow = now;
+      // The sub-tick guard: an accumulated context clock (a double) can
+      // land a genuinely due boundary a few ulps below the integer — a
+      // real 0.15+4.2 s read lands at 434.99999999999994 ticks — which
+      // would cost a whole paint. The 1e-6-tick guard (10 ns at 100 tps)
+      // absorbs that fuzz. It is a bounded trade, not exactness: a read
+      // up to 10 ns before a boundary can fire it early, far below clock
+      // and paint granularity.
+      const due = Math.floor((now - origin) * ticksPerSecond + 1e-6);
+      const target = Math.min(due, totalTicks);
+      while (loaded.player.state.tick < target) loaded.player.step();
+      if (due >= totalTicks) {
+        // The source's STOP was scheduled at origin+seconds when it
+        // started, so the audio has already ended itself; the handle is
+        // spent and nothing is scheduled again.
+        handle = null;
+        announce('ended');
+        return;
+      }
+      schedulePump();
+    } catch (cause) {
+      failShow(
+        'step_failed',
+        `the show could not advance a paint: ${cause?.message ?? cause}`,
+        { stage: 'play', cause },
+      );
+    }
+  }
+
+  const readyPromise = Promise.all([prepare(), decode()]).then(
+    ([prepared, decoded]) => {
+      // A host-reported failure can arrive while the load is still settling
+      // (an async device or shader error). It is the answer; READY never
+      // overwrites a failure that already stopped the show.
+      if (state === 'error') throw failure;
+      loaded = { driver: prepared.driver, player: prepared.player, renderer: prepared.renderer, decoded };
+      announce('ready');
+      return 'ready';
+    },
+    (cause) => {
+      if (state === 'error') throw failure;
+      // A failed load is discarded (nothing half-wired is kept) and
+      // reported as the error state; `ready()` rejects with this
+      // structured failure, not the naked cause.
+      failure = new ShowError(
+        'load_failed',
+        `the show could not be loaded: ${cause?.message ?? cause}`,
+        { stage: 'load', cause },
+      );
+      announce('error');
+      throw failure;
+    },
+  );
+  // The command queue attaches its own handlers, so a rejected load is a
+  // state and never an unhandled rejection.
+
+  // Commands serialize behind the load and each other: a double start,
+  // a pause during a pending resume or a restart mid-start cannot
+  // interleave, and a rejected command never wedges the queue.
+  let chain = readyPromise.then(() => {}, () => {});
+  function enqueue(operation) {
+    const result = chain.then(() => operation());
+    chain = result.then(() => {}, () => {});
+    return result;
+  }
+
+  /** The audio-master gesture: resume, then read the origin the clock answers. */
+  function start() {
+    return enqueue(async () => {
+      if (state !== 'ready' || loaded === null) return state;
+      try {
+        await audio.resume();
+        // A host failure that arrived while the resume was settling is
+        // the answer: the continuation never launches the source over
+        // it (fail() is immediate — the audio is already ended).
+        if (state === 'error') throw failure;
+        const now = clock();
+        if (!Number.isFinite(now)) {
+          throw new ShowError('clock_invalid', `the master clock read ${now} at the start; the show refuses to guess time`, {
+            stage: 'clock',
+          });
+        }
+        origin = now;
+        lastNow = now;
+        handle = audio.play(loaded.decoded, origin, origin + seconds);
+        announce('playing');
+        schedulePump();
+        return state;
+      } catch (cause) {
+        // The terminal failure is final: neither the bail-out above nor
+        // a resume rejection landing after it is rewrapped as a fresh
+        // start failure.
+        if (state === 'error') throw failure;
+        const error = cause instanceof ShowError
+          ? cause
+          : new ShowError('start_failed', `the show could not start: ${cause?.message ?? cause}`, { stage: 'play', cause });
+        throw failShow(error.code, error.message, {
+          stage: error.stage,
+          document: error.document,
+          diagnostics: error.diagnostics,
+          cause: error.cause ?? cause,
+        });
+      }
+    });
+  }
+
+  /** The hidden pause: await the suspend, and the frozen clock moves no ticks. */
+  function pause() {
+    return enqueue(async () => {
+      if (state !== 'playing') return state;
+      try {
+        await audio.suspend();
+      } catch (cause) {
+        if (state === 'error') throw failure;
+        throw failShow('audio_failed', `the audio could not be suspended: ${cause?.message ?? cause}`, { stage: 'audio', cause });
+      }
+      // A host failure that arrived while the suspend was settling is
+      // the answer: no paused announcement repaints over the error.
+      if (state === 'error') throw failure;
+      announce('paused');
+      return state;
+    });
+  }
+
+  /**
+   * Try to resume: a denial is the explicit `press-to-resume` state
+   * (a gesture is owed), never a silent play.
+   */
+  function resume() {
+    return enqueue(async () => {
+      if (state !== 'paused' && state !== 'press-to-resume') return state;
+      let denied = null;
+      try {
+        await audio.resume();
+      } catch (cause) {
+        denied = cause;
+      }
+      // A host failure that arrived while the resume was settling is
+      // final: it wins over both the denial (press-to-resume is not
+      // painted over an error) and the play (a dead show is not
+      // resurrected, its pump is not rescheduled).
+      if (state === 'error') throw failure;
+      if (denied !== null) {
+        announce('press-to-resume');
+        return state;
+      }
+      const now = clock();
+      if (!Number.isFinite(now) || (lastNow !== null && now < lastNow)) {
+        throw failShow(
+          'clock_invalid',
+          `the master clock read ${now} after ${lastNow} on resume; the show refuses to guess time`,
+          { stage: 'clock' },
+        );
+      }
+      lastNow = now;
+      announce('playing');
+      schedulePump();
+      return state;
+    });
+  }
+
+  /** End the show now: the audio stops and no pump is scheduled again. */
+  function stop() {
+    return enqueue(async () => {
+      // A failed show keeps its terminal answer: the failure already
+      // ended the audio and cancelled the wake, and a stopped repaint
+      // would clear the visible error while `error` still reports it.
+      // restart remains the recovery verb from the error state.
+      if (state === 'stopped' || state === 'loading' || state === 'error' || loaded === null) return state;
+      endAudio();
+      announce('stopped');
+      return state;
+    });
+  }
+
+  /**
+   * Back to READY at tick zero: the audio ends, every held control
+   * returns to its document default, the run core resets through its
+   * own verb, and the visual feedback state resets through the
+   * renderer's public restart.
+   */
+  function restart() {
+    return enqueue(async () => {
+      if (state === 'loading' || loaded === null) return state;
+      // A failure that already exists here is the recoverable case:
+      // restart is the public recovery verb from the error state. Only a
+      // NEWER failure — a different failure object, which can only be
+      // failShow during the reset await below — aborts the resurrection.
+      const priorFailure = failure;
+      endAudio();
+      for (const name of held) loaded.driver.clearControl(name);
+      held.clear();
+      loaded.player.reset();
+      try {
+        await loaded.renderer.restart();
+      } catch (cause) {
+        if (failure !== priorFailure) throw failure;
+        throw failShow(
+          'renderer_reset_failed',
+          `the renderer could not be reset for the restart: ${cause?.message ?? cause}`,
+          { stage: 'restart', cause },
+        );
+      }
+      if (failure !== priorFailure) throw failure;
+      origin = null;
+      lastNow = null;
+      failure = null;
+      announce('ready');
+      return state;
+    });
+  }
+
+  /**
+   * The host's explicit failure entry: a real renderer/GPU/shader error that
+   * arrives through a platform callback, not through the clock or step path.
+   * It ends the audio, cancels the wake and is final until a successful restart;
+   * it never starts a second page lifecycle. The layers split deliberately:
+   * this transport's `restart` accepts the error state (tests and QA drive
+   * recovery through that public verb), while the demo page intentionally
+   * offers no restart from its error state — its policy is conservative-fatal
+   * with a manual reload (README, "Playback states and controls").
+   */
+  function fail(code, message, detail = {}) {
+    if (state === 'error') return state;
+    failShow(code, message, detail);
+    return state;
+  }
+
+  /** Hold one control by its reflected name; the restart clears it. */
+  function holdControl(name, value) {
+    if (loaded === null || state === 'loading' || state === 'error') return false;
+    const accepted = loaded.driver.setControl(name, value);
+    if (accepted) held.add(name);
+    return accepted;
+  }
+
+  /** Return one control to its document default. */
+  function releaseControl(name) {
+    if (loaded === null || state === 'error') return false;
+    const accepted = loaded.driver.clearControl(name);
+    if (accepted) held.delete(name);
+    return accepted;
+  }
+
+  if (onState) onState('loading');
+
+  return {
+    get state() { return state; },
+    get error() { return failure; },
+    /** The current post-resume origin, or null before Start and after restart. */
+    get origin() { return origin; },
+    get tick() { return loaded === null ? 0 : loaded.player.state.tick; },
+    /** The tick the last paint drew: a step draws its tick then increments. */
+    get lastShownTick() { return loaded === null ? -1 : loaded.player.state.tick - 1; },
+    seconds,
+    totalTicks,
+    ready: () => readyPromise,
+    start,
+    pause,
+    resume,
+    stop,
+    restart,
+    fail,
+    holdControl,
+    releaseControl,
+  };
+}

package/lib/soundtrack.mjs

@@ -0,0 +1,67 @@
+// The one soundtrack filename allowlist and the generated player-config
+// format names. This module is pure data and predicates: no `node:` import,
+// no process state, no DOM — the CLI inspection, the receipts, the HTTP
+// routes, the host config and the browser loader all read the same lists
+// from here instead of maintaining private copies.
+//
+// Vorbis and Opus are separate audio codecs; Ogg is a container that can
+// carry either. The conventional extensions are `.ogg` for Ogg Vorbis and
+// `.opus` for Ogg Opus; both are served as `audio/ogg` and the browser
+// decodes the actual bytes, not the extension. `.ogg` does not imply that
+// the loader forces Vorbis decoding.
+
+/** The exact case-sensitive input names recognized at a project root. */
+export const SOUNDTRACK_NAMES = Object.freeze([
+  'soundtrack.wav',
+  'soundtrack.ogg',
+  'soundtrack.opus',
+]);
+
+/** The HTTP content type each recognized name is served as. */
+export const SOUNDTRACK_CONTENT_TYPES = Object.freeze({
+  'soundtrack.wav': 'audio/wav',
+  'soundtrack.ogg': 'audio/ogg',
+  'soundtrack.opus': 'audio/ogg',
+});
+
+/** Extension → content type for the route MIME vocabulary. */
+export const SOUNDTRACK_EXTENSIONS = Object.freeze({
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.opus': 'audio/ogg',
+});
+
+/** The starter's explicit choice; new projects still generate this WAV. */
+export const LEGACY_SOUNDTRACK = 'soundtrack.wav';
+
+/**
+ * The generated player-config formats. Version 1 configs carry no
+ * `soundtrack` field and mean the legacy WAV; version 2 configs carry a
+ * required explicit selection. Compressed audio requires version 2.
+ */
+export const PLAYER_CONFIG_FORMATS = Object.freeze({
+  demoLegacy: 'animader-demo-player/1',
+  demo: 'animader-demo-player/2',
+  releaseLegacy: 'animader-release-player/1',
+  release: 'animader-release-player/2',
+});
+
+export const ALL_PLAYER_CONFIG_FORMATS = Object.freeze([
+  PLAYER_CONFIG_FORMATS.demoLegacy,
+  PLAYER_CONFIG_FORMATS.demo,
+  PLAYER_CONFIG_FORMATS.releaseLegacy,
+  PLAYER_CONFIG_FORMATS.release,
+]);
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} true when the value is one of the exact allowlist names
+ */
+export function isSoundtrackName(value) {
+  return typeof value === 'string' && SOUNDTRACK_NAMES.includes(value);
+}
+
+/** The names as one line for usage text, errors and remedies. */
+export function soundtrackNamesText() {
+  return SOUNDTRACK_NAMES.join(', ');
+}

package/lib/vendor.mjs

@@ -0,0 +1,99 @@
+// The prepared runtime bundle's data contract. Portable: the model and its
+// canonical digest input live here; reading, copying and hashing are host
+// adapter work. A revision label alone never proves a file: the bundle's
+// identity is every copied byte's sha256 plus the source it came from.
+
+import { DemoError } from './errors.mjs';
+
+export const VENDOR_FORMAT = 'animader-demo-vendor/1';
+export const VENDOR_FILE = 'provenance.json';
+
+function bad(message) {
+  return new DemoError('bad_vendor_provenance', message, {
+    remedy: 'Regenerate the bundle with: node demo/prepare.mjs, then run node demo/prepare.mjs --verify.',
+  });
+}
+
+function comparePaths(a, b) {
+  return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+
+/**
+ * Validate and normalize the provenance document. Paths are bundle-relative;
+ * the provenance file itself is not one of its own entries.
+ *
+ * @param {unknown} provenance
+ * @returns {{format: string, producers: Object, files: Array<{path: string, source: string, sha256: string, bytes: number}>}}
+ */
+export function validateProvenance(provenance) {
+  if (provenance === null || typeof provenance !== 'object' || Array.isArray(provenance)) {
+    throw bad('provenance is not an object');
+  }
+  if (provenance.format !== VENDOR_FORMAT) {
+    throw bad(`provenance format is ${JSON.stringify(provenance.format)}, expected ${VENDOR_FORMAT}`);
+  }
+  if (!Array.isArray(provenance.files) || provenance.files.length === 0) {
+    throw bad('provenance has no files');
+  }
+  if (provenance.producers === null || typeof provenance.producers !== 'object' || Array.isArray(provenance.producers)) {
+    throw bad('provenance has no producers object');
+  }
+
+  const seen = new Set();
+  const files = provenance.files.map((entry) => {
+    if (entry === null || typeof entry !== 'object') throw bad('provenance file entry is not an object');
+    const path = String(entry.path ?? '');
+    if (
+      path === '' || path === VENDOR_FILE || path.startsWith('/') || path.includes('\\')
+      || path.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+    ) {
+      throw bad(`provenance file path is not a clean bundle-relative path: ${JSON.stringify(path)}`);
+    }
+    if (seen.has(path)) throw bad(`provenance repeats ${path}`);
+    seen.add(path);
+    if (!/^[0-9a-f]{64}$/.test(String(entry.sha256 ?? ''))) {
+      throw bad(`provenance file ${path} has no sha256 content digest`);
+    }
+    if (!Number.isInteger(entry.bytes) || entry.bytes < 0) {
+      throw bad(`provenance file ${path} has no byte length`);
+    }
+    return {
+      path,
+      source: String(entry.source ?? ''),
+      sha256: String(entry.sha256),
+      bytes: entry.bytes,
+    };
+  }).sort(comparePaths);
+
+  return {
+    format: VENDOR_FORMAT,
+    producers: provenance.producers,
+    files,
+  };
+}
+
+/**
+ * The exact bytes that the bundle's digest is taken over: path, content
+ * sha256 and byte length, sorted by path. Environment paths and revisions
+ * are deliberately absent, so a moved checkout does not change the identity
+ * of the copied runtime.
+ *
+ * @param {Array<{path: string, sha256: string, bytes: number}>} files
+ * @returns {string}
+ */
+export function provenanceLines(files) {
+  return [...files]
+    .sort(comparePaths)
+    .map((entry) => `${entry.path}\0${entry.sha256}\0${entry.bytes}\n`)
+    .join('');
+}
+
+export function makeProvenance({ producers, files, digest }) {
+  const normalized = validateProvenance({ format: VENDOR_FORMAT, producers, files });
+  return {
+    format: VENDOR_FORMAT,
+    producers: normalized.producers,
+    files: normalized.files,
+    digest,
+  };
+}