@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/shared/languages.ts

@@ -0,0 +1,94 @@
+// Learner texts in several languages, shared by the archetypes' runtimes (the explainer, the quiz): a text is a string while German is the app's only language, else a map of texts
+// by language, { de: …, en: … }, complete in every declared language and in no other. German is always first.
+
+/**
+ * The languages the runtime has texts for, German first. Every registry of the runtime's own texts has one entry per
+ * language (its type says so), so adding a language is complete when the compiler is.
+ */
+export const LANGUAGES = ["de", "en"] as const;
+export type Language = (typeof LANGUAGES)[number];
+
+export const isLanguage = (lang: string): lang is Language => (LANGUAGES as readonly string[]).includes(lang);
+
+const LOCALES = { de: "de-DE", en: "en-GB" } as const satisfies Readonly<Record<Language, string>>;
+/** The locale for numbers and dates in `lang`; German's for a language the runtime has no texts for. */
+export const localeOf = (lang: string): string => LOCALES[isLanguage(lang) ? lang : "de"];
+
+/** The entry of `registry` for `lang`; German's for a language the runtime has no texts for. */
+export const textsIn = <T>(registry: Readonly<Record<Language, T>>, lang: string): T =>
+  registry[isLanguage(lang) ? lang : "de"];
+
+/** A learner text: a string while German is the only language, else a map of texts by language. */
+export type Text = string | Readonly<Record<string, string>>;
+
+/** A problem with the languages of one text, in `lang`. */
+export interface LanguageProblem {
+  lang: string;
+  message: string;
+}
+
+/** The text in one language; `keyed` when it comes from a map (its place is then <path>.<lang>). */
+export interface TextIn {
+  lang: string;
+  text: string;
+  keyed: boolean;
+}
+
+/** The text in `lang`; a plain string is the same in every language. */
+export function inLanguage(text: Text, lang: string): string {
+  return typeof text === "string" ? text : (text[lang] ?? text["de"] ?? "");
+}
+
+/**
+ * The text in each of the app's `languages` that it has, and the problems of its languages: a translation missing,
+ * a language not declared (in `declaredIn`, the file with the app's languages). A plain string is German, and complete
+ * only while German is the only language; with `neutral` (a formula, a code), a plain string is the same in every
+ * language.
+ */
+export function textLanguages(
+  value: Text,
+  languages: readonly string[],
+  neutral = false,
+  declaredIn = "src/app.yaml",
+): { texts: TextIn[]; problems: LanguageProblem[] } {
+  if (typeof value === "string") {
+    if (neutral) return { texts: languages.map((lang) => ({ lang, text: value, keyed: false })), problems: [] };
+    const map = `{ ${languages.map((code) => `${code}: …`).join(", ")} }`;
+    return {
+      texts: [{ lang: "de", text: value, keyed: false }],
+      problems: languages
+        .slice(1)
+        .map((lang) => ({ lang, message: `the translation is missing; write the text as a map: ${map}` })),
+    };
+  }
+  const problems: LanguageProblem[] = [
+    ...Object.keys(value)
+      .filter((lang) => !languages.includes(lang))
+      .map((lang) => ({
+        lang,
+        message: `${lang} is not a language of the app; declare it in languages in ${declaredIn}, or remove it`,
+      })),
+    ...languages.filter((lang) => !(lang in value)).map((lang) => ({ lang, message: "the translation is missing" })),
+  ];
+  return {
+    texts: languages.filter((lang) => lang in value).map((lang) => ({ lang, text: value[lang] ?? "", keyed: true })),
+    problems,
+  };
+}
+
+/** What is wrong with an app's list of languages: German first, each once, each one the runtime has texts for. */
+export function languageListProblems(languages: readonly string[], supported: readonly string[]): LanguageProblem[] {
+  const problems: LanguageProblem[] = [];
+  if (languages[0] !== "de")
+    problems.push({ lang: languages[0] ?? "", message: "German comes first: languages: [de, …]" });
+  languages.forEach((lang, index) => {
+    if (languages.indexOf(lang) !== index) problems.push({ lang, message: `${lang} is listed twice` });
+    else if (!supported.includes(lang)) {
+      problems.push({
+        lang,
+        message: `the runtime has no texts of its own in ${lang} yet; it has ${supported.join(", ")}`,
+      });
+    }
+  });
+  return problems;
+}

package/runtime/shared/page.css

@@ -0,0 +1,101 @@
+/* The frame of every page of an app (the stylesheets of the archetypes import it): the colours, plain and readable
+   at 360 px with contrast for WCAG 2.1 AA in the light and the dark scheme, the reset, the body, links, the header with
+   the language switch and the footer. An app that needs a wider frame sets --page-max-width in its own :root rule. */
+:root {
+  --page-text: #1a1a1a;
+  --page-muted: #4a4a4a;
+  --page-background: #ffffff;
+  --page-surface: #f4f5f7;
+  --page-border: #8a8f98;
+  --page-accent: #1d4ed8;
+  --page-on-accent: #ffffff;
+  --page-right: #14532d;
+  --page-right-background: #dcfce7;
+  --page-wrong: #7f1d1d;
+  --page-wrong-background: #fee2e2;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --page-text: #ececec;
+    --page-muted: #b8bcc4;
+    --page-background: #121316;
+    --page-surface: #1d1f24;
+    --page-border: #7d838d;
+    --page-accent: #8ab4ff;
+    --page-on-accent: #0b1020;
+    --page-right: #bbf7d0;
+    --page-right-background: #143522;
+    --page-wrong: #fecaca;
+    --page-wrong-background: #3f1515;
+  }
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+[hidden] {
+  display: none !important;
+}
+
+body {
+  margin: 0;
+  background: var(--page-background);
+  color: var(--page-text);
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  font-size: 1.0625rem;
+  line-height: 1.55;
+}
+
+a {
+  color: var(--page-accent);
+}
+
+:focus-visible {
+  outline: 3px solid var(--page-accent);
+  outline-offset: 2px;
+}
+
+.page-header,
+.page-footer {
+  max-width: var(--page-max-width, 44rem);
+  margin: 0 auto;
+  padding: 0 1rem;
+  overflow-wrap: break-word;
+}
+
+/* the language switch of an app in several languages: a link to the page in each language, the current one marked */
+.page-header {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 1rem;
+  align-items: baseline;
+  justify-content: flex-end;
+  padding-top: 0.75rem;
+}
+
+.page-languages ul {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 0.75rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.page-languages a[aria-current="page"] {
+  color: var(--page-text);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.page-footer {
+  margin-top: 2rem;
+  padding-bottom: 1.5rem;
+  color: var(--page-muted);
+  font-size: 0.9375rem;
+}

package/runtime/shared/pages.ts

@@ -0,0 +1,114 @@
+// The page trees of an app in several languages, shared by the archetypes' build steps (the explainer, the quiz):
+// German at the root, every other language below /<language>/, the same address within each tree. Each page has its
+// language on <html>, an alternate link to itself in every language, and a language switch of plain links, so it
+// works without JavaScript. Every URL is relative, so the app works under any path.
+
+/** The root of a language's tree, from the app's root: "" for German, "en/" for English. */
+export const languageRoot = (lang: string): string => (lang === "de" ? "" : `${lang}/`);
+
+/** A relative URL from the page at `from` to `to` (both from the app's root). */
+export function relative(from: string, to: string): string {
+  const up = "../".repeat(from.split("/").filter((part) => part !== "").length);
+  const url = `${up}${to}`;
+  return url === "" ? "./" : url.startsWith("#") ? `./${url}` : url;
+}
+
+/** The built shell's relative URLs (./assets/…, built by Vite with base "./"), from a page at `path`. */
+export function fromDepth(html: string, path: string): string {
+  const up = "../".repeat(path.split("/").filter((part) => part !== "").length);
+  return html.replace(/((?:src|href)=")\.\/(?!\/)/g, `$1${up === "" ? "./" : up}`);
+}
+
+/** The page with `lang` as the language of its <html>, in place of the one it had. */
+export const withLanguage = (html: string, lang: string): string =>
+  html.replace(/<html([^>]*?)\slang="[^"]*"/, "<html$1").replace("<html", `<html lang="${lang}"`);
+
+/** Where a page is in its language tree, and the languages it exists in. */
+export interface PageInLanguages {
+  /** Where the page is, from the app's root: "", "en/", "en/prozent/prozentwert/". */
+  path: string;
+  /** The same page's address within any language tree: "", "prozent/prozentwert/". */
+  local: string;
+  /** The app's languages, German first. */
+  languages: readonly string[];
+}
+
+/** An alternate link to the page in each of its languages, for <head>. */
+export const alternateLinks = ({ path, local, languages }: PageInLanguages): string[] =>
+  languages.map(
+    (lang) => `<link rel="alternate" hreflang="${lang}" href="${relative(path, languageRoot(lang) + local)}" />`,
+  );
+
+/**
+ * The header of a page in `lang`: the language switch, a link to the page in each language, named in its own
+ * language, the current one marked; nothing while the app has one language. `label` and `name` give HTML, already
+ * escaped.
+ */
+export function pageHeader(
+  page: PageInLanguages & { lang: string; label: string; name: (lang: string) => string },
+): string {
+  const { path, local, languages, lang: current, label, name } = page;
+  if (languages.length < 2) return "";
+  const links = languages.map(
+    (lang) =>
+      `<li><a href="${relative(path, languageRoot(lang) + local)}" hreflang="${lang}" lang="${lang}"${lang === current ? ' aria-current="page"' : ""}>${name(lang)}</a></li>`,
+  );
+  return `<header class="page-header"><nav class="page-languages" aria-label="${label}"><ul>${links.join("")}</ul></nav></header>`;
+}
+
+/** The footer of a page: what the app is, and the links to the imprint and the privacy statement; texts as HTML, already escaped. */
+export const pageFooter = (words: { footer: string; imprint: string; privacy: string }): string =>
+  `<footer class="page-footer"><p>${words.footer} · <a href="https://lernapps.net/imprint/">${words.imprint}</a> · <a href="https://lernapps.net/privacy/">${words.privacy}</a></p></footer>`;
+
+/**
+ * The page for every address the app does not have, 404.html at the bundle's root: GitHub Pages serves it for any
+ * missing path below the site, at that path, so the page cannot know its own depth, and relative links in it would
+ * point below the missing path. Its script finds the app's root instead: from the missing path's folder upwards, the
+ * first folder whose 404.html exists (one HEAD request each, to the same server) is the root of the bundle that
+ * answers there: the app at /<repo>/, a preview at /<repo>/pr-preview/pr-<n>/ (which has its own 404.html), or / when
+ * served locally. It then moves on to that root's start page and points the link there. Without JavaScript the link
+ * leads to the start page of the site. German, plain language, not indexed, nothing loaded from another server.
+ */
+export function notFoundPage(): string {
+  const script = `(async () => {
+  const link = document.getElementById("start");
+  let folder = location.pathname.slice(0, location.pathname.lastIndexOf("/") + 1);
+  for (;;) {
+    try {
+      const found = await fetch(folder + "404.html", { method: "HEAD", cache: "no-store" });
+      if (found.ok) break;
+    } catch {
+      return;
+    }
+    if (folder === "/") return;
+    folder = folder.slice(0, folder.lastIndexOf("/", folder.length - 2) + 1);
+  }
+  link.href = folder;
+  link.textContent = "Zur Startseite der App";
+  if (folder === location.pathname) return;
+  document.getElementById("weiter").hidden = false;
+  location.replace(folder);
+})();`;
+  return [
+    `<!doctype html>`,
+    `<html lang="de">`,
+    `  <head>`,
+    `    <meta charset="utf-8" />`,
+    `    <meta name="viewport" content="width=device-width, initial-scale=1" />`,
+    `    <meta name="robots" content="noindex" />`,
+    `    <title>Seite nicht gefunden</title>`,
+    `    <style>body { margin: 2rem auto; max-width: 40rem; padding: 0 1rem; font-family: system-ui, sans-serif; line-height: 1.5; color: #1a1a1a; background: #ffffff; } a { color: #1d4ed8; }</style>`,
+    `  </head>`,
+    `  <body>`,
+    `    <main>`,
+    `      <h1>Seite nicht gefunden</h1>`,
+    `      <p>Diese Seite gibt es nicht (mehr).</p>`,
+    `      <p id="weiter" hidden>Du wirst zur Startseite der App weitergeleitet.</p>`,
+    `      <p><a id="start" href="/">Zur Startseite</a></p>`,
+    `    </main>`,
+    `    <script>${script}</script>`,
+    `  </body>`,
+    `</html>`,
+    ``,
+  ].join("\n");
+}

package/runtime/shared/questions/e2e.ts

@@ -0,0 +1,115 @@
+// The end-to-end helpers for a question on any page with a question that renderQuestion
+// (@lernapps/app-templates/questions) rendered and startQuestion made live: answerQuestion gives an answer through
+// the question's controls, as a learner does; expectBackground and expectFeedbackInView check what the learner then
+// sees. Run by the end-to-end tests of the archetypes that have questions.
+import { expect, type Locator, type Page } from "playwright/test";
+import { textsIn } from "../languages.ts";
+import { QUESTION_MESSAGES } from "./render.ts";
+import { questionId, type Answer, type Question } from "./question.ts";
+
+/** The question's own texts in `lang`. */
+const messagesOf = (lang: string) => textsIn(QUESTION_MESSAGES, lang);
+
+export const question = (page: Page, item: Question) => page.locator(`#${questionId(item)}`);
+
+/** Gives `answer` to the question through its controls, as a learner does, on a page in `lang`. */
+export async function answerQuestion(page: Page, item: Question, answer: Answer, lang = "de"): Promise<void> {
+  await giveAnswer(page, item, answer);
+  await question(page, item)
+    .getByRole("button", { name: messagesOf(lang).check })
+    .click();
+}
+
+/** Puts `answer` into the controls of the question, as a learner does, without checking it. */
+export async function giveAnswer(page: Page, item: Question, answer: Answer): Promise<void> {
+  const form = question(page, item);
+  switch (item.type) {
+    case "single-choice":
+    case "multiple-choice":
+    case "true-false": {
+      const values = typeof answer === "object" ? answer.map(String) : [String(answer)];
+      for (const value of values) await form.locator(`input[value="${value}"]`).check();
+      break;
+    }
+    case "number":
+      await form.locator("input").fill(String(answer));
+      break;
+    case "ordering":
+    case "matching": {
+      if (typeof answer !== "object") throw new Error(`${item.id}: an ${item.type} answer is a list`);
+      const key = item.type === "ordering" ? "item" : "left";
+      for (const [index, value] of answer.entries()) {
+        await form.locator(`select[data-${key}="${index}"]`).selectOption(String(value));
+      }
+      break;
+    }
+  }
+}
+
+/** What the learner learns about a question shows in `where`: each option's background, the explanation, the links. */
+export async function expectBackground(where: Locator, item: Question): Promise<void> {
+  if (item.type === "single-choice" || item.type === "multiple-choice") {
+    for (const option of item.options) {
+      await expect(where.getByText(option.info, { exact: true })).toBeVisible();
+      if (option.link) await expect(where.locator(`a[href="${option.link.url}"]`).first()).toBeVisible();
+    }
+  }
+  await expect(where.getByText(item.explanation, { exact: true })).toBeVisible();
+  for (const link of item.links) {
+    const anchor = where.locator(`a[href="${link.url}"]`).first();
+    await expect(anchor).toBeVisible();
+    await expect(anchor).toHaveAttribute("rel", "noopener");
+  }
+}
+
+/** After an answer, the learner sees the feedback without scrolling back; it has the focus, the next button follows. */
+export async function expectFeedbackInView(page: Page, item: Question): Promise<void> {
+  const feedback = question(page, item).locator(".question-feedback");
+  const top = await feedback.evaluate((element) => element.getBoundingClientRect().top);
+  const height = await page.evaluate(() => innerHeight);
+  expect(top, "the top of the feedback is in the viewport").toBeGreaterThanOrEqual(0);
+  expect(top, "the top of the feedback is in the viewport").toBeLessThan(height);
+  await expect(feedback).toBeFocused();
+}
+
+/** What a question shows besides its text (its material) is on the page, between the text and the answers; images load. */
+export async function expectMaterial(page: Page, item: Question, { loaded = true } = {}): Promise<void> {
+  const blocks = item.material ?? [];
+  const area = question(page, item).locator(".question-material");
+  if (blocks.length === 0) {
+    await expect(area).toHaveCount(0);
+    return;
+  }
+  await expect(area).toBeVisible();
+  const count = (type: string) => blocks.filter((block) => block.type === type).length;
+  for (const [type, selector] of [
+    ["text", ".block-text"],
+    ["formula", ".block-formula"],
+    ["figure", ".block-figure:not(.block-labelled)"],
+    ["labelled-figure", ".block-labelled"],
+    ["table", ".block-table"],
+    ["quote", ".block-quote"],
+    ["code", ".block-code"],
+  ] as const) {
+    await expect(area.locator(selector), `${item.id}: the ${type} blocks`).toHaveCount(count(type));
+  }
+  const withCredit = blocks.filter((block) => "licence" in block && block.licence !== undefined).length;
+  await expect(area.locator(".block-credit")).toHaveCount(withCredit);
+  const images = blocks.filter((block) => "image" in block && block.image !== undefined);
+  const pictures = area.locator("img");
+  await expect(pictures).toHaveCount(images.length);
+  for (const [index, block] of images.entries()) {
+    const picture = pictures.nth(index);
+    await expect(picture).toHaveAttribute(
+      "alt",
+      block.type === "figure" || block.type === "labelled-figure" ? block.alt : "",
+    );
+    if (!loaded) continue;
+    // the file is found from this page and drawn
+    await expect
+      .poll(() => picture.evaluate((element: HTMLImageElement) => element.complete && element.naturalWidth > 0), {
+        message: `${item.id}: image ${index + 1} loads`,
+      })
+      .toBe(true);
+  }
+}

package/runtime/shared/questions/engine.ts

@@ -0,0 +1,209 @@
+// One question in the browser, for every archetype that has questions (@lernapps/app-templates/questions): the page
+// has rendered it (render.ts); startQuestion makes it live. A complete answer gets its feedback, right or wrong, with
+// the most specific reason of a wrong answer; then the solution shows: the background of every option with the right
+// ones and the learner's choice marked, the explanation and further reading. A question can also be tried again
+// (retry), as an exercise is. The question's own texts are in the page's language (the option `lang`, German by
+// default). The browser imports only this module of the questions (@lernapps/app-templates/questions/engine), which
+// has no build-time code: its types and the id of a question. Used on the element that renderQuestion rendered:
+//
+//   startQuestion(element, question);
+import { moveFocus } from "@lernapps/tooling/a11y";
+import { translator } from "@lernapps/tooling/i18n";
+import { textsIn } from "../languages.ts";
+import { QUESTION_MESSAGES } from "./render.ts";
+import {
+  hash,
+  isComplete,
+  isCorrect,
+  missesRight,
+  shuffled,
+  wrongReasons,
+  type Answer,
+  type Question,
+} from "./question.ts";
+
+/** The learner's answer as the form holds it; undefined when nothing is given yet. */
+export function readAnswer(question: Question, form: HTMLFormElement): Answer | undefined {
+  const checked = [...form.querySelectorAll<HTMLInputElement>("input:checked")].map((input) => input.value);
+  switch (question.type) {
+    case "single-choice":
+      return checked[0] === undefined ? undefined : Number(checked[0]);
+    case "multiple-choice":
+      return checked.map(Number);
+    case "true-false":
+      return checked[0] === undefined ? undefined : checked[0] === "true";
+    case "number":
+      return form.querySelector<HTMLInputElement>("input")?.value ?? "";
+    case "ordering":
+    case "matching": {
+      const key = question.type === "ordering" ? "item" : "left";
+      const answer: number[] = [];
+      for (const select of form.querySelectorAll<HTMLSelectElement>(`select[data-${key}]`)) {
+        answer[Number(select.dataset[key])] = select.value === "" ? -1 : Number(select.value);
+      }
+      return answer;
+    }
+  }
+}
+
+/** The indices of the options the learner chose, for the question types with options. */
+function chosenOptions(question: Question, answer: Answer): number[] {
+  if (question.type !== "single-choice" && question.type !== "multiple-choice") return [];
+  return typeof answer === "number" ? [answer] : typeof answer === "object" ? [...answer] : [];
+}
+
+export { questionId, type Answer, type Question } from "./question.ts";
+
+/** What a page that runs one question may set. */
+export interface StartQuestionOptions {
+  /** Shows the options of a choice in an order given by this seed and the question; as rendered without one. */
+  seed?: number;
+  /** The page's language, for the feedback (German by default; the question is already in it). */
+  lang?: string;
+  /** What went wrong in a wrong answer, e.g. a typical mistake; shown under the feedback before any other reason. */
+  diagnose?: (answer: Answer) => string | undefined;
+  /**
+   * A wrong answer may be tried again, as an exercise does: the controls stay open, the feedback says why the answer
+   * is wrong and offers "Lösung zeigen"; the solution shows only after the right answer or that button. Without it,
+   * as in a quiz round, every complete answer locks the question and shows its solution at once.
+   */
+  retry?: boolean;
+  /**
+   * Called on each complete answer, right or wrong; once in a quiz round, where the answer locks the question. `said`
+   * is what the feedback says about a wrong answer, word for word as the question's texts have it (its formulas as
+   * written): the reasons, each with its option, without the verdict and the offer to try again; "" for a right one.
+   */
+  onAnswer?: (answer: Answer, right: boolean, said: string) => void;
+  /** Called once, when the solution shows. */
+  onReveal?: () => void;
+  /** How a text of the question that the feedback quotes becomes HTML (its formulas); plain text without it. */
+  format?: (text: string) => string;
+}
+
+/**
+ * Makes one rendered question (`item`, the element of renderQuestion) live: the button to check it shows; a complete
+ * answer gets its feedback, with a wrong one the most specific reason the question gives (the diagnosis, the
+ * background of each wrong option chosen, a number's typical mistake, else its hint). Then the solution shows: the
+ * background of every option with the right ones and the learner's choice marked, the explanation and further
+ * reading; the controls are locked, the button to the next question shows if there is one, and the focus moves to the
+ * feedback. With `retry`, a wrong answer keeps the controls open and offers "Lösung zeigen" instead. An incomplete
+ * answer is asked to be completed.
+ */
+export function startQuestion(item: HTMLElement, question: Question, options: StartQuestionOptions = {}): void {
+  const t = translator(textsIn(QUESTION_MESSAGES, options.lang ?? "de"));
+  const form = item.querySelector("form");
+  const feedback = item.querySelector<HTMLElement>(".question-feedback");
+  const check = item.querySelector<HTMLButtonElement>(".question-check");
+  const next = item.querySelector<HTMLButtonElement>(".question-next");
+  if (!form || !feedback || !check) return;
+  const doc = item.ownerDocument;
+  // the options of a choice in an order of their own, from the seed and the question
+  const fieldset = item.querySelector("fieldset");
+  if (
+    options.seed !== undefined &&
+    fieldset &&
+    (question.type === "single-choice" || question.type === "multiple-choice")
+  ) {
+    const labels = [...fieldset.querySelectorAll(".question-option")];
+    for (const index of shuffled(labels.length, options.seed ^ hash(question.id))) {
+      const label = labels[index];
+      if (label) fieldset.append(label);
+    }
+  }
+  const actions = item.querySelector<HTMLElement>(".question-actions");
+  if (actions) actions.hidden = false;
+  // "Lösung zeigen", after a wrong answer of a question that may be tried again
+  let solve: HTMLButtonElement | undefined;
+  if (options.retry === true) {
+    solve = doc.createElement("button");
+    solve.type = "button";
+    solve.className = "question-solve";
+    solve.textContent = t("showSolution");
+    solve.hidden = true;
+    check.after(" ", solve);
+  }
+  // what the feedback says about the answer, for onAnswer
+  let said: string[] = [];
+  const line = (text: string, option?: string) => {
+    said.push(option === undefined ? text : `${option}: ${text}`);
+    const why = doc.createElement("p");
+    why.className = "question-diagnosis";
+    if (option !== undefined) {
+      const name = doc.createElement("strong");
+      if (options.format) name.innerHTML = `${options.format(option)}:`;
+      else name.textContent = `${option}:`;
+      why.append(name, " ");
+    }
+    if (options.format) why.insertAdjacentHTML("beforeend", options.format(text));
+    else why.append(text);
+    feedback.append(why);
+  };
+  let answered = false;
+  let last: Answer | undefined;
+
+  /** The solution: every option's background, the right ones marked, the learner's last choice marked too. */
+  const reveal = () => {
+    answered = true;
+    const solution = item.querySelector<HTMLElement>(".question-reveal");
+    for (const index of last === undefined ? [] : chosenOptions(question, last)) {
+      const option = solution?.querySelector<HTMLElement>(`[data-option="${index}"]`);
+      if (!option) continue;
+      option.classList.add("question-info-chosen");
+      const badge = doc.createElement("span");
+      badge.className = "question-badge question-badge-chosen";
+      badge.textContent = t("yourChoice");
+      option.querySelector(".question-info-head")?.append(" ", badge);
+    }
+    if (solution) solution.hidden = false;
+    for (const control of form.querySelectorAll<HTMLInputElement | HTMLSelectElement>("input, select")) {
+      control.disabled = true;
+    }
+    check.hidden = true;
+    if (solve) solve.hidden = true;
+    if (next) next.hidden = false;
+    options.onReveal?.();
+  };
+
+  form.addEventListener("submit", (event) => {
+    event.preventDefault();
+    if (answered) return;
+    const answer = readAnswer(question, form);
+    if (!isComplete(question, answer)) {
+      feedback.textContent = t("incomplete");
+      feedback.className = "question-feedback";
+      return;
+    }
+    last = answer;
+    said = [];
+    const right = isCorrect(question, answer);
+    feedback.className = `question-feedback ${right ? "question-right" : "question-wrong"}`;
+    feedback.textContent = t(right ? "right" : "wrong");
+    if (!right) {
+      // the most specific reason: the diagnosis, else what the question says about this answer; the background of a
+      // chosen option only where the solution does not show it right away
+      const diagnosis = options.diagnose?.(answer);
+      const reasons =
+        diagnosis !== undefined
+          ? [{ text: diagnosis }]
+          : wrongReasons(question, answer).filter((reason) => options.retry === true || reason.option === undefined);
+      for (const reason of reasons) line(reason.text, reason.option);
+      const missing = missesRight(question, answer);
+      if (diagnosis === undefined && missing) line(t("missingRight"));
+      if (options.retry === true && reasons.length === 0 && !missing) line(t("lookAgain"));
+    }
+    const told = said.join(" ");
+    if (!right && options.retry === true) line(t("tryAgain"));
+    options.onAnswer?.(answer, right, told);
+    if (right || options.retry !== true) reveal();
+    else if (solve) solve.hidden = false;
+    // the focus on the feedback, not on the button below the background: the feedback stays in view, a screen
+    // reader reads it, and the next tab stops are the links of the background, then the button
+    moveFocus(feedback);
+  });
+  solve?.addEventListener("click", () => {
+    if (answered) return;
+    reveal();
+    // the focus on the solution, which shows below the feedback in place of the button
+    moveFocus(item.querySelector<HTMLElement>(".question-reveal") ?? feedback);
+  });
+}

package/runtime/shared/questions/index.ts

@@ -0,0 +1,39 @@
+// The questions of a lernapps app, for every archetype that has them (@lernapps/app-templates/questions), at build
+// time and in Node: the six types of question and their checker, the schema of a question for a `$ref` from another
+// schema, the validation of one question, the rendering of its controls and of its solution without JavaScript, and
+// the messages. In the browser, startQuestion (@lernapps/app-templates/questions/engine) makes a rendered question
+// live; the end-to-end helpers are in @lernapps/app-templates/questions/e2e. A page embeds a question as
+//
+//   renderQuestion(question) +
+//   `<details><summary>${messages.solution}</summary>${renderSolution(question)}</details>`
+//
+// and fails its build when validateQuestion(question, "<where it is>") finds problems. A page in several languages
+// writes each learner text of a question as a map, { de: …, en: … }: validateQuestion(question, at, languages) checks
+// that each declared language is there (German always), questionIn(question, lang) gives the question in the page's
+// language for the checker, and renderQuestion and renderSolution take the page's `lang` for their own texts.
+import de from "./messages/de.json" with { type: "json" };
+
+export * from "./question.ts";
+export {
+  answerText,
+  QUESTION_MESSAGES,
+  questionMessagesIn,
+  renderQuestion,
+  renderSolution,
+  type QuestionMessages,
+  type RenderQuestionOptions,
+  type RenderSolutionOptions,
+} from "./render.ts";
+export {
+  QUESTION_REF,
+  QUESTION_SCHEMA_ID,
+  questionDetails,
+  questionSchema,
+  questionSchemas,
+  questionSchemaProblems,
+  validateQuestion,
+  type QuestionProblem,
+} from "./validate.ts";
+
+/** The texts of a question for learners in German, by their key (messages/de.json); questionMessagesIn(lang) for another. */
+export const messages = de;