@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/explainer/video.ts

@@ -0,0 +1,123 @@
+// The video block of an explainer: a YouTube video behind two clicks. Nothing loads from YouTube or Google before the
+// learner asks for it. The build writes a figure with the video's title as a plain link to its page on youtube.com,
+// its channel and a note that playing it sends data to YouTube/Google, among them the learner's IP address: that is
+// the whole video without JavaScript. No thumbnail, as YouTube's would load before a click. The client module then
+// shows the button "Video abspielen", which puts the player of youtube-nocookie.com into the figure, and the choice
+// "Videos immer direkt laden". That choice is kept on the device (@lernapps/tooling/storage, the app's own prefix),
+// is the same for every video of the app, loads each player without the click from then on, and goes when the learner
+// clears it. The tutor page names the video in its section as a link with title and channel (videoLine). Browser-safe:
+// render.ts writes the figure at build, explainer.ts starts it in the browser.
+import { createStorage } from "@lernapps/tooling/storage";
+import type { BlockOf } from "./content.ts";
+import { escape } from "../shared/html.ts";
+import { message } from "./messages.ts";
+
+const YOUTUBE_ID = /^[A-Za-z0-9_-]{11}$/;
+
+/** Whether `id` is a YouTube id: 11 letters, digits, - or _. */
+export const isYoutubeId = (id: unknown): id is string => typeof id === "string" && YOUTUBE_ID.test(id);
+
+function checked(id: string): string {
+  if (!isYoutubeId(id)) throw new Error(`${JSON.stringify(id)} is no YouTube id`);
+  return id;
+}
+
+/** The video's page on YouTube, which the link opens: no request before the learner clicks it. */
+export const watchAddress = (id: string): string => `https://www.youtube.com/watch?v=${checked(id)}`;
+
+/** The player of the video on youtube-nocookie.com, which starts at once when the learner clicked for it. */
+export const embedAddress = (id: string, autoplay: boolean): string =>
+  `https://www.youtube-nocookie.com/embed/${checked(id)}${autoplay ? "?autoplay=1" : ""}`;
+
+/** A text as Markdown that shows it as written: its brackets, emphasis, code, formulas and HTML escaped. */
+const literal = (text: string) =>
+  text
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/[\\`*_[\]<&$]/g, "\\$&");
+
+/**
+ * The video as a KI tutor reads it in the page's content (tutor.ts): one line, `word` (e.g. "Video"), the title as a
+ * link to its page on YouTube, and the channel. A source the tutor can name; it cannot watch the video.
+ */
+export const videoLine = (block: BlockOf<"video">, word: string): string =>
+  `${word}: [${literal(block.title)}](${watchAddress(block.youtube)}), ${literal(block.channel)} (YouTube)`;
+
+/** The key "Videos immer direkt laden" is kept under on the device, for every video of the app. */
+export const VIDEO_KEY = "videos-direct";
+
+/**
+ * A video block as the build writes it: a figure with the title as a link to YouTube and the channel as its caption,
+ * the note on privacy, and the button and the choice, hidden until the client module runs. `storage` is the app's
+ * name for what it keeps on the device.
+ */
+export function renderVideo(block: BlockOf<"video">, lang: string, storage: string): string {
+  const t = (key: "videoNote" | "videoPlay" | "videoAlways") => escape(message(lang, key));
+  return [
+    `<figure class="explainer-video" data-youtube="${escape(block.youtube)}" data-storage="${escape(storage)}">`,
+    `<figcaption><a class="explainer-video-link" href="${escape(watchAddress(block.youtube))}" rel="noopener">${escape(block.title)}</a>`,
+    ` <span class="explainer-video-channel">${escape(message(lang, "videoChannel", { channel: block.channel }))}</span></figcaption>`,
+    `<p class="explainer-video-note">${t("videoNote")}</p>`,
+    `<p class="explainer-video-controls" hidden><button type="button" class="explainer-video-play">${t("videoPlay")}</button>`,
+    ` <label class="explainer-video-always"><input type="checkbox"> ${t("videoAlways")}</label></p>`,
+    `</figure>`,
+  ].join("");
+}
+
+const isTrue = (value: unknown): value is true => value === true;
+
+/**
+ * Puts the player of the video into its figure, above the caption, in place of the button. After a click it starts
+ * at once and gets the focus; loaded directly, it waits to be scrolled near and to be started.
+ */
+function loadPlayer(figure: HTMLElement, id: string, clicked: boolean): void {
+  if (figure.querySelector("iframe")) return;
+  const document = figure.ownerDocument;
+  const frame = document.createElement("div");
+  frame.className = "explainer-video-frame";
+  const player = document.createElement("iframe");
+  player.src = embedAddress(id, clicked);
+  player.title = figure.querySelector(".explainer-video-link")?.textContent ?? "";
+  player.allow = "autoplay; encrypted-media; picture-in-picture; fullscreen";
+  player.allowFullscreen = true;
+  // YouTube learns the app's origin, never the page's address with its task numbers or via=tutor
+  player.referrerPolicy = "strict-origin-when-cross-origin";
+  if (!clicked) player.loading = "lazy";
+  frame.append(player);
+  figure.prepend(frame);
+  figure.querySelector(".explainer-video-play")?.remove();
+  if (clicked) player.focus();
+}
+
+/**
+ * Starts every video of the page: the button and the choice show; the button loads the player. The choice is kept
+ * on the device as soon as the learner ticks it, goes as soon as they untick it, and is shown alike on every video of
+ * the page; while it is kept, each player loads without the click.
+ */
+export function startVideos(root: Document): void {
+  const figures = [...root.querySelectorAll<HTMLElement>("figure.explainer-video")];
+  const boxes = figures.flatMap((figure) => [
+    ...figure.querySelectorAll<HTMLInputElement>(".explainer-video-always input"),
+  ]);
+  for (const figure of figures) {
+    const id = figure.dataset["youtube"];
+    const controls = figure.querySelector<HTMLElement>(".explainer-video-controls");
+    if (!isYoutubeId(id) || !controls) continue;
+    const storage = createStorage(figure.dataset["storage"] ?? "explainer");
+    const box = controls.querySelector<HTMLInputElement>("input");
+    const direct = storage.load(VIDEO_KEY, isTrue) === true;
+    if (box) {
+      box.checked = direct;
+      box.addEventListener("change", () => {
+        if (box.checked) storage.save(VIDEO_KEY, true);
+        else storage.remove(VIDEO_KEY);
+        for (const other of boxes) other.checked = box.checked;
+      });
+    }
+    controls
+      .querySelector(".explainer-video-play")
+      ?.addEventListener("click", () => loadPlayer(figure, id, true), { once: true });
+    controls.hidden = false;
+    if (direct) loadPlayer(figure, id, false);
+  }
+}

package/runtime/interactive/contract.ts

@@ -0,0 +1,121 @@
+// The contract between the runtime of an interactive app and the app's core (src/core/index.ts), and its
+// playthroughs (src/playthroughs/*.yaml). The core is the app's logic: pure TypeScript without DOM, deterministic by
+// its seed, its state plain JSON data. The runtime keeps the state: it starts it with start(seed, route), gives every
+// input to step(state, input), a key the learner types or an input the app's root component emits, and calls
+// tick(state, TICK) every TICK milliseconds when the core has it; the app's components only show the state. A
+// playthrough is a seed, a route and a list of steps: inputs, then ticks (time passing), and the state (a part of it)
+// or the announcement expected after them. The build plays each against the core (plugin.ts); the end-to-end tests
+// play the same inputs and ticks in the browser (e2e.ts). Used in the browser and in Node alike.
+
+/** A JSON value: what an action input carries. */
+export type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };
+
+/**
+ * A key the learner typed, as the browser names it (KeyboardEvent.key: "a", "A", "Enter", " ", "ArrowLeft"); the
+ * root component may emit one too.
+ */
+export interface KeyInput {
+  kind: "key";
+  key: string;
+}
+
+/**
+ * An action the app's root component emits as input, for what the learner does with the pointer or by touch: the
+ * name the app gives it (e.g. "again", "pick"), and a JSON value if it needs one (e.g. the cell picked).
+ */
+export interface ActionInput {
+  kind: "action";
+  name: string;
+  value?: Json;
+}
+
+/**
+ * An input to the core. Told apart by its kind; later versions of the runtime may add kinds, so a core handles the
+ * kinds it knows and returns the state unchanged for any other.
+ */
+export type Input = KeyInput | ActionInput;
+
+/**
+ * The core of an interactive app, the exports of src/core/index.ts. `route` is the id of the hash route the app was
+ * opened at (app/#<id>, a route of src/app.yaml), the first route when the address names none, "" when the app has
+ * no routes. step returns the same state object for an input it ignores, so that a key keeps its default (Tab moves
+ * the focus).
+ */
+export interface Core<S> {
+  start(seed: number, route: string): S;
+  step(state: S, input: Input): S;
+  tick?(state: S, dt: number): S;
+}
+
+/** The milliseconds from one tick to the next: the runtime calls tick(state, TICK) every TICK ms. */
+export const TICK = 20;
+
+/** The property of the app's element that holds the state, for the end-to-end tests. */
+export const STATE_PROPERTY = "lernappsState";
+
+/**
+ * The global of the end-to-end tests' clock: when the page has it (an object, set before the client module runs),
+ * the runtime starts no interval and puts on it tick(count), which calls tick(state, TICK) count times, the same as
+ * count intervals would. Only the tests set it; for a learner, time passes on its own.
+ */
+export const CLOCK_PROPERTY = "lernappsClock";
+
+/**
+ * One step of a playthrough: keys (the short form of key inputs) or inputs, then ticks, the time that passes after
+ * them (ticks × TICK ms); then what is expected, the state (a part of it), the announcement, or both.
+ */
+export interface PlaythroughStep {
+  keys?: readonly string[];
+  inputs?: readonly Input[];
+  ticks?: number;
+  state?: unknown;
+  announce?: string;
+}
+
+/** A playthrough: the route and seed it starts with, and its steps. */
+export interface Playthrough {
+  route?: string;
+  seed: number;
+  steps: readonly PlaythroughStep[];
+}
+
+/** The inputs of a step, its keys as key inputs. */
+export function inputsOf(step: PlaythroughStep): Input[] {
+  return step.inputs !== undefined ? [...step.inputs] : (step.keys ?? []).map((key): Input => ({ kind: "key", key }));
+}
+
+/** An input as a playthrough's problem names it: a key as its JSON text, an action with its name and value. */
+export function inputText(input: Input): string {
+  if (input.kind === "key") return JSON.stringify(input.key);
+  return `action ${JSON.stringify(input.name)}${input.value === undefined ? "" : ` ${JSON.stringify(input.value)}`}`;
+}
+
+/** What a step does, as a playthrough's problem names it: its inputs, then its ticks. */
+export function doingText(step: PlaythroughStep): string[] {
+  const ticks = step.ticks === undefined ? [] : [`${step.ticks} tick${step.ticks === 1 ? "" : "s"}`];
+  return [...inputsOf(step).map(inputText), ...ticks];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Where `actual` differs from `expected`: the path of the first difference, with the value found there, or undefined
+ * when it matches. An object expects only the fields it names (each compared in the same way); anything else, a list
+ * too, is compared as a whole.
+ */
+export function mismatch(
+  actual: unknown,
+  expected: unknown,
+  path: readonly (string | number)[] = [],
+): { path: (string | number)[]; actual: unknown } | undefined {
+  if (isRecord(expected)) {
+    if (!isRecord(actual)) return { path: [...path], actual };
+    for (const [key, value] of Object.entries(expected)) {
+      const found = mismatch(actual[key], value, [...path, key]);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+  return JSON.stringify(actual) === JSON.stringify(expected) ? undefined : { path: [...path], actual };
+}

package/runtime/interactive/e2e.ts

@@ -0,0 +1,190 @@
+// The end-to-end tests of every interactive app (@lernapps/app-templates/interactive/e2e), run by `lernapps check
+// --pre-push` on the built app. An app's e2e/interactive.e2e.ts is
+//
+//   import { interactiveTests } from "@lernapps/app-templates/interactive/e2e";
+//   interactiveTests();
+//
+// What they expect comes from src/app.yaml and src/playthroughs/ (load.ts), not from the rendered pages. Without
+// JavaScript, in every language: the start page shows the title, what the app does, the note that the app needs
+// JavaScript, the link into the app, a link to each route, how to play, each competency and each background section,
+// and loads no script; the app page shows the title, the note with a link back to the start page, and an element
+// with each route's id; each page has its language, its alternates, a language switch and the archetype marker. With
+// JavaScript, in German: the app page mounts the app without a console error, and every playthrough plays at its
+// address (app/?seed=<seed>#<route>) on the tests' clock (CLOCK_PROPERTY), on which no time passes but the ticks a
+// step names, as in the build: each step's inputs one after the other, a key pressed on the keyboard with the focus
+// on the page, an action emitted as input by the app's root component, as the component itself does; then its ticks,
+// stepped through the runtime's own tick; after each step the state it expects (the fields it names, read from the
+// runtime) and the announcement it expects (the polite live region of @lernapps/tooling/a11y). The tests run in
+// parallel, with reduced motion; the preset runs them at desktop width and at 360 px; `lernapps check` adds axe and
+// the width on the pages it visits.
+import { expect, test, type Page } from "playwright/test";
+import { inLanguage } from "../shared/languages.ts";
+import { languageRoot } from "../shared/pages.ts";
+import { CLOCK_PROPERTY, doingText, inputsOf, mismatch, STATE_PROPERTY } from "./contract.ts";
+import { loadInteractive } from "./load.ts";
+import { message } from "./messages.ts";
+import { APP_PAGE } from "./render.ts";
+
+/** The page's language, its alternates and a switch to each other language, the archetype marker. */
+async function expectFrame(page: Page, lang: string, languages: readonly string[]): Promise<void> {
+  await expect(page.locator("html")).toHaveAttribute("lang", lang);
+  await expect(page.locator('meta[name="lernapps-archetype"]')).toHaveAttribute("content", "interactive");
+  for (const other of languages) {
+    await expect(page.locator(`link[rel="alternate"][hreflang="${other}"]`)).toHaveCount(1);
+    if (other === lang) continue;
+    const link = page.locator(`.page-languages a[hreflang="${other}"]`);
+    await expect(link).toBeVisible();
+    const response = await page.request.get(await link.evaluate((a) => (a as HTMLAnchorElement).href));
+    expect(response.status(), `the switch to ${other}`).toBe(200);
+  }
+}
+
+/** Collects the page's console errors and uncaught exceptions. */
+function consoleErrors(page: Page): string[] {
+  const errors: string[] = [];
+  page.on("console", (entry) => {
+    if (entry.type() === "error") errors.push(entry.text());
+  });
+  page.on("pageerror", (error) => errors.push(error.message));
+  return errors;
+}
+
+/** The instance of a component, as Vue mounts it. */
+type Instance = { emit(event: string, payload: unknown): void; subTree?: { component?: Instance } };
+
+/** Emits `input` (an Input) as input from the app's root component in `host`, as the component itself does. */
+function emitInput(host: Element, input: unknown): void {
+  const wrapper = (host as unknown as { _vnode?: { component?: Instance } })._vnode?.component;
+  const root = wrapper?.subTree?.component;
+  if (root === undefined) throw new Error("the app's root component is not mounted");
+  root.emit("input", input);
+}
+
+/** Steps `count` ticks on the tests' clock of the page, the global `property`. */
+function stepTicks({ count, property }: { count: number; property: string }): void {
+  (Reflect.get(globalThis, property) as { tick(count: number): void }).tick(count);
+}
+
+/**
+ * Presses `key` as the learner does. Playwright knows only the keys of a US keyboard by name; any other character
+ * (ä, ö, ü, ß, é) goes as the keydown event the runtime listens to, with that key.
+ */
+async function pressKey(page: Page, key: string): Promise<void> {
+  if (key.length === 1 && key > "~")
+    await page.evaluate((pressed) => {
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: pressed, bubbles: true, cancelable: true }));
+    }, key);
+  else await page.keyboard.press(key);
+}
+
+/** The interactive app's tests, for the app in `root`. */
+export function interactiveTests(root = "."): void {
+  const { app, playthroughs } = loadInteractive(root);
+  const routes = app.routes ?? [];
+
+  test.describe("interactive", () => {
+    test.describe.configure({ mode: "parallel" });
+    test.use({ reducedMotion: "reduce" });
+
+    test.describe("without JavaScript", () => {
+      test.use({ javaScriptEnabled: false });
+
+      for (const lang of app.languages) {
+        const start = languageRoot(lang);
+        const text = (value: Parameters<typeof inLanguage>[0]) => inLanguage(value, lang).replace(/\s+/g, " ").trim();
+
+        test(`${start || "./"}: the start page says what the app does, how to play and what one learns`, async ({
+          page,
+        }) => {
+          await page.goto(`./${start}`);
+          await expectFrame(page, lang, app.languages);
+          const main = page.locator("main");
+          await expect(main.locator("h1")).toHaveText(text(app.title));
+          await expect(main.locator(".interactive-intro")).toBeVisible();
+          await expect(main.locator(".interactive-noscript"), "the note that the app needs JavaScript").toBeVisible();
+          const play = main.locator("a.interactive-start");
+          await expect(play).toBeVisible();
+          const response = await page.request.get(await play.evaluate((a) => (a as HTMLAnchorElement).href));
+          expect(response.status(), "the link into the app").toBe(200);
+          for (const route of routes) {
+            const link = main.locator(`a[href$="${APP_PAGE}#${route.id}"]`);
+            await expect(link, `the link to the route ${route.id}`).toHaveText(text(route.title));
+          }
+          await expect(
+            main.getByRole("heading", { level: 2, name: message(lang, "howto"), exact: true }),
+          ).toBeVisible();
+          for (const competency of app.competencies) {
+            await expect(main.locator(".interactive-competencies li", { hasText: text(competency) })).toBeVisible();
+          }
+          for (const section of app.sections ?? []) {
+            await expect(main.locator(`h2[id="${section.id}"]`), `the section ${section.id}`).toHaveText(
+              text(section.title),
+            );
+          }
+          expect(await page.locator("script").count(), "the start page loads no script").toBe(0);
+        });
+
+        test(`${start}${APP_PAGE}: the app page says that the app needs JavaScript and has each route's anchor`, async ({
+          page,
+        }) => {
+          await page.goto(`./${start}${APP_PAGE}`);
+          await expectFrame(page, lang, app.languages);
+          const main = page.locator("main");
+          await expect(main.locator("h1"), "one h1: the title").toHaveText(text(app.title));
+          await expect(page.locator(".interactive-title-slot"), "the slot of the heading line").toBeHidden();
+          const note = main.locator(".interactive-noscript");
+          await expect(note, "the note that the app needs JavaScript").toBeVisible();
+          const back = await note.locator("a").evaluate((a) => (a as HTMLAnchorElement).href);
+          expect(back, "the note links the start page").toBe(new URL("../", page.url()).href);
+          for (const route of routes) {
+            await expect(main.locator(`[id="${route.id}"]`), `the anchor of the route ${route.id}`).toHaveText(
+              text(route.title),
+            );
+          }
+        });
+      }
+    });
+
+    test.describe("with JavaScript", () => {
+      test(`${APP_PAGE}: the app mounts without a console error`, async ({ page }) => {
+        const errors = consoleErrors(page);
+        await page.goto(`./${APP_PAGE}`);
+        await expect(page.locator(".interactive-app")).toHaveAttribute("data-mounted", "");
+        await expect(page.locator(".interactive-app")).not.toBeEmpty();
+        expect(errors, "no console error").toEqual([]);
+      });
+
+      for (const { yaml, playthrough } of playthroughs) {
+        const route = playthrough.route ?? routes[0]?.id;
+        test(`${yaml.file}: played with its inputs and ticks`, async ({ page }) => {
+          const errors = consoleErrors(page);
+          // before the client module runs: the runtime then starts no interval, and time passes only by stepTicks
+          await page.addInitScript((property) => Reflect.set(globalThis, property, {}), CLOCK_PROPERTY);
+          await page.goto(`./${APP_PAGE}?seed=${playthrough.seed}${route === undefined ? "" : `#${route}`}`);
+          const host = page.locator(".interactive-app");
+          await expect(host).toHaveAttribute("data-mounted", "");
+          // the polite live region of @lernapps/tooling/a11y, which announce() fills
+          const live = page.locator('body > [aria-live="polite"]');
+          for (const [index, step] of playthrough.steps.entries()) {
+            for (const input of inputsOf(step)) {
+              if (input.kind === "key") await pressKey(page, input.key);
+              else await host.evaluate(emitInput, input as unknown);
+            }
+            if (step.ticks !== undefined)
+              await page.evaluate(stepTicks, { count: step.ticks, property: CLOCK_PROPERTY });
+            const where = `${yaml.file}: steps[${index}] after ${doingText(step).join(", ")}`;
+            if (step.state !== undefined) {
+              const state = await host.evaluate(
+                (element, property) => (element as unknown as Record<string, unknown>)[property],
+                STATE_PROPERTY,
+              );
+              expect(mismatch(state, step.state), `${where}: the state`).toBeUndefined();
+            }
+            if (step.announce !== undefined) await expect(live, `${where}: the announcement`).toHaveText(step.announce);
+          }
+          expect(errors, "no console error").toEqual([]);
+        });
+      }
+    });
+  });
+}

package/runtime/interactive/interactive.css

@@ -0,0 +1,82 @@
+/* The look of an interactive app's shell (@lernapps/app-templates/interactive/style.css): the frame is shared
+   (page.css); this is the start page and the frame of the app page. The app styles its own components. */
+@import "../shared/page.css";
+
+.interactive {
+  /* an app that needs a wider frame sets --page-max-width in its own :root rule (here only the fallback, so
+     that the order of the stylesheets does not matter) */
+  max-width: var(--page-max-width, 44rem);
+  margin: 0 auto;
+  padding: 0 1rem;
+  overflow-wrap: break-word;
+}
+
+.interactive-routes ul {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 0.75rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.interactive-routes a[aria-current="true"] {
+  color: var(--page-text);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.interactive h1 {
+  font-size: 1.875rem;
+  line-height: 1.2;
+}
+
+.interactive-title {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0 1rem;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.interactive-title h1 {
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.interactive-title-slot {
+  flex: 0 0 auto;
+}
+
+.interactive h2 {
+  line-height: 1.25;
+  scroll-margin-top: 1rem;
+}
+
+.interactive-noscript {
+  padding: 0.5rem 1rem;
+  border-left: 4px solid var(--page-accent);
+  background: var(--page-surface);
+}
+
+.interactive-start {
+  display: inline-block;
+  padding: 0.5rem 1.25rem;
+  border-radius: 0.375rem;
+  background: var(--page-accent);
+  color: var(--page-on-accent);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.interactive-description {
+  color: var(--page-muted);
+}
+
+.interactive-routes {
+  margin: 1rem 0;
+}
+
+.interactive-app {
+  margin: 1rem 0 2rem;
+}

package/runtime/interactive/interactive.ts

@@ -0,0 +1,115 @@
+// The client module of an interactive app (@lernapps/app-templates/interactive), started by the app's src/main.ts:
+//
+//   import "@lernapps/app-templates/interactive/style.css";
+//   import { startInteractive } from "@lernapps/app-templates/interactive";
+//   import * as core from "./core/index.ts";
+//   import App from "./ui/App.vue";
+//   startInteractive(core, App);
+//
+// An app that wants a small control in the heading line (next to the h1: "Help", "Sound off") passes a component for
+// it as the option `title`: startInteractive(core, App, { title: Controls }). It gets the same props and emits the
+// same input as the root component, and is mounted into the slot of the heading line, which stays hidden (and empty)
+// without it.
+//
+// On the app page it keeps the core's state (contract.ts): it starts it with the seed of the address (?seed=<n>, else
+// a random one) and the route of the address (#<id>, else the first route), gives every key typed on the page to
+// step as a key input (not a key typed on a link, button or form field, which is theirs, nor one with Ctrl, Alt or
+// Meta), and calls tick every TICK ms when the core has it (the end-to-end tests step the ticks themselves:
+// CLOCK_PROPERTY). A key that changes the state loses its default (the space bar does not scroll). A new route in the
+// address starts the core again with it. It mounts the app's root component into the page with the props state (the
+// core's state) and lang (the page's language), and steps every input the component emits as input (an action of a
+// button or a tap, or a key it stands for). The start page loads no script; the build removes it there.
+import { createApp, h, shallowRef, type Component } from "vue";
+import { CLOCK_PROPERTY, STATE_PROPERTY, TICK, type Core, type Input } from "./contract.ts";
+
+export {
+  TICK,
+  type ActionInput,
+  type Core,
+  type Input,
+  type Json,
+  type KeyInput,
+  type Playthrough,
+  type PlaythroughStep,
+} from "./contract.ts";
+
+/** Where a key belongs to the page's own controls, not to the app. */
+const CONTROLS = "a[href], button, input, select, textarea, summary, [contenteditable]";
+
+/** What an app may add to the shell. */
+export interface InteractiveOptions {
+  /**
+   * A component for the slot in the heading line, beside the h1. It is given the props of the root component, `state`
+   * and `lang`, and emits `input` the same way.
+   */
+  title?: Component;
+}
+
+/**
+ * Starts the app on the app page: its state from `core`, shown by the component `root`, and in the heading line the
+ * component `options.title` if there is one. Nothing on another page.
+ */
+export function startInteractive<S>(core: Core<S>, root: Component, options: InteractiveOptions = {}): void {
+  const host = document.querySelector<HTMLElement>(".interactive-app");
+  if (host === null) return;
+  const routes = JSON.parse(host.dataset["routes"] ?? "[]") as string[];
+  const seedParam = Number(new URL(location.href).searchParams.get("seed"));
+  const seed = Number.isInteger(seedParam) && seedParam > 0 ? seedParam : 1 + Math.floor(Math.random() * 2 ** 31 - 1);
+  const routeOf = (): string => {
+    const id = decodeURIComponent(location.hash.slice(1));
+    return routes.includes(id) ? id : (routes[0] ?? "");
+  };
+  let route = routeOf();
+  const state = shallowRef(core.start(seed, route));
+  const set = (next: S): void => {
+    state.value = next;
+    Object.assign(host, { [STATE_PROPERTY]: next });
+  };
+  set(state.value);
+  const markRoute = (): void => {
+    for (const link of document.querySelectorAll<HTMLAnchorElement>(".interactive-routes a")) {
+      if (link.hash === `#${route}`) link.setAttribute("aria-current", "true");
+      else link.removeAttribute("aria-current");
+    }
+  };
+  markRoute();
+  /** Gives `given` to the core; whether it changed the state. */
+  const input = (given: Input): boolean => {
+    const next = core.step(state.value, given);
+    if (next === state.value) return false;
+    set(next);
+    return true;
+  };
+  document.addEventListener("keydown", (event) => {
+    if (event.ctrlKey || event.altKey || event.metaKey || event.isComposing) return;
+    if (event.target instanceof Element && event.target.closest(CONTROLS) !== null) return;
+    if (input({ kind: "key", key: event.key })) event.preventDefault();
+  });
+  addEventListener("hashchange", () => {
+    if (routeOf() === route) return;
+    route = routeOf();
+    set(core.start(seed, route));
+    markRoute();
+  });
+  const tick = (): void => set(core.tick?.(state.value, TICK) ?? state.value);
+  const clock: unknown = Reflect.get(globalThis, CLOCK_PROPERTY);
+  if (typeof clock === "object" && clock !== null) {
+    // the end-to-end tests' clock: no time passes but the ticks they step
+    Object.assign(clock, {
+      tick: (count: number) => {
+        for (let at = 0; at < count; at++) tick();
+      },
+    });
+  } else if (core.tick !== undefined) setInterval(tick, TICK);
+  const lang = document.documentElement.lang || "de";
+  const mount = (component: Component, into: HTMLElement): void => {
+    createApp({ render: () => h(component, { state: state.value, lang, onInput: input }) }).mount(into);
+  };
+  const slot = document.querySelector<HTMLElement>(".interactive-title-slot");
+  if (options.title !== undefined && slot !== null) {
+    mount(options.title, slot);
+    slot.hidden = false;
+  }
+  mount(root, host);
+  host.dataset["mounted"] = "";
+}