@lernapps/app-templates 0.0.1 → 0.1.0

package/runtime/shared/blocks/image.ts

@@ -0,0 +1,25 @@
+// A bundled image at build time, in Node: whether it has no size of its own. Not part of index.ts, which the browser
+// may import.
+import { readFileSync } from "node:fs";
+
+const TYPES: Readonly<Record<string, string>> = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  webp: "image/webp",
+};
+
+/** The media type of a bundled image, by its file name. */
+export const imageType = (name: string): string =>
+  TYPES[name.slice(name.lastIndexOf(".") + 1)] ?? "application/octet-stream";
+
+/**
+ * Whether the SVG file `file` has no size of its own: its root has neither a width nor a height (only a viewBox, or
+ * percentages). In a box as wide as its content, as the image of a labelled figure is, the browser draws such an image
+ * with zero width. Another kind of image has a size.
+ */
+export function isSizeless(file: string): boolean {
+  if (!file.endsWith(".svg")) return false;
+  const root = /<svg\b[^>]*>/i.exec(readFileSync(file, "utf8"))?.[0] ?? "";
+  return !/\s(?:width|height)\s*=\s*["']?\s*\d*\.?\d+\s*(?:px|pt|pc|mm|cm|in|em|ex|rem)?\s*["'\s/>]/i.test(root);
+}

package/runtime/shared/blocks/index.ts

@@ -0,0 +1,13 @@
+// The blocks that show content (@lernapps/app-templates/blocks): see block.ts, validate.ts and render.ts.
+export * from "./block.ts";
+export { highlight, type CodeLanguage } from "./code.ts";
+export { bar, hundredGrid } from "./figures.ts";
+export { renderCredit, renderMaterial, type MaterialContext } from "./render.ts";
+export {
+  checkMaterial,
+  MATERIAL_DEFINITIONS,
+  type AppChecks,
+  type BlockChecks,
+  type BlockLink,
+  type BlockProblem,
+} from "./validate.ts";

package/runtime/shared/blocks/messages/de.json

@@ -0,0 +1,4 @@
+{
+  "credit": "Quelle: {source}. Lizenz: {licence}.",
+  "code": "Code in {language}"
+}

package/runtime/shared/blocks/messages/en.json

@@ -0,0 +1,4 @@
+{
+  "credit": "Source: {source}. Licence: {licence}.",
+  "code": "Code in {language}"
+}

package/runtime/shared/blocks/render.ts

@@ -0,0 +1,134 @@
+// Renders blocks that show content at build time into HTML: prose, a formula (MathML), a figure (an inline SVG drawn
+// from data, or a bundled image), a labelled figure (a bundled image with markers and, unless it is left out, a legend), a table, a
+// quotation and highlighted code, each with its caption and, for an image or a quotation, its credit. The page that
+// shows them says where a bundled image is from the page and how a link to one of its pages resolves; the look is
+// blocks.css.
+import { escape } from "../html.ts";
+import { inLanguage, localeOf, textsIn, type Language, type Text } from "../languages.ts";
+import { renderFormula } from "../text/formula.ts";
+import { renderInline, renderMarkdown } from "../text/markdown.ts";
+import { isUrl } from "../text/check.ts";
+import { markerOf, type Credit, type MaterialBlock } from "./block.ts";
+import { highlight } from "./code.ts";
+import { bar, hundredGrid } from "./figures.ts";
+import de from "./messages/de.json" with { type: "json" };
+import en from "./messages/en.json" with { type: "json" };
+
+export const BLOCK_MESSAGES: Readonly<Record<Language, typeof de>> = { de, en };
+
+/** What rendering blocks needs from the page that shows them. */
+export interface MaterialContext {
+  /** The language of the page. */
+  lang: string;
+  /** The address of the bundled image `image` (images/<name>) from the page. */
+  href: (image: string) => string;
+  /** Where a link to a page of the app leads; an https address is left as it is. */
+  resolve?: (href: string) => string;
+  /**
+   * Whether the bundled image has no size of its own: an SVG whose root has neither a width nor a height (only a
+   * viewBox, or percentages). In a box as wide as its content, as the image of a labelled figure is, the browser
+   * draws such an image with zero width.
+   */
+  sizeless?: (image: string) => boolean;
+}
+
+const external = (url: string) => `<a href="${escape(url)}" rel="noopener">${escape(url)}</a>`;
+
+/** The credit of an image or a quotation: its source, as a link when it is a URL, and its licence. */
+export function renderCredit(item: Credit<Text>, lang: string): string {
+  if (item.source === undefined || item.licence === undefined) return "";
+  const given = inLanguage(item.source, lang);
+  const source = isUrl(given) ? external(given) : escape(given);
+  const text = textsIn(BLOCK_MESSAGES, lang)
+    .credit.replace("{licence}", () => escape(item.licence ?? ""))
+    .replace("{source}", () => source);
+  return ` <span class="block-credit">${text}</span>`;
+}
+
+function renderBlock(block: MaterialBlock<Text>, context: MaterialContext): string {
+  const { lang } = context;
+  const resolve = context.resolve ?? ((href: string) => href);
+  const plain = (text: Text) => escape(inLanguage(text, lang));
+  const markdown = (text: Text) => renderMarkdown(inLanguage(text, lang), resolve);
+  const inline = (text: Text) => renderInline(inLanguage(text, lang), resolve);
+  switch (block.type) {
+    case "text":
+      return `<div class="block-text">${markdown(block.text)}</div>`;
+    case "formula":
+      return `<div class="block-formula">${renderFormula(inLanguage(block.formula, lang), true)}</div>`;
+    case "figure": {
+      const alt = inLanguage(block.alt, lang);
+      let picture = "";
+      if (block.draw?.kind === "hundred-grid") picture = hundredGrid(block.draw.filled, alt);
+      else if (block.draw?.kind === "bar") picture = bar(block.draw.part, block.draw.whole, alt, localeOf(lang));
+      else if (block.image !== undefined)
+        picture = `<img src="${escape(context.href(block.image))}" alt="${escape(alt)}" loading="lazy" decoding="async">`;
+      return `<figure class="block-figure">${picture}<figcaption>${markdown(block.caption)}${renderCredit(block, lang)}</figcaption></figure>`;
+    }
+    case "labelled-figure": {
+      const markers = block.labels
+        .map(
+          (label, index) =>
+            `<span class="block-marker" style="left: ${label.x}%; top: ${label.y}%" aria-hidden="true">${escape(markerOf(label, index))}</span>`,
+        )
+        .join("");
+      // a legend names the markers the image shows: numbered by the list as long as no label names its own marker
+      const named = block.labels.some((label) => label.marker !== undefined);
+      const item = (label: (typeof block.labels)[number], index: number) =>
+        named
+          ? `<li><b>${escape(markerOf(label, index))}</b> ${plain(label.text)}</li>`
+          : `<li>${plain(label.text)}</li>`;
+      const legend =
+        block.legend === false
+          ? ""
+          : `<ol class="block-legend${named ? " block-legend-named" : ""}">${block.labels.map(item).join("")}</ol>`;
+      const caption = block.caption === undefined ? "" : markdown(block.caption);
+      const fill = context.sizeless?.(block.image) === true ? " block-labelled-fill" : "";
+      return [
+        `<figure class="block-figure block-labelled">`,
+        `<div class="block-labelled-image${fill}"><img src="${escape(context.href(block.image))}" alt="${plain(block.alt)}" loading="lazy" decoding="async">${markers}</div>`,
+        legend,
+        `<figcaption>${caption}${renderCredit(block, lang)}</figcaption>`,
+        `</figure>`,
+      ].join("");
+    }
+    case "table": {
+      const caption = plain(block.caption);
+      const head =
+        block.header === undefined
+          ? ""
+          : `<thead><tr>${block.header.map((cell) => `<th scope="col">${inline(cell)}</th>`).join("")}</tr></thead>`;
+      const rows = block.rows
+        .map(
+          (row) =>
+            `<tr>${row
+              .map((cell, index) =>
+                index === 0 && block.rowHeaders === true
+                  ? `<th scope="row">${inline(cell)}</th>`
+                  : `<td>${inline(cell)}</td>`,
+              )
+              .join("")}</tr>`,
+        )
+        .join("");
+      return `<div class="block-table" role="region" aria-label="${caption}" tabindex="0"><table><caption>${caption}</caption>${head}<tbody>${rows}</tbody></table></div>`;
+    }
+    case "quote": {
+      const { author, work, year } = block.origin;
+      const origin = [
+        plain(author),
+        ...(work === undefined ? [] : [`<cite>${plain(work)}</cite>`]),
+        ...(year === undefined ? [] : [typeof year === "number" ? String(year) : plain(year)]),
+      ].join(", ");
+      return `<figure class="block-quote"><blockquote>${markdown(block.text)}</blockquote><figcaption>— ${origin}.${renderCredit(block, lang)}</figcaption></figure>`;
+    }
+    case "code": {
+      const label = textsIn(BLOCK_MESSAGES, lang).code.replace("{language}", () => block.language);
+      const caption = block.caption === undefined ? "" : `<figcaption>${plain(block.caption)}</figcaption>`;
+      return `<figure class="block-code"><pre role="region" aria-label="${escape(label)}" tabindex="0"><code class="hljs language-${block.language}">${highlight(block.code, block.language)}</code></pre>${caption}</figure>`;
+    }
+  }
+}
+
+/** The blocks as HTML, one after the other. */
+export const renderMaterial = (blocks: readonly MaterialBlock<Text>[], context: MaterialContext): string =>
+  blocks.map((block) => renderBlock(block, context)).join("");

package/runtime/shared/blocks/validate.ts

@@ -0,0 +1,165 @@
+// What the schema cannot say about blocks that show content, at build time: a figure is drawn or an image, not both
+// and not neither; a bundled image exists; every text is complete in the declared languages and holds what its kind
+// allows (plain text without raw HTML, restricted Markdown, a formula, a name, the source of a credit). The place of a
+// problem is a path below the blocks: [2, "caption", "en"] for the English caption of the third block.
+import { inLanguage, type Text } from "../languages.ts";
+import { checkText, type TextFinding, type TextKind } from "../text/check.ts";
+import { markerOf, type MaterialBlock } from "./block.ts";
+
+/** The definition of each type of block in the schema of the blocks (blocks.v1.schema.json). */
+export const MATERIAL_DEFINITIONS: Readonly<Record<MaterialBlock["type"], string>> = {
+  text: "textBlock",
+  formula: "formula",
+  figure: "figure",
+  "labelled-figure": "labelledFigure",
+  table: "table",
+  quote: "quote",
+  code: "code",
+};
+
+/** Whether `text` names `marker`: as a word of its own, so that the marker A is not found in "Grundriss". */
+const names = (text: string, marker: string): boolean =>
+  new RegExp(`(?<![\\p{L}\\p{N}])${marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\p{L}\\p{N}])`, "u").test(text);
+
+/** A problem in blocks: where in them (a path), in which language, in Markdown on which line below the first, and what. */
+export interface BlockProblem {
+  path: (string | number)[];
+  lang?: string;
+  line?: number;
+  message: string;
+}
+
+/** A link to a page of the app in a text of a block. */
+export interface BlockLink {
+  path: (string | number)[];
+  lang: string;
+  href: string;
+}
+
+/** What the checks need to know about the app. */
+export interface BlockChecks {
+  /** The languages of the app, German first; ["de"] while German is the only one. */
+  languages: readonly string[];
+  /** Where the app declares its languages, for the message about a language it does not declare. */
+  declaredIn?: string;
+  /** Whether the bundled image `image` (images/<name>) is a file in src/images/ of the app. */
+  imageExists(image: string): boolean;
+  /**
+   * What to do with a link to a page of the app in a caption or a text: the page that holds the blocks resolves it
+   * later. Without it such a link is a problem, as an app without pages (a quiz) has none.
+   */
+  onLink?(link: BlockLink): void;
+}
+
+/** What the checks need to know about the app beyond its languages. */
+export type AppChecks = Pick<BlockChecks, "imageExists" | "onLink">;
+
+/** The problems of `blocks`. */
+export function checkMaterial(blocks: readonly MaterialBlock<Text>[], checks: BlockChecks): BlockProblem[] {
+  const problems: BlockProblem[] = [];
+  const text = (at: (string | number)[], value: Text | undefined, kind: TextKind) => {
+    if (value === undefined) return;
+    const { findings, links } = checkText(value, kind, checks.languages, checks.declaredIn);
+    for (const finding of findings as TextFinding[]) problems.push({ ...finding, path: [...at, ...finding.path] });
+    for (const link of links) {
+      const place = [...at, ...link.path];
+      if (checks.onLink !== undefined) checks.onLink({ ...link, path: place });
+      else {
+        problems.push({
+          path: place,
+          lang: link.lang,
+          message: `${link.href} is a link to a page of the app; here there are no pages: link an https address`,
+        });
+      }
+    }
+  };
+  blocks.forEach((block, index) => {
+    const at: (string | number)[] = [index];
+    switch (block.type) {
+      case "text":
+        text([...at, "text"], block.text, "markdown");
+        break;
+      case "formula":
+        text([...at, "formula"], block.formula, "latex");
+        break;
+      case "figure":
+      case "labelled-figure": {
+        if (block.type === "figure" && (block.draw === undefined) === (block.image === undefined)) {
+          problems.push({
+            path: at,
+            message:
+              block.draw === undefined
+                ? "draw or image is missing; a figure is drawn from data (draw) or a bundled image (image)"
+                : "draw and image: a figure is either drawn from data or a bundled image",
+          });
+        }
+        if (block.image !== undefined && !checks.imageExists(block.image)) {
+          problems.push({
+            path: [...at, "image"],
+            message: `${block.image} is missing: put the file into src/images/`,
+          });
+        }
+        text([...at, "alt"], block.alt, "plain");
+        text([...at, "caption"], block.caption, "markdown");
+        if (block.type === "labelled-figure") {
+          const seen = new Set<string>();
+          block.labels.forEach((label, number) => {
+            text([...at, "labels", number, "text"], label.text, "plain");
+            const marker = markerOf(label, number);
+            if (seen.has(marker)) {
+              problems.push({
+                path: [...at, "labels", number, "marker"],
+                message: `${marker} is used twice; give each label its own marker`,
+              });
+            }
+            seen.add(marker);
+          });
+          // without a legend, alt is the only text that tells which part a marker stands for
+          if (block.legend === false) {
+            for (const lang of checks.languages) {
+              const alt = inLanguage(block.alt, lang);
+              block.labels.forEach((label, number) => {
+                const marker = markerOf(label, number);
+                if (!names(alt, marker)) {
+                  problems.push({
+                    path: [...at, "alt"],
+                    lang,
+                    message: `alt does not name the marker ${marker}; with legend: false, alt names every marker with its part`,
+                  });
+                }
+              });
+            }
+          }
+        }
+        text([...at, "source"], block.source, "credit");
+        break;
+      }
+      case "table": {
+        text([...at, "caption"], block.caption, "plain");
+        block.header?.forEach((cell, number) => text([...at, "header", number], cell, "markdown"));
+        const columns = block.header?.length ?? block.rows[0]?.length ?? 0;
+        block.rows.forEach((row, line) => {
+          if (row.length !== columns) {
+            problems.push({
+              path: [...at, "rows", line],
+              message: `${row.length} cells, but the table has ${columns} columns; give each row a cell per column`,
+            });
+          }
+          row.forEach((_cell, number) => text([...at, "rows", line, number], row[number], "markdown"));
+        });
+        break;
+      }
+      case "quote":
+        text([...at, "text"], block.text, "markdown");
+        text([...at, "origin", "author"], block.origin.author, "name");
+        text([...at, "origin", "work"], block.origin.work, "name");
+        if (typeof block.origin.year !== "number") text([...at, "origin", "year"], block.origin.year, "plain");
+        text([...at, "source"], block.source, "credit");
+        break;
+      case "code":
+        text([...at, "caption"], block.caption, "plain");
+        break;
+    }
+  });
+  return problems;
+}

package/runtime/shared/content.ts

@@ -0,0 +1,197 @@
+// The content of an app as YAML files, for every archetype whose content is YAML (the explainer, the interactive
+// archetype): reading a file with its line positions, collecting the problems with their place in it (one line each:
+// the file, its line and the path of the value), turning the errors of a JSON Schema into problems an author can act
+// on, and checking the texts of the content (languages, raw HTML, restricted Markdown, formulas).
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ErrorObject } from "ajv/dist/2020.js";
+import { isNode, LineCounter, parseDocument, type Document } from "yaml";
+import type { Text } from "./languages.ts";
+import { checkText, type TextKind } from "./text/check.ts";
+
+export type Path = readonly (string | number)[];
+
+/** A YAML file of the content, parsed, with its line positions. */
+export interface YamlFile {
+  file: string;
+  doc: Document;
+  lines: LineCounter;
+  value: unknown;
+}
+
+/** `["blocks", 0, "text"]` as `blocks[0].text`. */
+export function pathText(path: Path): string {
+  return path.map((part, index) => (typeof part === "number" ? `[${part}]` : index === 0 ? part : `.${part}`)).join("");
+}
+
+export const get = (value: unknown, path: Path): unknown =>
+  path.reduce<unknown>(
+    (at, part) => (typeof at === "object" && at !== null ? (at as Record<string, unknown>)[part] : undefined),
+    value,
+  );
+export const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Collects the problems, one line each, without repeating one. */
+export class Problems {
+  readonly lines: string[] = [];
+  add(line: string): void {
+    if (!this.lines.includes(line)) this.lines.push(line);
+  }
+  /** A problem at `path` in `yaml` (in `lang`), `offset` lines below the line of the value there. */
+  at(yaml: YamlFile, path: Path, message: string, lang?: string, offset = 0): void {
+    const line = lineOf(yaml, path, offset);
+    // the text of one language is at <path>.<lang>: named as <path> (<lang>)
+    const shown = lang !== undefined && path.at(-1) === lang ? path.slice(0, -1) : path;
+    const where = shown.length === 0 ? "" : ` ${pathText(shown)}${lang === undefined ? "" : ` (${lang})`}:`;
+    this.add(`${yaml.file}${line === undefined ? "" : `:${line}`}:${where} ${message}`);
+  }
+  file(file: string, message: string): void {
+    this.add(`${file}: ${message}`);
+  }
+}
+
+/** The line of the value at `path`, or of the nearest value around it; a block scalar's text starts a line lower. */
+export function lineOf(yaml: YamlFile, path: Path, offset: number): number | undefined {
+  for (let length = path.length; length >= 0; length--) {
+    const node = yaml.doc.getIn(path.slice(0, length), true);
+    if (!isNode(node) || node.range === undefined || node.range === null) continue;
+    const block = "type" in node && (node.type === "BLOCK_LITERAL" || node.type === "BLOCK_FOLDED");
+    const start = yaml.lines.linePos(node.range[0]).line;
+    return start + (length === path.length ? offset + (block && offset > 0 ? 1 : block ? 1 : 0) : 0);
+  }
+  return undefined;
+}
+
+/** Reads a YAML file of the content (`file` from the app's root); undefined, with its problems, when it is not valid YAML. */
+export function readYaml(root: string, file: string, problems: Problems): YamlFile | undefined {
+  const lines = new LineCounter();
+  const doc = parseDocument(readFileSync(join(root, file), "utf8"), { lineCounter: lines, prettyErrors: false });
+  if (doc.errors.length > 0) {
+    for (const error of doc.errors) {
+      const line = lines.linePos(error.pos[0]).line;
+      problems.add(`${file}:${line}: not valid YAML: ${error.message.split("\n")[0] ?? ""}`);
+    }
+    return undefined;
+  }
+  return { file, doc, lines, value: doc.toJS() as unknown };
+}
+
+/**
+ * What an archetype says about an error of its schema in its own words: the message, at the error's place or at `path`;
+ * null to say nothing (another error says it); undefined to leave it to the general messages.
+ */
+export type DescribeError = (
+  error: ErrorObject,
+  path: Path,
+  value: unknown,
+) => { message: string; path?: Path; lang?: string } | null | undefined;
+
+/** The schema's errors as problems: one per cause, the branches of texts and blocks folded. */
+export function schemaProblems(
+  yaml: YamlFile,
+  errors: readonly ErrorObject[],
+  problems: Problems,
+  describe?: DescribeError,
+): void {
+  const pathOf = (pointer: string): Path =>
+    pointer
+      .split("/")
+      .slice(1)
+      .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))
+      .map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+  const texts = errors.filter((error) => error.keyword === "anyOf").map((error) => error.instancePath);
+  const underText = (error: ErrorObject) =>
+    texts.some((text) => error.instancePath === text || error.instancePath.startsWith(`${text}/`));
+  for (const error of errors) {
+    const path = pathOf(error.instancePath);
+    const value = get(yaml.value, path);
+    const described = describe?.(error, path, value);
+    if (described !== undefined) {
+      if (described !== null) problems.at(yaml, described.path ?? path, described.message, described.lang);
+      continue;
+    }
+    switch (error.keyword) {
+      case "if":
+        break;
+      case "anyOf": {
+        if (typeof value === "string") problems.at(yaml, path, "must not be empty");
+        else if (isObject(value)) {
+          for (const [lang, text] of Object.entries(value)) {
+            if (typeof text !== "string") problems.at(yaml, path, "must be a text", lang);
+            else if (text.trim() === "") problems.at(yaml, path, "must not be empty", lang);
+            else if (!/^[a-z]{2}$/.test(lang)) {
+              problems.at(yaml, path, `${lang} is not a language code; use two letters, e.g. de, en`);
+            }
+          }
+        } else problems.at(yaml, path, "must be a text, or a map of texts by language: { de: …, en: … }");
+        break;
+      }
+      case "required":
+      case "dependentRequired":
+        problems.at(yaml, path, `${String(error.params["missingProperty"])} is missing`);
+        break;
+      case "additionalProperties":
+        problems.at(yaml, path, `${String(error.params["additionalProperty"])} is not allowed here`);
+        break;
+      case "unevaluatedProperties":
+        problems.at(yaml, path, `${String(error.params["unevaluatedProperty"])} is not allowed here`);
+        break;
+      case "enum":
+        problems.at(yaml, path, `must be one of ${(error.params["allowedValues"] as unknown[]).join(", ")}`);
+        break;
+      case "pattern":
+        if (underText(error)) break;
+        if (error.schemaPath.includes("/id/") || error.schemaPath.startsWith("#/$defs/id")) {
+          problems.at(yaml, path, `use lower-case letters, digits and hyphens, e.g. "prozentwert"`);
+        } else if (String(error.params["pattern"]) === "\\S") problems.at(yaml, path, "must not be empty");
+        else problems.at(yaml, path, `must match ${String(error.params["pattern"])}`);
+        break;
+      case "type":
+      case "minLength":
+        if (!underText(error)) problems.at(yaml, path, error.message ?? "is not valid");
+        break;
+      case "minItems":
+        problems.at(yaml, path, "must not be empty");
+        break;
+      default:
+        if (!underText(error)) problems.at(yaml, path, error.message ?? "is not valid");
+    }
+  }
+}
+
+/** Where a link inside a text was written, to check its target once every page is known. */
+export interface TextLink {
+  yaml: YamlFile;
+  path: Path;
+  lang: string;
+  offset: number;
+  href: string;
+}
+
+/** The checks of the texts: languages, raw HTML, Markdown, formulas. */
+export class Texts {
+  readonly links: TextLink[] = [];
+  readonly languages: readonly string[];
+  private readonly problems: Problems;
+  constructor(languages: readonly string[], problems: Problems) {
+    this.languages = languages;
+    this.problems = problems;
+  }
+
+  /**
+   * The text at `path` of `yaml`: a plain text, restricted Markdown, a formula, a name (a person, a work), or the source
+   * of a credit (a URL or a citation); a formula, a name or a URL given as a string is the same in every language, a
+   * citation is a plain text.
+   */
+  check(yaml: YamlFile, path: Path, kind: TextKind): void {
+    const value = get(yaml.value, path);
+    if (value === undefined) return;
+    const { findings, links } = checkText(value as Text, kind, this.languages);
+    for (const finding of findings) {
+      this.problems.at(yaml, [...path, ...finding.path], finding.message, finding.lang, finding.line);
+    }
+    for (const link of links)
+      this.links.push({ yaml, path: [...path, ...link.path], lang: link.lang, offset: 0, href: link.href });
+  }
+}

package/runtime/shared/examples.ts

@@ -0,0 +1,20 @@
+// The examples of an exercise (`examples: { accepted, rejected }`): test cases for the build, never shown to learners.
+// The build runs each through the same check the page uses: the quiz's checker for its question types
+// (../quiz/validate.ts), the comparator of a generated exercise (../explainer/generated.ts), the exported check of an
+// exercise component (../explainer/components.ts). An accepted example the check rejects, or a rejected one it
+// accepts, fails the build with this message.
+
+/**
+ * What to do about an example the check judges otherwise than it is listed: `right`, whether the check accepts it;
+ * `check`, what judges it; `fix`, what to change so that the check agrees.
+ */
+export function verdict(
+  example: string,
+  right: boolean,
+  check = "the check",
+  fix = "change the exercise so that its check",
+): string {
+  return right
+    ? `${check} accepts ${example}, but it is listed as rejected; if the task's text rules it out, ${fix} rejects it, else move it to accepted`
+    : `${check} rejects ${example}, but it is listed as accepted; if the task's text allows it, ${fix} accepts it, else move it to rejected`;
+}

package/runtime/shared/html.ts

@@ -0,0 +1,10 @@
+// Escaping a learner text for HTML, once for every archetype: `escape` for text and attribute values, `escapeText`
+// for text only (inside <code>, where a quotation mark is no markup).
+
+/** `text` for HTML text or a double-quoted attribute value. */
+export const escape = (text: string): string =>
+  text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** `text` for HTML text, quotation marks as they are. */
+export const escapeText = (text: string): string =>
+  text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");