animader-cli 0.0.0-stage → 0.1.1

package/hello/run.js

@@ -0,0 +1,259 @@
+// The hello player's deterministic run core: the piece of player.js that
+// can run without a browser. The page injects pngine's `draw`/`setUniform`
+// and pacer's compiled driver with its public routing pair
+// (`routeWrites`/`toUniforms`); this module owns the 100-tick clock, the
+// score's frame contract (pacer's pair, `eval(now)` in session microseconds
+// returning write entries, split across the two buses in wire order and
+// folded per entry into the `{ name: value }` shape the sinks take), the
+// twelve input lanes pngine's `attachPointerTracking` holds, and the mapping
+// from a session record back onto those lanes
+// (npm/animader/test/pngine-normalizer.js is the same normaliser, kept for
+// the comparison).
+//
+// The node test drives this module with recording fakes, so the tick
+// arithmetic and the record-to-lane rules are pinned without WebGPU. The
+// page's own run is the same code with the real viewer attached.
+
+/** The piece's tick rate: a second is a hundred ticks. */
+export const TICKS_PER_SECOND = 100;
+
+/** One tick on the session clock, the same microseconds `:at` carries. */
+export const MICROS_PER_TICK = 1_000_000 / TICKS_PER_SECOND;
+
+/** The most ticks one paint may step, the page's catch-up cap. */
+export const CATCH_UP_CAP = 12;
+
+/** The buses the frame contract names: registry 0 visual, registry 1 audio. */
+const REGISTRY_BUSES = 2;
+
+const SPACE = 16;
+
+/**
+ * Build one run over injected siblings.
+ *
+ * @param {object} options
+ * @param {{ setControl: Function, clearControl: Function, eval: Function }} options.pacer
+ *   pacer's public pair as the frame contract injects it: `setControl(ref,
+ *   value)` pins before `eval`, and `eval(now)` takes the frame's now in
+ *   session microseconds and answers its write entries.
+ * @param {(entries: object[], registryCount: number) => object[][]} options.routeWrites
+ *   pacer's public routing split (`pacer/route`): the frame's entries
+ *   grouped by their `registry` bus index.
+ * @param {(entries: object[], registry?: number) => object} options.toUniforms
+ *   pacer's public fold (`pacer/route`): one bus as `{ [name]: value }`, a
+ *   number for one lane and a plain array for a wider target.
+ * @param {(name: string, value: number | number[], options: object) => void} options.setUniform
+ *   writes one registry-0 entry by the target's own reflected name
+ *   (pngine's `setUniform`).
+ * @param {(name: string, value: number | number[], options: object) => void} [options.setParam]
+ *   writes one registry-1 entry (an audio host; absent on this page).
+ * @param {(options: {time: number}) => void} options.draw draws one frame
+ *   (pngine's `draw`).
+ * @param {(frame: object) => void} [options.onFrame] the page's readout.
+ */
+export function createPlayer({ pacer, routeWrites, toUniforms, setUniform, setParam = null, draw, onFrame = null }) {
+  const state = { tick: 0, heat: null, grain: null, held: null, draws: 0, writes: [] };
+  // pngine's twelve lanes: x, y, clickX, clickY, dx, dy, buttons,
+  // pressure, modifiers, scrollX, scrollY, pad.
+  const pointer = new Float32Array(12);
+  let lastX = 0;
+  let lastY = 0;
+  let mods = 0;
+
+  const lane = (value) => value / 65535;
+  /** The record's four modifier bits, the held Space bit kept. */
+  const modsOf = (bits) => (bits & 15) | (mods & SPACE);
+
+  /**
+   * One session record lands on the input lanes, the rule pngine's
+   * `attachPointerTracking` applies to the event the record came from
+   * (pointer position, accumulated deltas, buttons, pressure, modifiers;
+   * a release negates the click point and zeroes buttons and pressure; a
+   * wheel adds the sign of its 24.8 deltas to the scroll lanes; Space
+   * toggles the sixteenth modifier bit).
+   */
+  function apply(record) {
+    switch (record.kind) {
+      case "down": {
+        const x = lane(record.x);
+        const y = lane(record.y);
+        pointer[0] = x;
+        pointer[1] = y;
+        pointer[2] = x;
+        pointer[3] = y;
+        pointer[6] = record.buttons;
+        // pngine reads `e.pressure || 0.5` on a down, so a zero lane is a
+        // half press on the event the record rebuilds.
+        pointer[7] = lane(record.p) || 0.5;
+        pointer[8] = modsOf(record.mods);
+        mods = pointer[8];
+        lastX = x;
+        lastY = y;
+        break;
+      }
+      case "move": {
+        const x = lane(record.x);
+        const y = lane(record.y);
+        pointer[4] += x - lastX;
+        pointer[5] += y - lastY;
+        pointer[0] = x;
+        pointer[1] = y;
+        pointer[6] = record.buttons;
+        // `e.pressure || (e.buttons ? 0.5 : 0)` on a move.
+        pointer[7] = lane(record.p) || (record.buttons ? 0.5 : 0);
+        pointer[8] = modsOf(record.mods);
+        mods = pointer[8];
+        lastX = x;
+        lastY = y;
+        break;
+      }
+      case "up":
+      case "cancel": {
+        pointer[2] = -Math.abs(pointer[2]);
+        pointer[3] = -Math.abs(pointer[3]);
+        pointer[6] = 0;
+        pointer[7] = 0;
+        break;
+      }
+      case "wheel": {
+        pointer[9] += Math.sign(record.v[0]);
+        pointer[10] += Math.sign(record.v[1]);
+        pointer[8] = modsOf(record.mods);
+        mods = pointer[8];
+        break;
+      }
+      case "key": {
+        if (record.str === "Space") {
+          mods = record.buttons ? mods | SPACE : mods & ~SPACE;
+          pointer[8] = mods;
+        }
+        break;
+      }
+      default:
+        // resize, custom, input-write, mark, adjust and reset do not move the
+        // lanes; the page's input path is pointer, wheel and key.
+        break;
+    }
+  }
+
+  /**
+   * One tick: the score's writes at the tick's own time, then one frame of
+   * the program at that time. pacer's route pair splits the frame's entries
+   * across the buses in wire order (`routeWrites`), and folding one entry at
+   * a time through `toUniforms` gives each write's value in the shape its bus
+   * sink takes: a number for one lane, a plain array otherwise. The writes
+   * reach the sinks in that order, so when two write the same name the later
+   * one wins, the frame contract's last-word rule. Every write rides
+   * `redraw: false`, and the tick's one draw carries them. Registry 0 lands
+   * by the target's own reflected name; registry 1 goes to `setParam` when
+   * the page has an audio sink. A declared-only target with no host name
+   * cannot key a by-name fold, so it is not written, exactly as the sinks
+   * could not have taken it.
+   */
+  function step() {
+    const t = state.tick / TICKS_PER_SECOND;
+    const entries = pacer.eval(state.tick * MICROS_PER_TICK);
+    state.writes = [];
+    if (entries) {
+      const groups = routeWrites(entries, REGISTRY_BUSES);
+      for (let registry = 0; registry < groups.length; registry++) {
+        for (const entry of groups[registry]) {
+          const value = toUniforms([entry], registry)[entry.name];
+          if (value === undefined) continue;
+          state.writes.push({ name: entry.name, registry, ncomp: entry.ncomp, value });
+          if (registry === 0) {
+            setUniform(entry.name, value, { redraw: false });
+          } else if (registry === 1 && setParam) {
+            setParam(entry.name, value, { redraw: false });
+          }
+          const scalar = Array.isArray(value) ? value[0] : value;
+          if (entry.name === "heat") state.heat = scalar;
+          if (entry.name === "grain") state.grain = scalar;
+        }
+      }
+    }
+    draw({ time: t });
+    state.tick += 1;
+    state.draws += 1;
+    // pngine drains dx, dy and the wheel sums after each frame
+    // (vendor/pngine.mjs, the draw path).
+    pointer[4] = 0;
+    pointer[5] = 0;
+    pointer[9] = 0;
+    pointer[10] = 0;
+    if (onFrame) onFrame(frame());
+    return state.tick;
+  }
+
+  /** The writes the last tick applied and the lanes it left, as plain values. */
+  function frame() {
+    return {
+      tick: state.tick,
+      heat: state.heat,
+      grain: state.grain,
+      held: state.held,
+      draws: state.draws,
+      writes: state.writes.map((w) => ({
+        name: w.name,
+        registry: w.registry,
+        ncomp: w.ncomp,
+        value: Array.isArray(w.value) ? [...w.value] : w.value,
+      })),
+      pointer: Array.from(pointer),
+    };
+  }
+
+  /** Step until the tick counter reaches `tick`. */
+  function stepTo(tick) {
+    while (state.tick < tick) step();
+    return state.tick;
+  }
+
+  /** Step the ticks strictly before session microsecond `micros`. */
+  function stepAt(micros) {
+    while (state.tick * MICROS_PER_TICK < micros) step();
+    return state.tick;
+  }
+
+  function setHeat(value) {
+    state.held = value;
+    pacer.setControl("heat", value);
+  }
+
+  function release() {
+    state.held = null;
+    pacer.clearControl("heat");
+  }
+
+  /** Back to tick zero, no held control, fresh lanes and no writes. */
+  function reset() {
+    state.tick = 0;
+    state.heat = null;
+    state.grain = null;
+    state.held = null;
+    state.draws = 0;
+    state.writes = [];
+    pointer.fill(0);
+    lastX = 0;
+    lastY = 0;
+    mods = 0;
+    pacer.clearControl("heat");
+  }
+
+  return {
+    state,
+    pointer,
+    apply,
+    step,
+    stepTo,
+    stepAt,
+    tick(n) {
+      for (let i = 0; i < n; i++) step();
+      return state.tick;
+    },
+    setHeat,
+    release,
+    reset,
+    frame,
+  };
+}

package/lib/build.mjs

@@ -0,0 +1,126 @@
+// Build orchestration, portable: the sequence and the honesty rules live
+// here; every byte and process comes from an injected adapter. The order is
+// fixed: verify the prepared runtime, clear stale generated output, validate
+// the program, bake the executable payload. `preflightProject` is the
+// legacy graphics-only spelling that adds the `/1` receipt on top of the
+// shared bake — the score-validated full build (`lib/pipeline.mjs`) calls
+// `bakeProject` directly and derives, packs, audits and receipts the score
+// itself. There is deliberately no score compile, pacer invocation or
+// target inference in the graphics bake; those semantics belong to the full
+// pipeline and the browser's PieceHost/Pacer.load/READY chain.
+
+import { DemoError, buildError } from './errors.mjs';
+import { makeBuildReceipt, serializeReceipt } from './receipt.mjs';
+
+function nativeFailure(error, phase) {
+  if (error instanceof DemoError || error?.code === 'native_pngine_failed') return error;
+  return buildError(
+    `native_${phase}`,
+    `pngine ${phase} failed: ${error?.message ?? String(error)}`,
+    'Check the program with pngine validate; the demo does not infer or retry score targets.',
+  );
+}
+
+/**
+ * The shared graphics bake: verify the prepared runtime, ensure the output
+ * directory, clear the caller-named stale generated files, then validate
+ * and bake the program with pngine. Answers the payload bytes, their
+ * digest, the native tool identity and the verified runtime row — the
+ * inputs a receipt or an export drift check needs. Writes no receipt.
+ *
+ * @param {Object} options
+ * @param {{folder: string, files: Object}} options.project
+ * @param {{folder: string, outDir: string, payload: string}} options.paths
+ * @param {string[]} [options.staleFiles] generated files to clear first
+ * @param {Object} options.io
+ * @param {Object} options.native
+ * @param {Object} options.runtime
+ * @param {(bytes: Uint8Array) => string} options.hashBytes
+ */
+export async function bakeProject({ project, paths, staleFiles = [], io, native, runtime, hashBytes }) {
+  const verified = await runtime.verify();
+
+  await io.ensureDir(paths.outDir);
+  for (const stale of staleFiles) {
+    await io.removeFile(stale);
+  }
+
+  const identity = await native.identity();
+  try {
+    await native.validate({ cwd: paths.folder, program: project.files.program.name });
+  } catch (error) {
+    throw nativeFailure(error, 'validate');
+  }
+
+  try {
+    await native.bake({ cwd: paths.folder, program: project.files.program.name, output: paths.payload });
+  } catch (error) {
+    throw nativeFailure(error, 'bake');
+  }
+
+  const stats = await io.statFile(paths.payload);
+  if (stats === null || !stats.isFile || stats.size === 0) {
+    throw buildError(
+      'bake_missing_output',
+      `pngine did not leave a non-empty payload at ${paths.payloadRelative ?? paths.payload}`,
+      'Run pngine render by hand from the project folder and inspect its stderr.',
+    );
+  }
+  const bytes = await io.readFile(paths.payload);
+  return {
+    payloadPath: paths.payload,
+    bytes,
+    sha256: hashBytes(bytes),
+    identity,
+    runtime: {
+      format: verified.format,
+      digest: verified.digest,
+      files: verified.files.length,
+    },
+  };
+}
+
+/**
+ * The legacy graphics-only preflight: the shared bake plus the
+ * `animader-demo-build/1` receipt. `node demo/show.mjs --preflight-only`
+ * keeps exactly this meaning; it never validates a score.
+ *
+ * @param {Object} options
+ * @param {{folder: string, files: Object}} options.project
+ * @param {number} options.seconds
+ * @param {Object} options.paths
+ * @param {Object} options.io
+ * @param {Object} options.native
+ * @param {Object} options.runtime
+ * @param {(bytes: Uint8Array) => string} options.hashBytes
+ */
+export async function preflightProject({ project, seconds, paths, io, native, runtime, hashBytes }) {
+  const baked = await bakeProject({
+    project,
+    paths,
+    staleFiles: [paths.payload, paths.receipt],
+    io,
+    native,
+    runtime,
+    hashBytes,
+  });
+  const receipt = makeBuildReceipt({
+    project,
+    projectName: paths.projectName,
+    seconds,
+    output: {
+      name: paths.payloadRelative,
+      bytes: baked.bytes.byteLength,
+      sha256: baked.sha256,
+    },
+    runtime: baked.runtime,
+    tool: baked.identity,
+  });
+
+  await io.writeFile(paths.receipt, serializeReceipt(receipt));
+  return {
+    payloadPath: paths.payload,
+    receiptPath: paths.receipt,
+    receipt,
+  };
+}

package/lib/buildloop.mjs

@@ -0,0 +1,254 @@
+// The watch-mode build loop (plan section 5): the scheduling decisions only.
+// Bursts of change notifications coalesce into one build (a trailing debounce
+// while idle); changes that arrive while a build is running set one dirty
+// flag, so however many landed, exactly one follow-up build is queued; a
+// candidate built while any change was observed is discarded and rebuilt —
+// it is never published — so only a candidate that observed a quiet window
+// becomes the served generation. Builds are serialized by construction (one
+// cycle at a time), which is what keeps two generations from interleaving.
+//
+// When the caller provides `isStale`, the discard decision stops depending
+// on event delivery: after `build` resolves and before the discard/publish
+// choice, the candidate's own inputs are checked once more, so a change
+// whose event has not been delivered yet (a platform watcher with latency,
+// a silent watcher) still cannot publish. `isStale` is the authority
+// whenever it is provided — a `dirty` flag set by a prompt whose identity
+// the candidate's own start snapshot already consumed is a late duplicate
+// (the macOS FSEvents shape) and is dropped by that same check; callers
+// that pass no `isStale` keep the dirty flag as the decision, exactly as
+// before.
+//
+// When the caller provides `shouldBuild`, one more decision moves out of
+// the loop's own state: a cycle entered from a prompt (the debounce timer,
+// the initial kick, or the one follow-up owed by a dirty build) asks it
+// whether the inputs a build would read have moved since the last
+// attempt, and a `false` answer clears the owed work and schedules
+// nothing — a prompt for unchanged inputs costs no build. The check runs
+// once, before the cycle's first build only: a candidate discarded by
+// `dirty` or `isStale` always owes its rebuild, so that path never asks.
+// A check that cannot run cannot prove a skip either and builds, the same
+// safe direction `isStale` takes.
+//
+// The loop builds nothing and owns no filesystem: `build` produces a
+// candidate, `discard` throws one away, `publish` makes it current, and each
+// is injected. A rejected `build` reaches `onError` and the loop keeps
+// serving later changes — the caller reports it, the watcher keeps watching.
+// `close` is final: a pending debounce is cancelled, an in-flight candidate
+// is discarded when it lands, and later changes start nothing.
+//
+// This module is portable: no `node:` import, no process state, no DOM. The
+// debounce uses the plain global timer pair, the same shape in a host and a
+// test.
+
+/**
+ * @param {Object} options
+ * @param {() => Promise<any>} options.build one build over a fresh staging
+ *   area, resolving to its candidate
+ * @param {(candidate: any) => void|Promise<void>} options.discard throw a
+ *   candidate away without ever publishing it
+ * @param {(candidate: any) => void|Promise<void>} options.publish make a
+ *   candidate the current generation
+ * @param {(error: unknown) => void} [options.onError] a rejected build,
+ *   reported instead of thrown
+ * @param {(candidate: any) => boolean|Promise<boolean>} [options.isStale]
+ *   the authority on whether the candidate's own inputs moved while it was
+ *   being built, consulted after `build` resolves and before the
+ *   discard/publish decision; true sends the candidate down the same
+ *   discard-and-rebuild path the dirty flag does. When provided it decides
+ *   even when `dirty` is set — an arrived event is not a moved input, and
+ *   the platform's late duplicate delivery for a write the candidate
+ *   already consumed is not a change
+ * @param {() => boolean|Promise<boolean>} [options.shouldBuild] the
+ *   authority on whether the inputs a scheduled build would read have moved
+ *   since the last attempt, consulted when a cycle entered from a prompt is
+ *   about to start its first build; false clears the owed work and builds
+ *   nothing. Never consulted for a rebuild a discard owes.
+ * @param {number} [options.debounceMs] the idle burst-coalescing window
+ */
+export function createBuildLoop({ build, discard, publish, onError = null, isStale = null, shouldBuild = null, debounceMs = 150 }) {
+  if (typeof build !== 'function' || typeof discard !== 'function' || typeof publish !== 'function') {
+    throw new TypeError('createBuildLoop needs build, discard and publish functions');
+  }
+
+  let closed = false;
+  let running = false;
+  let dirty = false;
+  let timer = null;
+  const idleWaiters = new Set();
+
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+
+  /** Resolve the idle waiters once no cycle runs and none is owed. */
+  function settleIfIdle() {
+    if (running || dirty || timer !== null) return;
+    const waiters = [...idleWaiters];
+    idleWaiters.clear();
+    for (const waiter of waiters) waiter();
+  }
+
+  /**
+   * A discard or publish rejection is reported like a build failure instead
+   * of leaving an unhandled rejection in the host; the cycle then settles
+   * until the next change.
+   */
+  async function guard(step) {
+    try {
+      await step();
+    } catch (error) {
+      if (onError) onError(error);
+    }
+  }
+
+  /** One serialized cycle: build until a candidate saw a quiet window. */
+  async function cycle() {
+    running = true;
+    try {
+      // A scheduled build is about to start: the caller's own authority on
+      // whether the inputs it would read have moved since the last
+      // attempt. This runs for every cycle a prompt enters — the debounce
+      // timer, the initial kick, the one follow-up a dirty build owes —
+      // and never for the rebuild a discard owes (that rebuild is owed by
+      // the discard itself, whatever the inputs now equal). A prompt that
+      // arrives while the check runs sets `dirty` here, and a dirty cycle
+      // builds regardless of the answer, so no prompt is lost to the gap
+      // between the check's stat and its verdict.
+      if (shouldBuild !== null) {
+        let wanted;
+        try {
+          wanted = await shouldBuild();
+        } catch (error) {
+          // A check that cannot run cannot prove a skip either: report it
+          // like a build failure and build — the safe direction.
+          if (onError) onError(error);
+          wanted = true;
+        }
+        if (!wanted) {
+          if (!dirty) return; // nothing moved: no build, nothing scheduled
+        }
+      }
+      for (;;) {
+        dirty = false;
+        let candidate;
+        try {
+          candidate = await build();
+        } catch (error) {
+          if (onError) onError(error);
+          // The dirty flag set during the failed build still owes its one
+          // follow-up; otherwise the loop settles until the next change.
+          if (!dirty) return;
+          continue;
+        }
+        if (closed) {
+          await guard(() => discard(candidate));
+          return;
+        }
+        let moved = dirty;
+        if (isStale !== null) {
+          // The authority, even over a dirty flag a prompt set: the check
+          // re-stats the candidate's own start snapshot, so a prompt whose
+          // identity that snapshot already consumed (a late duplicate
+          // delivered while this candidate was in flight) answers fresh
+          // and is dropped — "an event arrived" is not "the inputs
+          // moved". Callers without isStale keep the dirty flag as
+          // before.
+          try {
+            moved = await isStale(candidate);
+          } catch (error) {
+            // A check that cannot run cannot prove the candidate fresh
+            // either: report it like a build failure and let the rebuild
+            // decide — the same safe direction an unanswerable stat has.
+            if (onError) onError(error);
+            moved = true;
+          }
+        }
+        if (moved) {
+          // A change was observed while this candidate was being taken or
+          // built — by an event (the fast path) or by the candidate's own
+          // inputs having moved on disk (the authority): discard it and
+          // rebuild before publishing anything.
+          await guard(() => discard(candidate));
+          continue;
+        }
+        await guard(() => publish(candidate));
+        return;
+      }
+    } finally {
+      running = false;
+      if (!closed && dirty && timer === null) {
+        // Exactly one follow-up for the changes that landed during the last
+        // build; no debounce is owed because the events already happened.
+        dirty = false;
+        cycle();
+        return;
+      }
+      settleIfIdle();
+    }
+  }
+
+  /**
+   * A promise that resolves once no build is running and none is queued —
+   * the initial build's settle, and the test/telemetry seam for the same.
+   */
+  function idle() {
+    if (!running && !dirty && timer === null) return Promise.resolve();
+    return new Promise((resolve) => {
+      idleWaiters.add(resolve);
+    });
+  }
+
+  return {
+    /** True while a build cycle is in flight. */
+    get running() { return running; },
+    /** True when a change arrived during the current build. */
+    get dirty() { return dirty; },
+    /** True when a debounce is scheduled or a follow-up is queued. */
+    get pending() { return timer !== null; },
+    /** True once close() has been called; the loop does nothing after it. */
+    get closed() { return closed; },
+    /** Resolves when no build runs and none is queued (or once closed). */
+    idle,
+
+    /**
+     * One filtered change arrived. Idle: schedule one coalesced cycle after
+     * the debounce window (the timer resets per event, so a burst is one
+     * build). Building: set the single dirty flag that queues one follow-up.
+     */
+    notifyChange() {
+      if (closed) return;
+      if (running) {
+        dirty = true;
+        return;
+      }
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        cycle();
+      }, debounceMs);
+    },
+
+    /** Start one cycle now (the initial build); a no-op while one runs. */
+    kick() {
+      if (closed || running) return;
+      clearTimer();
+      cycle();
+    },
+
+    /** Final: cancel the pending debounce, discard what is in flight. */
+    async close() {
+      if (closed) return;
+      closed = true;
+      clearTimer();
+      // An in-flight cycle observes `closed` when its build resolves and
+      // discards the candidate itself; a cycle between builds has nothing
+      // in flight. Wait for neither: close must not block on a build.
+      const waiters = [...idleWaiters];
+      idleWaiters.clear();
+      for (const waiter of waiters) waiter();
+    },
+  };
+}