@lernapps/app-templates 0.2.0 → 0.3.0

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

@@ -124,7 +124,8 @@ implements: concept-archetype-extension
 
 Built. The plugin `explainer()` reads and validates the content, runs the component rules and the property test of
 each generated exercise and exercise component over fixed seeds, and only then writes every page in each language,
-the tutor pages where the tutor is on, and the 404 page; `vp dev` serves the same pages.
+the tutor pages where the tutor is on, and the 404 page; for an app of format 2 also the list of its pages for the
+catalog (`if-page-list`); `vp dev` serves the same pages.
 
 ```arc42
 :::building-block
@@ -137,6 +138,22 @@ requires: if-archetype-content, if-component-rules, if-exercise-logic, if-tutor-
 :::
 ```
 
+#### Page list for the catalog
+
+The build provides the catalog with the app's place on the learning map: its strand and its pages with their
+competencies. The catalog consumes it to place the app and checks the ids, which the app cannot know. Only format 2
+apps have one.
+
+```arc42
+:::interface
+id: if-page-list
+title: Page list lernapps-pages.json (format 2)
+provider: bb-build
+protocol: JSON file over HTTPS, beside index.html
+path: runtime/explainer/page-list.ts
+:::
+```
+
 #### Build plugin interface
 
 The app's vite.config.ts adds `explainer()` to the tooling preset.
@@ -153,10 +170,10 @@ path: runtime/explainer/plugin.ts
 
 ### Content validation
 
-Built. Validates every content file against its part of the schema, then what a schema cannot say (complete order
-lists, depth, unique ids, complete languages, restricted Markdown, formulas in the command list, sources and
-licences, links to pages and sections, an exercise on every page, components and their props), one line per problem
-with file and line.
+Built. Validates every content file against its part of the schema of its format, then what a schema cannot say
+(complete order lists, depth, unique ids, complete languages, restricted Markdown, formulas in the command list,
+sources and licences, links to pages and sections, the exercises a page needs, components and their props, and in
+format 2 the competencies of the pages), one line per problem with file and line.
 
 ```arc42
 :::building-block
@@ -567,15 +584,16 @@ path: explainer/src/app.yaml
 ### Content interface
 
 The explainer's content: build, validation, rendering, generated exercises, tutor pages and tests read it only through
-its schema.
+its schema: format 2 for the template and new apps, which adds the app's place on the learning map to format 1; format
+1 stays valid (`dec-explainer-format-2`).
 
 ```arc42
 :::interface
 id: if-archetype-content
-title: Content YAML (explainer.v1 schema)
+title: Content YAML (explainer.v1 and v2 schemas)
 provider: bb-explainer-content
 protocol: YAML, JSON Schema
-path: runtime/explainer/explainer.v1.schema.json
+path: runtime/explainer/explainer.v2.schema.json
 :::
 ```
 

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

@@ -28,6 +28,11 @@ only adds. `lernapps check` opens every explainer page a second time with JavaSc
 inside a component or a live exercise. The one exception is the optional self-assessment (`dec-self-assessment`),
 which needs a run in the browser and is no content of its own.
 
+Formulas, too, are set at build; the browser has no formula renderer. Trade-off for a generated exercise: the build
+sets a chemical formula of a drawn value (`\ce{{{r.gl}}}`) once for every value of its list. That makes the page
+larger and allows only values from a list, and only as the whole formula. Rejected: Temml in the client, which would
+make every page with an exercise larger.
+
 ```arc42
 :::decision
 id: dec-explainer-complete-without-js
@@ -441,3 +446,40 @@ date: 2026-10-28
 addresses: qg-understandable, qg-privacy, con-no-request-before-click
 :::
 ```
+
+## Format 2 Places the App on the Learning Map
+
+The catalog's learning map shows which apps practise which competencies. The app owns where it belongs: it names one
+strand (or `none`, so that none forgets), and each page the competencies it practises. The build hands this to the
+catalog (`if-page-list`); the catalog owns the subjects' ids and checks them. The fields are required, so this is a
+new format; format 1 stays valid for apps that do not move, and they are not on the map. Rejected: strand and
+competencies in the catalog entry (the pages would be listed twice); optional fields in format 1 (an app could forget
+them).
+
+```arc42
+:::decision
+id: dec-explainer-format-2
+title: Explainer format 2 names the app's strand and each page's competencies, and the build lists the pages
+status: accepted
+date: 2026-11-03
+addresses: qg-checkable, con-runtime-unchanged
+:::
+```
+
+## A Recap Page Repeats a Competency the App Does Not Practise
+
+A competency may require one the app does not practise; its learners may need it again. A recap page repeats it with
+descriptive blocks only: practising stays the job of the apps the map lists for it. The runtime, not the author, links
+the competency on the map, so the link cannot be missing; the catalog checks that the competency exists. Rejected:
+exercises on a recap page (the app would practise a competency the map does not show for it); a link the author writes
+(it could be missing or wrong).
+
+```arc42
+:::decision
+id: dec-explainer-recap-page
+title: A recap page repeats a competency of another strand without exercises and links it on the learning map
+status: accepted
+date: 2026-11-03
+addresses: qg-understandable, qg-checkable, con-no-request-before-click
+:::
+```

package/explainer/package.json

@@ -9,7 +9,7 @@
   },
   "devDependencies": {
     "@lernapps/app-templates": "file:..",
-    "@lernapps/tooling": "^0.1.2",
+    "@lernapps/tooling": "0.3.1",
     "vite-plus": "1.4.0"
   },
   "overrides": {

package/explainer/src/app.yaml

@@ -1,4 +1,6 @@
-# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
+format: 2
+strand: mathematik/arithmetik
 title: Prozentrechnung
 intro: |
   Prozentwert, Prozentsatz und Grundwert: Was sie bedeuten, wie du sie ausrechnest, und je ein Beispiel dazu.

package/explainer/src/prozent/chapter.yaml

@@ -1,4 +1,4 @@
-# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
 title: Prozent
 summary: Mit Prozenten vergleichst du Anteile, egal wie groß das Ganze ist.
 pages: [prozentwert, prozentsatz, grundwert]

package/explainer/src/prozent/grundwert.yaml

@@ -1,6 +1,7 @@
-# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
 title: Grundwert
 description: "Den Grundwert berechnen: G = W · 100 : p, mit einem Beispiel und dem Hunderterfeld."
+competencies: [prozent-grundwert]
 scope: |
   Gesucht ist das Ganze, wenn nur ein Teil und sein Prozentsatz bekannt sind, etwa der alte Preis, wenn 30 € gespart
   sind und das 12 % waren. Man rechnet $G = \frac{W \cdot 100}{p}$: $W$ geteilt durch $p$ ist 1 %, mal 100 das Ganze.

package/explainer/src/prozent/prozentsatz.yaml

@@ -1,6 +1,7 @@
-# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
 title: Prozentsatz
 description: "Den Prozentsatz berechnen: p = W : G · 100, mit einem Beispiel und dem Prozentstreifen."
+competencies: [prozent-prozentsatz]
 scope: |
   Gesucht ist, welcher Anteil der Teil vom Ganzen ist, etwa „18 von 24 Schülern“. Man rechnet
   $p = \frac{W}{G} \cdot 100$: Teil durch Ganzes gibt den Anteil, mal 100 die Prozent. Erst der Prozentsatz macht

package/explainer/src/prozent/prozentwert.yaml

@@ -1,6 +1,7 @@
-# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
 title: Prozentwert
 description: "Den Prozentwert berechnen: W = G · p : 100, mit einem Beispiel und dem Hunderterfeld."
+competencies: [prozent-prozentwert]
 scope: |
   Gesucht ist der Teil des Ganzen, etwa wie viel Euro man bei 20 % Rabatt auf 80 € spart. Man rechnet
   $W = \frac{G \cdot p}{100}$: erst 1 % des Grundwerts ($G$ geteilt durch 100), dann mal $p$. Der Prozentwert hat die

package/interactive/package.json

@@ -9,7 +9,7 @@
   },
   "devDependencies": {
     "@lernapps/app-templates": "file:..",
-    "@lernapps/tooling": "^0.1.2",
+    "@lernapps/tooling": "0.3.1",
     "vite-plus": "1.4.0"
   },
   "overrides": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/app-templates",
-  "version": "0.2.0",
+  "version": "0.3.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": {
@@ -68,6 +68,7 @@
     },
     "./explainer/style.css": "./runtime/explainer/explainer.css",
     "./explainer/explainer.v1.schema.json": "./runtime/explainer/explainer.v1.schema.json",
+    "./explainer/explainer.v2.schema.json": "./runtime/explainer/explainer.v2.schema.json",
     "./interactive": {
       "types": "./runtime/interactive/interactive.ts",
       "default": "./dist/interactive.mjs"
@@ -91,9 +92,7 @@
   "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"
+    "check:vue": "vue-tsc --noEmit -p tsconfig.vue.json"
   },
   "dependencies": {
     "@vitejs/plugin-vue": "6.0.10",

package/quiz/package.json

@@ -9,7 +9,7 @@
   },
   "devDependencies": {
     "@lernapps/app-templates": "file:..",
-    "@lernapps/tooling": "^0.1.2",
+    "@lernapps/tooling": "0.3.1",
     "vite-plus": "1.4.0"
   },
   "overrides": {

package/runtime/explainer/assessment.ts

@@ -121,13 +121,15 @@ export function assessments(site: Site): Assessment[] {
   // the app's: the pages of every chapter's, in the order of the chapters
   const steps = site.chapters.flatMap((chapter) => chapter.selfAssessment?.pages ?? []);
   if (steps.length === 0) return [];
-  const all = site.chapters.flatMap((chapter) => chapter.pages);
+  // a recap page has no exercise: the self-assessment leaves it out
+  const asked = (pages: readonly Page[]) => pages.filter((page) => page.recap === undefined);
+  const all = asked(site.chapters.flatMap((chapter) => chapter.pages));
   // a chapter's of its own only where the app shows its chapters: with one chapter, the app's is the chapter's
   const own = site.chapters.length === 1 ? [] : site.chapters;
   return [
     of({ pages: steps }, all),
     ...own.flatMap((chapter) =>
-      chapter.selfAssessment === undefined ? [] : [of(chapter.selfAssessment, chapter.pages, chapter)],
+      chapter.selfAssessment === undefined ? [] : [of(chapter.selfAssessment, asked(chapter.pages), chapter)],
     ),
   ];
 }

package/runtime/explainer/check-page.ts

@@ -20,7 +20,7 @@ import {
   type Text,
 } from "./content.ts";
 import { ExpressionError, parse, variables } from "./expression.ts";
-import { dataOf, templatesOf } from "./exercises.ts";
+import { ChemError, dataOf, templatesOf } from "./exercises.ts";
 import { exampleProblems, soundness } from "./generated/soundness.ts";
 import { templateProblems, unusedVariables } from "./generated/texts.ts";
 import { type Generated, type Templates } from "./generated/types.ts";
@@ -501,8 +501,12 @@ function checkGenerated(check: PageCheck, block: Generated, at: Path): void {
   for (const [name, file] of check.dataFiles) records[name] = file.value as DataRecord[];
   let templates: Templates;
   try {
-    templates = templatesOf(block, texts.languages);
+    templates = templatesOf(block, texts.languages, dataOf(block, records));
   } catch (error) {
+    if (error instanceof ChemError) {
+      problems.at(yaml, at, error.message);
+      return;
+    }
     const reason = (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
     problems.at(
       yaml,

package/runtime/explainer/content.ts

@@ -1,4 +1,5 @@
-// The content of an explainer, as the YAML files in src/ give it (explainer.v1.schema.json) and the build reads it
+// The content of an explainer, as the YAML files in src/ give it (explainer.v1.schema.json, or in format 2
+// explainer.v2.schema.json) and the build reads it
 // (load.ts): the app, its chapters in order, their pages in order, the data files, the bundled images and the
 // components (src/components/, components.ts) with the blocks that use them.
 
@@ -43,6 +44,10 @@ export interface Source {
 }
 
 export interface App {
+  /** The format of the content: 2, or none for format 1. */
+  format?: 2;
+  /** Format 2: the strand of the learning map the app stays in, <subject>/<strand>, or none. */
+  strand?: string;
   title: Text;
   intro: Text;
   languages: readonly string[];
@@ -102,6 +107,14 @@ export interface Page {
   file: string;
   title: Text;
   description?: Text;
+  /** Format 2: the ids of the competencies of the learning map that the page practises. */
+  competencies?: readonly string[];
+  /**
+   * Format 2: makes the page a recap page, which repeats this competency (one the app does not practise), <subject>/<competency>,
+   * instead of practising competencies of its own: no exercise, a link to the competency on the learning map, left
+   * out of the self-assessment.
+   */
+  recap?: string;
   /** What the page teaches, for the tutor's scope (scope.ts). */
   scope?: Text;
   blocks: readonly Block[];
@@ -253,6 +266,12 @@ export function* allBlocks(blocks: readonly Block[]): Generator<Block> {
   }
 }
 
+/** The page of a competency on the learning map of lernapps.net, from <subject>/<competency> (a recap page's recap). */
+export function mapUrl(recap: string): string {
+  const [subject = "", competency = ""] = recap.split("/");
+  return `https://lernapps.net/apps/map/${subject}/c/${competency}/`;
+}
+
 /** Whether a block is an exercise. */
 export const isExercise = (block: Block): block is Exercise =>
   block.type === "generated" ||

package/runtime/explainer/exercises.ts

@@ -10,8 +10,10 @@ import { renderMaterial, type MaterialContext } from "../shared/blocks/index.ts"
 import { answerText, questionMessagesIn, renderQuestion, renderSolution } from "../shared/questions/render.ts";
 import { inLanguage, type Text } from "../shared/languages.ts";
 import type { DataRecord, Exercise, OpenTask, QuestionBlock } from "./content.ts";
-import { hintOf, stepsOf, taskText, tokenize } from "./generated/texts.ts";
-import { generate } from "./generated/values.ts";
+import { chemPlaceholdersIn, hintOf, label, stepsOf, taskText, tokenize, writtenTemplates } from "./generated/texts.ts";
+import { generate, items } from "./generated/values.ts";
+import { evaluate, parse, type Value } from "./expression.ts";
+import { renderFormula } from "../shared/text/formula.ts";
 import { questionFor, taskKey } from "./generated/question.ts";
 import { WORKED_TASKS } from "./tasks.ts";
 import { type Data, type Generated, type LanguageTemplates, type Templates } from "./generated/types.ts";
@@ -57,20 +59,83 @@ export interface OpenTaskData {
   hint?: string;
 }
 
-/** The templates of a generated exercise in each of `languages`; links inside them through `resolve`. */
+/** A value of a placeholder in \ce{{{…}}} whose formula does not parse; the check reports its message as it is. */
+export class ChemError extends Error {}
+
+/**
+ * The chemical formula of each value of the placeholders in \ce{{{…}}} of an exercise's templates in `lang`, as
+ * MathML without <math>, by the value as the learner reads it: each value of the list the placeholder's root is
+ * drawn from (oneOf, or pick: 1 from a list or a data file), set by mhchem as \ce{value}. Throws a ChemError for a
+ * value that does not parse.
+ */
+export function chemFormulas(spec: Generated, data: Data, lang: string): Record<string, string> {
+  const formulas: Record<string, string> = {};
+  const paths = new Set(
+    writtenTemplates(spec)
+      .filter((written) => written.lang === undefined || written.lang === lang)
+      .flatMap((written) => chemPlaceholdersIn(written.text)),
+  );
+  for (const path of paths) {
+    const root = path.split(".")[0] ?? "";
+    const arbitrary = spec.given[root];
+    if (arbitrary === undefined) continue; // reported by templateProblems
+    const source = arbitrary.oneOf ?? (arbitrary.pick === 1 ? arbitrary.from : undefined);
+    if (source === undefined) continue; // reported by templateProblems
+    let candidates: Value[];
+    try {
+      candidates = items(source, data);
+    } catch {
+      continue; // a missing data file is reported on its own
+    }
+    for (const candidate of candidates) {
+      let text: string;
+      try {
+        text = label(evaluate(parse(path), { [root]: candidate }), lang);
+      } catch {
+        continue; // a record without the field, reported when a task draws it
+      }
+      if (text in formulas) continue;
+      try {
+        // a value with unbalanced braces would end \ce early and leave the rest outside it
+        let depth = 0;
+        for (const char of text) {
+          if (char === "{") depth++;
+          else if (char === "}" && --depth < 0) break;
+        }
+        if (depth !== 0) throw new Error("its braces are not balanced");
+        const math = renderFormula(`\\ce{${text}}`, false);
+        formulas[text] = /^<math[^>]*>([\s\S]*)<\/math>$/.exec(math)?.[1] ?? math;
+      } catch (error) {
+        const reason = (error instanceof Error ? error.message : String(error)).split("\n")[0]?.trim() ?? "";
+        throw new ChemError(
+          `\\ce{{{${path}}}}: the value "${text}" is no chemical formula mhchem can set (${reason}); write it in mhchem's notation, e.g. 2H2 + O2 -> 2H2O`,
+        );
+      }
+    }
+  }
+  return formulas;
+}
+
+/**
+ * The templates of a generated exercise in each of `languages`, with the formulas of the values in \ce{{{…}}} drawn
+ * from `data`; links inside them through `resolve`.
+ */
 export function templatesOf(
   spec: Generated,
   languages: readonly string[],
+  data: Data,
   resolve: (href: string) => string = (href) => href,
 ): Templates {
   const templates: Record<string, LanguageTemplates> = {};
   for (const lang of languages) {
     const inline = (text: Text) => renderInline(tokenize(inLanguage(text, lang)), resolve);
+    const chem = chemFormulas(spec, data, lang);
     templates[lang] = {
       task: inline(spec.task.text),
       steps: (spec.steps ?? []).map(inline),
       hint: spec.hint === undefined ? undefined : inline(spec.hint),
       messages: (spec.mistakes ?? []).map((mistake) => tokenize(inLanguage(mistake.message, lang))),
+      ...(Object.keys(chem).length === 0 ? {} : { chem }),
     };
   }
   return templates;
@@ -93,7 +158,7 @@ const seedCache = new WeakMap<Generated, number[]>();
 export function taskSeeds(spec: Generated, data: Data): number[] {
   let seeds = seedCache.get(spec);
   if (seeds === undefined) {
-    const templates = templatesOf(spec, ["de"]);
+    const templates = templatesOf(spec, ["de"], data);
     seeds = distinctSeeds((seed) => {
       try {
         return taskKey(spec, generate(spec, seed, data), "de", templates);
@@ -192,7 +257,7 @@ function generatedData(
     kind: "generated",
     lang,
     spec: shipped,
-    templates: templatesOf(spec, [lang], resolve),
+    templates: templatesOf(spec, [lang], data, resolve),
     data,
     seeds: taskSeeds(spec, data),
     texts: {
@@ -277,8 +342,8 @@ function generatedExercise(
   all: Readonly<Record<string, readonly DataRecord[]>>,
   resolve: (href: string) => string,
 ): string {
-  const templates = templatesOf(spec, [lang], resolve);
   const data = dataOf(spec, all);
+  const templates = templatesOf(spec, [lang], data, resolve);
   const solution = questionMessagesIn(lang).solution;
   const worked = workedTasks(spec, data, templates, lang).map((item) =>
     [

package/runtime/explainer/explainer.css

@@ -162,6 +162,27 @@
   font-size: 0.9375rem;
 }
 
+/* a recap page: what it is, and where the competency is practised */
+.explainer-recap {
+  margin: 1rem 0 1.5rem;
+  padding: 0.75rem 1rem;
+  border-left: 4px solid var(--page-border);
+  background: var(--page-surface);
+}
+
+.explainer-recap p {
+  margin: 0.25rem 0;
+}
+
+.explainer-recap-label {
+  font-weight: 600;
+}
+
+.explainer-recap-note {
+  color: var(--page-muted);
+  font-size: 0.9375rem;
+}
+
 .explainer-glossary dt {
   margin-top: 1rem;
   font-weight: 600;

package/runtime/explainer/explainer.v1.schema.json

@@ -748,7 +748,7 @@
       "type": "object"
     },
     "expression": {
-      "description": "An expression of the expression language, e.g. \"G * p / 100\": numbers (exact fractions), + - * /, parentheses, == != < <= > >=, and, or, not, strings in quotes, record fields (e.year), list index (xs[0]), lists ([1, 2]), and the functions round(x, n), decimals, map(xs, field), sortBy(xs, field), reverse. It may use the variables of given.",
+      "description": "An expression of the expression language, e.g. \"G * p / 100\": numbers (exact fractions), + - * /, parentheses, == != < <= > >=, and, or, not, strings in quotes, record fields (e.year), list index (xs[0]), lists ([1, 2]), and the functions round(x, n), decimals, map(xs, field), sortBy(xs, field), reverse, sqrt(x), pow(x, n), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x). Angles are in degrees: sin(30) is 1/2. Round a result that is not rational (sqrt(2)) with round(x, n). It may use the variables of given.",
       "type": "string",
       "minLength": 1,
       "pattern": "\\S"
@@ -881,7 +881,7 @@
       }
     },
     "generated": {
-      "description": "An exercise drawn from a seed, property-based: given draws the values, where filters them, task is the text with placeholders ({{G}}, {{e.name}}; {{answer}} in the steps), answer is an expression with its comparator, mistakes are typical wrong answers each with a message saying what went wrong, hint and steps help. A placeholder is always two braces around a declared name or its field, nothing else inside, in prose and in formulas alike ($\\frac{{{W}}}{{{G}}}$); an index is no field, so {{opts[0].x}} is no placeholder and the build reports it: draw the record on its own (given: { e: { pick: 1, from: { data: name } } }) and write {{e.x}}; one brace is never a placeholder, so in a formula G and {G} are the letter. The build checks that every placeholder names a variable of given (or answer), that no text has double braces around anything but a name or its field, that no prose has a placeholder with one brace or spaces inside, and that every variable of given is used in a placeholder or in an expression of the answer or mistakes; then it checks it over 200 fixed seeds: where holds in at least 1 of 10 draws; the answer is defined, in its format and passes its comparator; no mistake equals it; the task is the same each time and keeps no placeholder. Its tasks are numbered: the build walks the seeds 1, 2, 3, … and numbers only the distinct tasks, Aufgabe Nr. 1 to N (N at most 67; fewer when the exercise has fewer distinct tasks, noted in the build output). The number is what the page shows, what a learner names to a tutor, and what the address carries: ?seed=<n>#<id> opens task number n (a number above N wraps around). Without JavaScript the page shows the tasks 1, 2 and 3 as worked tasks with their solution; with JavaScript a live task of a random number, Neue Aufgabe, which moves to the next number (after N back to 1) and writes it into the address, and the deep link: a wrong answer gets the message of the mistake it matches (else a line to look again, with the hint above) and may be tried again; the solution and the steps show after the right answer or Lösung zeigen.",
+      "description": "An exercise drawn from a seed, property-based: given draws the values, where filters them, task is the text with placeholders ({{G}}, {{e.name}}; {{answer}} in the steps), answer is an expression with its comparator, mistakes are typical wrong answers each with a message saying what went wrong, hint and steps help. A placeholder is always two braces around a declared name or its field, nothing else inside, in prose and in formulas alike ($\\frac{{{W}}}{{{G}}}$); an index is no field, so {{opts[0].x}} is no placeholder and the build reports it: draw the record on its own (given: { e: { pick: 1, from: { data: name } } }) and write {{e.x}}; one brace is never a placeholder, so in a formula G and {G} are the letter. A chemical formula from a record is $\\ce{{{r.gl}}}$: the whole formula in one field (gl: \"2H2 + O2 -> 2H2O\"), r drawn with pick: 1 or oneOf; a placeholder inside a longer \\ce or in \\pu is not possible. The build checks that every placeholder names a variable of given (or answer), that no text has double braces around anything but a name or its field, that no prose has a placeholder with one brace or spaces inside, and that every variable of given is used in a placeholder or in an expression of the answer or mistakes; then it checks it over 200 fixed seeds: where holds in at least 1 of 10 draws; the answer is defined, in its format and passes its comparator; no mistake equals it; the task is the same each time and keeps no placeholder. Its tasks are numbered: the build walks the seeds 1, 2, 3, … and numbers only the distinct tasks, Aufgabe Nr. 1 to N (N at most 67; fewer when the exercise has fewer distinct tasks, noted in the build output). The number is what the page shows, what a learner names to a tutor, and what the address carries: ?seed=<n>#<id> opens task number n (a number above N wraps around). Without JavaScript the page shows the tasks 1, 2 and 3 as worked tasks with their solution; with JavaScript a live task of a random number, Neue Aufgabe, which moves to the next number (after N back to 1) and writes it into the address, and the deep link: a wrong answer gets the message of the mistake it matches (else a line to look again, with the hint above) and may be tried again; the solution and the steps show after the right answer or Lösung zeigen.",
       "required": ["id", "given", "task", "answer"],
       "properties": {
         "id": {

package/runtime/explainer/explainer.v2.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:lernapps:schema:explainer.v2",
+  "title": "Content of a lernapps explainer, format 2",
+  "description": "Format 2 of an explainer's content, as YAML in src/: src/app.yaml, src/<chapter>/chapter.yaml, src/<chapter>/<page>.yaml and src/data/<name>.yaml. It is format 1 (explainer.v1.schema.json) plus the app's place on the learning map: format: 2 and strand in src/app.yaml, and on each page the competencies it practises, or recap on a page that repeats a competency from elsewhere. An app.yaml without format is format 1.",
+  "allOf": [
+    {
+      "if": {
+        "type": "object",
+        "required": ["chapters"],
+        "properties": {
+          "chapters": {}
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/app"
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "required": ["pages"],
+        "properties": {
+          "pages": {}
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/chapter"
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "required": ["blocks"],
+        "properties": {
+          "blocks": {}
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/page"
+      }
+    },
+    {
+      "if": {
+        "type": "array"
+      },
+      "then": {
+        "$ref": "#/$defs/data"
+      }
+    }
+  ],
+  "$defs": {
+    "id": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/id"
+    },
+    "strand": {
+      "description": "The one strand (Strang) of the learning map the app belongs to, <subject>/<strand>, e.g. mathematik/stochastik; or none if it belongs to none (then it is not on the map).",
+      "type": "string",
+      "pattern": "^(none|[a-z0-9]+(-[a-z0-9]+)*/[a-z0-9]+(-[a-z0-9]+)*)$"
+    },
+    "competency": {
+      "description": "A competency of the learning map, <subject>/<competency>, e.g. physik/gewichtskraft-berechnen.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*/[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "app": {
+      "description": "src/app.yaml in format 2: format: 2 and strand, everything else as in format 1.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["format", "strand", "title", "intro", "languages", "chapters"],
+      "properties": {
+        "format": {
+          "description": "Always 2. Without it, the content is format 1 (explainer.v1.schema.json).",
+          "const": 2
+        },
+        "strand": {
+          "$ref": "#/$defs/strand"
+        },
+        "title": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/title"
+        },
+        "intro": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/intro"
+        },
+        "languages": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/languages"
+        },
+        "chapters": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/chapters"
+        },
+        "sources": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/sources"
+        },
+        "tutor": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/tutor"
+        },
+        "scope": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/app/properties/scope"
+        }
+      }
+    },
+    "chapter": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/chapter"
+    },
+    "page": {
+      "description": "src/<chapter>/<page>.yaml in format 2: a page as in format 1, plus competencies, or recap on a recap page.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "blocks"],
+      "properties": {
+        "title": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/title"
+        },
+        "description": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/description"
+        },
+        "competencies": {
+          "description": "The competencies (Bausteine) the page practises, ids of the subject of the app's strand; as a rule one. Required when the app has a strand; leave it out with strand: none and on a recap page. The catalog checks the ids when it lists the app.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "recap": {
+          "description": "Makes the page a recap page: it repeats a competency that the app's competencies require but the app does not practise, e.g. physik/gewichtskraft-berechnen. Use it instead of competencies, also with strand: none. A recap page has descriptive blocks only, no exercise; the link to the competency on the learning map is added for you.",
+          "$ref": "#/$defs/competency"
+        },
+        "blocks": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/blocks"
+        },
+        "scope": {
+          "$ref": "urn:lernapps:schema:explainer.v1#/$defs/page/properties/scope"
+        }
+      },
+      "not": {
+        "required": ["competencies", "recap"],
+        "properties": {
+          "competencies": {},
+          "recap": {}
+        }
+      }
+    },
+    "data": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/data"
+    },
+    "event": {
+      "$ref": "urn:lernapps:schema:explainer.v1#/$defs/event"
+    }
+  }
+}