@docyrus/animaguru 0.19.0 → 0.20.0

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);
+  }
+}

package/templates/video/src/story.ts

@@ -0,0 +1,112 @@
+import { validateStory, type StoryGraph, type StorySegment } from "../scripts/story.mjs";
+import type { Branding } from "./player-types";
+
+export type { StoryGraph, StorySegment };
+export type StoryCopy = { theEnd: string; playAgain: string; back: string; choose: string };
+/** What the panel over the picture shows: nothing, the segment's choices, or its ending. */
+export type StoryView =
+  | { kind: "none" }
+  | { kind: "choices"; segment: StorySegment; picked: number | null; remaining: number | null }
+  | { kind: "ending"; segment: StorySegment; canGoBack: boolean };
+
+/** The story's segments by id and by time; the graph is checked once, against the film's duration. */
+export class StoryMap {
+  private readonly byId: Map<string, StorySegment>;
+  private readonly ordered: StorySegment[];
+  constructor(readonly graph: StoryGraph, duration: number) {
+    validateStory(graph, { duration });
+    this.byId = new Map(graph.segments.map((segment) => [segment.id, segment]));
+    this.ordered = [...graph.segments].sort((a, b) => a.start - b.start);
+  }
+  get first() { return this.get(this.graph.start); }
+  get(id: string) {
+    const segment = this.byId.get(id);
+    if (!segment) throw new Error(`The story has no segment ${id}.`);
+    return segment;
+  }
+  /** The segment playing at a time of the film's timeline; a boundary belongs to the segment that starts there. */
+  at(time: number) {
+    let found = this.ordered[0];
+    for (const segment of this.ordered) if (segment.start <= time + 1e-6) found = segment;
+    return found;
+  }
+  /** When a segment's choices appear. */
+  choiceAt(segment: StorySegment) { return segment.choiceAt ?? segment.end; }
+}
+
+/**
+ * The choice and ending panels over the picture. They are HTML buttons, so a viewer can tab to them, a screen reader
+ * reads them and a touch picks them; 1–4 on the keyboard choose too. The panels are rebuilt only when what they show
+ * changes, so focus and hover survive every frame's update.
+ */
+export class StoryOverlay {
+  readonly element = document.createElement("div");
+  private readonly live = document.createElement("p");
+  private shown = "";
+  private timer: HTMLElement | null = null;
+
+  constructor(host: HTMLElement, graph: StoryGraph, private readonly copy: StoryCopy, branding: Branding | undefined,
+    private readonly actions: { choose(index: number): void; restart(): void; back(): void }) {
+    this.element.className = "story-layer";
+    const theme = graph.theme ?? {};
+    this.element.style.setProperty("--story-accent", theme.accent ?? branding?.colors.primary ?? "#2c6bd0");
+    this.element.style.setProperty("--story-surface", theme.surface ?? "#fffdfa");
+    this.element.style.setProperty("--story-text", theme.text ?? branding?.colors.text ?? "#16232a");
+    if (branding) this.element.style.setProperty("--story-font", branding.fonts.heading.family);
+    this.live.className = "story-live"; this.live.setAttribute("role", "status");
+    host.append(this.element, this.live);
+  }
+
+  render(view: StoryView) {
+    const key = view.kind === "none" ? "none" : `${view.kind}:${view.segment.id}:${view.kind === "choices" ? view.picked : view.canGoBack}`;
+    if (key !== this.shown) { this.shown = key; this.build(view); }
+    if (view.kind === "choices" && this.timer) this.timer.style.transform = `scaleX(${Math.max(0, view.remaining ?? 0)})`;
+  }
+
+  private build(view: StoryView) {
+    this.element.replaceChildren(); this.timer = null;
+    this.element.dataset.view = view.kind;
+    if (view.kind === "none") return;
+    const panel = document.createElement("div");
+    panel.className = `story-panel story-panel-${view.kind}`;
+    const button = (label: string, action: () => void, className = "") => {
+      const element = document.createElement("button");
+      element.type = "button"; element.className = className; element.textContent = label;
+      // A click on a choice is not a click on the picture, which would pause the film.
+      element.addEventListener("click", (event) => { event.stopPropagation(); action(); });
+      return element;
+    };
+    if (view.kind === "choices") {
+      const { segment, picked } = view;
+      panel.setAttribute("role", "group");
+      const prompt = segment.prompt ?? this.copy.choose;
+      panel.setAttribute("aria-label", prompt);
+      if (segment.prompt) {
+        const heading = document.createElement("p"); heading.className = "story-prompt"; heading.textContent = segment.prompt;
+        panel.append(heading);
+      }
+      if (segment.timeout !== undefined && picked === null) {
+        const track = document.createElement("div"); track.className = "story-timer"; track.setAttribute("aria-hidden", "true");
+        this.timer = document.createElement("span"); track.append(this.timer); panel.append(track);
+      }
+      const choices = document.createElement("div"); choices.className = "story-choices";
+      segment.choices!.forEach((choice, index) => {
+        const element = button(choice.label, () => this.actions.choose(index), picked === index ? "picked" : "");
+        element.dataset.key = String(index + 1);
+        if (picked !== null) { element.disabled = picked !== index; element.setAttribute("aria-pressed", String(picked === index)); }
+        choices.append(element);
+      });
+      panel.append(choices);
+      this.live.textContent = picked === null ? `${prompt} ${segment.choices!.map((choice, index) => `${index + 1}: ${choice.label}.`).join(" ")}` : segment.choices![picked].label;
+    } else {
+      const eyebrow = document.createElement("p"); eyebrow.className = "story-eyebrow"; eyebrow.textContent = this.copy.theEnd;
+      const title = document.createElement("h2"); title.className = "story-title"; title.textContent = view.segment.ending!;
+      const actions = document.createElement("div"); actions.className = "story-choices";
+      actions.append(button(this.copy.playAgain, this.actions.restart, "picked"));
+      if (view.canGoBack) actions.append(button(this.copy.back, this.actions.back));
+      panel.append(eyebrow, title, actions);
+      this.live.textContent = `${this.copy.theEnd}: ${view.segment.ending}`;
+    }
+    this.element.append(panel);
+  }
+}

package/templates/video/src/style.css

@@ -117,3 +117,90 @@ body:not(.capture) #canvas-host canvas { cursor: pointer; }
 
 #audio-status { margin: 0; padding: 9px 16px; font-size: 12px; color: #8b2f25; background: #fff1eb; }
 .capture #audio-status { display: none; }
+
+/* A branching story's choice and ending panels, over the picture. Sizes follow the player's width (cqi), so the panels
+   keep their proportions from a phone to full screen; the minimums keep text readable and buttons easy to tap. */
+#canvas-host { container-type: inline-size; }
+.story-layer { position: absolute; inset: 0; z-index: 2; display: flex; align-items: flex-end; justify-content: center; pointer-events: none; font-family: var(--story-font, inherit); }
+.story-layer[data-view="choices"] { background: linear-gradient(to top, rgb(8 12 11 / .66), rgb(8 12 11 / 0) 52%); }
+.story-layer[data-view="ending"] { align-items: center; background: rgb(8 12 11 / .62); pointer-events: auto; }
+.story-panel { pointer-events: auto; width: min(94%, 70cqi); padding: 0 0 4.5cqi; display: grid; justify-items: center; gap: 1.5cqi; text-align: center; animation: story-in .35s ease-out both; }
+.story-panel-ending { padding: 0; }
+.story-prompt { margin: 0; color: #fff; font-size: clamp(15px, 2.6cqi, 42px); font-weight: 700; line-height: 1.15; text-shadow: 0 2px 14px rgb(0 0 0 / .5); }
+.story-timer { width: min(100%, 34cqi); height: max(3px, .35cqi); border-radius: 9px; background: rgb(255 255 255 / .3); overflow: hidden; }
+.story-timer span { display: block; height: 100%; background: var(--story-accent); transform-origin: left; }
+.story-choices { display: flex; flex-wrap: wrap; justify-content: center; gap: max(8px, 1.2cqi); width: 100%; }
+.story-choices button { display: flex; align-items: center; justify-content: center; gap: .7em; flex: 1 1 0; min-width: min(100%, 18cqi); max-width: 33cqi; min-height: 44px; padding: 1.1cqi 2.2cqi; border: 2px solid transparent; border-radius: 999px; background: var(--story-surface); color: var(--story-text); font: inherit; font-size: clamp(13px, 1.8cqi, 30px); font-weight: 700; line-height: 1.2; box-shadow: 0 10px 30px -12px rgb(0 0 0 / .65); transition: transform .15s, border-color .15s; }
+.story-choices button::before { content: attr(data-key); display: grid; place-items: center; flex: none; width: 1.6em; height: 1.6em; border-radius: 50%; background: color-mix(in srgb, var(--story-accent) 16%, transparent); color: var(--story-accent); font-size: .72em; }
+.story-panel-ending .story-choices button::before { content: none; }
+.story-choices button:hover:enabled, .story-choices button:focus-visible { transform: translateY(-2px); border-color: var(--story-accent); }
+/* A picked choice keeps the story's text color on a tint of the accent, readable whatever the accent is. */
+.story-choices button.picked { border-color: var(--story-accent); background: color-mix(in srgb, var(--story-accent) 24%, var(--story-surface)); }
+.story-choices button.picked::before { background: var(--story-accent); color: var(--story-surface); }
+.story-eyebrow { margin: 0; color: rgb(255 255 255 / .78); font-size: clamp(11px, 1.3cqi, 20px); font-weight: 700; letter-spacing: .22em; text-transform: uppercase; }
+.story-title { margin: 0 0 1cqi; color: #fff; font-size: clamp(22px, 4.8cqi, 78px); line-height: 1.05; text-wrap: balance; }
+.story-live { position: absolute; width: 1px; height: 1px; margin: 0; overflow: hidden; clip-path: inset(50%); }
+@keyframes story-in { from { opacity: 0; transform: translateY(12px); } }
+@container (max-width: 560px) { .story-panel { width: 96%; padding-bottom: 10px; gap: 8px; } .story-choices button { max-width: none; } }
+@media (prefers-reduced-motion: reduce) { .story-panel { animation: none; } .story-choices button { transition: none; } }
+.capture .story-layer { display: none; }
+/* A quiz's question and score cards, centered over the dimmed picture. Sizes follow the player's width (cqi) like the
+   story panels; a card taller than a small player scrolls inside it. Right and wrong carry an icon as well as a color. */
+.quiz-layer { --quiz-right: #1d8a4e; --quiz-wrong: #c8412f; position: absolute; inset: 0; z-index: 3; display: grid; overflow-y: auto; overscroll-behavior: contain; padding: clamp(8px, 2.4cqi, 40px); box-sizing: border-box; background: rgb(8 12 11 / .6); font-family: var(--quiz-font, inherit); }
+.quiz-layer[hidden] { display: none; }
+.quiz-card { margin: auto; width: min(100%, 64cqi); box-sizing: border-box; display: grid; gap: clamp(8px, 1.25cqi, 22px); padding: clamp(14px, 2.7cqi, 48px); border-radius: clamp(14px, 1.7cqi, 30px); background: var(--quiz-surface); color: var(--quiz-text); box-shadow: 0 30px 80px -30px rgb(0 0 0 / .75); }
+.quiz-card-in { animation: quiz-in .3s ease-out both; }
+.quiz-eyebrow { margin: 0; color: color-mix(in srgb, var(--quiz-accent) 72%, var(--quiz-text)); font-size: clamp(11px, 1.15cqi, 19px); font-weight: 800; letter-spacing: .14em; text-transform: uppercase; }
+.quiz-prompt { margin: 0; font-size: clamp(16px, 2.45cqi, 42px); font-weight: 800; line-height: 1.18; text-wrap: balance; }
+.quiz-hint { margin: -.2em 0 0; font-size: clamp(12px, 1.3cqi, 21px); opacity: .72; }
+.quiz-options { display: grid; grid-template-columns: 1fr 1fr; gap: clamp(6px, .95cqi, 16px); }
+.quiz-options.quiz-long, .quiz-options.quiz-odd { grid-template-columns: 1fr; }
+.quiz-option { display: flex; align-items: center; gap: .7em; min-height: 44px; padding: clamp(8px, 1cqi, 18px) clamp(10px, 1.35cqi, 24px); border: 2px solid color-mix(in srgb, var(--quiz-text) 14%, transparent); border-radius: clamp(10px, 1.1cqi, 18px); background: color-mix(in srgb, var(--quiz-text) 3%, var(--quiz-surface)); color: inherit; font: inherit; font-size: clamp(13px, 1.6cqi, 28px); font-weight: 650; line-height: 1.25; text-align: left; cursor: pointer; transition: border-color .15s, background-color .15s, transform .15s; }
+.quiz-option:hover:enabled, .quiz-option:focus-visible { border-color: var(--quiz-accent); transform: translateY(-1px); }
+.quiz-option:focus-visible, .quiz-actions button:focus-visible { outline: 3px solid color-mix(in srgb, var(--quiz-accent) 50%, transparent); outline-offset: 2px; }
+.quiz-option:disabled { cursor: default; opacity: 1; }
+.quiz-key { flex: none; display: grid; place-items: center; width: 1.75em; height: 1.75em; border-radius: 50%; background: color-mix(in srgb, var(--quiz-accent) 18%, transparent); color: color-mix(in srgb, var(--quiz-accent) 62%, var(--quiz-text)); font-size: .78em; font-weight: 800; }
+.quiz-multi .quiz-key { border-radius: 28%; }
+.quiz-option-text { flex: 1; min-width: 0; }
+.quiz-option.selected { border-color: var(--quiz-accent); background: color-mix(in srgb, var(--quiz-accent) 15%, var(--quiz-surface)); }
+.quiz-option.selected .quiz-key { background: var(--quiz-accent); color: var(--quiz-on-accent); }
+.quiz-option.correct { border-color: var(--quiz-right); background: color-mix(in srgb, var(--quiz-right) 13%, var(--quiz-surface)); }
+.quiz-option.wrong { border-color: var(--quiz-wrong); background: color-mix(in srgb, var(--quiz-wrong) 11%, var(--quiz-surface)); }
+.quiz-option.missed { border-style: dashed; }
+.quiz-option.correct .quiz-key { background: var(--quiz-right); color: #fff; }
+.quiz-option.wrong .quiz-key { background: var(--quiz-wrong); color: #fff; }
+.quiz-option.dim { opacity: .5; }
+.quiz-icon { display: grid; place-items: center; width: 100%; height: 100%; }
+.quiz-icon svg { width: 62%; height: 62%; }
+.quiz-feedback { margin: 0; padding: clamp(8px, 1.05cqi, 18px) clamp(10px, 1.35cqi, 22px); border-left: 4px solid var(--quiz-right); border-radius: clamp(8px, .9cqi, 14px); background: color-mix(in srgb, var(--quiz-right) 11%, var(--quiz-surface)); font-size: clamp(13px, 1.45cqi, 25px); line-height: 1.42; }
+.quiz-feedback.wrong { border-left-color: var(--quiz-wrong); background: color-mix(in srgb, var(--quiz-wrong) 9%, var(--quiz-surface)); }
+.quiz-answer { font-weight: 700; }
+.quiz-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: clamp(6px, 1cqi, 14px); }
+.quiz-actions button { min-height: 44px; padding: 0 clamp(14px, 2cqi, 34px); border-radius: 999px; font: inherit; font-size: clamp(13px, 1.45cqi, 25px); font-weight: 750; cursor: pointer; transition: transform .15s, filter .15s; }
+.quiz-actions button:hover:enabled { transform: translateY(-1px); filter: brightness(1.06); }
+.quiz-actions button:disabled { opacity: .45; cursor: default; }
+.quiz-primary { border: 2px solid var(--quiz-accent); background: var(--quiz-accent); color: var(--quiz-on-accent); }
+.quiz-secondary { border: 2px solid color-mix(in srgb, var(--quiz-text) 24%, transparent); background: transparent; color: inherit; }
+.quiz-results { justify-items: center; text-align: center; }
+.quiz-results .quiz-actions { justify-content: center; }
+.quiz-score { margin: 0; color: color-mix(in srgb, var(--quiz-accent) 75%, var(--quiz-text)); font-size: clamp(38px, 7cqi, 124px); font-weight: 900; line-height: 1; }
+.quiz-score span { font-size: .42em; opacity: .62; }
+.quiz-verdict { margin: 0; font-size: clamp(13px, 1.6cqi, 27px); font-weight: 750; }
+.quiz-verdict.passed { color: color-mix(in srgb, var(--quiz-right) 80%, var(--quiz-text)); }
+.quiz-marks { display: flex; flex-wrap: wrap; justify-content: center; gap: clamp(4px, .6cqi, 10px); margin: 0; padding: 0; list-style: none; }
+.quiz-marks li { width: clamp(22px, 2.5cqi, 42px); height: clamp(22px, 2.5cqi, 42px); border-radius: 50%; background: var(--quiz-right); color: #fff; }
+.quiz-marks li.wrong { background: var(--quiz-wrong); }
+.quiz-marks li.skipped { background: color-mix(in srgb, var(--quiz-text) 22%, transparent); color: var(--quiz-text); }
+@keyframes quiz-in { from { opacity: 0; transform: translateY(10px) scale(.985); } }
+@container (max-width: 560px) {
+  .quiz-layer { padding: 6px; }
+  .quiz-card { width: 100%; padding: 12px; gap: 8px; border-radius: 12px; }
+  .quiz-options, .quiz-options.quiz-odd { grid-template-columns: 1fr 1fr; gap: 6px; }
+  /* A small player keeps the answer in the feedback's words and the next step in reach. */
+  .quiz-card.answered .quiz-options { display: none; }
+  .quiz-actions { position: sticky; bottom: -12px; margin: 0 -12px -12px; padding: 8px 12px 12px; background: var(--quiz-surface); border-radius: 0 0 12px 12px; }
+  .quiz-option { min-height: 40px; padding: 6px 8px; font-size: 12.5px; }
+  .quiz-feedback { font-size: 12.5px; padding: 7px 9px; }
+  .quiz-actions button { min-height: 40px; padding: 0 14px; font-size: 13px; }
+}
+@media (prefers-reduced-motion: reduce) { .quiz-card-in { animation: none; } .quiz-option, .quiz-actions button { transition: none; } }