@lernapps/app-templates 0.0.1 → 0.1.1

package/interactive/docs/arc42/09-interactive-decisions.arc42.md

@@ -0,0 +1,130 @@
+# Architecture Decisions
+
+The interactive archetype's decisions, besides the generic ones; decisions the runtime made when it was built
+(commit c5e7285, 2026-10-16) are accepted because they are in force. An app adds its own below these (for example
+canvas or DOM).
+
+## One Archetype for All Kinds
+
+Typing game, Kniffel trainer and proofreading app run differently (frame loop, turns, tasks) but share frame and
+rules. One archetype carries them all, and its skill gives the principles they share. Rejected: one archetype per kind. An
+app that needs explanation pages is an explainer with a component instead.
+
+```arc42
+:::decision
+id: dec-one-archetype
+title: One interactive archetype for every kind of app
+status: accepted
+date: 2026-10-16
+addresses: con-runtime-unchanged, qg-understandable
+:::
+```
+
+## The Runtime Owns the State and the Clock
+
+The core is pure TypeScript without DOM; the shell holds its state, starts it, steps it and calls `tick(state, 20)`
+every 20 ms when the core has `tick`, and the components only show the state. So the core plays the same in Node and
+in the browser, and a real-time app needs no loop of its own in the core. Rejected: state kept in components, a
+variable frame time. The fixed tick is the runtime's choice; the sketch names only `tick(state, dt)`.
+
+```arc42
+:::decision
+id: dec-runtime-owns-state
+title: The runtime holds the core's state and ticks it every 20 ms
+status: accepted
+date: 2026-10-16
+addresses: qg-checkable, con-runtime-unchanged
+:::
+```
+
+## Keys Are the Core's Input
+
+Superseded by `dec-typed-input`. The sketch named `step(state, input)`; the runtime made the input a key as the browser
+names it (`KeyboardEvent.key`), pointer input reaching the core as a key the root component emits as `input`, and a
+key the core ignores keeping its default (Tab moves the focus).
+
+```arc42
+:::decision
+id: dec-keys-as-input
+title: Keys as the core's only input
+status: superseded
+date: 2026-10-16
+addresses: qg-checkable, qg-accessibility
+:::
+```
+
+## A Typed Input for the Core
+
+Interactive apps will use more than keys and mouse: touch, gestures and other input later. So the core's
+`step(state, input)` takes a typed input (a key, a pointer or touch action, …), extensible by new kinds; playthroughs
+record such inputs, and the components translate any device input into inputs, so that the build and the browser play
+the same steps. Rejected: keys as the only input, with pointer and touch disguised as keys. Built: a key input and an
+action input; a core returns the state unchanged for a kind it does not know.
+
+```arc42
+:::decision
+id: dec-typed-input
+title: The core's input is typed and extensible (key, pointer, touch, …)
+status: accepted
+date: 2026-10-16
+supersedes: dec-keys-as-input
+addresses: qg-checkable, qg-accessibility
+:::
+```
+
+## start(seed, route)
+
+The sketch names `start(seed)`; the runtime also passes the route of the address, so that each mode or level has an
+address an entry's topics can point to and the core starts there. The seed comes from `?seed=<n>`, else at random, so
+a round can be replayed and tested at its address.
+
+```arc42
+:::decision
+id: dec-start-seed-route
+title: The core starts from a seed and a route of the address
+status: accepted
+date: 2026-10-16
+addresses: qg-checkable
+:::
+```
+
+## Playthroughs as Data
+
+A playthrough is a seed, a route and steps of inputs with the state or announcement expected after them, written as
+YAML under `src/playthroughs/`. The build plays each against the core twice and the browser plays the same inputs, so
+determinism and behaviour are checked without test code per app. A step can let n ticks pass; the build calls `tick`
+n times, and the browser steps the shell's tick through the tests' clock (`if-test-clock`) rather than Playwright's
+fake clock, which would also freeze the announcement's timer. The core's property tests over fixed seeds are not
+built; until then every playthrough played twice checks determinism. Rejected: free test code as the only behaviour
+check.
+
+```arc42
+:::decision
+id: dec-playthroughs-as-data
+title: Playthroughs as data, played in the build and in the browser
+status: accepted
+date: 2026-10-16
+addresses: qg-checkable, risk-no-core-property-tests
+:::
+```
+
+## Libraries in the Dependencies
+
+An interactive app may use libraries: its components and modules may import the packages listed in the dependencies
+of its package.json, which the build bundles; their licences are checked by `lernapps check` (`dependency-licence`).
+An import from a URL, network APIs, `eval`, `innerHTML` and `v-html` stay forbidden. The explainer's components keep
+their narrower scope. Rejected: only Vue, the runtime and the tooling helpers, which would make every app write again
+what a library already does well.
+
+```arc42
+:::decision
+id: dec-libraries
+title: An interactive app may import the libraries in its dependencies
+status: accepted
+date: 2026-10-16
+addresses: qg-privacy
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->

package/interactive/docs/arc42/10-interactive-quality-requirements.arc42.md

@@ -0,0 +1,45 @@
+# Quality Requirements
+
+The interactive archetype's scenarios, besides the generic ones.
+
+<!-- at the top of the generic chapter -->
+```arc42
+:::ignore W006 two high-priority goals is the owner's decision (2026-10-16): privacy and checkable high; the interactive archetype adds no goal of its own
+:::
+```
+<!-- end -->
+
+## The same inputs play the same twice
+
+At build, every playthrough is played against the core twice, with only the ticks its steps name; a core that draws
+from `Math.random` or
+the clock gives different states.
+
+```arc42
+:::quality-scenario
+id: qs-deterministic-core
+title: The same inputs give the same states
+quality: qg-checkable
+stimulus: The build plays a playthrough's seed, route and inputs against the core twice
+response: The build fails with one line naming the first step whose state differs, or whose state differs from the expected one
+metric: Both plays give identical states at every step and match every expected state, else the build fails
+:::
+```
+
+## Playthroughs in the browser
+
+`interactiveTests()` plays every playthrough at its address in the browser, at desktop width and at 360 px.
+
+```arc42
+:::quality-scenario
+id: qs-playthrough-in-browser
+title: Playthroughs play the same in the browser
+quality: qg-checkable
+stimulus: lernapps check --pre-push runs the e2e tests on the built app
+response: Each playthrough opens app/?seed=<seed>#<route> on the test clock, gives its inputs and ticks and compares the state and the polite announcement after each step
+metric: Every expected state and announcement matches, with no console error, at desktop width and 360 px
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->

package/interactive/docs/arc42/11-interactive-risks.arc42.md

@@ -0,0 +1,20 @@
+# Risks and Technical Debt
+
+The interactive archetype's risks, besides the generic ones, highest first.
+
+## Core Property Tests Not Built
+
+The sketch has the build run the core's property tests over fixed seeds; the build plays only the playthroughs, so a
+core is checked for the seeds its playthroughs name and no others.
+
+```arc42
+:::risk
+id: risk-no-core-property-tests
+title: Core property tests over fixed seeds not built
+severity: low
+mitigation: Planned; until then the build checks determinism with every playthrough played twice.
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->

package/interactive/docs/arc42/12-interactive-glossary.arc42.md

@@ -0,0 +1,80 @@
+# Glossary
+
+The interactive archetype's terms, besides the generic ones.
+
+## Core
+
+The app's logic in `src/core/index.ts`. Called "core" rather than "engine" or "model" because it holds no state of its
+own: the shell keeps it.
+
+```arc42
+:::glossary-term
+id: term-core
+title: Core
+definition: The app's logic, pure TypeScript without DOM, exporting start(seed, route), step(state, input) and optionally tick(state, dt); deterministic by its seed, its state plain JSON.
+:::
+```
+
+## App Page
+
+The one page on which the app runs; without JavaScript it shows only a note and a link back to the start page.
+
+```arc42
+:::glossary-term
+id: term-app-page
+title: App page
+definition: The page that loads the app's client module, into whose element the shell mounts the app.
+:::
+```
+
+## Route
+
+A mode or level of the app, declared in `src/app.yaml`. The core receives the route's id in `start`.
+
+```arc42
+:::glossary-term
+id: term-route
+title: Route
+definition: A mode or level of the app with its own address on the app page (app/#<id>); the first route when the address names none.
+:::
+```
+
+## Tick
+
+The runtime's constant `TICK` is 20. A learner's browser ticks in real time; the build and the end-to-end tests tick
+only as a playthrough step's `ticks` say.
+
+```arc42
+:::glossary-term
+id: term-tick
+title: Tick
+definition: A call of tick(state, 20) that the shell makes every 20 ms when the core has tick, so the state moves with time.
+:::
+```
+
+## Playthrough
+
+A YAML file in `src/playthroughs/`. Not a free-form test: it holds only data the runtime plays.
+
+```arc42
+:::glossary-term
+id: term-playthrough
+title: Playthrough
+definition: A seed, a route and a list of steps, each inputs (keys as their short form) and ticks followed by the state (a part of it) or the announcement expected after them; played by the build against the core and by the browser test.
+:::
+```
+
+## Input
+
+What the core's `step` takes: a key input or an action input (`dec-typed-input`).
+
+```arc42
+:::glossary-term
+id: term-input
+title: Input
+definition: A typed, extensible value the core's step takes: a key as the browser names it, a pointer or touch action, and other kinds later; the components translate any device input into inputs, and playthroughs record them.
+:::
+```
+
+<!-- app: begin -->
+<!-- app: end -->

package/interactive/e2e/interactive.e2e.ts

@@ -0,0 +1,3 @@
+import { interactiveTests } from "@lernapps/app-templates/interactive/e2e";
+
+interactiveTests();

package/interactive/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="de">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <script type="module" src="/src/main.ts"></script>
+  </head>
+  <body>
+    <!-- interactive -->
+  </body>
+</html>

package/interactive/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "interactive",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp build",
+    "check": "lernapps check"
+  },
+  "devDependencies": {
+    "@lernapps/app-templates": "file:..",
+    "@lernapps/tooling": "^0.1.2",
+    "vite-plus": "1.4.0"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
+  }
+}

package/interactive/playwright.config.ts

@@ -0,0 +1 @@
+export { default } from "@lernapps/tooling/playwright";

package/interactive/src/app.yaml

@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/interactive/interactive.v1.schema.json
+title: Buchstaben tippen
+description: |
+  Ein Buchstabe erscheint, du tippst ihn auf der Tastatur. Für jeden hast du fünf Sekunden.
+  Zum Üben der Grundreihe und der oberen Reihe, ab Klasse 3.
+howto: |
+  - Tippe den Buchstaben, der groß in der Mitte steht.
+  - Richtig getippt gibt einen Punkt, und der nächste Buchstabe kommt.
+  - Ein falscher Buchstabe oder zu langes Warten zählt als Fehler.
+  - Nach zehn Buchstaben ist die Runde vorbei. Mit Enter spielst du die nächste.
+competencies:
+  - Ich kann die Buchstaben der Grundreihe auf der Tastatur finden.
+  - Ich kann die Buchstaben der oberen Reihe tippen.
+languages: [de]
+routes:
+  - id: grundreihe
+    title: Grundreihe
+    description: a s d f j k l
+  - id: obere-reihe
+    title: Obere Reihe
+    description: q w e r t z u i o p
+sections:
+  - id: zehn-finger
+    title: Warum die Grundreihe?
+    text: |
+      Auf der Grundreihe liegen deine Finger, wenn du nicht tippst: links auf a, s, d, f, rechts auf j, k, l.
+      Von dort erreicht jeder Finger seine Tasten. Wer die Grundreihe sicher findet, muss beim Tippen nicht mehr auf
+      die Tastatur schauen.

package/interactive/src/core/index.ts

@@ -0,0 +1,101 @@
+// The game's logic: a round of letters from the lesson of the route, drawn from the seed; each letter typed right
+// scores, a wrong key or a letter not typed in time is a miss; after the round, Enter or the action "again" (the button
+// of the component) starts the next. Pure TypeScript without DOM; the runtime keeps the state and calls start, step
+// and tick (@lernapps/app-templates/interactive).
+import type { Input } from "@lernapps/app-templates/interactive";
+import lessons from "../data/lessons.json" with { type: "json" };
+
+/** A lesson of src/data/lessons.json: the letters it draws from, how many a round has, the seconds for each. */
+export interface Lesson {
+  letters: string;
+  count: number;
+  seconds: number;
+}
+
+export interface State {
+  seed: number;
+  route: string;
+  /** The letters of the round, in order. */
+  letters: string;
+  /** The position of the letter to type now. */
+  index: number;
+  score: number;
+  misses: number;
+  /** Milliseconds left for the letter to type now. */
+  left: number;
+  /** What the last change was. */
+  last: "start" | "hit" | "miss" | "late";
+  done: boolean;
+}
+
+const LESSONS: Readonly<Record<string, Lesson>> = lessons;
+
+/** The lesson of a route. */
+export function lessonOf(route: string): Lesson {
+  const lesson = LESSONS[route];
+  if (lesson === undefined) throw new Error(`no lesson ${route} in src/data/lessons.json`);
+  return lesson;
+}
+
+/** A random number from 0 to 1 for each call, the same sequence for the same seed (mulberry32). */
+function random(seed: number): () => number {
+  let value = seed >>> 0;
+  return () => {
+    value = (value + 0x6d2b79f5) >>> 0;
+    let mixed = Math.imul(value ^ (value >>> 15), 1 | value);
+    mixed = (mixed + Math.imul(mixed ^ (mixed >>> 7), 61 | mixed)) ^ mixed;
+    return ((mixed ^ (mixed >>> 14)) >>> 0) / 4_294_967_296;
+  };
+}
+
+export function start(seed: number, route: string): State {
+  const lesson = lessonOf(route);
+  const next = random(seed);
+  const letters = Array.from(
+    { length: lesson.count },
+    () => lesson.letters[Math.floor(next() * lesson.letters.length)] ?? "",
+  ).join("");
+  return {
+    seed,
+    route,
+    letters,
+    index: 0,
+    score: 0,
+    misses: 0,
+    left: lesson.seconds * 1000,
+    last: "start",
+    done: false,
+  };
+}
+
+/** The state with the next letter to type, after a hit or a late one. */
+function advance(state: State, change: Partial<State>): State {
+  const index = state.index + 1;
+  return {
+    ...state,
+    ...change,
+    index,
+    left: lessonOf(state.route).seconds * 1000,
+    done: index >= state.letters.length,
+  };
+}
+
+/** Whether `input` asks for the next round: Enter, or the component's action "again". */
+const again = (input: Input): boolean =>
+  (input.kind === "key" && input.key === "Enter") || (input.kind === "action" && input.name === "again");
+
+export function step(state: State, input: Input): State {
+  if (state.done) return again(input) ? start(state.seed + 1, state.route) : state;
+  // only a typed letter counts: no Shift, Tab or other named key, no action
+  if (input.kind !== "key" || input.key.length !== 1) return state;
+  const key = input.key;
+  if (key.toLowerCase() === state.letters[state.index]) return advance(state, { score: state.score + 1, last: "hit" });
+  return { ...state, misses: state.misses + 1, last: "miss" };
+}
+
+export function tick(state: State, dt: number): State {
+  if (state.done) return state;
+  const left = state.left - dt;
+  if (left > 0) return { ...state, left };
+  return advance(state, { misses: state.misses + 1, last: "late" });
+}

package/interactive/src/data/lessons.json

@@ -0,0 +1,4 @@
+{
+  "grundreihe": { "letters": "asdfjkl", "count": 10, "seconds": 5 },
+  "obere-reihe": { "letters": "qwertzuiop", "count": 10, "seconds": 5 }
+}

package/interactive/src/env.d.ts

@@ -0,0 +1,6 @@
+// The type of a single-file component, for src/main.ts, which imports the root component.
+declare module "*.vue" {
+  import type { Component } from "vue";
+  const component: Component;
+  export default component;
+}

package/interactive/src/main.ts

@@ -0,0 +1,6 @@
+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);

package/interactive/src/messages/de.json

@@ -0,0 +1,12 @@
+{
+  "game": "Spiel",
+  "type": "Tippe {letter}.",
+  "hit": "Richtig. Tippe {letter}.",
+  "miss": "Falsch. Tippe {letter}.",
+  "late": "Zu spät. Tippe {letter}.",
+  "start": "Neue Runde. Tippe {letter}.",
+  "score": "Punkte: {score} von {total}",
+  "misses": "Fehler: {misses}",
+  "done": "Fertig: {score} von {total} richtig. Mit Enter spielst du noch eine Runde.",
+  "again": "Noch eine Runde"
+}

package/interactive/src/playthroughs/grundreihe.yaml

@@ -0,0 +1,33 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/interactive/playthrough.v1.schema.json
+# A round of the Grundreihe with seed 1, whose letters are j a f l l s j k d l: a hit, a wrong key, two seconds that
+# pass, three more that make the letter late, a capital letter that counts, the rest of the round; the button for the
+# next round (the action "again"), that round typed through, and Enter for the one after it.
+route: grundreihe
+seed: 1
+steps:
+  - keys: [j]
+    state: { index: 1, score: 1, misses: 0 }
+    announce: Richtig. Tippe a.
+  - keys: [x]
+    state: { index: 1, score: 1, misses: 1 }
+    announce: Falsch. Tippe a.
+  - ticks: 100
+    state: { index: 1, misses: 1, left: 3000 }
+  - ticks: 150
+    state: { index: 2, misses: 2, left: 5000, last: late }
+    announce: Zu spät. Tippe f.
+  - keys: [F]
+    state: { index: 3, score: 2 }
+    announce: Richtig. Tippe l.
+  - keys: [l, l, s, j, k, d, l]
+    state: { score: 9, misses: 2, done: true }
+    announce: "Fertig: 9 von 10 richtig. Mit Enter spielst du noch eine Runde."
+  - inputs: [{ kind: action, name: again }]
+    state: { seed: 2, letters: kdsfljfdka, index: 0, score: 0, misses: 0, done: false }
+    announce: Neue Runde. Tippe k.
+  - keys: [k, d, s, f, l, j, f, d, k, a]
+    state: { score: 10, misses: 0, done: true }
+    announce: "Fertig: 10 von 10 richtig. Mit Enter spielst du noch eine Runde."
+  - keys: [Enter]
+    state: { seed: 3, letters: kafakffssf, index: 0, score: 0, done: false }
+    announce: Neue Runde. Tippe k.

package/interactive/src/playthroughs/obere-reihe.yaml

@@ -0,0 +1,14 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/interactive/playthrough.v1.schema.json
+# The obere Reihe with seed 1, whose letters start with u q z p: three hits, then the space bar and ü, wrong keys.
+route: obere-reihe
+seed: 1
+steps:
+  - keys: [u, q, z]
+    state: { route: obere-reihe, index: 3, score: 3 }
+    announce: Richtig. Tippe p.
+  - keys: [" "]
+    state: { index: 3, misses: 1 }
+    announce: Falsch. Tippe p.
+  - keys: [ü]
+    state: { index: 3, misses: 2 }
+    announce: Falsch. Tippe p.

package/interactive/src/ui/App.vue

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+// The game: the letter to type, the time left for it, the score; after the round the result and a button for the
+// next round. It announces every change for screen readers. The runtime gives it the core's state and steps every
+// key typed on the page; the button emits the action "again" as input.
+import { computed, watch } from "vue";
+import { announce } from "@lernapps/tooling/a11y";
+import { translator } from "@lernapps/tooling/i18n";
+import type { Input } from "@lernapps/app-templates/interactive";
+import { lessonOf, type State } from "../core/index.ts";
+import de from "../messages/de.json";
+
+const props = defineProps<{ state: State; lang: string }>();
+const emit = defineEmits<{ input: [input: Input] }>();
+const t = translator(de);
+
+const letter = computed(() => props.state.letters[props.state.index] ?? "");
+const total = computed(() => props.state.letters.length);
+const timeLeft = computed(() => (100 * props.state.left) / (lessonOf(props.state.route).seconds * 1000));
+
+watch(
+  () => [props.state.index, props.state.misses, props.state.done, props.state.seed] as const,
+  () => {
+    const { state } = props;
+    if (state.done) announce(t("done", { score: state.score, total: total.value }));
+    else announce(t(state.last, { letter: letter.value }));
+  },
+);
+</script>
+
+<template>
+  <section class="game" :aria-label="t('game')">
+    <template v-if="!state.done">
+      <p class="letter" aria-hidden="true">{{ letter }}</p>
+      <p class="prompt">{{ t("type", { letter }) }}</p>
+      <div class="time" aria-hidden="true"><div class="time-left" :style="{ width: `${timeLeft}%` }"></div></div>
+    </template>
+    <template v-else>
+      <p class="result">{{ t("done", { score: state.score, total }) }}</p>
+      <button type="button" class="again" @click="emit('input', { kind: 'action', name: 'again' })">
+        {{ t("again") }}
+      </button>
+    </template>
+    <p class="score">{{ t("score", { score: state.score, total }) }} · {{ t("misses", { misses: state.misses }) }}</p>
+  </section>
+</template>
+
+<style scoped>
+.game {
+  padding: 1rem;
+  border-radius: 0.5rem;
+  background: var(--page-surface);
+  text-align: center;
+}
+
+.letter {
+  margin: 0;
+  font-size: 5rem;
+  font-weight: 700;
+  line-height: 1.2;
+}
+
+.time {
+  height: 0.5rem;
+  margin: 0.5rem auto;
+  max-width: 20rem;
+  border-radius: 0.25rem;
+  background: var(--page-border);
+  overflow: hidden;
+}
+
+.time-left {
+  height: 100%;
+  background: var(--page-accent);
+}
+
+.again {
+  padding: 0.5rem 1.25rem;
+  border: 0;
+  border-radius: 0.375rem;
+  background: var(--page-accent);
+  color: var(--page-on-accent);
+  font: inherit;
+  font-weight: 600;
+}
+</style>

package/interactive/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "@lernapps/tooling/tsconfig.json", "include": ["src"] }

package/interactive/vite.config.ts

@@ -0,0 +1,4 @@
+import { lernapps } from "@lernapps/tooling/preset";
+import { interactive } from "@lernapps/app-templates/interactive/plugin";
+
+export default lernapps({ plugins: [interactive()] });