@lernapps/app-templates 0.2.1 → 0.3.1

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 }),
+    })),
+  };
+}

package/runtime/explainer/plugin.ts

@@ -12,7 +12,8 @@
 // depth. The bundled images go to images/, the tutor page of each content page to <chapter>/<page>/tutor/ with its
 // Markdown beside it (index.md; tutorpage.ts), and of each self-assessment to <assessment>/tutor/ (assessment-page.ts),
 // every link of them checked, and 404.html, which leads every address the
-// app does not have to its start page (notFoundPage of ../shared/pages.ts). `vp dev` serves the same pages and tutor pages, rendered on each request.
+// app does not have to its start page (notFoundPage of ../shared/pages.ts). An app of format 2 also gets
+// lernapps-pages.json at the root, the list of its pages with their competencies for the catalog (page-list.ts). `vp dev` serves the same pages and tutor pages, rendered on each request.
 //
 // Components (src/components/<Name>.vue, components.ts): only when the app has them, the plugin compiles them with
 // @vitejs/plugin-vue and resolves vue to the copy this runtime depends on, so that the components and the islands
@@ -53,6 +54,7 @@ import {
   tutorPageDocument,
 } from "./tutorpage.ts";
 import { imageType } from "../shared/blocks/image.ts";
+import { PAGE_LIST, pageList } from "./page-list.ts";
 
 const MARKER = "<!-- explainer -->";
 const ISLANDS = "\0lernapps-explainer-islands";
@@ -263,7 +265,9 @@ export function explainer(): Plugin[] {
       }
       if (command !== "build" || content.components.length === 0) return;
       const rendered = await withServer(root, (loader) => renderComponents(content, loader, true));
-      if (rendered.problems.length > 0) this.error(new ContentError(rendered.problems).message);
+      if (rendered.problems.length > 0) {
+        this.error(new ContentError(rendered.problems, content.app.format ?? 1).message);
+      }
       islands = rendered.islands;
       descriptions = rendered.descriptions;
       islandsChunk = this.emitFile({ type: "chunk", id: ISLANDS, name: "islands" });
@@ -289,6 +293,11 @@ export function explainer(): Plugin[] {
         else this.emitFile({ type: "asset", fileName: `${page.route.path}index.html`, source: html });
       }
       this.emitFile({ type: "asset", fileName: "404.html", source: notFoundPage() });
+      // format 2: the list of the pages for the catalog
+      const list = pageList(content);
+      if (list !== undefined) {
+        this.emitFile({ type: "asset", fileName: PAGE_LIST, source: `${JSON.stringify(list, null, 2)}\n` });
+      }
       for (const [image, file] of content.images) {
         this.emitFile({ type: "asset", fileName: image, source: readFileSync(file) });
       }
@@ -404,7 +413,7 @@ export function explainer(): Plugin[] {
           );
         }
       }
-      if (problems.length > 0) this.error(new ContentError(problems).message);
+      if (problems.length > 0) this.error(new ContentError(problems, content.app.format ?? 1).message);
     },
     configureServer(server) {
       devServer = server;
@@ -442,7 +451,7 @@ export function explainer(): Plugin[] {
         if (dev === undefined) return next();
         renderComponents(content, (id) => dev.ssrLoadModule(id), false)
           .then(({ islands: rendered, descriptions: described, problems }) => {
-            if (problems.length > 0) throw new ContentError(problems);
+            if (problems.length > 0) throw new ContentError(problems, content.app.format ?? 1);
             if (forScope) {
               const markdown = path.endsWith(TUTOR_MARKDOWN);
               const lang =

package/runtime/explainer/render.ts

@@ -2,7 +2,8 @@
 // as inline SVG or an image, tables, timelines, definitions, quotes, highlighted code, the exercises (exercises.ts:
 // each with its solution in a <details>, a generated one with three worked tasks), and the navigation (contents,
 // breadcrumbs, previous and next, the contents of a page with three or more sections, the glossary, the language
-// switch). Without JavaScript the page is complete; the client module only adds. A vue-component block is its island:
+// switch; a recap page marked in the contents, and at its top its notice with the link to the learning map). Without
+// JavaScript the page is complete; the client module only adds. A vue-component block is its island:
 // the component's markup as the build rendered it (`hidden` until it hydrates), its nojs text, its props in the page's
 // language, and for an exercise its anchor, its task number with "Neue Aufgabe", the task of number 1 as its describe
 // states it with the solution folded, and the place of its feedback. Links to other sites are plain links with rel="noopener":
@@ -13,6 +14,7 @@ import { questionMessagesIn } from "../shared/questions/render.ts";
 import { propsIn } from "./components/props.ts";
 import {
   inLanguage,
+  mapUrl,
   termId as termIdOf,
   timelineEvents,
   type Block,
@@ -322,7 +324,10 @@ function pageList(context: Context, pages: readonly NonNullable<Route["page"]>[]
         page.description === undefined
           ? ""
           : ` <span class="explainer-description">${context.text(page.description)}</span>`;
-      return `<li><a href="${context.to(`${page.chapter}/${page.id}/`)}">${context.text(page.title)}</a>${description}</li>`;
+      // a recap page repeats a competency the app does not practise: marked, so that no one takes it for the app's own
+      const recap =
+        page.recap === undefined ? "" : ` <span class="explainer-recap-note">(${plain(context.t("recapNote"))})</span>`;
+      return `<li><a href="${context.to(`${page.chapter}/${page.id}/`)}">${context.text(page.title)}</a>${recap}${description}</li>`;
     })
     .join("")}</ol>`;
 }
@@ -407,6 +412,7 @@ function main(context: Context): string {
         title,
         tutorSection(context),
         `</div>`,
+        page.recap === undefined ? "" : recapNotice(context, page.recap),
         pageContents(context, page.blocks),
         renderBlocks(context, page.blocks, 1),
       ].join("\n");
@@ -414,6 +420,24 @@ function main(context: Context): string {
   }
 }
 
+/**
+ * At the top of a recap page: that it is a recap, and the link to the competency's page on the learning map, where the
+ * apps are that practise it. The runtime writes it, so that it cannot be missing; a plain link, nothing loaded before
+ * a click.
+ */
+function recapNotice(context: Context, recap: string): string {
+  const link = external(mapUrl(recap), context.t("recapLink"));
+  // the message keeps its placeholder {link} unfilled: the link goes in its place as markup
+  const [before = "", after = ""] = context.t("recapText").split("{link}");
+  const label = plain(context.t("recap"));
+  return [
+    `<aside class="explainer-recap" aria-label="${label}">`,
+    `<p class="explainer-recap-label">${label}</p>`,
+    `<p>${plain(before)}${link}${plain(after)}</p>`,
+    `</aside>`,
+  ].join("\n");
+}
+
 /** What a part of a self-assessment needs of the page it is on (assessment-page.ts). */
 const assessmentContext = (context: Context): AssessmentContext => ({
   site: context.site,

package/runtime/explainer/schema.ts

@@ -1,25 +1,35 @@
-// The explainer's content schema (explainer.v1.schema.json) at build time: the validators of its files (the app, a
-// chapter, a page, a data file), and the explainer's own words for the errors of the schema (what a quote or a bundled
+// The explainer's content schemas at build time: format 1 (explainer.v1.schema.json) and format 2
+// (explainer.v2.schema.json, which adds the strand of the app, the competencies of each page and recap pages, and refers to format 1
+// for everything else); the validators of their files (the app, a chapter, a page, a data file) by format, and the explainer's own words for the errors of the schema (what a quote or a bundled
 // image lacks, which fields a block type has, which an exercise of a question type); the general messages are
 // shared/content.ts's.
 import { Ajv2020, type ValidateFunction } from "ajv/dist/2020.js";
 import schema from "./explainer.v1.schema.json" with { type: "json" };
+import schemaV2 from "./explainer.v2.schema.json" with { type: "json" };
 import questionSchema from "../shared/questions/question.v1.schema.json" with { type: "json" };
 import { knownProperties, schemasById } from "../shared/schema.ts";
 import { addressProblem, QUESTION_BRANCH, questionSchemas } from "../shared/questions/validate.ts";
 import { isObject, schemaProblems, type DescribeError, type Problems, type YamlFile } from "../shared/content.ts";
 
 export const SCHEMA_ID = schema.$id;
-/** Where an app finds the schema of its content, for the message that names it. */
-export const SCHEMA_FILE = "node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json";
+export const SCHEMA_ID_V2 = schemaV2.$id;
+/** The formats of the content: 1 without `format` in src/app.yaml, 2 with `format: 2`. */
+export type Format = 1 | 2;
+/** Where an app finds the schema of its content, by format, for the message that names it. */
+export const SCHEMA_FILES: Readonly<Record<Format, string>> = {
+  1: "node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json",
+  2: "node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json",
+};
+export const SCHEMA_FILE = SCHEMA_FILES[1];
 
 // union types ("type": ["string", "object"]) keep the messages of the comparator and the lists plain
 const ajv = new Ajv2020({ allErrors: true, strict: true, allowUnionTypes: true });
 for (const each of questionSchemas) ajv.addSchema(each);
 ajv.addSchema(schema);
-const validator = (name: string): ValidateFunction => {
-  const validate = ajv.getSchema(`${SCHEMA_ID}#/$defs/${name}`);
-  if (validate === undefined) throw new Error(`the schema has no $defs/${name}`);
+ajv.addSchema(schemaV2);
+const validator = (name: string, id = SCHEMA_ID): ValidateFunction => {
+  const validate = ajv.getSchema(`${id}#/$defs/${name}`);
+  if (validate === undefined) throw new Error(`the schema ${id} has no $defs/${name}`);
   return validate;
 };
 export const validators = {
@@ -29,6 +39,20 @@ export const validators = {
   data: validator("data"),
   event: validator("event"),
 };
+/** The validators of format 2: its own app and page; chapters, data files and events are those of format 1. */
+const validatorsV2: typeof validators = {
+  ...validators,
+  app: validator("app", SCHEMA_ID_V2),
+  page: validator("page", SCHEMA_ID_V2),
+};
+
+/** The format of the app `app` (src/app.yaml as read): 2 when it names any format, which its schema then checks. */
+export const formatOf = (app: unknown): Format => (isObject(app) && app["format"] !== undefined ? 2 : 1);
+
+/** The fields of format 2, which format 1 does not know. */
+const FORMAT_2_FIELDS = new Set(["format", "strand", "competencies", "recap"]);
+/** The fields of format 2 on a page. */
+const PAGE_FIELDS = new Set(["competencies", "recap"]);
 
 const schemas = schemasById(...questionSchemas, schema);
 
@@ -61,6 +85,9 @@ const questionFields = (type: string): Set<string> => {
 /** What `required` names as missing, with why it is needed. */
 function missing(property: string, object: unknown): string {
   const type = isObject(object) ? object["type"] : undefined;
+  if (property === "strand") {
+    return "strand is missing; name the strand of the learning map the app stays in, <subject>/<strand> (e.g. mathematik/stochastik), or none when the app is on no strand";
+  }
   if (property === "origin") return "origin is missing; a quote names who said or wrote it, where and when";
   if ((property === "licence" || property === "source") && type === "quote") {
     return `${property} is missing; a quote names its source and its licence`;
@@ -80,7 +107,58 @@ const describe: DescribeError = (error, path, value) => {
       const { lang, message } = addressProblem(value);
       return { message, ...(lang === undefined ? {} : { lang }) };
     }
+    case "not":
+      // a page with both: it practises competencies of the app's strand, or it repeats one the app does not practise
+      if (path.length !== 0 || !isObject(value) || !("recap" in value) || !("competencies" in value)) return undefined;
+      return {
+        path: ["recap"],
+        message:
+          "a page has competencies or recap, never both: a page practises competencies of the app's strand, a recap page only repeats a competency the app does not practise; remove one of them",
+      };
+    case "const":
+      // the format of the content: 2, or none at all for format 1
+      if (path.length !== 1 || path[0] !== "format") return undefined;
+      return { message: `${String(value)} is not a format; write format: 2, or leave format out for format 1` };
+    case "uniqueItems":
+      if (path.at(-1) !== "competencies") return undefined;
+      return { message: "names a competency twice; name each competency once" };
+    case "additionalProperties": {
+      // a field of format 2 in an app of format 1
+      const property = String(error.params["additionalProperty"]);
+      if (path.length !== 0 || !FORMAT_2_FIELDS.has(property) || !isObject(value)) return undefined;
+      if (PAGE_FIELDS.has(property) && "blocks" in value) {
+        return {
+          path: [property],
+          message: `${property} is a field of format 2; add format: 2 and the app's strand to src/app.yaml, or remove it`,
+        };
+      }
+      if (!PAGE_FIELDS.has(property) && "chapters" in value) {
+        return {
+          path: [property],
+          message: `${property} is a field of format 2; add format: 2 to src/app.yaml, with the app's strand`,
+        };
+      }
+      return undefined;
+    }
     case "pattern":
+      // the strand of the app: <subject>/<strand> or none
+      if (path.length === 1 && path[0] === "strand") {
+        return {
+          message: `${String(value)} is no strand; write <subject>/<strand> with the ids of the learning map, e.g. mathematik/stochastik, or none`,
+        };
+      }
+      // the competency a recap page repeats: <subject>/<competency>
+      if (path.length === 1 && path[0] === "recap") {
+        return {
+          message: `${String(value)} is no competency of the learning map; write <subject>/<competency> with the ids of the learning map, e.g. physik/gewichtskraft-berechnen`,
+        };
+      }
+      // a competency of a page: an id of the learning map
+      if (path.at(-2) === "competencies") {
+        return {
+          message: `${String(value)} is no competency id; use the competency's id in the learning map: lower-case letters, digits and hyphens, e.g. laplace`,
+        };
+      }
       // an exercise of a self-assessment: by its page and id
       if (path.at(-2) === "exercises" && path[0] === "selfAssessment") {
         return { message: `${String(value)} is no exercise's address; write /<chapter>/<page>/#<exercise>` };
@@ -129,8 +207,13 @@ const describe: DescribeError = (error, path, value) => {
   return undefined;
 };
 
-export function validate(yaml: YamlFile, kind: keyof typeof validators, problems: Problems): boolean {
-  const check = validators[kind];
+export function validate(
+  yaml: YamlFile,
+  kind: keyof typeof validators,
+  problems: Problems,
+  format: Format = 1,
+): boolean {
+  const check = (format === 2 ? validatorsV2 : validators)[kind];
   if (check(yaml.value)) return true;
   const before = problems.lines.length;
   schemaProblems(yaml, check.errors ?? [], problems, describe);

package/runtime/explainer/tutorpage.ts

@@ -27,6 +27,7 @@ import { escape } from "../shared/html.ts";
 import { answerText } from "../shared/questions/render.ts";
 import {
   inLanguage,
+  mapUrl,
   type Block,
   type ComponentExercise,
   type Descriptions,
@@ -72,6 +73,8 @@ interface Words {
   needsIntro: string;
   needs: Readonly<Record<Need, string>>;
   contextTitle: string;
+  /** On a recap page: that it has no exercise, and where the competency is practised ({url}). */
+  recap: string;
   exercise: string;
   steps: string;
   link: string;
@@ -139,6 +142,8 @@ const WORDS: Readonly<Record<string, Words>> = {
         "Zeig Zahlen der Seite als Menge, z. B. „37 sind 3 Zehner und 7 Einer“, aber nie das Ergebnis einer Aufgabe. Ein Schritt pro Nachricht, nie Zeitdruck.",
     },
     contextTitle: "Kontext: die Seite „{page}“",
+    recap:
+      "Diese Seite ist eine Wiederholung: Sie wiederholt etwas, das das Kind schon können sollte, und hat keine Übung. Erklär mit dem Inhalt der Seite und frag nach, ob das Kind ihn verstanden hat. Üben kann es das in anderen Apps; welche das sind, steht hier: {url}",
     exercise: "Übung",
     steps: "Lösungsweg",
     link: "Link",
@@ -205,6 +210,8 @@ const WORDS: Readonly<Record<string, Words>> = {
         "Show numbers of the page as amounts, e.g. “37 is 3 tens and 7 ones”, but never the result of a task. One step per message, never time pressure.",
     },
     contextTitle: "Context: the page “{page}”",
+    recap:
+      "This page is a recap: it goes over something the child should already know, and has no exercise. Explain with the content of the page and ask whether the child has understood it. It can practise it in other apps; which ones, it says here: {url}",
     exercise: "Exercise",
     steps: "Steps of the solution",
     link: "Link",
@@ -341,7 +348,7 @@ export function generatedLines(spec: Generated, site: Site, lang: string, format
   lines.push(`- ${words.linkNumber}: \`${page}?${spec.id}=n&via=tutor#${spec.id}\``);
   const { paths, answer } = placeholdersOf(spec, lang);
   const data = dataOf(spec, site.data);
-  const templates = templatesOf(spec, [lang]);
+  const templates = templatesOf(spec, [lang], data);
   let choices = false;
   const rows = taskSeeds(spec, data).map((seed, index) => {
     const task = generate(spec, seed, data);
@@ -569,6 +576,7 @@ function pageMarkdown(
     `## ${fill(words.contextTitle)}`,
     "",
   );
+  if (page.recap !== undefined) lines.push(words.recap.replace("{url}", mapUrl(page.recap)), "");
   if (page.description !== undefined) lines.push(own(page.description), "");
   lines.push(
     ...contentLines(

package/runtime/shared/blocks/blocks.css

@@ -30,6 +30,24 @@
   height: auto;
 }
 
+/* The drawings take the page's colours, so they follow the dark mode too (the attributes in figures.ts are the fallback
+   for an SVG outside a page) */
+.block-drawing .fig-on {
+  fill: var(--page-accent);
+}
+
+.block-drawing .fig-off {
+  fill: var(--page-background);
+}
+
+.block-drawing .fig-line {
+  stroke: var(--page-muted);
+}
+
+.block-drawing .fig-text {
+  fill: var(--page-text);
+}
+
 .block-hundred-grid {
   width: 16rem;
 }

package/runtime/shared/blocks/blocks.v1.schema.json

@@ -328,7 +328,7 @@
       "type": "object"
     },
     "latex": {
-      "description": "One formula in the LaTeX subset of the formula command list: \\frac, \\cdot, \\times, \\div, \\%, \\text, ^, _, \\sqrt, \\approx, \\pm, \\le, \\ge, \\neq, \\, (thin space), parentheses and braces; \\ce{…} for chemical equations and \\pu{…} for units (mhchem). Written without the $ signs. A map by language only when it has \\text{…} that differs by language.",
+      "description": "One formula in the LaTeX subset of the formula command list: \\frac, \\cdot, \\times, \\div, \\%, \\text, ^, _, \\sqrt, \\approx, \\pm, \\le, \\ge, \\neq, \\, (thin space), \\  (space), \\quad, \\qquad, \\Rightarrow, \\Leftrightarrow, \\left( … \\right), parentheses and braces; \\sin, \\cos, \\tan, \\arcsin, \\arccos, \\arctan (or \\sin^{-1}), \\circ for degrees (30^\\circ); the Greek letters \\alpha to \\omega (also \\varepsilon, \\vartheta, \\varphi) and the capitals \\Gamma, \\Delta, \\Theta, \\Lambda, \\Xi, \\Pi, \\Sigma, \\Phi, \\Psi, \\Omega; \\ce{…} for chemical equations and \\pu{…} for units (mhchem). The build names any other command and lists these. Written without the $ signs. A map by language only when it has \\text{…} that differs by language.",
       "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
     },
     "table": {