@lernapps/app-templates 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,146 @@
 {
   "name": "@lernapps/app-templates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The templates of the archetypes of lernapps.net apps, and the runtime of each archetype that apps depend on (the quiz: engine, build step, styles, end-to-end tests, the schema of the question bank, the questions it shares with the explainer are in ./questions; the explainer: build step, client module with its exercises, the islands of its Vue components, styles, end-to-end tests, the schema of its content; the interactive archetype: build step, the start page and the app page around the app's own Vue components and core, its playthroughs, styles, end-to-end tests, the schemas of its start page and its playthroughs)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lernapps/app-templates.git"
+  },
+  "files": [
+    "dist",
+    "runtime",
+    "docs/arc42",
+    "explainer",
+    "interactive",
+    "quiz",
+    "!**/package-lock.json",
+    "!**/node_modules"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./blocks": {
+      "types": "./runtime/shared/blocks/index.ts",
+      "default": "./dist/blocks.mjs"
+    },
+    "./blocks/blocks.v1.schema.json": "./runtime/shared/blocks/blocks.v1.schema.json",
+    "./text/text.v1.schema.json": "./runtime/shared/text/text.v1.schema.json",
+    "./questions": {
+      "types": "./runtime/shared/questions/index.ts",
+      "default": "./dist/questions.mjs"
+    },
+    "./questions/engine": {
+      "types": "./runtime/shared/questions/engine.ts",
+      "default": "./dist/questions-engine.mjs"
+    },
+    "./questions/e2e": {
+      "types": "./runtime/shared/questions/e2e.ts",
+      "default": "./dist/questions-e2e.mjs"
+    },
+    "./questions/question.v1.schema.json": "./runtime/shared/questions/question.v1.schema.json",
+    "./quiz": {
+      "types": "./runtime/quiz/engine.ts",
+      "default": "./dist/quiz.mjs"
+    },
+    "./quiz/plugin": {
+      "types": "./runtime/quiz/plugin.ts",
+      "default": "./dist/quiz-plugin.mjs"
+    },
+    "./quiz/e2e": {
+      "types": "./runtime/quiz/e2e.ts",
+      "default": "./dist/quiz-e2e.mjs"
+    },
+    "./quiz/style.css": "./runtime/quiz/quiz.css",
+    "./quiz/quiz.v1.schema.json": "./runtime/quiz/quiz.v1.schema.json",
+    "./explainer": {
+      "types": "./runtime/explainer/explainer.ts",
+      "default": "./dist/explainer.mjs"
+    },
+    "./explainer/plugin": {
+      "types": "./runtime/explainer/plugin.ts",
+      "default": "./dist/explainer-plugin.mjs"
+    },
+    "./explainer/e2e": {
+      "types": "./runtime/explainer/e2e.ts",
+      "default": "./dist/explainer-e2e.mjs"
+    },
+    "./explainer/style.css": "./runtime/explainer/explainer.css",
+    "./explainer/explainer.v1.schema.json": "./runtime/explainer/explainer.v1.schema.json",
+    "./interactive": {
+      "types": "./runtime/interactive/interactive.ts",
+      "default": "./dist/interactive.mjs"
+    },
+    "./interactive/plugin": {
+      "types": "./runtime/interactive/plugin.ts",
+      "default": "./dist/interactive-plugin.mjs"
+    },
+    "./interactive/e2e": {
+      "types": "./runtime/interactive/e2e.ts",
+      "default": "./dist/interactive-e2e.mjs"
+    },
+    "./interactive/style.css": "./runtime/interactive/interactive.css",
+    "./interactive/interactive.v1.schema.json": "./runtime/interactive/interactive.v1.schema.json",
+    "./interactive/playthrough.v1.schema.json": "./runtime/interactive/playthrough.v1.schema.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "prepare": "vp pack && vp config --no-agent",
+    "test": "vp test",
+    "check:vue": "vue-tsc --noEmit -p tsconfig.vue.json",
+    "prepack": "node scripts/pack-dotfiles.ts stage",
+    "postpack": "node scripts/pack-dotfiles.ts clean"
+  },
+  "dependencies": {
+    "@vitejs/plugin-vue": "6.0.10",
+    "ajv": "8.20.0",
+    "highlight.js": "11.12.0",
+    "marked": "18.1.2",
+    "source-map-js": "1.2.2",
+    "temml": "0.14.0",
+    "vue": "3.5.44",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@doctc/arc42": "0.38.0",
+    "@types/node": "26.6.5",
+    "typescript": "6.0.3",
+    "vite-plus": "1.4.0",
+    "vue-tsc": "3.3.13"
+  },
+  "peerDependencies": {
+    "@lernapps/tooling": "*",
+    "playwright": "*",
+    "vite-plus": "1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@lernapps/tooling": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    },
+    "vite-plus": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
+  },
+  "lernapps": {
+    "changes": {
+      "kind": "app"
+    },
+    "archetypes": [
+      "explainer",
+      "interactive",
+      "quiz"
+    ]
+  }
+}

package/quiz/README.md

@@ -0,0 +1,31 @@
+# Archetype quiz
+
+A quiz about things to know: one page of questions with options, feedback on every option, score and solutions.
+
+## What it can do
+
+- Six question types: single choice, multiple choice, true or false, a number within a tolerance, putting items in
+  order, matching pairs.
+- Background on every option, an explanation for every question, links to further reading, an optional hint, typical
+  wrong numbers with their message.
+- One question at a time with feedback; at the end the score and all solutions. Without JavaScript: a worksheet with
+  the solutions.
+- Questions in a shuffled order; a link with a seed gives every learner the same order. A link to each question.
+- The learner chooses at the start how many questions to answer (at most all of them): the seed picks them, and the address (`?seed=…&n=…`) keeps the choice, so a link gives every learner the same questions.
+- German, plus English: a page per language.
+- Optionally keeps the last score on the learner's device.
+- Content in a question, between its text and its answers (`material`): prose, a formula, a figure (your own image in
+  `src/images/` with its source and licence, or drawn from numbers), a labelled figure, a table, a quotation, code.
+  Every figure has an alternative text and a caption; the build checks the blocks and carries the images.
+
+## What it cannot do
+
+- No other media than images: no audio, no video. Content does not move.
+- No own colours or layout: the look is the runtime's, calm like a worksheet. Dark mode follows the device.
+- No timer, no new tasks drawn each time, no count the learner chooses.
+
+## What the app supplies
+
+- The question bank `src/quiz.json` ([schema](../runtime/quiz/quiz.v1.schema.json)) and, for the figures of its
+  questions, the image files in `src/images/` (`<name>.svg`, `.png`, `.jpg` or `.webp`, referred to as
+  `images/<name>.…`). No code: the runtime `@lernapps/app-templates` does the rest.

package/quiz/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+_site/
+test-results/
+playwright-report/

package/quiz/docs/arc42/05-quiz-building-blocks.arc42.md

@@ -0,0 +1,283 @@
+# Building Blocks
+
+The quiz's extension of the generic architecture (`docs/arc42/` at the root of `lernapps/app-templates`): a quiz
+about things to know, whose build step, rendering, validation, engine and tests the runtime `runtime/quiz/` ships, and
+whose creator writes only the question bank `src/quiz.json` (`quiz-only-data`) and keeps `src/main.ts` as generated.
+The quiz has no components, no tutor handoff, no task numbers and no exercise contract; its question types are the shared
+runtime's (`bb-questions`), which the explainer builds on alike, and what a question shows besides its text (`material`: figures, tables, quotations, code, ...) is the shared runtime's content blocks (`bb-blocks`). The creator's assistant follows the skill `lernapps-quiz` (`if-skills`). A quiz app writes no
+architecture of its own: the bank's schema fixes its structure.
+
+## Level 1 (quiz)
+
+```arc42
+:::diagram
+id: building-blocks-quiz-level-1
+view: building-block
+notation: mermaid
+:::
+```
+
+```mermaid
+flowchart TB
+    subgraph bb-runtime["Shared runtime"]
+        bb-blocks["Content blocks"]
+        bb-questions["Questions"]
+    end
+    bb-tooling["Tooling helpers"]
+    bb-archetype-runtime["Quiz runtime"]
+    bb-quiz-bank["Question bank"]
+    bb-archetype-runtime -->|"if-shared-runtime"| bb-runtime
+    bb-archetype-runtime -->|"if-questions"| bb-questions
+    bb-archetype-runtime -->|"if-blocks"| bb-blocks
+    bb-archetype-runtime -->|"if-preset"| bb-tooling
+```
+
+## Level 2: the quiz runtime
+
+```arc42
+:::diagram
+id: building-blocks-quiz-runtime
+view: building-block
+notation: mermaid
+:::
+```
+
+```mermaid
+flowchart TB
+    subgraph bb-archetype-runtime["Quiz runtime"]
+        bb-build["Build step"]
+        bb-validation["Bank validation"]
+        bb-render["Quiz rendering"]
+        bb-shell["Quiz engine"]
+        bb-e2e["End-to-end tests"]
+        bb-runtime-texts["Runtime texts"]
+    end
+    bb-quiz-bank["Question bank"]
+    bb-tooling["Tooling helpers"]
+    bb-build -->|"if-archetype-content"| bb-quiz-bank
+    bb-validation -->|"if-archetype-content"| bb-quiz-bank
+    bb-render -->|"if-archetype-content"| bb-quiz-bank
+    bb-render -->|"if-runtime-texts"| bb-runtime-texts
+    bb-render -->|"if-translator"| bb-tooling
+    bb-shell -->|"if-runtime-texts"| bb-runtime-texts
+    bb-shell -->|"if-device-storage"| bb-tooling
+    bb-shell -->|"if-a11y"| bb-tooling
+    bb-shell -->|"if-translator"| bb-tooling
+    bb-e2e -->|"if-archetype-content"| bb-quiz-bank
+    bb-e2e -->|"if-runtime-texts"| bb-runtime-texts
+```
+
+## Quiz runtime
+
+Built. The runtime of every quiz, which the app does not change: it renders the bank into the page, validates it,
+turns the page into a quiz in the browser and brings the end-to-end tests.
+
+```arc42
+:::building-block
+id: bb-archetype-runtime
+title: Quiz runtime
+path: runtime/quiz
+technology: TypeScript, Vite plugin, DOM
+requires: if-shared-runtime, if-preset, if-questions, if-blocks
+implements: concept-archetype-extension
+:::
+```
+
+### Build step
+
+Built. The plugin `quiz()` reads and validates the bank and writes the quiz page in every language and the 404 page;
+`vp dev` serves the same pages.
+
+```arc42
+:::building-block
+id: bb-build
+title: Build step
+parent: bb-archetype-runtime
+path: runtime/quiz/plugin.ts
+technology: Vite plugin
+requires: if-archetype-content
+:::
+```
+
+#### Build plugin interface
+
+The app's vite.config.ts adds `quiz()` to the tooling preset.
+
+```arc42
+:::interface
+id: if-build-plugin
+title: quiz() Vite plugin
+provider: bb-build
+protocol: TypeScript import, @lernapps/app-templates/quiz/plugin
+path: runtime/quiz/plugin.ts
+:::
+```
+
+### Bank validation
+
+Built. Validates the bank against its schema, then what a schema cannot say (one correct option in a single choice,
+unique ids, complete languages, the examples through the checker), one line per problem naming the question.
+
+```arc42
+:::building-block
+id: bb-validation
+title: Bank validation
+parent: bb-archetype-runtime
+path: runtime/quiz/validate.ts
+technology: Ajv, JSON Schema
+requires: if-archetype-content
+:::
+```
+
+### Quiz rendering
+
+Built. Renders every question into the page with its controls, the hidden background, explanation and further
+reading, the solutions and the sources, a page per language. Without JavaScript the page reads as a worksheet with its
+answer key; the quiz's own tests check it, not `lernapps check`.
+
+```arc42
+:::building-block
+id: bb-render
+title: Quiz rendering
+parent: bb-archetype-runtime
+path: runtime/quiz/render.ts
+technology: TypeScript, HTML
+requires: if-archetype-content, if-runtime-texts, if-translator
+implements: concept-readable-without-js
+:::
+```
+
+#### Pages interface
+
+Learners, teachers and parents read the quiz at `lernapps.net/<repo>/` (and `/<language>/`), with `?seed=<n>` and the
+deep link `#frage-<id>`; the catalog entry links there.
+
+```arc42
+:::interface
+id: if-pages
+title: Quiz page at lernapps.net/<repo>/
+provider: bb-render
+protocol: HTML pages over HTTPS
+path: runtime/quiz/render.ts
+:::
+```
+
+### Quiz engine
+
+Built. Turns the rendered page into a quiz: one question at a time in the order of the seed in the address, each
+answer checked with the question types' checker, the feedback after each answer, the score and the solutions at the
+end. It stores nothing but the last result, and only when the bank asks for it (`rememberLastResult`).
+
+```arc42
+:::building-block
+id: bb-shell
+title: Quiz engine
+parent: bb-archetype-runtime
+path: runtime/quiz/engine.ts
+technology: TypeScript, DOM
+requires: if-runtime-texts, if-device-storage, if-a11y, if-translator
+implements: concept-determinism, concept-accessibility
+:::
+```
+
+#### Start interface
+
+The app's `src/main.ts` imports the quiz's style and calls `startQuiz()`.
+
+```arc42
+:::interface
+id: if-start
+title: startQuiz()
+provider: bb-shell
+protocol: TypeScript import, @lernapps/app-templates/quiz
+path: runtime/quiz/engine.ts
+:::
+```
+
+### End-to-end tests
+
+Built. `quizTests()` checks every question of the bank in the browser (deep link, right and wrong answer, feedback in
+view with the focus), the full score, the page without JavaScript, and each further language.
+
+```arc42
+:::building-block
+id: bb-e2e
+title: End-to-end tests
+parent: bb-archetype-runtime
+path: runtime/quiz/e2e.ts
+technology: Playwright
+requires: if-archetype-content, if-runtime-texts
+:::
+```
+
+#### Tests interface
+
+The app's `e2e/quiz.e2e.ts` only calls `quizTests()`.
+
+```arc42
+:::interface
+id: if-e2e-tests
+title: quizTests()
+provider: bb-e2e
+protocol: TypeScript import, @lernapps/app-templates/quiz/e2e
+path: runtime/quiz/e2e.ts
+:::
+```
+
+### Runtime texts
+
+Built. The quiz's own learner texts in German and English; a bank may declare only these languages.
+
+```arc42
+:::building-block
+id: bb-runtime-texts
+title: Runtime texts
+parent: bb-archetype-runtime
+path: runtime/quiz/messages
+technology: JSON per language
+implements: concept-languages
+:::
+```
+
+#### Runtime texts interface
+
+The rendering, the engine and the tests take the quiz's texts by language.
+
+```arc42
+:::interface
+id: if-runtime-texts
+title: Quiz texts by language
+provider: bb-runtime-texts
+protocol: JSON module import
+path: runtime/quiz/messages
+:::
+```
+
+## Question bank
+
+Built in the template, written by the creator: title, intro, languages, sources, `rememberLastResult` and the
+questions; the only file of a quiz the creator changes.
+
+```arc42
+:::building-block
+id: bb-quiz-bank
+title: Question bank
+technology: JSON
+implements: concept-languages
+path: quiz/src/quiz.json
+:::
+```
+
+### Question bank interface
+
+The quiz's content: rendering, validation, build and tests read the bank only through its schema.
+
+```arc42
+:::interface
+id: if-archetype-content
+title: src/quiz.json (quiz.v1 schema)
+provider: bb-quiz-bank
+protocol: JSON, JSON Schema
+path: runtime/quiz/quiz.v1.schema.json
+:::
+```

package/quiz/docs/arc42/06-quiz-runtime-view.arc42.md

@@ -0,0 +1,21 @@
+# Runtime View
+
+The quiz's own scenario, besides the generic ones.
+
+## Answering a question
+
+The learner opens the quiz, possibly with `?seed=<n>` or `#frage-<id>`. Without JavaScript the page is a worksheet:
+every question, then the solutions with the same background and links. With JavaScript `startQuiz()` turns it into a
+quiz: the questions in the order of the seed (the address gets one when it has none), one at a time. Before the first question the learner chooses how many to answer (`?n=<n>` in the address, all by default; a link with `n` or to a question skips the choice), the first of them in the order of the seed; an answer is
+checked by the question types' checker, and right or wrong, the background of every option, the explanation and the
+further reading show, the feedback in view with the focus and announced. At the end come the score and the solutions;
+when the bank asks for it, the last result is kept on the device.
+
+```arc42
+:::runtime-scenario
+id: scenario-quiz-answer
+title: Answering a question of the quiz
+trigger: The learner opens the quiz or answers a question
+involves: bb-archetype-runtime, bb-render, bb-shell, bb-questions, bb-blocks, bb-quiz-bank, bb-runtime-texts, bb-tooling
+:::
+```

package/quiz/docs/arc42/07-quiz-deployment-view.arc42.md

@@ -0,0 +1,33 @@
+# Deployment View
+
+Where the quiz's blocks run, below the generic nodes.
+
+## Quiz build
+
+The quiz's build, validation and end-to-end tests run in CI and, through the same hooks, on the creator's machine;
+the bank is built into the page and the bundle there.
+
+```arc42
+:::deployment-node
+id: dn-quiz-build
+title: Quiz build
+type: container
+parent: dn-ci-runner
+hosts: bb-quiz-bank
+:::
+```
+
+## Quiz page
+
+The quiz engine with the question types' checker and the quiz's texts runs in the learner's browser on the page the
+build rendered.
+
+```arc42
+:::deployment-node
+id: dn-quiz-page
+title: Quiz page
+type: container
+parent: dn-learner-browser
+hosts: bb-shell, bb-runtime-texts
+:::
+```

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

@@ -0,0 +1,36 @@
+# Architecture Decisions
+
+The quiz's decisions, besides the generic ones.
+
+## The Creator Writes Only the Question Bank
+
+The quiz is a deep scaffold: engine, six question types, feedback, scoring, order, accessibility and the page
+without JavaScript come from the runtime, and the creator writes only `src/quiz.json`, no code. What the bank cannot
+say goes into the retrospective instead of code around the runtime. So the schema fixes the quiz's structure, and a
+quiz app writes no architecture of its own. Rejected: quiz-specific code in the app.
+
+```arc42
+:::decision
+id: dec-quiz-only-bank
+title: A quiz is only its question bank
+status: accepted
+date: 2026-10-16
+addresses: qg-checkable, qg-understandable, con-runtime-unchanged
+:::
+```
+
+## A Worksheet Without JavaScript
+
+The build renders every question with its solution into the page, so that without JavaScript the quiz reads as a
+worksheet with its answer key and the engine only adds the one-question-at-a-time quiz. Rejected: a page that needs
+JavaScript to show its questions.
+
+```arc42
+:::decision
+id: dec-quiz-worksheet
+title: The quiz page is a worksheet without JavaScript
+status: accepted
+date: 2026-10-16
+addresses: qg-quiz-readable-without-js, qg-accessibility
+:::
+```

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

@@ -0,0 +1,53 @@
+# Quality Requirements
+
+The quiz's goal and scenarios, besides the generic ones.
+
+## Readable without JavaScript (quiz)
+
+A quiz is text-heavy, so its questions, solutions, background and links read without JavaScript, as far as a quiz
+can: as a worksheet with its answer key, not as a quiz answered one question at a time. Realised by the quiz
+rendering and checked by the quiz's end-to-end tests (`dec-quiz-worksheet`).
+
+High priority, because the archetype is text-heavy (owner, 2026-10-16).
+
+```arc42
+:::ignore W014 the extension's goal follows the generic goals in the combined chapter; the generic part cannot hold it
+:::
+:::ignore H010 the generic solution strategy cannot name an archetype's goal; the quiz's rendering realises it, see the decisions that address it
+:::
+:::quality-goal
+id: qg-quiz-readable-without-js
+title: Readable without JavaScript (quiz)
+priority: high
+:::
+```
+
+## Every question readable without JavaScript
+
+`quizTests()` opens the page with JavaScript off, in every language of the bank.
+
+```arc42
+:::quality-scenario
+id: qs-quiz-without-js
+title: Every question and its solution read without JavaScript
+quality: qg-quiz-readable-without-js
+stimulus: The quiz's end-to-end tests open the built quiz with JavaScript off
+response: Every question and its solution, with the same background and links, are visible; in each further language too
+metric: All questions of the bank and their solutions visible, in every declared language
+:::
+```
+
+## A broken bank fails the build
+
+The bank validation runs before the page is written.
+
+```arc42
+:::quality-scenario
+id: qs-quiz-bank-valid
+title: A broken question bank fails the build
+quality: qg-checkable
+stimulus: The bank has two correct options in a single choice, a duplicate id or a missing translation
+response: The build fails with one line per problem, naming the question by its position and id
+metric: 0 pages written from an invalid bank
+:::
+```

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

@@ -0,0 +1,19 @@
+# Risks and Technical Debt
+
+The quiz's risks, besides the generic ones.
+
+## Readability Without JavaScript Checked Only by Its Own Tests
+
+`lernapps check` checks pages without JavaScript only for the explainer (`explainer-readable-without-js`); the quiz's
+worksheet is checked by the quiz's end-to-end tests alone, so a deployed quiz is not checked for it again.
+
+```arc42
+:::ignore H007 accepted without a decision of its own: the quiz's own end-to-end tests check the worksheet before every push and in CI
+:::
+:::risk
+id: risk-quiz-no-js-not-in-check
+title: The quiz's page without JavaScript is not checked by lernapps check
+severity: low
+mitigation: Accepted for now; the quiz's end-to-end tests run before every push and in CI.
+:::
+```

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

@@ -0,0 +1,27 @@
+# Glossary
+
+The quiz's terms, besides the generic ones.
+
+## Question Bank
+
+`src/quiz.json`, checked against `quiz.v1.schema.json`.
+
+```arc42
+:::glossary-term
+id: term-question-bank
+title: Question bank
+definition: The quiz's title, intro, languages, sources and questions, the only file a quiz's creator writes.
+:::
+```
+
+## Worksheet
+
+What the quiz page shows without JavaScript.
+
+```arc42
+:::glossary-term
+id: term-worksheet
+title: Worksheet
+definition: The quiz page without JavaScript, all questions followed by their solutions with background and links.
+:::
+```

package/quiz/e2e/quiz.e2e.ts

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

package/quiz/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>
+    <!-- quiz -->
+  </body>
+</html>