@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/quiz/engine.ts

@@ -0,0 +1,242 @@
+// The quiz engine in the browser (@lernapps/app-templates/quiz). The build has rendered every question into the page
+// (render.ts); the engine turns that page into a quiz: one question at a time in an order given by the seed in the
+// address (?seed=<number>), as many as the learner chooses at the start (?n=<number>, all by default); after each answer, right or wrong, the background of every option with the right ones
+// and the learner's choice marked, the explanation and further reading; the score and the solutions at the end, with confetti from 80% right and fireworks for all right. A deep
+// link (#frage-<id>) opens its question. The quiz's own texts are in the page's language (its data's lang, German
+// without one). Nothing is stored, except the last result on the device when the bank asks for it
+// (rememberLastResult), through the storage of @lernapps/tooling. An app's src/main.ts is
+//
+//   import "@lernapps/app-templates/quiz/style.css";
+//   import { startQuiz } from "@lernapps/app-templates/quiz";
+//   startQuiz();
+//
+// One question on its own (startQuestion, shared/questions/engine.ts): the quiz runs each of its questions so.
+import { announce, moveFocus } from "@lernapps/tooling/a11y";
+import { translator } from "@lernapps/tooling/i18n";
+import { createStorage } from "@lernapps/tooling/storage";
+import de from "./messages/de.json" with { type: "json" };
+import en from "./messages/en.json" with { type: "json" };
+import { startQuestion } from "../shared/questions/engine.ts";
+import { isCorrect, questionId, shuffled, type Answer } from "../shared/questions/question.ts";
+import { solutionId, type QuizData } from "./quiz.ts";
+
+/** The quiz's texts, by the page's language. */
+const BY_LANGUAGE: Readonly<Record<string, typeof de>> = { de, en };
+const SEED = "seed";
+const COUNT = "n";
+
+interface LastResult {
+  score: number;
+  total: number;
+}
+
+const isLastResult = (value: unknown): value is LastResult =>
+  typeof value === "object" &&
+  value !== null &&
+  "score" in value &&
+  "total" in value &&
+  typeof value.score === "number" &&
+  typeof value.total === "number";
+
+/** The seed in the address; a new one, written into the address, when there is none. */
+function seedOf(location: Location): number {
+  const url = new URL(location.href);
+  const given = Number(url.searchParams.get(SEED));
+  if (Number.isInteger(given) && given > 0) return given;
+  const seed = 1 + Math.floor(Math.random() * 999_999);
+  url.searchParams.set(SEED, String(seed));
+  history.replaceState(history.state, "", url);
+  return seed;
+}
+
+/** The number of questions in the address (?n=<number>), if it is one from 1 to `total`. */
+function countOf(location: Location, total: number): number | undefined {
+  const given = Number(new URL(location.href).searchParams.get(COUNT));
+  return Number.isInteger(given) && given >= 1 && given <= total ? given : undefined;
+}
+
+/** The share of right answers from which the result rains confetti; all right gives fireworks instead. */
+const CONFETTI_FROM = 0.8;
+
+/**
+ * Celebrates a result on a layer over the page that takes no clicks and is hidden for those who prefer less motion
+ * (quiz.css): confetti from 80% right, fireworks for all right. Positions, delays and colours are fixed by index, so
+ * the same result always looks the same.
+ */
+function celebrate(root: Document, right: number, total: number): HTMLElement | undefined {
+  if (total === 0 || right / total < CONFETTI_FROM) return undefined;
+  const layer = root.createElement("div");
+  layer.setAttribute("aria-hidden", "true");
+  const add = (parent: HTMLElement, tag: string, style: Record<string, string>): HTMLElement => {
+    const element = root.createElement(tag);
+    for (const [name, value] of Object.entries(style)) element.style.setProperty(name, value);
+    parent.append(element);
+    return element;
+  };
+  if (right === total) {
+    layer.className = "quiz-celebration quiz-fireworks";
+    const bursts = [
+      { left: "24%", top: "26%", delay: "0.3s", hue: 20 },
+      { left: "76%", top: "22%", delay: "0.9s", hue: 200 },
+      { left: "50%", top: "40%", delay: "1.5s", hue: 320 },
+      { left: "18%", top: "58%", delay: "2.1s", hue: 140 },
+      { left: "82%", top: "56%", delay: "2.7s", hue: 50 },
+    ];
+    for (const burst of bursts) {
+      const element = add(layer, "span", { left: burst.left, top: burst.top, "--hue": String(burst.hue) });
+      element.className = "quiz-burst";
+      for (let index = 0; index < 28; index++) {
+        const spark = add(element, "i", {
+          "--angle": `${index * (360 / 28)}deg`,
+          "--far": index % 2 === 0 ? "1" : "0.6",
+        });
+        spark.style.animationDelay = burst.delay;
+      }
+    }
+  } else {
+    layer.className = "quiz-celebration quiz-confetti";
+    for (let index = 0; index < 28; index++) {
+      const piece = add(layer, "span", {
+        left: `${(index * 37) % 100}%`,
+        "--hue": String((index * 47) % 360),
+        "--turn": `${(index % 2 === 0 ? 1 : -1) * (180 + ((index * 29) % 360))}deg`,
+      });
+      piece.style.animationDelay = `${((index * 53) % 100) / 100}s`;
+    }
+  }
+  root.body.append(layer);
+  return layer;
+}
+
+/** Starts the quiz on the page the build rendered; does nothing on a page without one. */
+export function startQuiz(root: Document = document): void {
+  const dataElement = root.getElementById("quiz-data");
+  const main = root.getElementById("quiz");
+  if (!dataElement || !main) return;
+  const { quiz, storage: storageName, lang = "de" } = JSON.parse(dataElement.textContent ?? "{}") as QuizData;
+  const t = translator(BY_LANGUAGE[lang] ?? de);
+  const storage = storageName === undefined ? undefined : createStorage(storageName);
+  const seed = seedOf(root.location);
+  const total = quiz.questions.length;
+  const shuffledQuestions = shuffled(total, seed).flatMap((index) => quiz.questions[index] ?? []);
+  const hashId = decodeURIComponent(root.location.hash.slice(1));
+  const list = main.querySelector<HTMLElement>(".quiz-questions");
+  const progress = main.querySelector<HTMLElement>(".quiz-progress");
+  const result = main.querySelector<HTMLElement>(".quiz-result");
+  const solutions = main.querySelector<HTMLElement>(".quiz-solutions");
+  if (!list || !progress || !result || !solutions) return;
+  const heading = main.querySelector<HTMLElement>(".quiz-heading");
+  const form = main.querySelector<HTMLFormElement>(".quiz-start");
+
+  /** Runs the quiz with the first `count` questions in the order of the seed. */
+  const run = (count: number) => {
+    const order = shuffledQuestions.slice(0, count);
+    // a link to a question that this run does not ask puts that question first, so every question keeps its link
+    const linked = shuffledQuestions.find((question) => questionId(question) === hashId);
+    if (linked && !order.includes(linked)) order[0] = linked;
+    const answers = new Map<string, Answer>();
+
+    main.classList.add("quiz-running");
+    solutions.hidden = true;
+    progress.hidden = false;
+    const items = new Map<string, HTMLElement>();
+    for (const question of order) {
+      const item = root.getElementById(questionId(question));
+      if (!item) continue;
+      items.set(question.id, item);
+      list.append(item); // in the order of the seed
+      startQuestion(item, question, { seed, lang, onAnswer: (answer) => answers.set(question.id, answer) });
+    }
+    // the questions this run does not ask: neither the question nor its solution
+    for (const question of quiz.questions.filter((candidate) => !order.includes(candidate))) {
+      root.getElementById(questionId(question))?.remove();
+      root.getElementById(solutionId(question))?.remove();
+    }
+
+    let celebration: HTMLElement | undefined;
+    const show = (index: number, focus: boolean) => {
+      celebration?.remove();
+      order.forEach((question, at) => {
+        const item = items.get(question.id);
+        if (item) item.hidden = at !== index;
+      });
+      result.hidden = true;
+      solutions.hidden = true;
+      progress.textContent = t("progress", { current: index + 1, total: order.length });
+      const legend = items.get(order[index]?.id ?? "")?.querySelector<HTMLElement>("legend");
+      if (focus && legend) moveFocus(legend);
+      // the previous question was longer than this one, so the page shrank and the browser left the view at the top:
+      // the heading "Frage N" comes into view, after the focus, which scrolls on its own
+      if (focus) progress.scrollIntoView({ block: "start" });
+    };
+
+    const finish = () => {
+      for (const item of items.values()) item.hidden = true;
+      progress.hidden = true;
+      const right = order.filter((question) => {
+        const answer = answers.get(question.id);
+        return answer !== undefined && isCorrect(question, answer);
+      }).length;
+      const scoreText = main.querySelector(".quiz-score");
+      if (scoreText) scoreText.textContent = t("score", { score: right, total: order.length });
+      const last = storage?.load("last-result", isLastResult);
+      const lastText = main.querySelector<HTMLElement>(".quiz-last");
+      if (lastText && last) {
+        lastText.textContent = t("last", { score: last.score, total: last.total });
+        lastText.hidden = false;
+      }
+      storage?.save("last-result", { score: right, total: order.length } satisfies LastResult);
+      const restart = main.querySelector<HTMLAnchorElement>(".quiz-restart");
+      if (restart) restart.href = `?${SEED}=${1 + ((seed * 7919) % 999_999)}&${COUNT}=${order.length}`;
+      result.hidden = false;
+      solutions.hidden = false;
+      celebration?.remove();
+      celebration = celebrate(root, right, order.length);
+      moveFocus(result);
+      announce(scoreText?.textContent ?? "");
+    };
+
+    order.forEach((question, index) => {
+      const next = items.get(question.id)?.querySelector<HTMLButtonElement>(".question-next");
+      if (!next) return;
+      const isLast = index === order.length - 1;
+      if (isLast) next.textContent = t("toResult");
+      next.addEventListener("click", () => {
+        if (isLast) finish();
+        else show(index + 1, true);
+      });
+    });
+
+    const fromAddress = (focus: boolean) => {
+      const hashId = decodeURIComponent(root.location.hash.slice(1));
+      const index = order.findIndex((question) => questionId(question) === hashId);
+      show(index >= 0 ? index : 0, focus || index >= 0);
+    };
+    globalThis.addEventListener("hashchange", () => fromAddress(true));
+    fromAddress(false);
+  };
+
+  const given = countOf(root.location, total);
+  // the learner chooses how many questions to answer, unless the address already says (or links to a question)
+  if (given !== undefined || hashId !== "" || !form || total < 2) {
+    run(given ?? total);
+    return;
+  }
+  const input = form.querySelector<HTMLInputElement>("input");
+  if (!input) return run(total);
+  list.hidden = true;
+  solutions.hidden = true;
+  if (heading) heading.hidden = true;
+  form.hidden = false;
+  form.addEventListener("submit", (event) => {
+    event.preventDefault();
+    const count = Math.min(total, Math.max(1, Math.floor(Number(input.value)) || total));
+    const url = new URL(root.location.href);
+    url.searchParams.set(COUNT, String(count));
+    history.replaceState(history.state, "", url);
+    form.hidden = true;
+    list.hidden = false;
+    if (heading) heading.hidden = false;
+    run(count);
+  });
+}

package/runtime/quiz/messages/de.json

@@ -0,0 +1,23 @@
+{
+  "howto": "Beantworte die Fragen der Reihe nach. Nach jeder Antwort siehst du, ob sie stimmt, und erfährst mehr über jede Antwort. Am Ende siehst du dein Ergebnis.",
+  "noscript": "Ohne JavaScript kannst du alle Fragen lesen. Die Lösungen mit mehr Wissen zu jeder Antwort stehen am Ende der Seite.",
+  "questions": "Fragen",
+  "countLabel": "Wie viele Fragen möchtest du beantworten?",
+  "countOf": "von {total}",
+  "start": "Los geht’s",
+  "progress": "Frage {current} von {total}",
+  "toResult": "Zum Ergebnis",
+  "result": "Ergebnis",
+  "score": "Du hast {score} von {total} Fragen richtig beantwortet.",
+  "last": "Beim letzten Mal waren es {score} von {total}.",
+  "restart": "Noch einmal",
+  "solutions": "Lösungen",
+  "toQuestion": "Zur Frage",
+  "footer": "Ein Quiz auf lernapps.net",
+  "imprint": "Impressum",
+  "privacy": "Datenschutz",
+  "sources": "Quellen",
+  "sourcesIntro": "Die Fakten in diesem Quiz stammen aus diesen Quellen:",
+  "language": "Deutsch",
+  "languages": "Sprache"
+}

package/runtime/quiz/messages/en.json

@@ -0,0 +1,23 @@
+{
+  "howto": "Answer the questions one by one. After each answer you see whether it is right and learn more about every answer. At the end you see your result.",
+  "noscript": "Without JavaScript you can read all questions. The solutions, with more on every answer, are at the end of the page.",
+  "questions": "Questions",
+  "countLabel": "How many questions do you want to answer?",
+  "countOf": "of {total}",
+  "start": "Start",
+  "progress": "Question {current} of {total}",
+  "toResult": "To the result",
+  "result": "Result",
+  "score": "You answered {score} of {total} questions right.",
+  "last": "Last time it was {score} of {total}.",
+  "restart": "Again",
+  "solutions": "Solutions",
+  "toQuestion": "To the question",
+  "footer": "A quiz on lernapps.net",
+  "imprint": "Imprint",
+  "privacy": "Privacy",
+  "sources": "Sources",
+  "sourcesIntro": "The facts in this quiz come from these sources:",
+  "language": "English",
+  "languages": "Language"
+}

package/runtime/quiz/plugin.ts

@@ -0,0 +1,150 @@
+// The build step of a quiz (@lernapps/app-templates/quiz/plugin), a Vite plugin. An app's vite.config.ts adds it to
+// the shared preset of @lernapps/tooling:
+//
+//   import { lernapps } from "@lernapps/tooling/preset";
+//   import { quiz } from "@lernapps/app-templates/quiz/plugin";
+//   export default lernapps({ plugins: [quiz()] });
+//
+// It reads the question bank (src/quiz.json), validates it against its JSON Schema and fails the build with a
+// message naming each problem, and renders every question into index.html where it says <!-- quiz -->, so the page
+// reads without JavaScript. The app's src/main.ts starts the engine (@lernapps/app-templates/quiz) on that page.
+// A bank in several languages (languages: ["de", "en"]) gives a page per language: German in index.html, every other
+// language in <language>/index.html, the built index.html with that language's quiz and its relative asset URLs
+// rewritten for its depth; each with its language, its alternates and a language switch. 404.html leads every address
+// the app does not have to its start page (notFoundPage of ../shared/pages.ts). `vp dev` serves the same pages, /en/
+// in English.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Plugin } from "vite-plus";
+import { appName } from "../shared/appname.ts";
+import { imageType, isSizeless } from "../shared/blocks/image.ts";
+import { materialImages } from "../shared/blocks/index.ts";
+import type { Text } from "../shared/languages.ts";
+import { fromDepth, languageRoot, notFoundPage, withLanguage } from "../shared/pages.ts";
+import { quizIn, quizLanguages, type Quiz } from "./quiz.ts";
+import { renderQuiz } from "./render.ts";
+import { readBank } from "./validate.ts";
+import { escape } from "../shared/html.ts";
+
+/** Where the question bank is, relative to the app's root. */
+export const BANK = "src/quiz.json";
+const MARKER = "<!-- quiz -->";
+
+/** The bank, in all its languages, and the name of the app's storage when the quiz keeps the last result. */
+interface Bank {
+  quiz: Quiz<Text>;
+  storage?: string;
+  /** The bundled images the questions show, by their path from src/ (images/<name>), with their files. */
+  images: ReadonlyMap<string, string>;
+}
+
+/** The page in `lang`: the shell with the quiz in that language, its title, description and alternates. */
+function fill(html: string, { quiz, storage, images }: Bank, lang: string): string {
+  if (!html.includes(MARKER)) {
+    throw new Error(`index.html has no ${MARKER}: put it in <body>, where the quiz goes`);
+  }
+  const data = {
+    quiz: quizIn(quiz, lang),
+    ...(storage === undefined ? {} : { storage }),
+    ...(lang === "de" ? {} : { lang }),
+  };
+  const { title, description, alternates, body } = renderQuiz(data, {
+    languages: quizLanguages(quiz),
+    sizeless: (image) => {
+      const file = images.get(image);
+      return file !== undefined && isSizeless(file);
+    },
+  });
+  const head = [
+    `<title>${escape(title)}</title>`,
+    `<meta name="description" content="${escape(description)}" />`,
+    ...alternates,
+  ].join("\n    ");
+  const withHead = /<title>[\s\S]*?<\/title>/.test(html)
+    ? html.replace(/<title>[\s\S]*?<\/title>/, head)
+    : html.replace("</head>", `    ${head}\n  </head>`);
+  return (lang === "de" ? withHead : withLanguage(withHead, lang)).replace(MARKER, () => body);
+}
+
+/** The language of a page the dev server serves: the first part of its address, if the quiz has that language. */
+function languageOf(url: string | undefined, languages: readonly string[]): string {
+  const first = /^\/([a-z]{2})\//.exec(url ?? "")?.[1];
+  return first !== undefined && first !== "de" && languages.includes(first) ? first : "de";
+}
+
+/** The build step of the quiz: validates the question bank and renders it into index.html, a page per language. */
+export function quiz(): Plugin {
+  let root = process.cwd();
+  let bank: Bank | undefined;
+  /** The built index.html before the quiz is in it, for the pages in the other languages. */
+  let shell: string | undefined;
+  const load = (): Bank => {
+    const file = join(root, BANK);
+    let text: string;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch {
+      throw new Error(`${BANK} is missing: the quiz's questions belong there (schema quiz.v1.schema.json)`);
+    }
+    const quiz = readBank(text, BANK, { imageExists: (image) => existsSync(join(root, "src", image)) });
+    const images = new Map(
+      quiz.questions
+        .flatMap((question) => materialImages(question.material ?? []))
+        .map((image) => [image, join(root, "src", image)]),
+    );
+    return quiz.rememberLastResult === true ? { quiz, storage: appName(root, "quiz"), images } : { quiz, images };
+  };
+  return {
+    name: "lernapps-quiz",
+    // after Vite has written the built index.html, so the pages in the other languages are made from it
+    enforce: "post",
+    configResolved(config) {
+      root = config.root;
+    },
+    buildStart() {
+      this.addWatchFile(join(root, BANK));
+      try {
+        bank = load();
+      } catch (error) {
+        this.error(error instanceof Error ? error.message : String(error));
+      }
+    },
+    handleHotUpdate({ file, server }) {
+      if (file === join(root, BANK)) {
+        bank = undefined;
+        server.ws.send({ type: "full-reload" });
+      }
+    },
+    configureServer(server) {
+      // the bundled images, before Vite's own fallback to index.html
+      server.middlewares.use((request, response, next) => {
+        const path = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname).replace(/^\//, "");
+        if (!path.startsWith("images/")) return next();
+        const file = (bank ??= load()).images.get(path);
+        if (file === undefined) return next();
+        response.setHeader("content-type", imageType(path));
+        response.end(readFileSync(file));
+      });
+    },
+    transformIndexHtml(html, context) {
+      bank ??= load();
+      shell = html;
+      return fill(html, bank, languageOf(context.originalUrl, quizLanguages(bank.quiz)));
+    },
+    generateBundle() {
+      if (bank === undefined || shell === undefined) return;
+      this.emitFile({ type: "asset", fileName: "404.html", source: notFoundPage() });
+      for (const [image, file] of bank.images)
+        this.emitFile({ type: "asset", fileName: image, source: readFileSync(file) });
+      for (const lang of quizLanguages(bank.quiz).slice(1)) {
+        const path = languageRoot(lang);
+        this.emitFile({
+          type: "asset",
+          fileName: `${path}index.html`,
+          // the shell's asset URLs for the depth of the page, before the quiz is in it (its own links are relative to it)
+          source: fill(fromDepth(shell, path), bank, lang),
+        });
+      }
+    },
+  };
+}

package/runtime/quiz/quiz.css

@@ -0,0 +1,154 @@
+/* The look of a quiz (@lernapps/app-templates/quiz/style.css): the frame and the questions are shared (page.css,
+   questions.css); this is the quiz's page: its start form, its progress, its result, its solutions and its celebration. */
+@import "../shared/page.css";
+@import "../shared/blocks/blocks.css";
+@import "../shared/questions/questions.css";
+
+.quiz {
+  max-width: var(--page-max-width, 44rem);
+  margin: 0 auto;
+  padding: 1rem;
+  overflow-wrap: break-word;
+}
+
+.quiz h1 {
+  font-size: 1.75rem;
+  line-height: 1.2;
+}
+
+.quiz-questions,
+.quiz-solutions ol {
+  padding-left: 1.5rem;
+}
+
+.quiz-running .quiz-questions {
+  list-style: none;
+  padding-left: 0;
+}
+
+.quiz-start button {
+  font: inherit;
+  padding: 0.5rem 1rem;
+  border: 2px solid var(--page-accent);
+  border-radius: 0.375rem;
+  background: var(--page-accent);
+  color: var(--page-on-accent);
+  cursor: pointer;
+}
+
+.quiz a.quiz-restart {
+  display: inline-block;
+  padding: 0.5rem 1rem;
+  border: 2px solid var(--page-accent);
+  border-radius: 0.375rem;
+  background: var(--page-accent);
+  color: var(--page-on-accent);
+  text-decoration: none;
+}
+
+.quiz-progress {
+  color: var(--page-muted);
+}
+
+.quiz-solution h3 {
+  font-size: 1.0625rem;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  html {
+    scroll-behavior: smooth;
+  }
+}
+
+.quiz-start input {
+  font: inherit;
+  width: 4.5rem;
+  padding: 0.375rem 0.5rem;
+  border: 2px solid var(--page-border);
+  border-radius: 0.375rem;
+  background: var(--page-surface);
+  color: inherit;
+}
+
+/* the celebration of a good result: confetti from 80% right, fireworks for all right (engine.ts) */
+.quiz-celebration {
+  position: fixed;
+  inset: 0;
+  overflow: hidden;
+  pointer-events: none;
+  z-index: 10;
+}
+
+.quiz-fireworks {
+  background: rgb(6 10 28 / 0.72);
+  animation: quiz-dim 4.8s ease-in-out forwards;
+}
+
+@keyframes quiz-dim {
+  0% {
+    opacity: 0;
+  }
+  15%,
+  80% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+  }
+}
+
+.quiz-burst {
+  position: absolute;
+  width: 0;
+  height: 0;
+}
+
+.quiz-burst i {
+  position: absolute;
+  left: -0.4rem;
+  top: -0.4rem;
+  width: 0.8rem;
+  height: 0.8rem;
+  border-radius: 50%;
+  background: hsl(var(--hue) 90% 62%);
+  box-shadow: 0 0 0.9rem 0.25rem hsl(var(--hue) 90% 62% / 0.7);
+  opacity: 0;
+  animation: quiz-spark 2.2s ease-out forwards;
+}
+
+@keyframes quiz-spark {
+  0% {
+    opacity: 0;
+    transform: rotate(var(--angle)) translateX(0);
+  }
+  12% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+    transform: rotate(var(--angle)) translateX(calc(min(20rem, 42vw) * var(--far)));
+  }
+}
+
+.quiz-confetti span {
+  position: absolute;
+  top: -1.5rem;
+  width: 0.6rem;
+  height: 1rem;
+  border-radius: 2px;
+  background: hsl(var(--hue) 80% 55%);
+  animation: quiz-confetti-fall 2.8s ease-in forwards;
+}
+
+@keyframes quiz-confetti-fall {
+  to {
+    transform: translateY(105vh) rotate(var(--turn));
+    opacity: 0.9;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .quiz-celebration {
+    display: none;
+  }
+}

package/runtime/quiz/quiz.ts

@@ -0,0 +1,56 @@
+// The question bank of a quiz about things to know (src/quiz.json, schema quiz.v1.schema.json): the quiz around its
+// questions, and the score. The questions themselves, and what counts as a right answer, are in
+// ../shared/questions/question.ts. A quiz in several languages writes each learner text as a map of texts by
+// language, { de: …, en: … } (Quiz<Text>); quizIn gives it in the page's language.
+import { inLanguage, type Text } from "../shared/languages.ts";
+import { isCorrect, questionIn, type Answer, type Question } from "../shared/questions/question.ts";
+
+export interface Quiz<T extends Text = string> {
+  /** The quiz's languages, German first; German only when it has none. */
+  languages?: string[];
+  title: T;
+  intro: T;
+  rememberLastResult?: boolean;
+  questions: Question<T>[];
+  /** Where the facts come from. */
+  sources?: { title: T; url?: string }[];
+}
+
+/** The quiz's languages, German first. */
+export const quizLanguages = (quiz: Pick<Quiz<Text>, "languages">): readonly string[] => quiz.languages ?? ["de"];
+
+/** The quiz in `lang`: each text from its map, a plain string as it is; everything else as it is. */
+export function quizIn(quiz: Quiz<Text>, lang: string): Quiz {
+  const { sources } = quiz;
+  // the keys in their order, so a quiz in German only is as it was
+  return {
+    ...(quiz as Omit<Quiz<Text>, "sources">),
+    title: inLanguage(quiz.title, lang),
+    intro: inLanguage(quiz.intro, lang),
+    questions: quiz.questions.map((question) => questionIn(question, lang)),
+    ...(sources === undefined
+      ? {}
+      : { sources: sources.map((source) => ({ ...source, title: inLanguage(source.title, lang) })) }),
+  };
+}
+
+/** The number of questions answered right; questions without an answer count as wrong. */
+export function score(questions: readonly Question[], answers: ReadonlyMap<string, Answer>): number {
+  return questions.filter((question) => {
+    const answer = answers.get(question.id);
+    return answer !== undefined && isCorrect(question, answer);
+  }).length;
+}
+
+/** What the engine reads from the page (script#quiz-data). */
+export interface QuizData {
+  /** The quiz in the page's language. */
+  quiz: Quiz;
+  /** The name of the app's storage, when the quiz keeps the last result on the device. */
+  storage?: string;
+  /** The page's language, when it is not German. */
+  lang?: string;
+}
+
+/** The id of the element of the solution of a question, in the list of solutions. */
+export const solutionId = (question: Pick<Question, "id">): string => `loesung-${question.id}`;