animader-cli 0.0.0-stage → 0.1.1

package/player/boot.mjs

@@ -0,0 +1,792 @@
+// The shared browser page implementation. It owns the DOM view, the
+// controller handoff, fullscreen, the renderer-failure bridge and the real
+// load sequence; each entry supplies only the profile (which modules to
+// import, which bytes to fetch, how the score was prepared). The dev entry
+// points at the server's mount names; the release entry statically imports
+// the same portable core and fetches the exported files relative to itself.
+//
+// One implementation, not two players: the transport, score compile, route
+// pair and pngine wiring below are the same code on both spellings.
+
+const canvas = document.getElementById('canvas');
+const performanceElement = document.getElementById('performance');
+const stage = document.getElementById('stage');
+const statusLine = document.getElementById('status');
+const primaryButton = document.getElementById('primary');
+const fullscreenButton = document.getElementById('fullscreen');
+const errorBanner = document.getElementById('error');
+const errorMessage = document.getElementById('error-message');
+const diagnostics = document.getElementById('diagnostics');
+const diagnosticsText = document.getElementById('diagnostics-text');
+
+let controller = null;
+let show = null;
+let context = null;
+let port = null;
+let stageScale = 1;
+let hostSeconds = null;
+let decodedDuration = null;
+let reflection = null;
+let join = null;
+let scoreText = null;
+let scoreBytes = null;
+let metaSafe = null;
+let provenance = null;
+let manifest = null;
+let config = null;
+let activeProfile = null;
+let renderer = null;
+let rendererError = null;
+let ShowErrorClass = Error;
+const hashes = { payload: null, timeline: null, soundtrack: null, score: null, manifest: null };
+
+function fallbackFatal(error) {
+  const message = error?.message ?? String(error);
+  statusLine.textContent = 'error — page';
+  errorBanner.hidden = false;
+  errorMessage.textContent = message;
+  diagnostics.hidden = false;
+  diagnostics.open = true;
+  diagnosticsText.textContent = `error: ${message}\nstage: page`;
+}
+
+// The compiled metadata carries BigInt fields (pacer's own tick units). The
+// QA projection keeps the actual values but makes them JSON-safe; the actual
+// Show/Pacer objects remain available on the seam.
+function jsonSafe(value) {
+  if (typeof value === 'bigint') return value.toString();
+  if (Array.isArray(value)) return value.map(jsonSafe);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) out[key] = jsonSafe(entry);
+    return out;
+  }
+  return value;
+}
+
+function renderDiagnostics(lines) {
+  diagnosticsText.replaceChildren();
+  for (const line of lines) {
+    const row = document.createElement('span');
+    row.className = 'diag-line';
+    const at = line.indexOf(':');
+    if (at > 0) {
+      const marker = document.createElement('span');
+      marker.className = 'marker';
+      marker.textContent = line.slice(0, at + 1);
+      row.append(marker, document.createTextNode(line.slice(at + 1)));
+    } else {
+      row.textContent = line;
+    }
+    diagnosticsText.append(row);
+  }
+}
+
+// The fullscreen control is the way out as well as the way in: while the
+// browser reports an active fullscreen element, the same button's label must
+// say 'Exit fullscreen'. The button carries no aria-label, so its accessible
+// name is its text — one honest string for the eye and for assistive
+// technology, nothing left to go stale. The controller owns the 'Fullscreen'
+// vocabulary; the page overlays the exit spelling, and both every render and
+// every fullscreenchange re-derive it from the actual fullscreen state.
+const FULLSCREEN_EXIT_LABEL = 'Exit fullscreen';
+
+function secondaryLabel(label) {
+  return document.fullscreenElement ? FULLSCREEN_EXIT_LABEL : label;
+}
+
+function syncFullscreenLabel() {
+  const secondary = controller?.ui?.secondary;
+  if (secondary) fullscreenButton.textContent = secondaryLabel(secondary.label);
+}
+
+const view = {
+  apply(ui) {
+    statusLine.textContent = ui.status;
+    if (ui.primary) {
+      primaryButton.hidden = false;
+      primaryButton.textContent = ui.primary.label;
+    } else {
+      primaryButton.hidden = true;
+    }
+    if (ui.secondary) {
+      fullscreenButton.hidden = false;
+      fullscreenButton.textContent = secondaryLabel(ui.secondary.label);
+    } else {
+      fullscreenButton.hidden = true;
+    }
+    errorBanner.hidden = !ui.errorVisible;
+    errorMessage.textContent = ui.errorText;
+    diagnostics.hidden = false;
+    renderDiagnostics(ui.diagnostics);
+    diagnostics.open = ui.diagnosticsOpen;
+  },
+  activeElement() {
+    if (document.activeElement === primaryButton) return 'primary';
+    if (document.activeElement === fullscreenButton) return 'fullscreen';
+    return 'none';
+  },
+  focusPrimary() {
+    if (!primaryButton.hidden) primaryButton.focus();
+  },
+  focusSecondary() {
+    if (!fullscreenButton.hidden) fullscreenButton.focus();
+  },
+  focusError() {
+    errorBanner.focus();
+  },
+};
+
+function updateStageScale() {
+  const width = stage.clientWidth;
+  const height = stage.clientHeight;
+  if (width < 1 || height < 1) return;
+  const scale = Math.min(width / 1280, height / 720);
+  stageScale = scale;
+  canvas.style.transform = `scale(${scale})`;
+  canvas.style.left = `${(width - 1280 * scale) / 2}px`;
+  canvas.style.top = `${(height - 720 * scale) / 2}px`;
+}
+
+// The fullscreen action is a toggle: the control's label names what the
+// next press does ('Fullscreen' to enter, 'Exit fullscreen' to leave), so
+// the action must do exactly that in both directions. The browser confirms
+// every direction with a fullscreenchange event; the label never assumes a
+// transition the browser has not reported.
+async function toggleFullscreen() {
+  if (document.fullscreenElement) {
+    if (typeof document.exitFullscreen !== 'function') return false;
+    try {
+      await document.exitFullscreen();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  if (!document.fullscreenEnabled || typeof performanceElement.requestFullscreen !== 'function') return false;
+  try {
+    await performanceElement.requestFullscreen();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const actions = {
+  start: async () => (show ? show.start() : undefined),
+  pause: async () => (show ? show.pause() : undefined),
+  resume: async () => (show ? show.resume() : undefined),
+  stop: async () => (show ? show.stop() : undefined),
+  restart: async () => {
+    if (!show) return undefined;
+    updateStageScale();
+    await show.restart();
+    if (show.state === 'ready') await show.start();
+    return show.state;
+  },
+  fullscreen: toggleFullscreen,
+};
+
+function rendererFailure(error) {
+  const name = error?.name ?? 'Error';
+  const source = error?.source ? ` (source: ${error.source})` : '';
+  const line = Number.isInteger(error?.lineNum)
+    ? ` at line ${error.lineNum}${Number.isInteger(error?.linePos) ? `:${error.linePos}` : ''}`
+    : '';
+  const detail = error?.message ?? String(error);
+  return {
+    code: 'renderer_failed',
+    message: `the renderer reported ${name}${source}${line}: ${detail}`,
+    stage: 'render',
+    document: activeProfile?.documents?.payload ?? 'out/show.png',
+    diagnostics: [{
+      source: 'pngine',
+      severity: 'error',
+      code: 0,
+      start: 0,
+      end: 0,
+      message: `${name}${source}: ${detail}`,
+    }],
+    cause: error,
+  };
+}
+
+function handlePngineError(error) {
+  rendererError = error;
+  const failure = rendererFailure(error);
+  if (show) show.fail(failure.code, failure.message, failure);
+  else if (controller) controller.fail(failure);
+}
+
+function structuredFailure(error) {
+  if (error && typeof error === 'object'
+    && ((typeof error.stage === 'string' && error.stage !== '')
+      || (typeof error.code === 'string' && error.code !== ''))) {
+    return error;
+  }
+  return {
+    code: 'page_failed',
+    message: error?.message ?? String(error),
+    stage: 'page',
+    document: 'player/boot.mjs',
+    diagnostics: [{ source: 'player', severity: 'error', code: 0, message: String(error?.stack ?? error) }],
+  };
+}
+
+/**
+ * Route one runtime failure through the page's existing failure surface: the
+ * show's structured error state when it can still take one, else the
+ * controller's. Returns the structured failure so callers can add their own
+ * context (the action handlers also log it to the console).
+ */
+function reportRuntimeFailure(error) {
+  const failure = structuredFailure(error);
+  if (show && show.state !== 'error') show.fail(failure.code, failure.message, failure);
+  else if (controller && controller.state !== 'error') controller.fail(failure);
+  return failure;
+}
+
+function qaGeometry() {
+  const rect = canvas.getBoundingClientRect();
+  return {
+    dpr: window.devicePixelRatio,
+    stage: { width: stage.clientWidth, height: stage.clientHeight },
+    canvas: {
+      backingWidth: canvas.width,
+      backingHeight: canvas.height,
+      cssWidth: rect.width,
+      cssHeight: rect.height,
+      inlineWidth: canvas.style.width,
+      inlineHeight: canvas.style.height,
+    },
+    viewer: { width: renderer?.width ?? 0, height: renderer?.height ?? 0 },
+    scale: stageScale,
+  };
+}
+
+// The deterministic QA seam: every value is the actual runtime state or a
+// digest of the bytes the page actually loaded. Nothing here is a counter, a
+// forced state or a second renderer path.
+window.animaderDemo = Object.freeze({
+  get state() { return show?.state ?? controller?.state ?? 'loading'; },
+  get tick() { return show?.tick ?? 0; },
+  get lastShownTick() { return show?.lastShownTick ?? -1; },
+  get origin() { return show?.origin ?? null; },
+  get mode() { return activeProfile?.name ?? null; },
+  get hostSeconds() { return hostSeconds; },
+  get decodedDuration() { return decodedDuration; },
+  get audioContext() { return context; },
+  get audioContextState() { return context?.state ?? null; },
+  get analyser() { return port?.analyser ?? null; },
+  get reflection() { return reflection; },
+  get join() { return join; },
+  get score() { return scoreText; },
+  get scoreBytes() { return scoreBytes; },
+  get scoreSha256() { return hashes.score; },
+  get payloadSha256() { return hashes.payload; },
+  get timelineSha256() { return hashes.timeline; },
+  get soundtrackSha256() { return hashes.soundtrack; },
+  get manifestSha256() { return hashes.manifest; },
+  get config() { return config; },
+  get manifest() { return manifest; },
+  get provenance() { return provenance; },
+  get meta() { return metaSafe; },
+  get notes() { return controller?.notes ?? []; },
+  get error() {
+    const failure = show?.error ?? controller?.error ?? null;
+    if (!failure) return null;
+    return {
+      code: failure.code ?? null,
+      message: failure.message ?? String(failure),
+      stage: failure.stage ?? '',
+      document: failure.document ?? '',
+      diagnostics: jsonSafe(failure.diagnostics ?? []),
+    };
+  },
+  get geometry() { return qaGeometry(); },
+  get show() { return show; },
+  get port() { return port; },
+});
+
+function armDprWatcher() {
+  if (typeof window.matchMedia !== 'function') return;
+  const query = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+  const onChange = () => {
+    controller?.handleResize();
+    armDprWatcher();
+  };
+  if (typeof query.addEventListener === 'function') query.addEventListener('change', onChange, { once: true });
+  else query.addListener?.(onChange);
+}
+
+async function sha256Hex(bytes) {
+  const data = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes;
+  const digest = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(digest), (value) => value.toString(16).padStart(2, '0')).join('');
+}
+
+async function safeHash(bytes) {
+  try {
+    return await sha256Hex(bytes);
+  } catch {
+    return null;
+  }
+}
+
+function labelOf(url) {
+  return url instanceof URL ? url.pathname : String(url);
+}
+
+function decodeText(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+
+function parseJson(bytes) {
+  return JSON.parse(decodeText(bytes));
+}
+
+async function fetchBytes(url, { code = 'asset_failed', stageName = 'asset', document = labelOf(url) } = {}) {
+  let response;
+  try {
+    response = await fetch(url, { cache: 'no-store' });
+  } catch (cause) {
+    throw new ShowErrorClass('network_failed', `${document} could not be fetched: ${cause?.message ?? cause}`, {
+      stage: 'network',
+      document,
+      cause,
+    });
+  }
+  if (!response.ok) {
+    throw new ShowErrorClass(code, `${document} could not be read (HTTP ${response.status})`, {
+      stage: stageName,
+      document,
+    });
+  }
+  let bytes;
+  try {
+    bytes = new Uint8Array(await response.arrayBuffer());
+  } catch (cause) {
+    throw new ShowErrorClass(code, `${document} could not be read: ${cause?.message ?? cause}`, {
+      stage: stageName,
+      document,
+      cause,
+    });
+  }
+  return bytes;
+}
+
+function manifestIndex(document) {
+  if (!document || typeof document !== 'object' || !Array.isArray(document.files)) {
+    throw new ShowErrorClass('manifest_invalid', 'manifest.json has no files array', {
+      stage: 'manifest',
+      document: 'manifest.json',
+    });
+  }
+  const index = new Map();
+  for (const entry of document.files) {
+    if (!entry || typeof entry.path !== 'string' || entry.path === ''
+      || !Number.isInteger(entry.bytes) || entry.bytes < 0
+      || typeof entry.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(entry.sha256)) {
+      throw new ShowErrorClass('manifest_invalid', 'manifest.json carries a malformed file row', {
+        stage: 'manifest',
+        document: 'manifest.json',
+      });
+    }
+    if (index.has(entry.path)) {
+      throw new ShowErrorClass('manifest_invalid', `manifest.json lists ${entry.path} twice`, {
+        stage: 'manifest',
+        document: 'manifest.json',
+      });
+    }
+    index.set(entry.path, entry);
+  }
+  return index;
+}
+
+async function verifyManifested(manifestDocument, checks) {
+  if (!manifestDocument) return;
+  const index = manifestIndex(manifestDocument);
+  for (const check of checks) {
+    if (!check.manifestPath) continue;
+    const entry = index.get(check.manifestPath);
+    if (!entry) {
+      throw new ShowErrorClass('manifest_unlisted', `${check.manifestPath} is not listed in manifest.json`, {
+        stage: 'manifest',
+        document: 'manifest.json',
+      });
+    }
+    if (entry.bytes !== check.bytes.byteLength) {
+      throw new ShowErrorClass(
+        'asset_tampered',
+        `${check.manifestPath} is ${check.bytes.byteLength} bytes but manifest.json records ${entry.bytes}`,
+        { stage: check.stage, document: check.manifestPath },
+      );
+    }
+    const digest = await safeHash(check.bytes);
+    if (digest !== entry.sha256) {
+      throw new ShowErrorClass('asset_tampered', `${check.manifestPath} does not match its manifest sha256`, {
+        stage: check.stage,
+        document: check.manifestPath,
+      });
+    }
+  }
+}
+
+async function loadAsset(asset) {
+  const bytes = await fetchBytes(asset.url, {
+    code: asset.code ?? 'asset_failed',
+    stageName: asset.stage ?? 'assets',
+    document: asset.document ?? labelOf(asset.url),
+  });
+  const result = { bytes };
+  if (asset.kind === 'text') result.text = decodeText(bytes);
+  else if (asset.kind === 'json') result.json = parseJson(bytes);
+  return result;
+}
+
+async function load(controllerModule, profile) {
+  const { audioDurationNote } = controllerModule;
+  const documents = profile.documents;
+
+  controller.setLoading('modules');
+  const modules = await profile.loadModules();
+  const { score: scoreModule, show: showModule, webaudio: webaudioModule, pngine: pngineModule } = modules;
+  const { ShowError } = scoreModule;
+  ShowErrorClass = ShowError;
+  const { createShow } = showModule;
+  const { createWebAudioPort } = webaudioModule;
+  const { pngine, draw, setUniform, getUniforms, restartSettled } = pngineModule;
+  if (typeof restartSettled !== 'function') {
+    throw new ShowError(
+      'runtime_stale',
+      `the prepared pngine runtime at ${documents.runtimeModule} does not export restartSettled; `
+        + (profile.remedy ?? 're-run the one-time prepare (node demo/prepare.mjs) to re-vendor it from the actual build'),
+      { stage: 'modules', document: documents.runtimeModule },
+    );
+  }
+  const { routeWrites, toUniforms } = modules.route;
+  const { createPlayer } = modules.run;
+
+  controller.setLoading('config');
+  const configBytes = await fetchBytes(profile.configUrl, {
+    code: 'config_failed',
+    stageName: 'config',
+    document: documents.config,
+  });
+  let parsedConfig;
+  try {
+    parsedConfig = parseJson(configBytes);
+  } catch (cause) {
+    throw new ShowError('config_failed', `${documents.config} is not JSON: ${cause?.message ?? cause}`, {
+      stage: 'config',
+      document: documents.config,
+      cause,
+    });
+  }
+  if (typeof parsedConfig?.seconds !== 'number' || !Number.isFinite(parsedConfig.seconds) || parsedConfig.seconds <= 0) {
+    throw new ShowError('invalid_config', `the host configuration has no positive seconds value (got ${String(parsedConfig?.seconds)})`, {
+      stage: 'config',
+      document: documents.config,
+    });
+  }
+  // The generated config names its format and the selected soundtrack; the
+  // loader accepts version 1 with no explicit selection as the legacy WAV,
+  // refuses compressed names on version 1, and refuses unknown versions or
+  // selections outright. The audio URL is derived only from a validated name.
+  const soundtrackData = modules.soundtrack;
+  const format = parsedConfig.format;
+  if (!soundtrackData.ALL_PLAYER_CONFIG_FORMATS.includes(format)) {
+    throw new ShowError(
+      'invalid_config',
+      `${documents.config} names the unsupported format ${JSON.stringify(format ?? null)}; the supported formats are ${soundtrackData.ALL_PLAYER_CONFIG_FORMATS.join(', ')}`,
+      { stage: 'config', document: documents.config },
+    );
+  }
+  const legacyFormats = [soundtrackData.PLAYER_CONFIG_FORMATS.demoLegacy, soundtrackData.PLAYER_CONFIG_FORMATS.releaseLegacy];
+  let soundtrackName;
+  if (legacyFormats.includes(format)) {
+    const requested = parsedConfig.soundtrack;
+    if (requested === undefined) {
+      soundtrackName = soundtrackData.LEGACY_SOUNDTRACK;
+    } else if (requested === soundtrackData.LEGACY_SOUNDTRACK) {
+      soundtrackName = requested;
+    } else {
+      throw new ShowError(
+        'invalid_config',
+        `${documents.config} is a version-1 config but carries the explicit selection ${JSON.stringify(requested)}; version 1 means the legacy ${soundtrackData.LEGACY_SOUNDTRACK}, and compressed audio requires version 2`,
+        { stage: 'config', document: documents.config },
+      );
+    }
+  } else if (!soundtrackData.isSoundtrackName(parsedConfig.soundtrack)) {
+    throw new ShowError(
+      'invalid_config',
+      `${documents.config} requires a soundtrack field naming exactly one of ${soundtrackData.SOUNDTRACK_NAMES.join(', ')}; got ${JSON.stringify(parsedConfig.soundtrack ?? null)}`,
+      { stage: 'config', document: documents.config },
+    );
+  } else {
+    soundtrackName = parsedConfig.soundtrack;
+  }
+  config = parsedConfig;
+  hostSeconds = parsedConfig.seconds;
+  controller.setSeconds(hostSeconds);
+
+  if (profile.manifestUrl) {
+    const manifestBytes = await fetchBytes(profile.manifestUrl, {
+      code: 'manifest_failed',
+      stageName: 'manifest',
+      document: documents.manifest,
+    });
+    try {
+      manifest = parseJson(manifestBytes);
+    } catch (cause) {
+      throw new ShowError('manifest_failed', `${documents.manifest} is not JSON: ${cause?.message ?? cause}`, {
+        stage: 'manifest',
+        document: documents.manifest,
+        cause,
+      });
+    }
+    hashes.manifest = await safeHash(manifestBytes);
+    // Release order: the manifest is validated and the config bytes are
+    // verified against their entry before the validated selection constructs
+    // any asset request, so a config that is not the shipped one never
+    // triggers the audio or asset fetches.
+    await verifyManifested(manifest, [
+      { bytes: configBytes, manifestPath: profile.configManifestPath, stage: 'config' },
+    ]);
+  }
+
+  controller.setLoading('audio');
+  const AudioContextClass = globalThis.AudioContext ?? globalThis.webkitAudioContext;
+  if (typeof AudioContextClass !== 'function') {
+    throw new ShowError('unsupported_audio', 'this browser exposes no AudioContext for the demo soundtrack', {
+      stage: 'audio',
+    });
+  }
+  context = new AudioContextClass();
+  if (context.state !== 'suspended') {
+    try {
+      await context.suspend();
+    } catch {
+      // The state check below names the real failure.
+    }
+  }
+  if (context.state !== 'suspended') {
+    throw new ShowError('audio_suspended_failed', `the audio context could not be created suspended (state ${context.state})`, {
+      stage: 'audio',
+    });
+  }
+  port = createWebAudioPort({ context });
+
+  controller.setLoading('assets');
+  const assetList = [...profile.assets, profile.soundtrackAsset(soundtrackName)];
+  const fetched = await Promise.all(assetList.map((asset) => loadAsset(asset)));
+  const assets = {};
+  assetList.forEach((asset, index) => { assets[asset.key] = fetched[index]; });
+
+  // The config entry was already verified against the manifest before the
+  // asset requests; this second pass covers the fetched assets themselves,
+  // including the selected soundtrack, so the decoded audio is the manifest's
+  // audio and not merely something served at its URL.
+  await verifyManifested(manifest, assetList.map((asset) => ({
+    bytes: assets[asset.key].bytes,
+    manifestPath: asset.manifestPath,
+    stage: asset.stage ?? 'assets',
+  })));
+
+  provenance = assets.provenance?.json ?? null;
+  hashes.payload = assets.payload ? await safeHash(assets.payload.bytes) : null;
+  hashes.timeline = assets.timeline ? await safeHash(assets.timeline.bytes) : null;
+  hashes.soundtrack = assets.soundtrack ? await safeHash(assets.soundtrack.bytes) : null;
+
+  controller.setLoading('viewer');
+  if (!globalThis.navigator?.gpu) {
+    throw new ShowError('unsupported_webgpu', 'this browser exposes no WebGPU, which the prepared viewer requires', {
+      stage: 'gpu',
+      document: documents.payload,
+    });
+  }
+  const payload = assets.payload.bytes;
+  try {
+    renderer = await pngine(payload, { canvas, onError: handlePngineError });
+  } catch (cause) {
+    if (cause && typeof cause === 'object' && typeof cause.code === 'string') throw cause;
+    throw new ShowError('renderer_failed', `the prepared viewer could not initialize: ${cause?.message ?? cause}`, {
+      stage: 'gpu',
+      document: documents.payload,
+      cause,
+      diagnostics: [{ source: 'pngine', severity: 'error', code: 0, message: String(cause?.message ?? cause) }],
+    });
+  }
+  if (rendererError !== null) throw rendererFailure(rendererError);
+  reflection = await getUniforms(renderer);
+  if (rendererError !== null) throw rendererFailure(rendererError);
+  if (!reflection || Object.keys(reflection).length === 0) {
+    throw new ShowError('reflection_empty', 'the prepared program reflects no uniform targets', {
+      stage: 'reflect',
+      document: documents.payload,
+    });
+  }
+
+  controller.setLoading('score');
+  const loaded = await profile.loadScore({ modules, assets, reflection });
+  if (rendererError !== null) throw rendererFailure(rendererError);
+  scoreText = typeof loaded.score === 'string' ? loaded.score : null;
+  scoreBytes = Number.isInteger(loaded.scoreBytes)
+    ? loaded.scoreBytes
+    : scoreText === null
+      ? (loaded.score instanceof Uint8Array ? loaded.score.byteLength : null)
+      : new TextEncoder().encode(scoreText).byteLength;
+  join = loaded.join;
+  metaSafe = jsonSafe(loaded.meta);
+  hashes.score = await safeHash(loaded.score);
+
+  controller.setLoading('player');
+  const player = createPlayer({
+    pacer: {
+      setControl: (ref, value) => loaded.driver.setControl(ref, value),
+      clearControl: (ref) => loaded.driver.clearControl(ref),
+      eval: (now) => loaded.driver.eval(now / 1_000_000),
+    },
+    routeWrites,
+    toUniforms,
+    setUniform: (name, value, options) => setUniform(renderer, name, value, options),
+    draw: (options) => draw(renderer, options),
+  });
+
+  controller.setLoading('audio decode');
+  show = createShow({
+    seconds: hostSeconds,
+    prepare: async () => ({
+      driver: loaded.driver,
+      player,
+      renderer: {
+        // The owner's settled verb resolves only after the real device
+        // rebuild; returning it makes the show's restart await the reset
+        // instead of resolving on the legacy fire-and-forget post.
+        restart: () => restartSettled(renderer),
+      },
+    }),
+    decode: async () => {
+      const audioBytes = assets.soundtrack.bytes;
+      let decoded;
+      try {
+        decoded = await port.decode(audioBytes.buffer.slice(
+          audioBytes.byteOffset,
+          audioBytes.byteOffset + audioBytes.byteLength,
+        ));
+      } catch (cause) {
+        // Corrupt, truncated or unsupported audio names the asset and the
+        // browser's own decode cause; it is never treated as empty audio.
+        throw new ShowErrorClass(
+          'audio_decode_failed',
+          `${soundtrackName} could not be decoded: ${cause?.message ?? cause}`,
+          { stage: 'audio', document: soundtrackName, cause },
+        );
+      }
+      decodedDuration = decoded.duration;
+      const note = audioDurationNote(decoded.duration, hostSeconds);
+      if (note) controller.addNote(note);
+      return decoded;
+    },
+    audio: port,
+    scheduleWake: (fn) => {
+      const id = requestAnimationFrame(fn);
+      return () => cancelAnimationFrame(id);
+    },
+    onState: (state) => controller.handleState(state, show?.error ?? null),
+  });
+
+  try {
+    await show.ready();
+  } catch (error) {
+    if (show.state !== 'error') controller.fail(error);
+  }
+}
+
+/**
+ * Boot the shared page with one profile.
+ *
+ * @param {{
+ *   name: 'dev'|'release',
+ *   remedy?: string,
+ *   loadController: () => Promise<object>,
+ *   loadModules: () => Promise<object>,
+ *   configUrl: string|URL,
+ *   configManifestPath?: string|null,
+ *   manifestUrl?: string|URL|null,
+ *   assets: Array<{key: string, url: string|URL, kind: 'bytes'|'text'|'json', code?: string,
+ *     stage?: string, document?: string, manifestPath?: string|null}>,
+ *   loadScore: (options: {modules: object, assets: object, reflection: object}) => Promise<object>,
+ *   documents: {config: string, payload: string, runtimeModule: string, manifest: string},
+ * }} profile
+ */
+export async function boot(profile) {
+  activeProfile = profile;
+  let controllerModule;
+  try {
+    controllerModule = await profile.loadController();
+  } catch (error) {
+    fallbackFatal(error);
+    return;
+  }
+
+  const { createPlayerController } = controllerModule;
+  controller = createPlayerController({
+    actions,
+    view,
+    seconds: null,
+    fullscreenAvailable: Boolean(document.fullscreenEnabled),
+  });
+
+  // A rejecting action must be observable: route it through the page's
+  // runtime-failure surface and log it. Swallowing here (`catch(() => {})`)
+  // once left a failed Start looking inert for minutes with the reason lost.
+  const reportActionFailure = (label) => (error) => {
+    const failure = reportRuntimeFailure(error);
+    console.error(`animader: the ${label} action failed: ${failure.message}`);
+  };
+  primaryButton.addEventListener('click', () => {
+    Promise.resolve(controller.pressPrimary()).catch(reportActionFailure('primary'));
+  });
+  fullscreenButton.addEventListener('click', () => {
+    Promise.resolve(controller.pressFullscreen()).catch(reportActionFailure('fullscreen'));
+  });
+  document.addEventListener('keydown', (event) => {
+    controller.handleKey(event);
+  });
+  document.addEventListener('visibilitychange', () => {
+    void controller.setVisibility(document.hidden);
+  });
+  document.addEventListener('fullscreenchange', () => {
+    updateStageScale();
+    syncFullscreenLabel();
+    if (!document.fullscreenElement) controller.handleFullscreenExit();
+  });
+  window.addEventListener('resize', () => {
+    updateStageScale();
+    controller.handleResize();
+  });
+  if (typeof ResizeObserver !== 'undefined') {
+    const observer = new ResizeObserver(updateStageScale);
+    observer.observe(stage);
+  }
+  updateStageScale();
+  armDprWatcher();
+
+  try {
+    await load(controllerModule, profile);
+  } catch (error) {
+    reportRuntimeFailure(error);
+  }
+}
+
+/**
+ * The shared entry failure bridge: entries call this if boot itself rejects
+ * before it can own the controller.
+ */
+export function reportBootFailure(error) {
+  const failure = structuredFailure(error);
+  if (show && show.state !== 'error') show.fail(failure.code, failure.message, failure);
+  else if (controller) controller.fail(failure);
+  else fallbackFatal(failure);
+}