animader-cli 0.0.0-stage → 0.1.0

package/player/controller.mjs

@@ -0,0 +1,366 @@
+// The player's state-to-interface decisions, kept portable so the same
+// decisions are unit-tested without a browser. The actual show transport is
+// injected as commands; the browser surface is injected as a view. This module
+// owns no clock, no tick, no audio graph and no renderer call — it maps the
+// actual show state to labels, focus, keyboard intent and the display-change
+// policy, and never steps or forces the show.
+//
+// Ownership: UI state vocabulary, keyboard intent, focus handoff, notes/errors.
+
+const ACTIVE_STATES = new Set(['playing', 'paused', 'press-to-resume']);
+const SPACE_STATES = new Set(['ready', 'playing', 'paused', 'press-to-resume']);
+const RESTARTABLE_STATES = new Set(['ended', 'stopped']);
+
+/** A host length in the design's one-decimal form when it is a whole second. */
+export function formatSeconds(seconds) {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds)) return String(seconds);
+  return Number.isInteger(seconds) ? seconds.toFixed(1) : String(seconds);
+}
+
+/**
+ * The actual decoded soundtrack length measured against the host end. A long
+ * track is cut at the host end; a short one leaves silence. This is a decode
+ * measurement, never a claim that music was heard.
+ *
+ * @param {number} decodedSeconds
+ * @param {number} hostSeconds
+ * @returns {string|null}
+ */
+export function audioDurationNote(decodedSeconds, hostSeconds) {
+  if (typeof decodedSeconds !== 'number' || !Number.isFinite(decodedSeconds)
+    || typeof hostSeconds !== 'number' || !Number.isFinite(hostSeconds)) {
+    return null;
+  }
+  const difference = decodedSeconds - hostSeconds;
+  if (Math.abs(difference) <= 1e-3) return null;
+  const host = formatSeconds(hostSeconds);
+  if (difference > 0) {
+    return `decoded soundtrack is ${decodedSeconds.toFixed(3)} s; cut at the ${host} s host end`;
+  }
+  return `decoded soundtrack is ${decodedSeconds.toFixed(3)} s; silence follows to the ${host} s host end`;
+}
+
+function normalizeError(error) {
+  if (error && typeof error === 'object') {
+    const diagnostics = Array.isArray(error.diagnostics) ? error.diagnostics : [];
+    return {
+      code: typeof error.code === 'string' ? error.code : 'error',
+      message: typeof error.message === 'string' ? error.message : String(error),
+      stage: typeof error.stage === 'string' ? error.stage : '',
+      document: typeof error.document === 'string' ? error.document : '',
+      diagnostics,
+      cause: error.cause,
+    };
+  }
+  return { code: 'error', message: String(error), stage: '', document: '', diagnostics: [] };
+}
+
+function isTextEntry(target) {
+  if (!target) return false;
+  if (target.isContentEditable === true) return true;
+  const tag = typeof target.tagName === 'string' ? target.tagName.toLowerCase() : '';
+  return tag === 'input' || tag === 'textarea' || tag === 'select';
+}
+
+function controlKind(target) {
+  return target?.dataset?.playerControl
+    ?? target?.getAttribute?.('data-player-control')
+    ?? '';
+}
+
+function keepsNativeSpace(target) {
+  const tag = typeof target?.tagName === 'string' ? target.tagName.toLowerCase() : '';
+  return tag === 'summary' || tag === 'a';
+}
+
+/**
+ * @param {object} options
+ * @param {object} options.actions actual show commands: start, pause, resume,
+ *   stop, restart, fullscreen. Each may return a promise.
+ * @param {object} options.view browser surface: apply(ui), activeElement(),
+ *   focusPrimary(), focusSecondary(), focusError().
+ * @param {number|null} [options.seconds] the host show length from config.
+ * @param {boolean} [options.fullscreenAvailable]
+ */
+export function createPlayerController({ actions, view, seconds = null, fullscreenAvailable = true }) {
+  if (!actions || typeof actions !== 'object') throw new TypeError('createPlayerController needs actual show action commands');
+  if (!view || typeof view.apply !== 'function' || typeof view.activeElement !== 'function') {
+    throw new TypeError('createPlayerController needs a view with apply() and activeElement()');
+  }
+
+  let state = 'loading';
+  let loadingStep = 'preparing';
+  let currentSeconds = typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0 ? seconds : null;
+  let canFullscreen = Boolean(fullscreenAvailable);
+  let error = null;
+  let notes = [];
+  let displayChanged = false;
+  let visibilityHidden = false;
+  let hiddenPause = false;
+  let ui = null;
+
+  function errorView() {
+    if (!error) {
+      const diagnostics = notes.map((note) => `note: ${note}`);
+      return { errorVisible: false, errorText: '', diagnostics, diagnosticsOpen: diagnostics.length > 0 };
+    }
+    const diagnostics = [];
+    for (const note of notes) diagnostics.push(`note: ${note}`);
+    diagnostics.push(`error: ${error.message}`);
+    if (error.stage) diagnostics.push(`stage: ${error.stage}`);
+    if (error.document) diagnostics.push(`document: ${error.document}`);
+    for (const diagnostic of error.diagnostics) {
+      const message = typeof diagnostic === 'string' ? diagnostic : diagnostic?.message;
+      if (message) diagnostics.push(`error: ${message}`);
+    }
+    return { errorVisible: true, errorText: error.message, diagnostics, diagnosticsOpen: true };
+  }
+
+  function derive() {
+    let primary = null;
+    if (state === 'ready') primary = { label: 'Start', action: 'start' };
+    else if (state === 'playing') primary = { label: 'Stop', action: 'stop' };
+    else if (state === 'paused' || state === 'press-to-resume') primary = { label: 'Resume', action: 'resume' };
+    else if (state === 'ended' || state === 'stopped') primary = { label: 'Restart', action: 'restart' };
+
+    const secondary = state === 'ready' && canFullscreen
+      ? { label: 'Fullscreen', action: 'fullscreen' }
+      : null;
+
+    let status;
+    if (state === 'loading') status = `loading — ${loadingStep || 'preparing'}`;
+    else if (state === 'ready') {
+      status = notes.length === 0
+        ? 'ready — press Start'
+        : `ready — press Start; ${notes.join('; ')}`;
+    } else if (state === 'playing') status = 'playing';
+    else if (state === 'paused') status = 'paused — Space to resume';
+    else if (state === 'press-to-resume') status = 'playback paused — press to resume';
+    else if (state === 'ended') status = currentSeconds === null ? 'ended' : `ended — ${formatSeconds(currentSeconds)} s`;
+    else if (state === 'stopped') {
+      status = displayChanged ? 'display changed — press Restart' : 'stopped — press Restart';
+    } else {
+      status = `error — ${error?.stage || 'load'}`;
+    }
+
+    return {
+      state,
+      status,
+      primary,
+      secondary,
+      ...errorView(),
+    };
+  }
+
+  /**
+   * Apply one view model, then move focus only when the control that had it was
+   * replaced or removed. Reading activeElement before apply() is load-bearing:
+   * apply() has already hidden the old button by the time focus could move.
+   */
+  function commit(next) {
+    const activeBefore = view.activeElement();
+    const previousPrimary = ui?.primary?.label ?? null;
+    const hadSecondary = Boolean(ui?.secondary);
+    ui = next;
+    view.apply(next);
+
+    if (activeBefore === 'primary') {
+      if (next.primary && next.primary.label !== previousPrimary) view.focusPrimary();
+      else if (!next.primary && next.errorVisible) view.focusError();
+    } else if (activeBefore === 'fullscreen' && hadSecondary && !next.secondary) {
+      if (next.primary) view.focusPrimary();
+      else if (next.errorVisible) view.focusError();
+    }
+  }
+
+  function render() {
+    commit(derive());
+  }
+
+  function setLoading(step) {
+    if (state !== 'loading') return;
+    loadingStep = String(step);
+    render();
+  }
+
+  function setSeconds(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return;
+    currentSeconds = value;
+    render();
+  }
+
+  function setFullscreenAvailable(value) {
+    canFullscreen = Boolean(value);
+    render();
+  }
+
+  function addNote(note) {
+    const text = String(note ?? '').trim();
+    if (text === '' || notes.includes(text)) return;
+    notes.push(text);
+    render();
+  }
+
+  function fail(cause) {
+    error = normalizeError(cause);
+    state = 'error';
+    render();
+    return state;
+  }
+
+  function handleState(next, showError = null) {
+    state = next;
+    if (next === 'error') error = normalizeError(showError ?? error ?? { message: 'the show failed' });
+    else error = null;
+    if (next === 'ready' || next === 'ended') displayChanged = false;
+    render();
+    return state;
+  }
+
+  function pressPrimary() {
+    if (state === 'ready') return Promise.resolve(actions.start());
+    if (state === 'playing') return Promise.resolve(actions.stop());
+    if (state === 'paused' || state === 'press-to-resume') return Promise.resolve(actions.resume());
+    if (state === 'ended' || state === 'stopped') {
+      displayChanged = false;
+      return Promise.resolve(actions.restart());
+    }
+    return Promise.resolve(state);
+  }
+
+  async function pressFullscreen() {
+    if (state !== 'ready' || !canFullscreen) return false;
+    let accepted = false;
+    try {
+      accepted = (await actions.fullscreen()) === true;
+    } catch {
+      accepted = false;
+    }
+    if (!accepted) addNote('fullscreen unavailable — playing windowed');
+    return accepted;
+  }
+
+  function handleFullscreenExit() {
+    if (state === 'ready' && ui?.secondary) view.focusSecondary();
+    else if (ui?.primary) view.focusPrimary();
+    else if (ui?.errorVisible) view.focusError();
+  }
+
+  function spaceAction() {
+    if (state === 'ready') return actions.start();
+    if (state === 'playing') return actions.pause();
+    if (state === 'paused' || state === 'press-to-resume') return actions.resume();
+    return undefined;
+  }
+
+  /**
+   * Fire a command from a browser event and swallow its rejection here: the
+   * transport already moved to its structured error state, which the view
+   * renders. Synchronous action calls stay synchronous for tests.
+   */
+  function dispatch(command) {
+    try {
+      const result = command();
+      if (result && typeof result.catch === 'function') result.catch(() => {});
+      return result;
+    } catch {
+      return undefined;
+    }
+  }
+
+  function handleKey(event) {
+    if (!event || event.defaultPrevented) return false;
+    if (isTextEntry(event.target)) return false;
+    if (event.ctrlKey || event.metaKey || event.altKey) return false;
+
+    const key = event.key;
+    if (key === ' ' || key === 'Spacebar') {
+      // A focused secondary button or native disclosure keeps its Space
+      // activation. The primary's Space is the transport contract, so it is
+      // handled once here.
+      if (controlKind(event.target) === 'fullscreen' || keepsNativeSpace(event.target)) return false;
+      if (!SPACE_STATES.has(state)) return false;
+      event.preventDefault?.();
+      dispatch(spaceAction);
+      return true;
+    }
+
+    if (key === 'Escape' && ACTIVE_STATES.has(state)) {
+      event.preventDefault?.();
+      dispatch(() => actions.stop());
+      return true;
+    }
+
+    if ((key === 'r' || key === 'R') && RESTARTABLE_STATES.has(state)) {
+      event.preventDefault?.();
+      displayChanged = false;
+      dispatch(() => actions.restart());
+      return true;
+    }
+
+    return false;
+  }
+
+  function handleResize() {
+    if (displayChanged || !ACTIVE_STATES.has(state)) return false;
+    displayChanged = true;
+    dispatch(() => actions.stop());
+    return true;
+  }
+
+  async function setVisibility(hidden) {
+    visibilityHidden = Boolean(hidden);
+    if (visibilityHidden) {
+      if (state !== 'playing') return;
+      hiddenPause = true;
+      try {
+        await actions.pause();
+      } catch {
+        return;
+      }
+      // A visible event may have arrived while the suspend was pending. The
+      // frozen clock is the same clock; resuming here never rebases it.
+      if (!visibilityHidden && hiddenPause && state === 'paused') {
+        hiddenPause = false;
+        try {
+          await actions.resume();
+        } catch {
+          // A denied resume lands in the show's press-to-resume state.
+        }
+      }
+      return;
+    }
+
+    if (!hiddenPause) return;
+    if (state === 'playing') return; // the pending hide will resume after suspend settles
+    hiddenPause = false;
+    if (state === 'paused') {
+      try {
+        await actions.resume();
+      } catch {
+        // A denied resume lands in the show's press-to-resume state.
+      }
+    }
+  }
+
+  render();
+
+  return {
+    get state() { return state; },
+    get ui() { return ui; },
+    get notes() { return [...notes]; },
+    get error() { return error; },
+    setLoading,
+    setSeconds,
+    setFullscreenAvailable,
+    addNote,
+    fail,
+    handleState,
+    handleKey,
+    handleResize,
+    handleFullscreenExit,
+    pressPrimary,
+    pressFullscreen,
+    setVisibility,
+  };
+}

package/player/devchannel.mjs

@@ -0,0 +1,306 @@
+// The development-only channel client (plan section 5). It is imported by
+// the dev entry (page.mjs) alone; the release entry, its bundle and the
+// exported file set never reach this module.
+//
+// The protocol is deliberately small and honest: on a successful build the
+// server broadcasts `reload` with the URL of the new generation, and the
+// page does a full location.replace onto it — playback stops, the page
+// boots into READY and requires Start again. No state is preserved and no
+// hot reload is claimed or attempted. On a failed build the server
+// broadcasts `stale` with the build error: the page keeps the last
+// successful view and shows a clear indication; recovery is the next
+// successful edit's reload. A (re)connecting client is greeted with the
+// CURRENT generation, so a channel that reconnects after a reload lands on
+// whatever is served now.
+//
+// The client uses the browser's own EventSource reconnection; no timers,
+// no workers, no second clock.
+//
+// The stale indication itself is built here too: the console warning below
+// is for the person debugging in devtools, and `showStaleNotice` is for the
+// person looking at the page. It overlays the viewport top out of flow —
+// the stylesheet owns that contract (`#dev-stale` in player.css) — so it
+// can never reflow the page: an in-flow notice once pushed the primary
+// control below the fold on a 1280x800 laptop, exactly when the person
+// needed to press it. The notice is a native <details> collapsed at rest:
+// its summary carries the failure's lead line (the code plus the message's
+// own identifying token), the recovery sentence and a line that says the
+// full failure is one press away, so the reassurance is visible at rest
+// instead of below a scroll; below the covered range the summary swaps the
+// sentence for a compact phrase that shares its line with the affordance,
+// because the cap at 320px holds three lines and the lead alone takes two
+// (round 3, finding 2). The summary is reachable and operable by keyboard
+// alone on every engine without scripting, and it is the notice's FIRST
+// stop: the element that scrolls is the opened body (`.stale-body`,
+// overflow-y: auto in the stylesheet) and it is focusable by markup —
+// tabindex="0" with the house :focus-visible ring — so once the disclosure
+// is open the capped body is scrollable by keyboard (ArrowDown/PageDown)
+// and the tab order is summary → body → out. The notice element itself
+// never scrolls and never carries a tabindex: round 2 made the notice the
+// scroller, which measured (2026-10-29) as a tab stop BEFORE its own
+// summary while Tab forward from the summary left the notice — the two
+// stops and the dead end this round removes (round 3, finding 1). When the
+// opened body is taller than its box, the builder measures it and the
+// stylesheet pins a cue to the scroller's bottom edge, so an at-rest
+// partial line never reads as the end of the message (round 3, finding 3).
+// The stylesheet caps the notice's height at the canvas's central third —
+// geometry measured off the stage, not a viewport breakpoint — and scrolls
+// anything taller inside the body, so the delivered text is never
+// truncated or hidden: the expanded body carries the whole failure
+// verbatim. The element enters the DOM before #status as a live region,
+// and repeat deliveries update the one notice instead of stacking notices.
+// The expanded/collapsed state rides on the native pair: the engine tree
+// exposes the summary as a disclosure triangle with its expanded state on
+// exactly this markup, so the builder manages no ARIA of its own.
+
+/**
+ * @param {Object} options
+ * @param {number|null} options.generation the generation this page booted on
+ * @param {(error: {code?: string|null, message?: string, remedy?: string|null}) => void} [options.onStale]
+ *   the dev entry's stale-build indication; the last successful view stays
+ * @param {typeof EventSource} [options.eventSourceClass] injectable for tests
+ * @returns {{close(): void}}
+ */
+export function connectDevChannel({ generation, onStale = () => {}, eventSourceClass = globalThis.EventSource }) {
+  if (typeof eventSourceClass !== 'function') {
+    return { close() {} };
+  }
+
+  const events = new eventSourceClass('/dev');
+
+  events.addEventListener('reload', (event) => {
+    let detail = null;
+    try {
+      detail = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    if (detail && typeof detail.url === 'string' && detail.url.startsWith('/')) {
+      // Stop playback and reload onto the new generation: a fresh boot, a
+      // fresh READY, Start pressed again by the person editing.
+      window.location.replace(detail.url);
+    }
+  });
+
+  events.addEventListener('hello', (event) => {
+    let detail = null;
+    try {
+      detail = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    // A reconnected channel greets us with the current generation; if the
+    // server has moved on (including a restarted session), follow it.
+    if (detail
+      && detail.generation !== null
+      && detail.generation !== generation
+      && typeof detail.url === 'string'
+      && detail.url.startsWith('/')) {
+      window.location.replace(detail.url);
+    }
+  });
+
+  // A failed dev build must also reach the console — where a developer
+  // looks when the page is the thing that broke — exactly once per failed
+  // build, naming the code and the message. It is a warning, not an error:
+  // the page keeps working on the last successful generation. The key is
+  // the failure itself, so the channel redelivering the same failed build
+  // stays silent while a new build failing another way is reported. The
+  // release entry never imports this module, so a release page can neither
+  // receive a stale frame nor leave a console trace.
+  let warnedFailure = null;
+  events.addEventListener('stale', (event) => {
+    let detail = null;
+    try {
+      detail = JSON.parse(event.data);
+    } catch {
+      detail = null;
+    }
+    const error = detail?.error ?? { code: null, message: 'the last build failed; showing the last successful generation', remedy: null };
+    onStale(error);
+    const key = `${error.code ?? ''}\u0000${error.message ?? ''}`;
+    if (key !== warnedFailure) {
+      warnedFailure = key;
+      console.warn(`animader: the dev build failed (${error.code ?? 'unknown'}): ${error.message ?? ''}`);
+    }
+  });
+
+  return {
+    close() {
+      events.close();
+    },
+  };
+}
+
+// The recovery sentence is the channel's advice, never part of the build
+// error. A message that already spans lines gets the advice on its own
+// line, so the diagnosis cannot read as one run-on with the advice (the
+// collapsed `…host registry 1 error, 0 warnings — showing…`); a
+// single-line message keeps the inline em-dash join.
+const RECOVERY = 'showing the last successful generation; it recovers on the next successful edit';
+
+// The compact recovery phrase for very narrow viewports (round 3, finding
+// 2). Geometry, not taste: the collapsed summary's cap is a third of the
+// canvas, and at 320px that cap (70px) holds exactly three 14.4px lines
+// while the lead line alone — code plus token — takes two of them, so the
+// reassurance and the affordance must share the third. This phrase plus
+// `the full failure …` is 36 characters against the 38-character line the
+// guard's conservative model holds at 320px, so both fit on that one line;
+// the stylesheet swaps it in below 359px, the last uncovered pixel under
+// the range the full sentence is proven for. It keeps the sentence's first
+// half (what is showing: the last good view) and hands the "it recovers"
+// half to the opened body, which always carries the full sentence.
+const RECOVERY_COMPACT = 'last good view;';
+
+// The identifying name: the message's own backquoted token with at most the
+// ONE word that introduces it ("target `x`"). The collapsed summary paints
+// the lead first and the person at rest reads it before anything else, so
+// the notice must open by naming what failed — derived from whatever
+// message arrives, never written for one build error. The word budget is
+// geometry, not taste: the lead must stay one line at 360px, where the
+// stylesheet's cap is 77.5px and the modelled line holds ~44 characters.
+// With up to three introducing words the measured lead was 48 characters —
+// two lines at phone width — which is exactly what pushed the collapsed
+// notice over its cap at 390px and below (round 2, finding 3); the dropped
+// words stay in the expanded body verbatim.
+const NAMED_FAILURE = /(?:[A-Za-z][\w-]*[ \t]+)?`[^`\n]+`/;
+
+function leadLine(error) {
+  const named = typeof error?.message === 'string' ? error.message.match(NAMED_FAILURE)?.[0] ?? null : null;
+  if (named === null) return null;
+  return error?.code ? `${error.code} — ${named}` : named;
+}
+
+/**
+ * The text one stale notice carries: a derived lead line — the code plus
+ * the message's identifying token — when the message names one, then the
+ * full failure, then the recovery sentence, inline after a single-line
+ * message and on its own line once the message already spans lines. The
+ * code is named exactly once: with a lead line the diagnosis follows
+ * unprefixed, without one the code prefixes the message as before.
+ *
+ * @param {{code?: string|null, message?: string, remedy?: string|null}} error
+ *   the failed build, as the stale frame carried it
+ * @returns {string} the notice's whole text
+ */
+function staleNoticeText(error) {
+  const message = error?.message ?? 'the last build failed';
+  const lead = leadLine(error);
+  const prefix = lead === null && error?.code ? `${error.code}: ` : '';
+  const separator = message.includes('\n') ? '\n— ' : ' — ';
+  const body = `${prefix}${message}${separator}${RECOVERY}`;
+  return lead === null ? body : `${lead}\n${body}`;
+}
+
+/**
+ * The notice's collapsed lead: the derived lead line when the message names
+ * a token, else the failure's code, else the fallback's own opening. Always
+ * short — the summary must stay inside the stylesheet's geometric cap at
+ * rest — while the full, untruncated failure stays one press away in the
+ * body.
+ *
+ * @param {{code?: string|null, message?: string, remedy?: string|null}} error
+ *   the failed build, as the stale frame carried it
+ * @returns {string} the summary's first line
+ */
+function summaryLead(error) {
+  const named = leadLine(error);
+  if (named !== null) return named;
+  return error?.code ?? 'the last build failed';
+}
+
+// The summary's second, third and fourth lines: the recovery guidance,
+// visible at rest (the review found it buried below the old cap's scroll),
+// the compact phrase that replaces it below the covered range, and the
+// affordance that says more text exists and opens it. Native <details>
+// semantics make the whole summary the control: keyboard-operable on every
+// engine, with no scripting and no tabindex of its own — the opened body
+// (the scroller) is the element that carries the markup tab stop, after
+// the summary in reading order.
+const AFFORDANCE = 'the full failure …';
+
+// Round 3, finding 3: the body is the scroller, and a scroller at rest
+// shows a partial last line. When the opened body is taller than its box,
+// it wears the class the stylesheet's sticky cue rides on. Measuring is
+// layout, so it only runs where the element has boxes — a real DOM after
+// insertion — and it runs twice per lifecycle: on every delivery, and on
+// the disclosure's own toggle event, because deliveries arrive while the
+// notice is closed, when the body has no boxes and nothing to measure.
+// A closed body has no client box (clientHeight 0) while its content still
+// reports a scrollHeight, so the closed state must read as "no cue", never
+// as "overflowing". No timers, no observers: the two moments the cue can
+// change are exactly the two moments the text or the state changes.
+function cueBeyond(body) {
+  if (typeof body.scrollHeight !== 'number' || typeof body.clientHeight !== 'number') return;
+  const beyond = body.clientHeight > 0 && body.scrollHeight - body.clientHeight > 1;
+  if (typeof body.classList?.toggle === 'function') body.classList.toggle('scrolls-more', beyond);
+}
+
+/**
+ * The page-side stale indication: the notice the person looking at the page
+ * reads when the last dev build failed. Created once, then updated in place
+ * by every delivery. The element is created unstyled — `#dev-stale` in
+ * player.css owns the out-of-flow layout contract — and nothing here may
+ * reintroduce flow layout or a style attribute, so the notice can never
+ * move the controls. It is a native <details> collapsed at rest: the
+ * summary carries the derived lead line, the recovery sentence (the
+ * compact phrase below the covered range) and the affordance as block
+ * lines, so at rest a person identifies the failure, knows the last good
+ * generation is showing and knows how to open the rest. The expanded body
+ * carries `staleNoticeText` — the lead, the code-less message and the full
+ * recovery sentence, wrapping rather than truncating — and it is the
+ * scroller: the cap's pressure lands on it (the engine's ::details-content
+ * row carries min-height: 0 and the body fills it under max-height: 100%),
+ * it is focusable by markup with the house ring, and when it overflows it
+ * wears the cue class, so the cap never trims the delivered text and a
+ * partial line never reads as the end.
+ *
+ * @param {Document} document the page document
+ * @param {{code?: string|null, message?: string, remedy?: string|null}} error
+ *   the failed build, as the stale frame carried it
+ */
+export function showStaleNotice(document, error) {
+  let banner = document.getElementById('dev-stale');
+  if (banner === null) {
+    banner = document.createElement('details');
+    banner.id = 'dev-stale';
+    banner.setAttribute('role', 'status');
+    // The notice element itself carries NO tabindex and never scrolls: the
+    // element that scrolls is the opened body (overflow-y: auto on
+    // .stale-body), and that body is the focusable one — tabindex as
+    // markup, so ArrowDown/PageDown move the capped text on every engine,
+    // as the second stop, after the summary, in reading order. Round 2
+    // had put the tabindex and the scrolling on the notice itself, which
+    // measured (2026-10-29) as a tab stop BEFORE its own summary, while
+    // Tab forward from the summary left the notice with the body
+    // unreachable but by Shift+Tab — the round-3 finding 1 defect. The
+    // closed disclosure does not render the body, so it is not a stop
+    // until it can be read. Nothing here moves focus: the attribute is
+    // the whole mechanism.
+    const summary = document.createElement('summary');
+    for (const className of ['stale-lead', 'stale-recovery', 'stale-recovery-compact', 'stale-more']) {
+      const line = document.createElement('span');
+      line.className = className;
+      summary.appendChild(line);
+    }
+    banner.appendChild(summary);
+    const body = document.createElement('p');
+    body.className = 'stale-body';
+    body.setAttribute('tabindex', '0');
+    banner.appendChild(body);
+    const status = document.getElementById('status');
+    status?.parentNode?.insertBefore(banner, status);
+    // The cue must appear when the disclosure opens, not only when a
+    // delivery happens to arrive while it is open: the native toggle event
+    // is the moment the body gains boxes and can be measured.
+    banner.addEventListener?.('toggle', () => cueBeyond(body));
+  }
+  const [summary, body] = banner.children;
+  const [lead, recovery, compact, more] = summary.children;
+  lead.textContent = summaryLead(error);
+  recovery.textContent = `— ${RECOVERY}`;
+  compact.textContent = `— ${RECOVERY_COMPACT} `;
+  more.textContent = AFFORDANCE;
+  body.textContent = staleNoticeText(error);
+  cueBeyond(body);
+}