animader-cli 0.0.0-stage → 0.1.1

package/player/index.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="dark">
+<title>Animader demo</title>
+<link rel="icon" href="data:,">
+<link rel="stylesheet" href="/player/player.css">
+</head>
+<body>
+<main>
+  <h1 class="visually-hidden">Animader demo</h1>
+  <div id="performance">
+    <div id="stage" class="stage">
+      <canvas id="canvas" width="1280" height="720" role="img" aria-label="Live performance canvas"></canvas>
+    </div>
+    <p id="status" class="status" role="status" aria-live="polite">loading</p>
+    <div id="controls" class="panel" role="group" aria-label="Playback controls">
+      <button id="primary" type="button" data-player-control="primary" hidden>Start</button>
+      <button id="fullscreen" type="button" class="secondary" data-player-control="fullscreen" hidden>Fullscreen</button>
+    </div>
+    <div id="error" class="banner" role="alert" tabindex="-1" hidden>
+      <span class="marker">error:</span> <span id="error-message"></span>
+    </div>
+  </div>
+  <details id="diagnostics" class="diagnostics" hidden>
+    <summary>diagnostics</summary>
+    <pre id="diagnostics-text"></pre>
+  </details>
+  <noscript>This demo needs JavaScript to load the prepared viewer and its audio clock.</noscript>
+</main>
+<script type="module" src="/player/page.mjs"></script>
+</body>
+</html>

package/player/page.mjs

@@ -0,0 +1,134 @@
+// The dev entry: the original server-mounted UI and URLs, injected into the
+// shared page implementation. The release entry replaces this profile with
+// static imports and relative export assets; it does not import this file.
+//
+// Generation pinning (plan section 5): the page boots either on the
+// generation the reload URL carries (?gen=N) or, on a bare load, learns the
+// current generation from /config.json before any show asset is requested —
+// then every project-derived fetch (config, payload, timeline, soundtrack)
+// is pinned to that one immutable /gen/<id>/ prefix, so a rebuild under a
+// live page can never mix a new timeline with an old payload or audio. The
+// development-only channel in devchannel.mjs reloads the page onto a new
+// generation when the server says so.
+
+import { boot, reportBootFailure } from './boot.mjs';
+import { connectDevChannel, showStaleNotice } from './devchannel.mjs';
+
+function pinnedGenerationFromUrl() {
+  const param = new URLSearchParams(window.location.search).get('gen');
+  if (param !== null && /^[1-9][0-9]*$/.test(param)) return Number(param);
+  return null;
+}
+
+async function currentGeneration() {
+  const pinned = pinnedGenerationFromUrl();
+  if (pinned !== null) return pinned;
+  try {
+    const response = await fetch('/config.json', { cache: 'no-store' });
+    if (!response.ok) return null;
+    const config = await response.json();
+    if (Number.isInteger(config?.generation) && config.generation > 0) return config.generation;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+const generation = await currentGeneration();
+const prefix = generation === null ? '' : `/gen/${generation}`;
+
+const documents = {
+  runtimeModule: '/runtime/pngine.mjs',
+  config: `${prefix}/config.json`,
+  payload: 'out/show.png',
+  manifest: 'manifest.json',
+};
+
+async function importModule(path) {
+  try {
+    return await import(path);
+  } catch (cause) {
+    const error = new Error(`${path} could not be loaded: ${cause?.message ?? cause}`);
+    error.code = 'module_failed';
+    error.stage = 'modules';
+    error.document = path;
+    error.cause = cause;
+    throw error;
+  }
+}
+
+const devProfile = {
+  name: 'dev',
+  remedy: 're-run the one-time prepare (node demo/prepare.mjs) to re-vendor it from the actual build',
+  documents,
+  loadController: () => importModule('./controller.mjs'),
+  loadModules: async () => {
+    const [
+      scoreModule,
+      showModule,
+      soundtrackData,
+      webaudioModule,
+      pngineModule,
+      pacerModule,
+      routeModule,
+      pieceModule,
+      runModule,
+    ] = await Promise.all([
+      importModule('/app/lib/score.mjs'),
+      importModule('/app/lib/show.mjs'),
+      importModule('/app/lib/soundtrack.mjs'),
+      importModule('/app/adapters/webaudio.mjs'),
+      importModule('/runtime/pngine.mjs'),
+      importModule('/runtime/pacer/index.js'),
+      importModule('/runtime/pacer/route.js'),
+      importModule('/runtime/animader/piece.js'),
+      importModule('/examples/hello/player/run.js'),
+    ]);
+    return {
+      score: scoreModule,
+      show: showModule,
+      soundtrack: soundtrackData,
+      webaudio: webaudioModule,
+      pngine: pngineModule,
+      pacer: pacerModule,
+      route: routeModule,
+      piece: pieceModule,
+      run: runModule,
+    };
+  },
+  configUrl: `${prefix}/config.json`,
+  manifestUrl: null,
+  configManifestPath: null,
+  assets: [
+    { key: 'payload', url: `${prefix}/project/out/show.png`, kind: 'bytes' },
+    { key: 'timeline', url: `${prefix}/project/timeline.piece.sjon`, kind: 'text' },
+    { key: 'provenance', url: '/runtime/provenance.json', kind: 'json' },
+    { key: 'pacerWasm', url: '/runtime/pacer/pacer.wasm', kind: 'bytes' },
+    { key: 'pieceWasm', url: '/runtime/animader/animader.wasm', kind: 'bytes' },
+  ],
+  // The audio URL comes from the validated config selection, never from a
+  // hardcoded name: the loader appends this asset after config validation.
+  soundtrackAsset: (name) => ({ key: 'soundtrack', url: `${prefix}/project/${name}`, kind: 'bytes' }),
+  loadScore: ({ modules, assets, reflection }) => modules.score.loadShow({
+    document: {
+      name: 'timeline.piece.sjon',
+      text: assets.timeline.text,
+    },
+    dep: {
+      pieceWasm: assets.pieceWasm.bytes,
+      pacerWasm: assets.pacerWasm.bytes,
+      reflection,
+    },
+    factories: {
+      instantiatePieceHost: modules.piece.PieceHost.instantiate,
+      loadPacer: modules.pacer.Pacer.load,
+    },
+  }),
+};
+
+// The stale notice is built by the dev channel module; the stylesheet owns
+// its out-of-flow layout contract, so it overlays without reflowing the
+// page and the primary control stays reachable.
+connectDevChannel({ generation, onStale: (error) => showStaleNotice(document, error) });
+
+boot(devProfile).catch(reportBootFailure);

package/player/player.css

@@ -0,0 +1,393 @@
+/* The demo player extends the incumbent hello tokens; the canvas is the only
+   thing that scales. The artboard's CSS content box stays 1280x720 and pngine
+   owns its backing store at the actual device DPR. There is deliberately no
+   canvas media query: the wrapper letterboxes by transform, so a narrow window
+   never changes the canvas content box or fires a mid-run reallocation. */
+
+:root {
+  color-scheme: dark;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: #0a0608;
+  color: #d8cfc4;
+  font: 14px/1.4 system-ui, sans-serif;
+}
+
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+main {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 12px;
+  width: 100%;
+  max-width: 1312px;
+  margin: 0 auto;
+  padding: 16px;
+}
+
+#performance {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.stage {
+  position: relative;
+  width: 100%;
+  max-width: 1280px;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  background: #000;
+  border: 1px solid #2c2026;
+}
+
+#canvas {
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: block;
+  background: #000;
+  transform-origin: 0 0;
+}
+
+#performance:fullscreen {
+  background: #0a0608;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 16px;
+}
+
+#performance:fullscreen .stage {
+  flex: 1;
+  min-height: 0;
+  max-width: none;
+  aspect-ratio: auto;
+}
+
+.status {
+  margin: 0;
+  color: #8f857a;
+  font-variant-numeric: tabular-nums;
+  overflow-wrap: anywhere;
+}
+
+.panel {
+  display: flex;
+  gap: 16px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+button {
+  background: #241a20;
+  color: #d8cfc4;
+  border: 1px solid #3a2a33;
+  padding: 4px 10px;
+  font: inherit;
+}
+
+button:hover {
+  border-color: #8f857a;
+}
+
+button:focus-visible {
+  outline: 2px solid #f0b27a;
+  outline-offset: 2px;
+}
+
+#primary {
+  border-color: #f0b27a;
+  color: #f0b27a;
+}
+
+.secondary {
+  background: transparent;
+  color: #8f857a;
+  border-color: #2c2026;
+}
+
+.banner {
+  padding: 8px 10px;
+  background: #140d11;
+  border: 1px solid #f0b27a;
+  color: #d8cfc4;
+  font: 12px/1.4 ui-monospace, monospace;
+  overflow-wrap: anywhere;
+}
+
+.banner:focus-visible {
+  outline: 2px solid #f0b27a;
+  outline-offset: 2px;
+}
+
+.marker {
+  color: #f0b27a;
+}
+
+/* The dev-only stale notice overlays the viewport top out of flow: a fixed
+   element is removed from normal flow, so the stage, the status line and
+   the controls keep the exact offsets they have without the notice — an
+   in-flow notice once pushed the primary control below the fold on a
+   1280x800 laptop. The message wraps instead of truncating or overflowing.
+   The release page has no dev channel and never renders the element. */
+
+/* The notice's height cap is geometry, not a device class: the notice may
+   grow down to the canvas's central third — the middle band of the picture,
+   where a subject sits — and no further, at every width. The stage is
+   width: 100% / max-width: 1280px / aspect-ratio: 16/9, so a third of the
+   canvas is min(100vw, 1280px) * 9/16 / 3 = min(100vw, 1280px) * 0.1875
+   tall. Two measured corrections make that expression honest (Chromium
+   153, viewport height 800, the 430–1280 sweep of 2026-10-28 recorded in
+   .agent/control/stale-cap-verify.md; canvas.top measured 17 at every
+   width — 16px main padding + 1px stage border-top):
+
+     - the canvas starts 17px down, which the expression does not know;
+     - main's 32px horizontal padding and the stage's 2px borders make the
+       real canvas height (min(100vw, 1312px) - 34px) * 0.5625, so the
+       expression over-counts a third by (34 * 0.5625) / 3 = 6.375px.
+
+   The exact allowance is therefore 17 - 6.375 = 10.625px; the largest
+   whole pixel under it, 10px, leaves the cap 0.19px (431 and 767px),
+   0.33–0.5px (the other measured widths) and structurally 0.625px below
+   the central third at every width up to 1280px. No max-width media query
+   owns this: the 767px boundary capped tablet presentations that already
+   cleared the third (at 640px the natural six-line notice cleared it by
+   11.6px) and answered a hypothetical longer message instead of the
+   measured one — diagnostic length is unbounded, so only the relationship
+   between the notice and the canvas bounds it.
+
+   The cap bounds the notice as a GRID of two rows: the summary's auto row
+   and the opened content's minmax(0, 1fr) row. The 1fr track is what makes
+   the cap reach the text: a fr row resolves against the clamped container
+   while an auto row (or a flex basis) cannot, and the engine's
+   ::details-content wrapper — the box that actually hosts the body inside a
+   <details> — is the grid item, so it carries min-height: 0 and the body
+   fills it under max-height: 100% and scrolls there. The notice itself is
+   never the scroller, because a scrollable details measures (Chromium,
+   2026-10-29) as a tab stop BEFORE its own summary while Tab forward from
+   the summary left the notice; the tab order is now summary → (open) body
+   → out (round 3, finding 1). The one media query that touches the notice
+   swaps text only — below the covered range the summary's recovery
+   sentence becomes a compact phrase that runs inline with the affordance —
+   never geometry; that is a sentence-length decision, not the rejected
+   width cap returning.
+
+   The collapsed summary (block lines: lead, recovery, affordance — see
+   devchannel.mjs) keeps its own tighter line-height (1.2 → 14.4px a line)
+   and the lead keeps to one introducing word. At 360px and wider it is
+   four lines: 4 × 14.4px + 18px chrome = 75.6px against the 77.5px cap at
+   360px, 83.125px at 390px, 85.9375px at 405px — it fits at rest at
+   360/375/390/405 and everywhere wider. Below 360px the compact phrase
+   takes over: at 320px the cap (70px) holds exactly three lines, the lead
+   alone takes two of them, and the compact phrase plus the affordance
+   share the third (36 model characters against the 38-character line), so
+   the collapsed summary is 3 × 14.4px + 18px = 61.2px — it fits at rest
+   down to 320px and (by the same arithmetic) to roughly 299px. Below that
+   floor not even the compact fits; the notice cannot scroll while
+   collapsed any more, so overflow: hidden clips at the cap — the geometry
+   holds, the sub-floor text is the recorded gap, and the proof, per width,
+   is the arithmetic guard in npm/cli/test/stale-cap.test.js.
+   100vw includes a classic scrollbar where one exists, which can move the
+   cap a couple of px past the true third there; only the opened, scrolling
+   state can ever reach the cap. Fullscreen does not follow this formula:
+   #performance:fullscreen .stage is flex: 1 with aspect-ratio: auto, so
+   the stage stops being 16:9 and no width-derived expression describes its
+   height. The cap keeps its >=1280px value (250px) there — conservative on
+   a tall stage, but on a short one it can sit past the stage's true third;
+   the collapsed summary is what shows at rest either way. */
+#dev-stale {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 1;
+  margin: 0;
+  padding: 8px 12px;
+  border: 1px solid #3a2a33;
+  background: #140d11;
+  color: #f0b27a;
+  font: 12px/1.4 ui-monospace, monospace;
+  overflow-wrap: anywhere;
+  white-space: pre-line;
+  max-height: calc(min(100vw, 1280px) * 0.1875 + 10px);
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr);
+  overflow: hidden;
+}
+
+/* The collapsed state is a native <details>: the summary is the keyboard
+   affordance on every engine without scripting — the review that reshaped
+   this found the previous capped scroll box reachable only where the
+   engine happens to make scroll containers tab stops. The UA marker is
+   dropped in favour of the summary's last line, which says in words that
+   the full failure is one press away (the ::-webkit-details-marker rule
+   covers engines whose summary ignores list-style). The focus ring is the
+   house 2px amber :focus-visible treatment that buttons, .banner and the
+   diagnostics summary already carry, not the UA default.
+   The summary's own line-height is deliberately tighter than the notice's
+   1.4: at 360px and wider the collapsed state is four lines (one-word
+   lead, twice-wrapped recovery sentence, affordance) and must fit the cap
+   at rest — 4 × 14.4px + 18px chrome = 75.6px against the 77.5px cap; at
+   1.4 the same four lines are 85.2px and over the 83.125px cap at 390px,
+   which is the defect round 2 fixed. The expanded body keeps the notice's
+   1.4 rhythm. The summary's grid row is auto, so the cap's pressure lands
+   on the content row — the element that can scroll. */
+#dev-stale summary {
+  display: block;
+  list-style: none;
+  cursor: pointer;
+  line-height: 1.2;
+}
+
+#dev-stale summary::-webkit-details-marker {
+  display: none;
+}
+
+#dev-stale summary:focus-visible {
+  outline: 2px solid #f0b27a;
+  outline-offset: 2px;
+}
+
+/* Round 3, finding 2 — the compact recovery phrase, the one place a width
+   query is allowed to touch the notice, because it chooses a sentence, not
+   a box. At 360px and wider the full reassurance fits (four summary lines,
+   75.6px, against caps of 77.5px at 360 and up). Below that the cap
+   shrinks 0.1875px per pixel until the full sentence no longer fits, so
+   the summary swaps it for a phrase that runs inline with the affordance
+   on one line — at 320px the cap (70px) holds exactly three 14.4px lines,
+   the lead alone takes two, and "— last good view; the full failure …"
+   (36 model characters against a 38-character line) carries the
+   reassurance AND the affordance on the third. The full sentence stays in
+   the opened body verbatim, and the display:none half is out of the
+   accessibility tree, so the summary's name matches what is painted.
+   The swap boundary is 359px — the widest pixel the full-sentence proof
+   (360 and up) does not cover; the compact phrase is proven down to 320px
+   and (by the guard's arithmetic) to roughly 299px. */
+#dev-stale .stale-recovery-compact {
+  display: none;
+}
+
+@media (max-width: 359px) {
+  #dev-stale .stale-recovery {
+    display: none;
+  }
+
+  #dev-stale .stale-recovery-compact,
+  #dev-stale .stale-more {
+    display: inline;
+  }
+}
+
+#dev-stale summary span {
+  display: block;
+}
+
+#dev-stale .stale-more {
+  color: #8f857a;
+}
+
+/* The expanded body: the whole failure verbatim, the built newlines painted
+   by the inherited pre-line, separated from the summary by the diagnostics
+   rhythm — and the notice's ONLY scroller (round 3, finding 1). Inside a
+   <details> the engine hosts the non-summary children in its own
+   ::details-content wrapper — THAT box is the second grid row, so it must
+   carry min-height: 0 or the row can never shrink below the body's
+   min-content and the notice clips instead of the body scrolling. The body
+   then fills the row under max-height: 100% and scrolls there, and
+   tabindex="0" (set as markup by devchannel.mjs) makes that scroller a tab
+   stop after the summary — so the summary is the notice's first and only
+   stop while collapsed, and summary → body → out once open. The closed
+   disclosure does not render the body, so it is not a stop until it can be
+   read. */
+#dev-stale::details-content {
+  min-height: 0;
+}
+
+#dev-stale .stale-body {
+  margin: 8px 0 0;
+  max-height: 100%;
+  overflow-y: auto;
+}
+
+/* The scroller's own ring: the same house 2px amber :focus-visible
+   treatment as the summary and the buttons, on the element that actually
+   scrolls — the opened body. */
+#dev-stale .stale-body:focus-visible {
+  outline: 2px solid #f0b27a;
+  outline-offset: 2px;
+}
+
+/* Round 3, finding 3 — when the opened body scrolls, say so. A scroller at
+   rest shows a partial last line, and at 320px the round-2 reading showed
+   exactly that reading as the end of the message ("successful edit" cut to
+   a sliver, no scrollbar painted). The builder measures scrollHeight
+   against clientHeight when the disclosure opens (the native toggle event)
+   and on every delivery, and wears the class; the cue is then a sticky
+   ::after inside the scroller: pinned to the scrollport's bottom edge —
+   opaque, in the notice's panel colour with the diagnostics separator — so
+   it covers the partial line while text follows, and it settles after the
+   last line once the end is reached. No hover anywhere: a cue that needs a
+   pointer hides the problem from touch and from the keyboard. */
+#dev-stale .stale-body.scrolls-more::after {
+  content: '…';
+  display: block;
+  position: sticky;
+  bottom: 0;
+  color: #8f857a;
+  text-align: right;
+  background: #140d11;
+  border-top: 1px solid #2c2026;
+}
+
+.diagnostics {
+  padding-top: 8px;
+  border-top: 1px solid #2c2026;
+  color: #8f857a;
+  font: 12px/1.4 ui-monospace, monospace;
+}
+
+.diagnostics summary {
+  cursor: pointer;
+}
+
+.diagnostics summary:focus-visible {
+  outline: 2px solid #f0b27a;
+  outline-offset: 2px;
+}
+
+#diagnostics-text {
+  margin: 8px 0 0;
+  color: #d8cfc4;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.diag-line {
+  display: block;
+}
+
+::selection {
+  background: #f0b27a;
+  color: #0a0608;
+}
+
+[hidden] {
+  display: none !important;
+}

package/player/release.mjs

@@ -0,0 +1,76 @@
+// The release entry. It statically imports the portable core, the prepared
+// pngine viewer, the playback-only pacer runtime and the hello run core, then
+// points the shared page implementation at the exported files relative to
+// this module. The third-party playback runtime arrives as bare
+// specifiers — 'pngine/viewer', '@mr_hugo/pacer/rt', '@mr_hugo/pacer/route' — which the
+// bundler resolves against the toolchain's pinned artifacts (the vendored
+// bundle in contributor mode, the installed packages otherwise), so this
+// file never carries a path out of the package. The authoring compiler
+// (animader.wasm/piece.js), pacer's text compile driver, the dev profile
+// and every server-mount path are absent from this graph by construction;
+// esbuild bundles this file and its static imports into the single shipped
+// app.mjs.
+//
+// `import.meta.url` is app.mjs at the export root, so every URL below stays
+// correct when the whole export is served from a nested path.
+
+import { createPlayerController, audioDurationNote } from './controller.mjs';
+import { boot, reportBootFailure } from './boot.mjs';
+import { loadPackedShow, ShowError } from '../lib/score.mjs';
+import { createShow } from '../lib/show.mjs';
+import * as soundtrackData from '../lib/soundtrack.mjs';
+import { createWebAudioPort } from '../adapters/webaudio.mjs';
+import { pngine, draw, setUniform, getUniforms, restartSettled } from 'pngine/viewer';
+import { PacerRt } from '@mr_hugo/pacer/rt';
+import { routeWrites, toUniforms } from '@mr_hugo/pacer/route';
+import { createPlayer } from '../hello/run.js';
+
+const root = new URL('./', import.meta.url);
+
+const releaseProfile = {
+  name: 'release',
+  remedy: 'rebuild the export with node demo/export.mjs so the prepared viewer carries restartSettled',
+  documents: {
+    runtimeModule: './app.mjs',
+    config: './config.json',
+    payload: 'assets/show.png',
+    manifest: 'manifest.json',
+  },
+  loadController: async () => ({ createPlayerController, audioDurationNote }),
+  loadModules: async () => ({
+    score: { loadPackedShow, ShowError },
+    show: { createShow },
+    soundtrack: soundtrackData,
+    webaudio: { createWebAudioPort },
+    pngine: { pngine, draw, setUniform, getUniforms, restartSettled },
+    pacerRt: { PacerRt },
+    route: { routeWrites, toUniforms },
+    run: { createPlayer },
+  }),
+  configUrl: new URL('./config.json', root),
+  configManifestPath: 'config.json',
+  manifestUrl: new URL('./manifest.json', root),
+  assets: [
+    { key: 'payload', url: new URL('./assets/show.png', root), kind: 'bytes', manifestPath: 'assets/show.png' },
+    { key: 'score', url: new URL('./assets/score.pacb', root), kind: 'bytes', manifestPath: 'assets/score.pacb' },
+    { key: 'pacerRtWasm', url: new URL('./pacer-rt.wasm', root), kind: 'bytes', manifestPath: 'pacer-rt.wasm' },
+  ],
+  // The audio asset follows the validated config selection so a release can
+  // ship any recognized name; the loader appends it after config validation.
+  soundtrackAsset: (name) => ({
+    key: 'soundtrack',
+    url: new URL(`./assets/${name}`, root),
+    kind: 'bytes',
+    manifestPath: `assets/${name}`,
+  }),
+  loadScore: ({ modules, assets, reflection }) => modules.score.loadPackedShow({
+    document: { name: 'score.pacb', bytes: assets.score.bytes },
+    dep: {
+      pacerRtWasm: assets.pacerRtWasm.bytes,
+      reflection,
+    },
+    factories: { loadPacerRt: modules.pacerRt.PacerRt.load },
+  }),
+};
+
+boot(releaseProfile).catch(reportBootFailure);