@lernapps/app-templates 0.2.1 → 0.3.0

package/runtime/explainer/expression.ts

@@ -4,7 +4,10 @@
 // - arithmetic on exact fractions: + - * /, parentheses, unary minus; numbers as written (0.1 is 1/10);
 // - comparisons == != < <= > >=, and, or, not; true, false; strings in quotes;
 // - record fields (e.year), list index (xs[0]), list literals ([1, 2, 3]);
-// - the functions round(x, n), decimals(x), map(xs, field), sortBy(xs, field), reverse(xs).
+// - the functions round(x, n), decimals(x), map(xs, field), sortBy(xs, field), reverse(xs);
+// - the functions sqrt(x), pow(x, n), sin(x), cos(x), tan(x) and asin(x), acos(x), atan(x), with angles in degrees as
+//   in school (sin(30) is 1/2). A result is exact where it is rational (sqrt(9/4), pow(2, 10), sin(30), cos(60),
+//   tan(45), asin(1/2)); otherwise it is the value to 12 decimal places, which an exercise rounds with round(x, n).
 // Errors are ExpressionErrors whose message says what to change.
 import { Fraction } from "./fraction.ts";
 
@@ -49,6 +52,14 @@ const FUNCTIONS: Readonly<Record<string, { arity: number; field?: number }>> = {
   map: { arity: 2, field: 1 },
   sortBy: { arity: 2, field: 1 },
   reverse: { arity: 1 },
+  sqrt: { arity: 1 },
+  pow: { arity: 2 },
+  sin: { arity: 1 },
+  cos: { arity: 1 },
+  tan: { arity: 1 },
+  asin: { arity: 1 },
+  acos: { arity: 1 },
+  atan: { arity: 1 },
 };
 const KEYWORDS = new Set(["and", "or", "not", "true", "false"]);
 
@@ -322,6 +333,107 @@ function integer(value: Fraction, what: string): number {
   return Number(value.n);
 }
 
+/** The decimal places of a result that is not rational (sqrt(2), sin(10)): enough for any rounding of an exercise. */
+export const APPROXIMATION_PLACES = 12;
+
+/** A real number that is no fraction, as the fraction of its first APPROXIMATION_PLACES decimals. */
+function approximate(value: number, what: string): Fraction {
+  if (!Number.isFinite(value)) throw new ExpressionError(`${what} has no result here`);
+  return Fraction.from(Number(value.toFixed(APPROXIMATION_PLACES)));
+}
+
+/** The square root of a whole number ≥ 0, if it is whole. */
+function wholeRoot(n: bigint): bigint | undefined {
+  if (n < 2n) return n;
+  let x = BigInt(Math.floor(Math.sqrt(Number(n))));
+  while (x * x > n) x--;
+  while ((x + 1n) * (x + 1n) <= n) x++;
+  return x * x === n ? x : undefined;
+}
+
+function sqrt(x: Fraction): Fraction {
+  if (x.n < 0n) throw new ExpressionError(`sqrt needs a number ≥ 0, not ${x.toNumber()}`);
+  const n = wholeRoot(x.n);
+  const d = wholeRoot(x.d);
+  return n !== undefined && d !== undefined ? Fraction.of(n, d) : approximate(Math.sqrt(x.toNumber()), "sqrt");
+}
+
+/** The largest exponent of pow: beyond it, a number has more digits than any exercise shows. */
+const MAX_EXPONENT = 1000;
+
+function pow(x: Fraction, n: Fraction): Fraction {
+  if (n.isInteger()) {
+    const e = Number(n.n);
+    if (Math.abs(e) > MAX_EXPONENT)
+      throw new ExpressionError(`pow takes an exponent from -${MAX_EXPONENT} to ${MAX_EXPONENT}`);
+    if (x.n === 0n && e < 0) throw new ExpressionError("pow(0, n) needs n ≥ 0: division by zero");
+    const power = Fraction.of(x.n ** BigInt(Math.abs(e)), x.d ** BigInt(Math.abs(e)));
+    return e < 0 ? Fraction.of(1).div(power) : power;
+  }
+  if (x.n < 0n) throw new ExpressionError("pow of a negative number needs a whole exponent");
+  return approximate(x.toNumber() ** n.toNumber(), "pow");
+}
+
+/** The angle `x` in degrees, brought into 0 ≤ x < 360 exactly. */
+function turn(x: Fraction): Fraction {
+  const full = Fraction.of(360);
+  const quotient = x.div(full);
+  // floor of the quotient
+  let floor = quotient.n / quotient.d;
+  if (quotient.n < 0n && quotient.n % quotient.d !== 0n) floor -= 1n;
+  return x.sub(full.mul(Fraction.of(floor)));
+}
+
+/** The sine of the angles 0°, 30°, 90°, … whose sine is rational, in degrees. */
+const EXACT_SINE: ReadonlyMap<number, Fraction> = new Map([
+  [0, Fraction.of(0)],
+  [30, Fraction.of(1, 2)],
+  [90, Fraction.of(1)],
+  [150, Fraction.of(1, 2)],
+  [180, Fraction.of(0)],
+  [210, Fraction.of(-1, 2)],
+  [270, Fraction.of(-1)],
+  [330, Fraction.of(-1, 2)],
+]);
+const RADIANS = Math.PI / 180;
+
+function sine(degrees: Fraction): Fraction {
+  const angle = turn(degrees);
+  const exact = angle.isInteger() ? EXACT_SINE.get(Number(angle.n)) : undefined;
+  return exact ?? approximate(Math.sin(angle.toNumber() * RADIANS), "sin");
+}
+
+const cosine = (degrees: Fraction): Fraction => sine(degrees.add(Fraction.of(90)));
+
+function tangent(degrees: Fraction): Fraction {
+  const angle = turn(degrees);
+  const cos = cosine(angle);
+  if (cos.n === 0n) throw new ExpressionError(`tan(${degrees.toNumber()}) has no value: the cosine of the angle is 0`);
+  if (angle.isInteger() && [45, 135, 225, 315].includes(Number(angle.n))) {
+    return Fraction.of(Number(angle.n) % 180 === 45 ? 1 : -1);
+  }
+  const sin = sine(angle);
+  return sin.n === 0n ? sin : approximate(Math.tan(angle.toNumber() * RADIANS), "tan");
+}
+
+/** The inverse of sin, cos or tan in degrees: exact for the values of the angles of EXACT_SINE and of 45°. */
+function inverse(fn: "asin" | "acos" | "atan", x: Fraction): Fraction {
+  if (fn !== "atan" && (x.compare(Fraction.of(-1)) < 0 || x.compare(Fraction.of(1)) > 0)) {
+    throw new ExpressionError(`${fn} needs a number from -1 to 1, not ${x.toNumber()}`);
+  }
+  const exact: Readonly<Record<string, number>> =
+    fn === "asin"
+      ? { "-1": -90, "-1/2": -30, "0": 0, "1/2": 30, "1": 90 }
+      : fn === "acos"
+        ? { "-1": 180, "-1/2": 120, "0": 90, "1/2": 60, "1": 0 }
+        : { "-1": -45, "0": 0, "1": 45 };
+  const known = exact[x.toString()];
+  if (known !== undefined) return Fraction.of(known);
+  const radians =
+    fn === "asin" ? Math.asin(x.toNumber()) : fn === "acos" ? Math.acos(x.toNumber()) : Math.atan(x.toNumber());
+  return approximate(radians / RADIANS, fn);
+}
+
 function call(fn: string, args: readonly Node[], env: Readonly<Record<string, Value>>): Value {
   const value = (index: number) => evaluate(args[index] as Node, env);
   const field = () => (args[1] as Extract<Node, { kind: "name" }>).name;
@@ -341,6 +453,20 @@ function call(fn: string, args: readonly Node[], env: Readonly<Record<string, Va
     }
     case "reverse":
       return [...asList(value(0), "reverse")].reverse();
+    case "sqrt":
+      return sqrt(asNumber(value(0), "sqrt"));
+    case "pow":
+      return pow(asNumber(value(0), "pow"), asNumber(value(1), "pow"));
+    case "sin":
+      return sine(asNumber(value(0), "sin"));
+    case "cos":
+      return cosine(asNumber(value(0), "cos"));
+    case "tan":
+      return tangent(asNumber(value(0), "tan"));
+    case "asin":
+    case "acos":
+    case "atan":
+      return inverse(fn, asNumber(value(0), fn));
     default:
       throw new ExpressionError(`${fn} is not a function of the expression language`);
   }

package/runtime/explainer/generated/texts.ts

@@ -18,6 +18,10 @@ const PATH_ONLY = new RegExp(String.raw`^${PATH}$`);
 const SPACED = new RegExp(String.raw`\{\{\s*(${PATH})\s*\}\}`, "g");
 /** A formula ($…$) or a run of prose, in a template. */
 const SEGMENT = /\$((?:\\.|[^\\$\n])+?)\$|([^$]+)/g;
+/** A chemical formula whose whole argument is one placeholder: \ce{{{e.gl}}}. */
+const CHEM = new RegExp(String.raw`\\ce\{\{\{(${PATH})\}\}\}`, "g");
+/** The start of the token of a placeholder that is the whole argument of \ce: ⟦ce:e.gl⟧. */
+const CHEM_TOKEN = "ce:";
 
 const formats = new Map<string, Intl.NumberFormat>();
 /** A number as the page shows it: up to six decimals, no grouping (a learner would type 1500, not 1.500). */
@@ -54,15 +58,89 @@ export function answerLabel(spec: Generated, task: Task, lang: string): string {
   return label(task.answer, lang);
 }
 
-/** A template's placeholders as tokens: {{G}} becomes ⟦G⟧, inside a formula ($…$) {\text{⟦G⟧}}. */
+/**
+ * A template's placeholders as tokens: {{G}} becomes ⟦G⟧, inside a formula ($…$) {\text{⟦G⟧}}; a chemical formula
+ * whose whole argument is a placeholder, \ce{{{e.gl}}}, becomes {\text{⟦ce:e.gl⟧}}, which fill() replaces by the
+ * formula the build set for the task's value (LanguageTemplates.chem).
+ */
 export function tokenize(text: string): string {
   return text.replace(SEGMENT, (whole, math: string | undefined, prose: string | undefined) =>
     math !== undefined
-      ? `$${math.replace(PLACEHOLDER, (_placeholder, path: string) => `{\\text{⟦${path}⟧}}`)}$`
+      ? `$${math
+          .replace(CHEM, (_chem, path: string) => `{\\text{⟦${CHEM_TOKEN}${path}⟧}}`)
+          .replace(PLACEHOLDER, (_placeholder, path: string) => `{\\text{⟦${path}⟧}}`)}$`
       : (prose ?? whole).replace(PLACEHOLDER, (_placeholder, path: string) => `⟦${path}⟧`),
   );
 }
 
+/** The formulas of a template ($…$), as written. */
+const formulasIn = (text: string): string[] =>
+  [...text.matchAll(SEGMENT)].flatMap((match) => (match[1] === undefined ? [] : [match[1]]));
+
+/** The placeholders that are the whole argument of a \ce in a formula of a template (\ce{{{e.gl}}}), by their path. */
+export function chemPlaceholdersIn(text: string): string[] {
+  return formulasIn(text).flatMap((math) => [...math.matchAll(CHEM)].map((match) => match[1] ?? ""));
+}
+
+/** The argument of each \ce and \pu of a formula, with its command; braces balanced. */
+function mhchemArguments(math: string): { command: string; argument: string }[] {
+  const found: { command: string; argument: string }[] = [];
+  for (const match of math.matchAll(/\\(ce|pu)\s*\{/g)) {
+    const start = (match.index ?? 0) + match[0].length;
+    let depth = 1;
+    for (let at = start; at < math.length; at++) {
+      if (math[at] === "{") depth++;
+      else if (math[at] === "}" && --depth === 0) {
+        found.push({ command: `\\${match[1] ?? ""}`, argument: math.slice(start, at) });
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+const WHOLE_PLACEHOLDER = new RegExp(String.raw`^\{\{${PATH}\}\}$`);
+
+/**
+ * The problems of the placeholders in \ce and \pu of one template. A placeholder in \ce is its whole argument,
+ * \ce{{{e.gl}}}, drawn from a finite list (oneOf, or pick: 1 from a list or a data file), so that the build can set
+ * the formula of every value; \pu takes none.
+ */
+export function chemProblems(text: string, given: Generated["given"]): string[] {
+  const problems: string[] = [];
+  for (const math of formulasIn(text)) {
+    for (const { command, argument } of mhchemArguments(math)) {
+      if (placeholdersIn(argument).length === 0) continue;
+      if (command === "\\pu") {
+        problems.push(
+          `\\pu{${argument}} has a placeholder inside; \\pu takes none: write the number before it, e.g. {{m}}\\,\\pu{g}`,
+        );
+      } else if (!WHOLE_PLACEHOLDER.test(argument)) {
+        problems.push(
+          `\\ce{${argument}} has a placeholder among other text; in \\ce a placeholder is the whole argument, \\ce{{{e.gl}}}: put the whole formula into one field of the data (gl: "2H2 + O2 -> 2H2O")`,
+        );
+      }
+    }
+  }
+  for (const path of chemPlaceholdersIn(text)) {
+    const root = path.split(".")[0] ?? "";
+    if (root === "answer") {
+      problems.push(
+        "\\ce{{{answer}}} is not possible: the build sets only the formulas of values drawn from a list; show the formula of a value of given",
+      );
+      continue;
+    }
+    const arbitrary = given[root];
+    if (arbitrary === undefined) continue; // reported as an unknown placeholder
+    if (arbitrary.oneOf === undefined && !(arbitrary.from !== undefined && arbitrary.pick === 1)) {
+      problems.push(
+        `\\ce{{{${path}}}} needs one value from a list: draw ${root} with oneOf, or with pick: 1 from a list or a data file, so that the build can set the formula of each value`,
+      );
+    }
+  }
+  return problems;
+}
+
 /** The placeholders of a template, by their path (G, e.name, answer). */
 export function placeholdersIn(text: string): string[] {
   return [...text.matchAll(PLACEHOLDER)].map((match) => match[1] ?? "");
@@ -136,7 +214,7 @@ export function templateProblems(spec: Generated): { path: (string | number)[];
   const declared = [...Object.keys(spec.given), "answer"];
   return writtenTemplates(spec).flatMap(({ path, lang, text }) => {
     const known = new Set(declared);
-    return placeholderProblems(text, known).map((message) => ({
+    return [...placeholderProblems(text, known), ...chemProblems(text, spec.given)].map((message) => ({
       path,
       ...(lang === undefined ? {} : { lang }),
       message,
@@ -194,10 +272,18 @@ export function fill(
   task: Task,
   lang: string,
   mode: "html" | "text" = "html",
+  chem: Readonly<Record<string, string>> = {},
 ): string {
   const withMath =
     mode === "html"
-      ? template.replace(/<mtext>⟦([^⟧]+)⟧<\/mtext>/g, (_whole, path: string) => {
+      ? template.replace(/<mtext>⟦([^⟧]+)⟧<\/mtext>/g, (_whole, token: string) => {
+          if (token.startsWith(CHEM_TOKEN)) {
+            const path = token.slice(CHEM_TOKEN.length);
+            const value = placeholderValue(spec, task, path, lang);
+            if (value === undefined) return `<mtext>{{${escape(path)}}}</mtext>`;
+            return chem[value.text] ?? `<mtext>${escape(value.text)}</mtext>`;
+          }
+          const path = token;
           const value = placeholderValue(spec, task, path, lang);
           if (value === undefined) return `<mtext>{{${escape(path)}}}</mtext>`;
           if (value.number === undefined) return `<mtext>${escape(value.text)}</mtext>`;
@@ -206,7 +292,8 @@ export function fill(
           return negative ? `<mo>−</mo><mn>${digits}</mn>` : `<mn>${digits}</mn>`;
         })
       : template;
-  return withMath.replace(/⟦([^⟧]+)⟧/g, (_whole, path: string) => {
+  return withMath.replace(/⟦([^⟧]+)⟧/g, (_whole, token: string) => {
+    const path = token.startsWith(CHEM_TOKEN) ? token.slice(CHEM_TOKEN.length) : token;
     const value = placeholderValue(spec, task, path, lang);
     if (value === undefined) return `{{${path}}}`;
     return mode === "html" ? escape(value.text) : value.text;
@@ -229,18 +316,20 @@ export const templatesIn = (templates: Templates, lang: string): LanguageTemplat
 
 /** The task's text as HTML, in `lang`. */
 export function taskText(spec: Generated, task: Task, lang: string, templates: Templates): string {
-  return fill(templatesIn(templates, lang).task, spec, task, lang);
+  const { task: text, chem } = templatesIn(templates, lang);
+  return fill(text, spec, task, lang, "html", chem);
 }
 
 /** The steps of the solution as HTML, in `lang`. */
 export function stepsOf(spec: Generated, task: Task, lang: string, templates: Templates): string[] {
-  return templatesIn(templates, lang).steps.map((step) => fill(step, spec, task, lang));
+  const { steps, chem } = templatesIn(templates, lang);
+  return steps.map((step) => fill(step, spec, task, lang, "html", chem));
 }
 
 /** The hint as HTML, in `lang`, if the exercise has one. */
 export function hintOf(spec: Generated, task: Task, lang: string, templates: Templates): string | undefined {
-  const hint = templatesIn(templates, lang).hint;
-  return hint === undefined ? undefined : fill(hint, spec, task, lang);
+  const { hint, chem } = templatesIn(templates, lang);
+  return hint === undefined ? undefined : fill(hint, spec, task, lang, "html", chem);
 }
 
 /** The text of HTML, as a learner reads it: tags left out, entities resolved, white space folded. */

package/runtime/explainer/generated/types.ts

@@ -17,6 +17,9 @@
 // around a lone name ({{G}}), means the same as the letter alone, so nothing is lost; any other group ({{G}^2},
 // {{G} + 1}) stays a group. To fill in a value where the formula needs a group, keep the group: \frac{{{W}}}{{{G}}}.
 // Two braces with spaces inside ({{ G }}) are an error everywhere, as they were most likely meant as a placeholder.
+// In \ce a placeholder is the whole argument, \ce{{{e.gl}}}, drawn from a finite list (oneOf, or pick: 1 from a list
+// or a data file): the build sets the formula of each value with mhchem (LanguageTemplates.chem), and fill() puts in
+// the one of the task's value. A placeholder among other text in \ce, or any in \pu, is an error.
 
 // This module: the types of a generated exercise, its task and its data.
 import { type Value } from "../expression.ts";
@@ -90,6 +93,11 @@ export interface LanguageTemplates {
   hint?: string | undefined;
   /** The mistakes' messages, plain text. */
   messages: string[];
+  /**
+   * The chemical formula of each value of the placeholders in \ce{{{…}}}, as MathML without <math>, by the value as
+   * the learner reads it; fill() puts it in for the token ⟦ce:…⟧.
+   */
+  chem?: Readonly<Record<string, string>>;
 }
 export type Templates = Readonly<Record<string, LanguageTemplates>>;
 

package/runtime/explainer/load.ts

@@ -1,9 +1,12 @@
-// Reads an explainer's content from src/ at build time and validates it: each file against its part of the schema
-// (explainer.v1.schema.json), then what a schema cannot say. The order lists are complete and unique, the depth is
+// Reads an explainer's content from src/ at build time and validates it: each file against its part of the schema of
+// its format (explainer.v1.schema.json without `format` in src/app.yaml, explainer.v2.schema.json with `format: 2`),
+// then what a schema cannot say. In format 2, every page names its competencies when the app has a strand (or is a
+// recap page, recap: <subject>/<competency>), and none when its strand is none; a recap page has no exercise, and
+// every other page at least one. The order lists are complete and unique, the depth is
 // app, chapter, page and two section levels, ids are unique per level, every text is complete in each declared
 // language and in no other, texts hold restricted Markdown without raw HTML or headings, formulas are in the command
 // list, bundled images and quotes name source and licence, links to pages of the app find their page and section,
-// every page has an exercise, a question of the question types passes the validation of a question in every declared language,
+// every page but a recap page has an exercise, a question of the question types passes the validation of a question in every declared language,
 // a generated exercise declares what it uses and passes its property test over fixed seeds (generated.ts), the check
 // of each exercise judges its examples as they are listed, a vue-component block names a component of src/components/
 // that passes its checks (components.ts), its props match the component's prop types, it has its nojs text (an exercise
@@ -17,6 +20,7 @@ import { readComponents } from "./components/read.ts";
 import {
   isExercise,
   type App,
+  type Block,
   type BlockOf,
   type Chapter,
   type ComponentUse,
@@ -27,12 +31,12 @@ import {
 } from "./content.ts";
 import { allBlocks } from "./routes.ts";
 import { ASSESSMENT, drawsTasks, exerciseOf, parseRef } from "./assessment.ts";
-import { SCHEMA_FILE, validate } from "./schema.ts";
+import { formatOf, SCHEMA_FILES, validate, type Format } from "./schema.ts";
 import { appName } from "../shared/appname.ts";
 import { isObject, Problems, readYaml, Texts, type Path, type YamlFile } from "../shared/content.ts";
 import { isLanguage, LANGUAGES, languageListProblems } from "../shared/languages.ts";
 
-export { SCHEMA_ID } from "./schema.ts";
+export { SCHEMA_ID, SCHEMA_ID_V2, type Format } from "./schema.ts";
 export const RULE_URL = "https://lernapps.net/tooling/rules/#explainer-content-valid";
 
 /** What src/ may hold besides the chapter folders. */
@@ -45,12 +49,12 @@ const IMAGE = /^[a-z0-9]+(-[a-z0-9]+)*\.(svg|png|jpg|webp)$/;
 /** The content could not be read: one problem per line in `problems`. */
 export class ContentError extends Error {
   readonly problems: readonly string[];
-  constructor(problems: readonly string[]) {
+  constructor(problems: readonly string[], format: Format = 1) {
     super(
       [
         `the explainer's content in src/ is not valid (${RULE_URL}):`,
         ...problems.map((problem) => `  - ${problem}`),
-        `Fix the content as its schema says: ${SCHEMA_FILE}`,
+        `Fix the content as its schema says: ${SCHEMA_FILES[format]}`,
       ].join("\n"),
     );
     this.problems = problems;
@@ -123,6 +127,14 @@ function checkAssessment(
         problems.at(yaml, path, `${ref} names no page of the app; write /<chapter>/<page>/#<exercise>`);
         return;
       }
+      if (page.recap !== undefined) {
+        problems.at(
+          yaml,
+          path,
+          `${ref} is on a recap page, which has no exercise and is left out of the self-assessment; choose an exercise of a page of the app's own competencies`,
+        );
+        return;
+      }
       const exercise = exerciseOf(components, page, parts.exercise);
       // a generated exercise or an exercise component may be listed again: each listing draws a task of its own
       if (twice && exercise !== undefined && !drawsTasks(exercise)) {
@@ -148,11 +160,21 @@ function checkAssessment(
   });
 }
 
+/** Each block of `blocks` and the blocks inside them, with its path in the page's file. */
+function* blockPaths(blocks: readonly Block[], path: Path): Generator<[Block, Path]> {
+  for (const [index, block] of blocks.entries()) {
+    yield [block, [...path, index]];
+    if (block.type === "section" || block.type === "example" || block.type === "note") {
+      yield* blockPaths(block.blocks, [...path, index, "blocks"]);
+    }
+  }
+}
+
 /** How many seeds the property test of each generated exercise draws at build time. */
 export const SEEDS = 200;
 
 /** The problems of the content in `root`/src, and the content when there are none. */
-export function check(root: string, seeds = SEEDS): { site?: Site; problems: string[] } {
+export function check(root: string, seeds = SEEDS): { site?: Site; problems: string[]; format: Format } {
   const problems = new Problems();
   const src = join(root, "src");
   if (!existsSync(join(src, "app.yaml"))) {
@@ -160,7 +182,7 @@ export function check(root: string, seeds = SEEDS): { site?: Site; problems: str
       "src/app.yaml",
       "is missing: the app's title, intro, languages and the order of its chapters belong there",
     );
-    return { problems: problems.lines };
+    return { problems: problems.lines, format: 1 };
   }
 
   // what src/ holds
@@ -213,13 +235,14 @@ export function check(root: string, seeds = SEEDS): { site?: Site; problems: str
 
   // the app
   const appYaml = readYaml(root, "src/app.yaml", problems);
-  if (appYaml === undefined || !validate(appYaml, "app", problems)) return { problems: problems.lines };
+  const format = formatOf(appYaml?.value);
+  if (appYaml === undefined || !validate(appYaml, "app", problems, format)) return { problems: problems.lines, format };
   const app = appYaml.value as App;
   const languageList = languageListProblems(app.languages, LANGUAGES);
   for (const problem of languageList) {
     problems.at(appYaml, ["languages", Math.max(app.languages.lastIndexOf(problem.lang), 0)], problem.message);
   }
-  if (languageList.length > 0) return { problems: problems.lines };
+  if (languageList.length > 0) return { problems: problems.lines, format };
   const texts = new Texts(app.languages, problems);
   texts.check(appYaml, ["title"], "plain");
   texts.check(appYaml, ["intro"], "markdown");
@@ -312,11 +335,30 @@ export function check(root: string, seeds = SEEDS): { site?: Site; problems: str
     for (const pageId of pagesOk ? chapter.pages : pageIds) {
       const file = `src/${chapterId}/${pageId}.yaml`;
       const yaml = readYaml(root, file, problems);
-      if (yaml === undefined || !validate(yaml, "page", problems)) {
+      if (yaml === undefined || !validate(yaml, "page", problems, format)) {
         complete = false;
         continue;
       }
       const page = yaml.value as Omit<Page, "id" | "chapter" | "file">;
+      // format 2: the competencies a page practises, by the app's strand
+      if (app.strand === "none" && page.competencies !== undefined) {
+        problems.at(
+          yaml,
+          ["competencies"],
+          "competencies is not allowed: src/app.yaml has strand: none, so the app is on no strand; remove it, or name the app's strand in src/app.yaml",
+        );
+      } else if (
+        app.strand !== undefined &&
+        app.strand !== "none" &&
+        page.competencies === undefined &&
+        page.recap === undefined
+      ) {
+        problems.at(
+          yaml,
+          [],
+          `competencies is missing; src/app.yaml names the strand ${app.strand}, so each page names the competencies of its subject that it practises, e.g. competencies: [laplace]; a page that only repeats a competency the app does not practise says recap: <subject>/<competency> instead`,
+        );
+      }
       texts.check(yaml, ["title"], "plain");
       texts.check(yaml, ["description"], "plain");
       const pageAnchors = new Set<string>();
@@ -341,7 +383,18 @@ export function check(root: string, seeds = SEEDS): { site?: Site; problems: str
         ["blocks"],
         0,
       );
-      if (![...allBlocks(page.blocks)].some(isExercise)) {
+      if (page.recap !== undefined) {
+        // a recap page repeats a competency the app does not practise: no exercise, not even a component's
+        for (const [block, path] of blockPaths(page.blocks, ["blocks"])) {
+          const component = uses.find((use) => use.block === block && use.component.exercise);
+          if (!isExercise(block) && component === undefined) continue;
+          problems.at(
+            yaml,
+            path,
+            `${component === undefined ? `the exercise ${block.type}` : `the exercise component ${component.component.name}`} is not allowed on a recap page: it repeats ${page.recap} with descriptive blocks only, and the apps of that competency's strand practise it; remove the exercise, or make it a page of the app's own competencies`,
+          );
+        }
+      } else if (![...allBlocks(page.blocks)].some(isExercise)) {
         problems.at(
           yaml,
           ["blocks"],
@@ -429,7 +482,7 @@ export function check(root: string, seeds = SEEDS): { site?: Site; problems: str
     }
   }
 
-  if (problems.lines.length > 0) return { problems: problems.lines };
+  if (problems.lines.length > 0) return { problems: problems.lines, format };
   const data: Record<string, DataRecord[]> = {};
   for (const [id, yaml] of dataFiles) data[id] = yaml.value as DataRecord[];
   return {
@@ -442,6 +495,7 @@ export function check(root: string, seeds = SEEDS): { site?: Site; problems: str
       storage: appName(root, "explainer"),
     },
     problems: [],
+    format,
   };
 }
 
@@ -449,8 +503,8 @@ export function check(root: string, seeds = SEEDS): { site?: Site; problems: str
  * The content in `root`/src, its generated exercises tested over `seeds` seeds (0: not at all, for a reader of content
  * the build has checked); throws a ContentError with every problem when it is not valid. */
 export function loadSite(root: string, seeds = SEEDS): Site {
-  const { site, problems } = check(root, seeds);
-  if (site === undefined) throw new ContentError(problems);
+  const { site, problems, format } = check(root, seeds);
+  if (site === undefined) throw new ContentError(problems, format);
   return site;
 }
 

package/runtime/explainer/messages/de.json

@@ -196,5 +196,9 @@
   "openTaskLocked": "Die Lösung öffnet sich nach deiner Antwort.",
   "resultPartly": "teilweise richtig ({n} von {total} Punkten, es fehlen {missed})",
   "resultPhoto": "Antwort als Foto",
-  "resultAnswer": "Antwort „{input}“"
+  "resultAnswer": "Antwort „{input}“",
+  "recap": "Wiederholung",
+  "recapText": "Diese Seite wiederholt etwas, das du schon können solltest. Üben kannst du es in anderen Apps: {link}",
+  "recapLink": "Baustein auf der Lernlandkarte von lernapps.net",
+  "recapNote": "Wiederholung"
 }

package/runtime/explainer/messages/en.json

@@ -196,5 +196,9 @@
   "openTaskLocked": "The solution opens after your answer.",
   "resultPartly": "partly right ({n} of {total} points, missing {missed})",
   "resultPhoto": "answer as a photo",
-  "resultAnswer": "answer “{input}”"
+  "resultAnswer": "answer “{input}”",
+  "recap": "Recap",
+  "recapText": "This page goes over something you should already know. You can practise it in other apps: {link}",
+  "recapLink": "building block on the learning map of lernapps.net",
+  "recapNote": "recap"
 }

package/runtime/explainer/outline.ts

@@ -196,7 +196,7 @@ function walk(
       }
       case "generated": {
         const data = dataOf(block, site.data);
-        const templates = templatesOf(block, [lang]);
+        const templates = templatesOf(block, [lang], data);
         const worked = workedTasks(block, data, templates, lang);
         for (const item of worked) {
           for (const html of [item.task, item.hint ?? "", ...item.steps])

package/runtime/explainer/page-list.ts

@@ -0,0 +1,38 @@
+// The list of an explainer's pages for the catalog of lernapps.net (lernapps-pages.json): only an app of format 2
+// (`format: 2` in src/app.yaml) has it. The build writes it at the root of the bundle, beside index.html; the catalog
+// reads it instead of hand-written topics, to place the app and its pages on the learning map. It holds the version of
+// the list itself (format 1), the app's strand (<subject>/<strand>, or none), and the content pages in the order of the
+// app, each with its address relative to the app's root as the app links it, its title as a text (a string, or by
+// language) and, unless the strand is none, the competencies it practises; a recap page names instead the competency
+// it repeats (recap: <subject>/<competency>), with any strand.
+import { contentPages } from "./routes.ts";
+import type { Site, Text } from "./content.ts";
+
+/** The file's name, at the root of the bundle. */
+export const PAGE_LIST = "lernapps-pages.json";
+
+export interface PageList {
+  /** The version of this list's own format. */
+  format: 1;
+  strand: string;
+  pages: { path: string; title: Text; competencies?: readonly string[]; recap?: string }[];
+}
+
+/** The list of the pages of `site`; undefined for an app of format 1, which has none. */
+export function pageList(site: Site): PageList | undefined {
+  const { format, strand } = site.app;
+  if (format !== 2 || strand === undefined) return undefined;
+  return {
+    format: 1,
+    strand,
+    pages: contentPages(site).map((page) => ({
+      path: `${page.chapter}/${page.id}/`,
+      title: page.title,
+      ...(page.recap !== undefined
+        ? { recap: page.recap }
+        : strand === "none" || page.competencies === undefined
+          ? {}
+          : { competencies: page.competencies }),
+    })),
+  };
+}