@docyrus/animaguru 0.19.0 → 0.22.0

package/templates/video/src/player.ts

@@ -5,9 +5,11 @@ import { publicAsset } from "./assets";
 import { downloadHtml, downloadUrl } from "./download";
 import { loadFonts } from "./kit/fonts";
 import type { ResourceTimeline } from "./resource-timeline";
+import { StoryMap, StoryOverlay, type StorySegment, type StoryView } from "./story";
+import { QuizOverlay, QuizRun, quizCopy } from "./quiz";
 import "./style.css";
 
-export async function mountPlayer({ config, Film, chapters, branding, exportEndpoint, templateLabel }: PlayerOptions) {
+export async function mountPlayer({ config, Film, chapters, branding, exportEndpoint, templateLabel, story: storyGraph, quiz: quizData }: PlayerOptions) {
   const root = document.querySelector<HTMLDivElement>("#app")!;
   // All variable copy is inserted as text, including agent-authored film titles.
   root.innerHTML = `<header class="masthead"><a class="brand" href="https://animaguru.com" target="_blank" rel="noreferrer"><img src="${publicAsset("brand/logo-mark.svg")}" alt=""/><strong>AnimaGuru</strong><span data-copy="studio"></span></a><span class="template" data-copy="template"></span></header>
@@ -31,6 +33,24 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
   const capture = params.has("capture");
   const exporting = !embed && params.has("export");
   const autoplay = embed && params.get("autoplay") === "1" && !matchMedia("(prefers-reduced-motion: reduce)").matches;
+  // A branching story plays one segment at a time and asks the viewer at its choices. Capture and review see its whole
+  // timeline as one film; an MP4 has one path, so a story never exports one.
+  let story: StoryMap | null = null;
+  // A quiz pauses the film at its checkpoints and follows its end with a final round and the score. Capture and review
+  // see the film without it; its questions wait for a viewer's answers, so a quiz never exports an MP4. visited: the story segments played since the last restart, whose questions count.
+  let quiz: QuizRun | null = null;
+  const visited = new Set<string>();
+  if (storyGraph || quizData) {
+    document.querySelector<HTMLElement>('[data-copy="exportHint"]')!.textContent = storyGraph ? copy.storyHint : copy.quizHint;
+    try {
+      if (exporting) throw new Error(storyGraph ? copy.storyNoMp4 : copy.quizNoMp4);
+      if (storyGraph && !capture && !params.has("review")) story = new StoryMap(storyGraph, config.duration);
+      if (quizData && !capture && !params.has("review")) quiz = new QuizRun(quizData, config.duration, story ? { segments: story.graph.segments, visited } : undefined);
+    } catch (error) {
+      status.textContent = error instanceof Error ? error.message : copy.failed; element("loading")?.remove(); console.error(error);
+      return;
+    }
+  }
   const loop = embed && params.get("loop") === "1";
   if (capture) document.body.classList.add("capture");
   if (embed) document.body.classList.add("embed");
@@ -53,6 +73,26 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
   type WebkitDocument = Document & { webkitFullscreenElement?: Element | null; webkitExitFullscreen?: () => void };
   type WebkitElement = HTMLElement & { webkitRequestFullscreen?: () => void };
   const fullscreenElement = () => document.fullscreenElement ?? (document as WebkitDocument).webkitFullscreenElement ?? null;
+  // The page's player fits the window (style.css). This measures the page above it and the controls under its picture,
+  // which change as the window resizes and the transport wraps. Full screen keeps the last measures for its way back; an
+  // embed or a capture fills its frame instead.
+  if (!embed && !capture) {
+    const main = theater.parentElement!, picture = element("canvas-host");
+    let frame = 0;
+    const measure = () => {
+      frame = 0;
+      if (fullscreenElement() || theater.classList.contains("expanded")) return;
+      const box = theater.getBoundingClientRect();
+      main.style.setProperty("--player-above", `${Math.round(box.top + scrollY)}px`);
+      main.style.setProperty("--player-controls", `${Math.ceil(box.height - picture.getBoundingClientRect().height)}px`);
+    };
+    main.style.setProperty("--film-aspect", `${config.width} / ${config.height}`);
+    main.classList.add("fit-window");
+    measure();
+    // A measure waits for the next frame, so the resize it causes is not reported as a loop.
+    const observer = new ResizeObserver(() => { frame ||= requestAnimationFrame(measure); });
+    for (const target of [theater, document.querySelector(".masthead")!]) observer.observe(target);
+  }
 
   async function start() {
     await document.fonts.ready;
@@ -71,6 +111,34 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     const initialMuted = autoplay || capture || exporting;
     if (audio) { audio.crossOrigin = "anonymous"; audio.src = publicAsset(String(config.audio)); audio.preload = "auto"; audio.muted = initialMuted; audio.addEventListener("error", audioFailure); }
     let time = Math.max(0, Math.min(Number(params.get("t")) || 0, config.duration));
+    // ?segment=ID starts a story at that segment; ?t= at that time of the timeline.
+    let segment: StorySegment | null = story ? story.graph.segments.find((item) => item.id === params.get("segment")) ?? (params.has("t") ? story.at(time) : story.first) : null;
+    if (segment && !params.has("t")) time = segment.start;
+    if (segment) visited.add(segment.id);
+    /** The choice taken while its segment still plays; the story follows it when the segment ends. */
+    let picked: number | null = null;
+    /** Seconds a timed choice has been on screen. */
+    let waited = 0;
+    /** The story is at an ending. */
+    let finished = false;
+    /** The segments the viewer chose at, for going back. */
+    const path: string[] = [];
+    /** A story's final quiz and score have shown at an ending in this playthrough. */
+    let quizEnded = false;
+    const overlay = story ? new StoryOverlay(element("canvas-host"), story.graph, {
+      theEnd: story.graph.ui?.theEnd ?? copy.storyEnd, playAgain: story.graph.ui?.playAgain ?? copy.storyPlayAgain,
+      back: story.graph.ui?.back ?? copy.storyBack, choose: story.graph.ui?.choose ?? copy.storyChoose,
+    }, branding, { choose, restart: () => { void restart(); }, back: () => { void back(); } }) : null;
+    const quizOverlay = quiz ? new QuizOverlay(element("canvas-host"), quiz.quiz, quizCopy(copy, quiz.quiz.ui), branding, {
+      pick, check: checkAnswer, next: () => { void nextQuestion(); }, watchAgain: () => { void watchAgain(); }, retake: retakeQuiz, finish: () => { void finishQuiz(); },
+    }) : null;
+    const span = () => segment ? { start: segment.start, end: segment.end } : { start: 0, end: config.duration };
+    const atEnd = () => time >= span().end - 0.0005;
+    const choosing = () => Boolean(story && segment?.choices && time >= story.choiceAt(segment) - 0.0005);
+    // A quiz card covers the story's panels until it closes.
+    const storyView = (): StoryView => !segment || quiz?.panel ? { kind: "none" }
+      : finished ? { kind: "ending", segment, canGoBack: path.length > 0 }
+      : choosing() ? { kind: "choices", segment, picked, remaining: segment.timeout ? 1 - waited / segment.timeout : null } : { kind: "none" };
     let playing = false;
     let muted = initialMuted;
     let last = performance.now();
@@ -78,32 +146,53 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     let playbackRequest = 0;
     let resources: ResourceTimeline | undefined;
     const update = () => {
-      playButton.textContent = playing ? copy.pause : time >= config.duration ? copy.replay : copy.play;
+      // A story's transport covers the segment playing, not the whole timeline of every path.
+      const { start: from, end: to } = span();
+      playButton.textContent = playing ? copy.pause : (segment ? finished : time >= config.duration) ? copy.replay : copy.play;
+      // A question showing holds the film: it continues once the viewer answers.
+      const asking = Boolean(quiz?.asking);
+      playButton.disabled = asking || Boolean(segment?.choices && !playing && atEnd() && picked === null);
+      timeline.disabled = asking;
       playButton.setAttribute("aria-label", playButton.textContent);
-      element("time").textContent = `${format(time)} / ${format(config.duration)}`;
-      timeline.value = String(time);
-      timeline.setAttribute("aria-valuetext", `${format(time)} / ${format(config.duration)}`);
+      element("time").textContent = `${format(time - from)} / ${format(to - from)}`;
+      timeline.max = String(to - from);
+      timeline.value = String(time - from);
+      timeline.setAttribute("aria-valuetext", `${format(time - from)} / ${format(to - from)}`);
       soundButton.textContent = !audio ? copy.noAudio : muted ? copy.unmute : copy.mute;
       soundButton.disabled = !audio;
       soundButton.setAttribute("aria-pressed", String(Boolean(audio) && !muted));
       captionsButton.setAttribute("aria-pressed", String(film.captions));
       resources?.update({ time, playing, captions: film.captions, muted });
+      overlay?.render(storyView());
+      if (quiz) quizOverlay?.render(quiz.view());
     };
     const render = (seconds: number) => {
+      // A story holding at a segment's end shows that segment's last frame, not the next segment's first.
+      const at = segment ? Math.min(seconds, segment.end - 0.001) : seconds;
       // Seeking and frame capture are serialized so decoded video frames cannot race.
-      renderQueue = renderQueue.then(() => film.render(seconds));
+      renderQueue = renderQueue.then(() => film.render(at));
       return renderQueue;
     };
     function pause() { playbackRequest++; playing = false; audio?.pause(); update(); }
     async function seek(seconds: number) {
       if (!Number.isFinite(seconds)) throw new Error("Seek time must be finite.");
       time = Math.max(0, Math.min(seconds, config.duration)); pause();
+      // A seek closes a quiz card unanswered; its checkpoint asks again when the film next reaches it.
+      quiz?.close();
+      // A seek stays in the story's segment while it can, up to its end; another time of the timeline enters its segment.
+      if (story && segment && !(time >= segment.start && time <= segment.end)) { segment = story.at(time); visited.add(segment.id); }
+      if (segment) { picked = null; waited = 0; finished = segment.ending !== undefined && atEnd(); }
       if (audio) audio.currentTime = time;
       await render(time); update();
     }
     async function play() {
-      if (exporting) return;
-      if (time >= config.duration) await seek(0);
+      if (exporting || quiz?.asking) return;
+      // Play over the score replays the film, or the story from its start.
+      quiz?.close();
+      if (segment) {
+        if (finished) { await restart(); return; }
+        if (segment.choices && picked === null && atEnd()) return;
+      } else if (time >= config.duration) await seek(0);
       const request = ++playbackRequest;
       if (audio) {
         audio.currentTime = time;
@@ -117,6 +206,82 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
       muted = value; audio.muted = muted; update();
     }
     function toggleSound() { setMuted(!muted); }
+    /** Plays a story segment from a time (its start by default); a choice shown at the segment's very end waits there. */
+    async function enter(target: StorySegment, at = target.start) {
+      segment = target; time = at; picked = null; waited = 0; finished = false; visited.add(target.id);
+      if (audio) audio.currentTime = time;
+      await render(time);
+      if (atEnd()) { pause(); return; }
+      if (playing) { last = performance.now(); update(); } else await play();
+    }
+    /** What a segment does at its end: continue, go where the viewer chose, wait for a choice, or end the story. */
+    async function arrive() {
+      if (!story || !segment) return;
+      if (segment.next) await enter(story.get(segment.next));
+      else if (segment.choices) {
+        if (picked !== null) await take(picked);
+        else { playbackRequest++; playing = false; audio?.pause(); }
+      } else {
+        finished = true; pause();
+        // A quiz's final round and score come before the story's ending card, once a playthrough.
+        if (quiz && !quizEnded) { quizEnded = true; if (quizEnd()) update(); }
+      }
+    }
+    function choose(index: number) {
+      if (!segment?.choices?.[index] || picked !== null || !choosing() || quiz?.panel) return;
+      picked = index;
+      // A choice made while the segment plays waits for its end, so the segment finishes as it was cut.
+      if (!playing || atEnd()) void take(index); else update();
+    }
+    async function take(index: number) {
+      path.push(segment!.id);
+      await enter(story!.get(segment!.choices![index].to));
+    }
+    async function restart() { path.length = 0; quiz?.reset(); visited.clear(); quizEnded = false; await enter(story!.first); }
+    /** Back to the last choice the viewer made, with its choices showing. */
+    async function back() {
+      const id = path.pop();
+      if (!id) { await restart(); return; }
+      const decision = story!.get(id);
+      await enter(decision, story!.choiceAt(decision));
+    }
+    /** A quiz event for a page hosting the film: each answer, and the score when the quiz is complete. */
+    const emit = (type: "answer" | "complete", detail: object | null) => window.dispatchEvent(new CustomEvent("animaguru:quiz", { detail: { type, ...detail } }));
+    function pick(index: number) {
+      if (!quiz?.pick(index)) return;
+      if (quiz.answered) emit("answer", quiz.lastAnswer);
+      update();
+    }
+    function checkAnswer() { if (quiz?.check()) { emit("answer", quiz.lastAnswer); update(); } }
+    /** The final quiz, or the score, at the film's end or a story's ending; false when the viewer met no question. */
+    function quizEnd() {
+      if (!quiz?.openEnd()) return false;
+      if (quiz.panel?.kind === "results") emit("complete", quiz.score());
+      return true;
+    }
+    /** After an answer: the next question, the score, or back to the film where the checkpoint paused it. */
+    async function nextQuestion() {
+      const step = quiz?.advance();
+      if (step === "results") emit("complete", quiz!.score());
+      update();
+      if (step !== "closed") return;
+      if (segment) { if (atEnd()) await arrive(); else await play(); }
+      else if (time >= config.duration - 0.0005) { if (quizEnd()) update(); }
+      else await play();
+    }
+    /** Back to the part a checkpoint covers, which asks again when the film reaches it. */
+    async function watchAgain() {
+      const panel = quiz?.panel;
+      if (panel?.kind !== "checkpoint") return;
+      quiz!.arm(panel.checkpoint);
+      await seek(quiz!.reviewTime(panel.checkpoint)); await play();
+    }
+    function retakeQuiz() { quiz?.retake(); update(); }
+    /** The score's last button: a story's ending card, or the film again from the start with every question fresh. */
+    async function finishQuiz() {
+      if (segment) { quiz?.close(); update(); return; }
+      quiz?.reset(); await seek(0); await play();
+    }
     function setCaptions(value: boolean) { film.captions = value; void render(time); update(); }
     const fullscreenButton = element<HTMLButtonElement>("fullscreen");
     function showFullscreen() {
@@ -141,8 +306,8 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     let resumeAfterScrub = false;
     async function scrub(seconds: number, done = true) {
       resumeAfterScrub ||= playing;
-      await seek(seconds);
-      if (done && resumeAfterScrub) { resumeAfterScrub = false; await play(); }
+      await seek(segment ? Math.max(segment.start, Math.min(segment.end, seconds)) : seconds);
+      if (done && resumeAfterScrub) { resumeAfterScrub = false; if (!finished) await play(); }
     }
     async function saveFrame() {
       pause(); await render(time);
@@ -211,11 +376,21 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
       app.canvas.addEventListener("dblclick", () => { void fullscreen(); });
     }
     element("save").addEventListener("click", () => { closeDownloads(true); void saveFrame(); });
-    timeline.addEventListener("input", () => { void scrub(Number(timeline.value), false); });
-    timeline.addEventListener("change", () => { void scrub(Number(timeline.value)); });
+    timeline.addEventListener("input", () => { void scrub(span().start + Number(timeline.value), false); });
+    timeline.addEventListener("change", () => { void scrub(span().start + Number(timeline.value)); });
     document.addEventListener("visibilitychange", () => { if (document.hidden && !exporting) pause(); });
     document.addEventListener("keydown", (event) => {
-      if (exporting || event.target instanceof HTMLElement && event.target.closest("button,input,a,summary,textarea,select,[contenteditable]")) return;
+      const target = event.target instanceof HTMLElement ? event.target : null;
+      if (exporting || target?.closest("input,textarea,select,[contenteditable]")) return;
+      // Number keys answer a question or pick a story's choice, also with focus on one of their buttons.
+      if (quiz?.asking && /^[1-6]$/.test(event.key)) { event.preventDefault(); pick(Number(event.key) - 1); return; }
+      if (segment && !quiz?.panel && /^[1-4]$/.test(event.key)) { choose(Number(event.key) - 1); return; }
+      if (target?.closest("button,a,summary")) return;
+      if (quiz?.asking) {
+        if (event.key === "Enter") { event.preventDefault(); if (quiz.answered) void nextQuestion(); else checkAnswer(); }
+        // The film waits for the answer: the play and seek keys do nothing.
+        if (["Space", "ArrowRight", "ArrowLeft"].includes(event.code)) { event.preventDefault(); return; }
+      }
       if (event.code === "Space") { event.preventDefault(); if (playing) pause(); else void play(); }
       if (event.code === "ArrowRight") { event.preventDefault(); void scrub(time + 5); }
       if (event.code === "ArrowLeft") { event.preventDefault(); void scrub(time - 5); }
@@ -227,11 +402,22 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     async function tick(now: number) {
       try {
         if (playing) {
-          time = Math.min(config.duration, audio && !audio.paused ? audio.currentTime : time + (now - last) / 1000);
-          await render(time);
-          if (time >= config.duration) { if (loop) { await seek(0); await play(); } else pause(); }
+          const end = span().end, from = time;
+          time = Math.min(end, audio && !audio.paused ? audio.currentTime : time + (now - last) / 1000);
+          // A checkpoint the film passes stops it on its own frame and asks.
+          const due = quiz?.due(from, time, segment ? span() : undefined);
+          if (due) { time = due.at; pause(); quiz!.open(due); await render(time); }
+          else {
+            await render(time);
+            if (time >= end) { if (segment) await arrive(); else if (quizEnd()) pause(); else if (loop) { await seek(0); await play(); } else pause(); }
+          }
           update();
         }
+        // A timed choice counts down while the film plays on and while it holds on the segment's last frame.
+        if (segment?.timeout !== undefined && picked === null && choosing() && (playing || atEnd()) && !quiz?.panel && !document.hidden) {
+          waited += (now - last) / 1000;
+          if (waited >= segment.timeout) choose(segment.default ?? 0); else if (!playing) update();
+        }
         last = now;
         requestAnimationFrame((next) => { void tick(next); });
       } catch (error) { pause(); status.textContent = copy.failed; console.error(error); }
@@ -241,8 +427,18 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     element("loading")?.remove();
     const api = {
       ready: true, width: config.width, height: config.height, duration: config.duration, fps: config.fps, language: config.language, languages: [{ code: config.language, name: config.language }], canvas: app.canvas,
-      get state() { return { time, playing, muted, captions: film.captions, audio: { configured: Boolean(audio), readyState: audio?.readyState ?? 0, error: audio?.error?.code ?? null } }; },
+      get state() {
+        return { time, playing, muted, captions: film.captions, audio: { configured: Boolean(audio), readyState: audio?.readyState ?? 0, error: audio?.error?.code ?? null },
+          // waiting: the segment has ended and only a choice continues the story, so play does nothing.
+          ...(segment ? { story: { segment: segment.id, start: segment.start, end: segment.end, choosing: choosing() && picked === null, waiting: Boolean(segment.choices && !playing && atEnd() && picked === null), ended: finished } } : {}),
+          // open: a quiz card shows; asking: it asks a question, so play and seeking wait for the answer.
+          ...(quiz ? { quiz: { open: Boolean(quiz.panel), asking: quiz.asking, card: quiz.panel?.kind ?? null, score: quiz.score() } } : {}) };
+      },
       resources: film.resources,
+      // A branching story: its graph, the path taken, and the viewer's actions.
+      ...(story ? { story: { graph: story.graph, get path() { return [...path]; }, choose, back, restart, async goTo(id: string) { path.length = 0; await enter(story!.get(id)); } } } : {}),
+      // A quiz: its questions, the viewer's actions on the card, and the score so far.
+      ...(quiz ? { quiz: { data: quiz.quiz, pick, check: checkAnswer, next: nextQuestion, retake: retakeQuiz, reset() { quiz!.reset(); update(); }, get score() { return quiz!.score(); } } } : {}),
       get texts() { return film.texts; },
       get cues() { return film.cues; },
       seek, play, pause, setMuted, setCaptions, saveFrame,

package/templates/video/src/quiz.ts

@@ -0,0 +1,315 @@
+import { checkpointSegment, QUIZ_UI_KEYS, validateQuiz, type Quiz, type QuizCheckpoint, type QuizQuestion, type QuizUiKey } from "../scripts/quiz.mjs";
+import type { StorySegment } from "./story";
+import type { Branding } from "./player-types";
+
+export type { Quiz, QuizCheckpoint, QuizQuestion };
+export type QuizCopy = Record<QuizUiKey, string>;
+type Answer = { chosen: number[]; correct: boolean };
+/** Where the quiz is: a checkpoint's question, the final quiz's question, or the score. */
+export type QuizPanel = { kind: "checkpoint"; checkpoint: QuizCheckpoint; index: number } | { kind: "final"; index: number } | { kind: "results" };
+export type QuizMark = "right" | "wrong" | "skipped";
+export type QuizScore = { correct: number; total: number; skipped: number; marks: QuizMark[]; pass: number | null; passed: boolean | null };
+/** What the card over the picture shows. */
+export type QuizView =
+  | { kind: "none" }
+  | { kind: "question"; key: string; title: string | undefined; final: boolean; number: number; count: number; question: QuizQuestion; selection: number[]; answer: Answer | null; watchAgain: boolean }
+  | { kind: "results"; score: QuizScore; retake: boolean; story: boolean };
+
+const EPSILON = 1e-6;
+const fill = (template: string, values: Record<string, string | number>) => template.replace(/\{(\w+)\}/g, (match, name: string) => name in values ? String(values[name]) : match);
+
+/** The cards' words: quiz.json's ui where it sets them, the player's (quizCheck, quizFinal…) otherwise. */
+export function quizCopy(defaults: Record<string, string>, ui: Quiz["ui"] = {}): QuizCopy {
+  return Object.fromEntries(QUIZ_UI_KEYS.map((key) => [key, ui[key] ?? defaults[`quiz${key[0].toUpperCase()}${key.slice(1)}`]])) as QuizCopy;
+}
+
+/**
+ * A viewer's way through the quiz: which checkpoint is due as the film plays, the question showing, the answers and
+ * the score. A checkpoint asks once; Watch again asks it again, and its new answers replace the old. The score covers
+ * the questions on the viewer's path: every checkpoint of a linear film, those of the story segments visited, then the
+ * final quiz once it is done.
+ */
+export class QuizRun {
+  panel: QuizPanel | null = null;
+  private readonly selection = new Set<number>();
+  private readonly answers = new Map<string, Answer>();
+  private readonly armed = new Set<string>();
+  private finalDone = false;
+  readonly checkpoints: QuizCheckpoint[];
+  private readonly segmentOf = new Map<string, StorySegment>();
+
+  constructor(readonly quiz: Quiz, duration: number, private readonly story?: { segments: StorySegment[]; visited: Set<string> }) {
+    validateQuiz(quiz, { duration }, story ? { segments: story.segments } : null);
+    this.checkpoints = quiz.checkpoints ?? [];
+    if (story) for (const checkpoint of this.checkpoints) this.segmentOf.set(checkpoint.id, checkpointSegment(checkpoint, story.segments)!);
+  }
+
+  /** Each question's id: its own, or its place ("orbit/1", "final/2"; ids cannot contain a slash). */
+  private keys(where: QuizCheckpoint | "final") {
+    const [name, questions] = where === "final" ? ["final", this.quiz.final?.questions ?? []] as const : [where.id, where.questions] as const;
+    return questions.map((question, index) => question.id ?? `${name}/${index + 1}`);
+  }
+  private get current() {
+    const panel = this.panel;
+    if (!panel || panel.kind === "results") return null;
+    const [questions, keys] = panel.kind === "final" ? [this.quiz.final!.questions, this.keys("final")] : [panel.checkpoint.questions, this.keys(panel.checkpoint)];
+    return { question: questions[panel.index], key: keys[panel.index], count: questions.length };
+  }
+  /** A question is showing: the film waits for its answer. */
+  get asking() { return this.current !== null; }
+  /** The question showing has its answer. */
+  get answered() { const current = this.current; return Boolean(current && this.answers.has(current.key)); }
+  /** The answer to the question showing, as the player's quiz events report it. */
+  get lastAnswer() {
+    const current = this.current; const answer = current && this.answers.get(current.key);
+    return current && answer ? { id: current.key, prompt: current.question.prompt, chosen: answer.chosen, correct: answer.correct } : null;
+  }
+
+  /** The checkpoint the film reaches playing from `from` to `to`, while it still has to ask; within a story segment's span. */
+  due(from: number, to: number, span?: { start: number; end: number }) {
+    return this.checkpoints.find((checkpoint) => checkpoint.at > from + EPSILON && checkpoint.at <= to + EPSILON
+      && (!span || (checkpoint.at > span.start + EPSILON && checkpoint.at <= span.end + EPSILON))
+      && (this.armed.has(checkpoint.id) || !this.keys(checkpoint).every((key) => this.answers.has(key)))) ?? null;
+  }
+  open(checkpoint: QuizCheckpoint) {
+    this.armed.delete(checkpoint.id);
+    for (const key of this.keys(checkpoint)) this.answers.delete(key);
+    this.show({ kind: "checkpoint", checkpoint, index: 0 });
+  }
+  /** At the film's end: the final quiz until it is done, then the score; false when no question was on the viewer's path. */
+  openEnd() {
+    if (this.quiz.final && !this.finalDone) {
+      for (const key of this.keys("final")) this.answers.delete(key);
+      this.show({ kind: "final", index: 0 });
+      return true;
+    }
+    if (!this.score().total) return false;
+    this.show({ kind: "results" });
+    return true;
+  }
+  /** Picks an option: answers a one-answer question at once, ticks or unticks one of a "select all that apply". */
+  pick(index: number) {
+    const current = this.current;
+    if (!current || this.answers.has(current.key) || !Number.isInteger(index) || index < 0 || index >= current.question.options.length) return false;
+    if (Array.isArray(current.question.answer)) { if (!this.selection.delete(index)) this.selection.add(index); }
+    else this.record([index]);
+    return true;
+  }
+  /** Answers a "select all that apply" with the options ticked. */
+  check() {
+    const current = this.current;
+    if (!current || !Array.isArray(current.question.answer) || this.answers.has(current.key) || !this.selection.size) return false;
+    this.record([...this.selection].sort((a, b) => a - b));
+    return true;
+  }
+  private record(chosen: number[]) {
+    const { question, key } = this.current!;
+    const right = Array.isArray(question.answer) ? question.answer : [question.answer];
+    this.answers.set(key, { chosen, correct: chosen.length === right.length && chosen.every((value, index) => value === right[index]) });
+  }
+  /** After an answer: the next question, the score after the final quiz's last, or closed after a checkpoint's last. */
+  advance(): "question" | "results" | "closed" | null {
+    const panel = this.panel; const current = this.current;
+    if (!panel || panel.kind === "results" || !current || !this.answers.has(current.key)) return null;
+    if (panel.index + 1 < current.count) { this.show({ ...panel, index: panel.index + 1 }); return "question"; }
+    if (panel.kind === "final") { this.finalDone = true; this.show({ kind: "results" }); return "results"; }
+    this.show(null);
+    return "closed";
+  }
+  /** Asks a checkpoint again the next time the film reaches it. */
+  arm(checkpoint: QuizCheckpoint) { this.armed.add(checkpoint.id); }
+  close() { this.show(null); }
+  retake() { if (!this.quiz.final) return; this.finalDone = false; this.openEnd(); }
+  /** Forgets every answer, for a fresh viewing. */
+  reset() { this.answers.clear(); this.armed.clear(); this.finalDone = false; this.show(null); }
+  private show(panel: QuizPanel | null) { this.panel = panel; this.selection.clear(); }
+
+  /** Where Watch again goes back to: the checkpoint's review, else the previous checkpoint (in its story segment) or the start. */
+  reviewTime(checkpoint: QuizCheckpoint) {
+    if (checkpoint.review !== undefined) return checkpoint.review;
+    const segment = this.segmentOf.get(checkpoint.id);
+    const earlier = this.checkpoints.filter((other) => other.at < checkpoint.at - EPSILON && (!segment || this.segmentOf.get(other.id) === segment));
+    return earlier.at(-1)?.at ?? segment?.start ?? 0;
+  }
+  score(): QuizScore {
+    const marks: QuizMark[] = [];
+    const mark = (key: string) => { const answer = this.answers.get(key); marks.push(!answer ? "skipped" : answer.correct ? "right" : "wrong"); };
+    for (const checkpoint of this.checkpoints) if (!this.story || this.story.visited.has(this.segmentOf.get(checkpoint.id)!.id)) this.keys(checkpoint).forEach(mark);
+    if (this.finalDone) this.keys("final").forEach(mark);
+    const correct = marks.filter((value) => value === "right").length;
+    const pass = this.quiz.final?.pass ?? null;
+    return { correct, total: marks.length, skipped: marks.filter((value) => value === "skipped").length, marks, pass, passed: pass === null || !marks.length ? null : correct * 100 >= pass * marks.length };
+  }
+  view(): QuizView {
+    const panel = this.panel; const current = this.current;
+    if (!panel) return { kind: "none" };
+    if (panel.kind === "results" || !current) return { kind: "results", score: this.score(), retake: Boolean(this.quiz.final), story: Boolean(this.story) };
+    return {
+      kind: "question", key: current.key, final: panel.kind === "final", title: panel.kind === "final" ? this.quiz.final!.title : panel.checkpoint.title,
+      number: panel.index + 1, count: current.count, question: current.question, selection: [...this.selection].sort((a, b) => a - b),
+      answer: this.answers.get(current.key) ?? null, watchAgain: panel.kind === "checkpoint",
+    };
+  }
+}
+
+const ICONS = { right: '<path d="M5 12.5l4.5 4.5L19 7.5"/>', wrong: '<path d="M6.5 6.5l11 11M17.5 6.5l-11 11"/>', skipped: '<path d="M6 12h12"/>' };
+function icon(kind: keyof typeof ICONS) {
+  const span = document.createElement("span");
+  span.className = "quiz-icon"; span.setAttribute("aria-hidden", "true");
+  span.innerHTML = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">${ICONS[kind]}</svg>`;
+  return span;
+}
+/** Black or white, whichever reads better on a color. */
+function readableOn(hex: string) {
+  const channel = (offset: number) => { const value = parseInt(hex.slice(offset, offset + 2), 16) / 255; return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4; };
+  const luminance = 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+  return luminance > 0.179 ? "#111418" : "#ffffff";
+}
+
+/**
+ * The question and score cards, centered over the dimmed picture. They are HTML buttons, so a viewer can tab to them,
+ * a screen reader reads them and a touch picks them; 1–6 on the keyboard pick too. A card is rebuilt only when its
+ * question or answer changes, so focus and hover survive every frame's update; ticks on a "select all" update in place.
+ */
+export class QuizOverlay {
+  readonly element = document.createElement("div");
+  private readonly live = document.createElement("p");
+  private shown = "";
+  private ticks = "";
+  private returnFocus: Element | null = null;
+
+  constructor(host: HTMLElement, quiz: Quiz, private readonly copy: QuizCopy, branding: Branding | undefined,
+    private readonly actions: { pick(index: number): void; check(): void; next(): void; watchAgain(): void; retake(): void; finish(): void }) {
+    this.element.className = "quiz-layer"; this.element.hidden = true;
+    const theme = quiz.theme ?? {};
+    const accent = theme.accent ?? branding?.colors.primary ?? "#2c6bd0";
+    const surface = theme.surface ?? "#fffdfa";
+    // The brand's text color suits the brand's background, not necessarily this card: the card picks its own.
+    this.element.style.setProperty("--quiz-accent", accent);
+    this.element.style.setProperty("--quiz-on-accent", readableOn(accent));
+    this.element.style.setProperty("--quiz-surface", surface);
+    this.element.style.setProperty("--quiz-text", theme.text ?? (readableOn(surface) === "#ffffff" ? "#f7f5ef" : "#16232a"));
+    if (branding) this.element.style.setProperty("--quiz-font", branding.fonts.heading.family);
+    this.live.className = "story-live"; this.live.setAttribute("role", "status");
+    host.append(this.element, this.live);
+  }
+
+  render(view: QuizView) {
+    const key = view.kind === "none" ? "none" : view.kind === "results" ? `results:${view.score.marks.join()}` : `question:${view.key}:${view.answer ? "answered" : ""}`;
+    if (key !== this.shown) {
+      const opening = this.shown === "" || this.shown === "none";
+      if (opening && view.kind !== "none") this.returnFocus = document.activeElement;
+      const hadFocus = this.element.contains(document.activeElement);
+      this.shown = key; this.build(view, opening);
+      if (view.kind === "none") {
+        // Focus that was on the card goes back where it was before the card opened.
+        if (hadFocus && this.returnFocus instanceof HTMLElement && this.returnFocus.isConnected) this.returnFocus.focus({ preventScroll: true });
+      } else {
+        const target = this.element.querySelector<HTMLElement>(view.kind === "question" && !view.answer ? ".quiz-option" : ".quiz-actions .quiz-primary");
+        target?.focus({ preventScroll: true });
+      }
+    }
+    if (view.kind === "question" && !view.answer && view.selection.join() !== this.ticks) this.tick(view.selection);
+  }
+
+  /** Shows the ticked options of a "select all" and enables Check answer once one is ticked. */
+  private tick(selection: number[]) {
+    this.ticks = selection.join();
+    for (const option of this.element.querySelectorAll<HTMLButtonElement>(".quiz-multi .quiz-option")) {
+      const on = selection.includes(Number(option.dataset.index));
+      option.classList.toggle("selected", on); option.setAttribute("aria-pressed", String(on));
+    }
+    const check = this.element.querySelector<HTMLButtonElement>(".quiz-check");
+    if (check) check.disabled = selection.length === 0;
+  }
+
+  /** opening: the card appears over the film, rather than changing to the next question or the score. */
+  private build(view: QuizView, opening: boolean) {
+    this.element.replaceChildren(); this.ticks = "";
+    this.element.dataset.view = view.kind; this.element.hidden = view.kind === "none";
+    if (view.kind === "none") return;
+    const { copy } = this;
+    const node = <K extends keyof HTMLElementTagNameMap>(tag: K, className: string, text?: string) => {
+      const element = document.createElement(tag); element.className = className;
+      if (text !== undefined) element.textContent = text;
+      return element;
+    };
+    const button = (label: string, action: () => void, className: string) => {
+      const element = node("button", className, label); element.type = "button";
+      // A click on the card is not a click on the picture, which would pause the film.
+      element.addEventListener("click", (event) => { event.stopPropagation(); action(); });
+      return element;
+    };
+    const card = node("div", `quiz-card${view.kind === "results" ? " quiz-results" : ""}${view.kind === "question" && view.answer ? " answered" : ""}${opening ? " quiz-card-in" : ""}`);
+    card.setAttribute("role", "dialog");
+    const actions = node("div", "quiz-actions");
+    if (view.kind === "question") {
+      const { question, answer } = view;
+      const multiple = Array.isArray(question.answer);
+      const right = Array.isArray(question.answer) ? question.answer : [question.answer];
+      const title = view.title ?? (view.final ? copy.final : copy.check);
+      const eyebrow = view.count > 1 ? `${title} · ${fill(copy.progress, { n: view.number, total: view.count })}` : title;
+      const prompt = node("h2", "quiz-prompt", question.prompt);
+      card.setAttribute("aria-label", `${eyebrow}: ${question.prompt}`);
+      card.append(node("p", "quiz-eyebrow", eyebrow), prompt);
+      if (multiple && !answer) card.append(node("p", "quiz-hint", copy.selectAll));
+      // Long options, and an odd number of them on a wide card, read best as a list; others sit in two columns.
+      const long = question.options.some((option) => option.length > 32);
+      const options = node("div", `quiz-options${multiple ? " quiz-multi" : ""}${long ? " quiz-long" : question.options.length % 2 ? " quiz-odd" : ""}`);
+      options.setAttribute("role", "group"); options.setAttribute("aria-label", question.prompt);
+      question.options.forEach((label, index) => {
+        const option = button("", () => this.actions.pick(index), "quiz-option");
+        option.dataset.index = String(index);
+        const isRight = right.includes(index), chosen = Boolean(answer?.chosen.includes(index));
+        const state = !answer ? null : isRight ? "right" : chosen ? "wrong" : null;
+        const key = node("span", "quiz-key");
+        if (state) key.append(icon(state)); else key.textContent = String(index + 1);
+        option.append(key, node("span", "quiz-option-text", label));
+        if (answer) {
+          option.disabled = true;
+          option.classList.add(state === "right" ? "correct" : state === "wrong" ? "wrong" : "dim");
+          if (isRight && !chosen) option.classList.add("missed");
+          if (multiple || chosen) option.setAttribute("aria-pressed", String(chosen));
+        } else if (multiple) option.setAttribute("aria-pressed", "false");
+        options.append(option);
+      });
+      card.append(options);
+      if (!answer) {
+        if (multiple) { const check = button(copy.checkAnswer, () => this.actions.check(), "quiz-primary quiz-check"); check.disabled = true; actions.append(check); }
+        this.live.textContent = `${eyebrow}. ${question.prompt} ${multiple ? `${copy.selectAll} ` : ""}${question.options.map((option, index) => `${index + 1}: ${option}.`).join(" ")}`;
+      } else {
+        const feedback = node("p", `quiz-feedback ${answer.correct ? "correct" : "wrong"}`);
+        feedback.append(node("strong", "", answer.correct ? copy.correct : copy.incorrect));
+        if (!answer.correct) feedback.append(" ", node("span", "quiz-answer", fill(copy.answer, { answer: right.map((index) => question.options[index]).join(", ") })));
+        if (question.explanation) feedback.append(" ", node("span", "", question.explanation));
+        card.append(feedback);
+        const last = view.number === view.count;
+        actions.append(button(last ? (view.final ? copy.seeResults : copy.continue) : copy.next, () => this.actions.next(), "quiz-primary"));
+        if (view.watchAgain && !answer.correct) actions.append(button(copy.watchAgain, () => this.actions.watchAgain(), "quiz-secondary"));
+        this.live.textContent = feedback.textContent ?? "";
+      }
+    } else {
+      const { score } = view;
+      const perfect = score.total > 0 && score.correct === score.total;
+      const heading = fill(copy.score, { correct: score.correct, total: score.total });
+      card.setAttribute("aria-label", `${copy.complete}: ${heading}`);
+      const total = node("p", "quiz-score");
+      total.append(node("strong", "", String(score.correct)), node("span", "", `/${score.total}`));
+      card.append(node("p", "quiz-eyebrow", copy.complete), total, node("h2", "quiz-prompt", heading));
+      const verdict = perfect ? copy.perfect : score.passed === null ? null : score.passed ? copy.passed : fill(copy.notPassed, { pass: score.pass ?? 0 });
+      if (verdict) card.append(node("p", `quiz-verdict${perfect || score.passed ? " passed" : ""}`, verdict));
+      const marks = node("ol", "quiz-marks"); marks.setAttribute("aria-hidden", "true");
+      for (const mark of score.marks) { const item = node("li", mark); item.append(icon(mark)); marks.append(item); }
+      card.append(marks);
+      if (score.skipped) card.append(node("p", "quiz-hint", fill(copy.skipped, { count: score.skipped })));
+      // A viewer who has not passed is offered the retake first; a story's score gives way to its ending.
+      const retakeFirst = view.retake && !perfect && score.passed !== true;
+      const finish = button(view.story ? copy.continue : copy.restart, () => this.actions.finish(), retakeFirst ? "quiz-secondary" : "quiz-primary");
+      const retake = view.retake ? button(copy.retake, () => this.actions.retake(), retakeFirst ? "quiz-primary" : "quiz-secondary") : null;
+      actions.append(...(retakeFirst && retake ? [retake, finish] : retake ? [finish, retake] : [finish]));
+      this.live.textContent = `${heading}${verdict ? ` ${verdict}` : ""}`;
+    }
+    if (actions.childElementCount) card.append(actions);
+    this.element.append(card);
+  }
+}