paperlint 14.0.0 → 14.2.0

package/skills/build-label-page/scripts/label-page-core.ts

@@ -7,12 +7,14 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import * as R from "remeda";
 import { z } from "zod";
 import {
   describeRule,
   type Described as RuleText,
   type RuleRef,
 } from "./rule-descriptions.ts";
+import { applyPreset } from "./label-page-presets.ts";
 
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
@@ -83,6 +85,11 @@ const writeJson = (path: string, value: unknown): void => {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 };
 const JSON_VALUE = z.json();
+/** The config with its named preset applied (label-page-presets.ts), refused by path. */
+const withPreset = (raw: Json): Json => {
+  const r = applyPreset(raw);
+  return r.ok ? JSON_VALUE.parse(r.value) : fail(r.message);
+};
 const readJson = (path: string): Json => {
   try {
     return JSON_VALUE.parse(JSON.parse(readFileSync(path, "utf8")));
@@ -100,6 +107,9 @@ const readJson = (path: string): Json => {
 // prettier-ignore
 const PAGE_FIELDS = ["group", "title", "body", "code", "context", "file"] as const;
 const PRIVATE_FIELDS = ["source_id"] as const;
+// Who of the page's `answerers` an item is shown to: tells the page whom to show it, nothing about
+// the answer or the source.
+const ANSWERERS_FIELD = "answerers";
 // The linter rules an item names ("read as ruff `TID253`"): the page shows each with the linter's
 // own description, looked up at build time (rule-descriptions.ts), never typed into items.json.
 const RULES_FIELD = "rules";
@@ -108,11 +118,23 @@ const RULES_FIELD = "rules";
 const UNIT_FIELD = "unit";
 // Two readings of one requirement, shown as rows A and B (#374).
 const READINGS_FIELD = "readings";
+// Content blocks (#380): generic, on any kind. Every label and sentence a block shows comes from
+// items.json (or a preset, label-page-presets.ts); the page knows only the block's shape.
+const BLOCK_FIELDS = [
+  "situation",
+  "excerpt",
+  "references",
+  "more",
+  "table",
+  "repeat",
+] as const;
 const ALLOWED_FIELDS: readonly string[] = [
   ...PAGE_FIELDS,
   RULES_FIELD,
   UNIT_FIELD,
   READINGS_FIELD,
+  ...BLOCK_FIELDS,
+  ANSWERERS_FIELD,
   ...PRIVATE_FIELDS,
 ];
 
@@ -140,6 +162,11 @@ const RESERVED_NAMES = [
   "__lookupSetter__",
 ];
 const NAME_PATTERN = `(?!(?:${RESERVED_NAMES.join("|")})$)[A-Za-z0-9_-]+`;
+/**
+ * With `answerers`, a document's id is `<answerer>~<id>`: `~` is outside NAME_PATTERN, so no
+ * answerer's name, item id, group or practice id can hold it, and the id splits at its first `~`.
+ */
+const SEP = "~";
 const SOURCES = ["page", "chat"];
 const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
 
@@ -152,6 +179,7 @@ const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
 // refusal, what a value must be (a pattern) or why a field is required (a page kind needs it).
 type SchemaNode = (
   | { kind: "string"; required: boolean; pattern?: string }
+  | { kind: "text"; required: boolean }
   | { kind: "integer"; required: boolean }
   | { kind: "boolean"; required: boolean }
   | { kind: "array"; required: boolean; min: number; items: SchemaNode }
@@ -179,6 +207,8 @@ const string = (required = true, pattern?: string, why?: string): SchemaNode =>
         pattern,
         ...(why === undefined ? {} : { why }),
       };
+/** A string that may be empty: a blank line of code. */
+const text = (): SchemaNode => ({ kind: "text", required: true });
 const integer = (required = true): SchemaNode => ({
   kind: "integer",
   required,
@@ -212,6 +242,14 @@ const obj = (
 
 // What an item and a practice item both may carry beyond text: a practice card looks like the real
 // cards it rehearses. Each is optional here; a page's `kind` makes some of them required (KINDS).
+const LINK = string(false, "https?://\\S+", "an http(s) link");
+const optional = (fields: Readonly<Record<string, SchemaNode>>): SchemaNode =>
+  obj(fields, true, false);
+const TEXT_FIELD = obj({
+  label: string(false),
+  text: string(),
+  style: string(false, "code|note", "code or note"),
+});
 const CARD_FIELDS: Readonly<Record<string, SchemaNode>> = {
   [RULES_FIELD]: array(
     obj({
@@ -235,6 +273,51 @@ const CARD_FIELDS: Readonly<Record<string, SchemaNode>> = {
   ),
   [READINGS_FIELD]: obj({ a: string(), b: string() }, true, false),
   file: string(false),
+  situation: optional({ summary: string(), question: string() }),
+  excerpt: optional({
+    file: string(false),
+    url: LINK,
+    lines: array(obj({ n: integer(), text: text(), mark: boolean() }), true, 1),
+    caption: string(false),
+    mark_label: string(false),
+  }),
+  references: optional({
+    summary: string(),
+    entries: array(
+      obj({
+        label: string(false),
+        title: string(),
+        fields: array(TEXT_FIELD, true, 1),
+        url: LINK,
+        url_label: string(false),
+      }),
+      true,
+      1,
+    ),
+  }),
+  more: optional({
+    summary: string(),
+    items: array(string(), true, 1),
+    rest: string(false),
+  }),
+  table: optional({
+    summary: string(),
+    note: string(false),
+    rows: array(
+      obj({
+        label: string(),
+        value: string(),
+        plain: string(false),
+        mark: optional({
+          tone: string(true, "yes|no", "yes or no"),
+          text: string(),
+        }),
+      }),
+      true,
+      1,
+    ),
+  }),
+  repeat: optional({ group: string(), index: integer(), of: integer() }),
 };
 /**
  * THE PAGE KINDS, and the card fields each requires on every item and practice card (#373). A fix to
@@ -283,6 +366,7 @@ const itemSchema = (kind: Kind): SchemaNode =>
         ]),
       ),
       ...cardFields(kind),
+      [ANSWERERS_FIELD]: array(string(true, NAME_PATTERN), false, 1),
     },
     false, // an unlisted item field is the leak guard's refusal, with its own message
   );
@@ -324,6 +408,10 @@ const configSchema = (kind: Kind): SchemaNode =>
     seed: integer(),
     groups: mapping(string(), NAME_PATTERN, 1), // ids become store document ids
     labeller_knows: array(string(true, NAME_PATTERN), false),
+    // Two or more people answer the same page, each under their own name (doc ids `<name>~<id>`).
+    answerers: array(string(true, NAME_PATTERN), false, 2),
+    // An item's answer saves only once the item has been on screen this many seconds.
+    min_seconds: integer(false),
     // true: a "how well do you know {group}" question per group, for a study that filters on it
     // (rule 5). Left out, none is asked: an approval page's author has never seen the repositories.
     familiarity: boolean(false),
@@ -331,6 +419,15 @@ const configSchema = (kind: Kind): SchemaNode =>
     questions: array(QUESTION_SCHEMA, true, 1),
     practice: array(practiceSchema(kind), true, MIN_PRACTICE),
     practice_round: integer(false),
+    // Page-level words the blocks use (references/closed-choice-generator.md §«Content blocks»).
+    labels: optional({
+      place: string(false),
+      body: string(false),
+      line: string(false),
+      line_part: string(false),
+      repeat: string(false),
+      practice_example: string(false),
+    }),
     items: array(itemSchema(kind), true, 1),
   });
 /** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
@@ -412,6 +509,20 @@ function checkBoolean(value: Json, where: string): void {
   if (typeof value !== "boolean")
     fail(`${where}: must be true or false, got ${repr(value)}`);
 }
+/** A string that may be empty (a blank line of code), or an integer. */
+function checkScalar(
+  value: Json,
+  kind: "text" | "integer",
+  where: string,
+): void {
+  if (kind === "text" && typeof value !== "string")
+    fail(`${where}: must be a string, got ${repr(value)}`);
+  if (
+    kind === "integer" &&
+    (typeof value !== "number" || !Number.isInteger(value))
+  )
+    fail(`${where}: must be an integer, got ${repr(value)}`);
+}
 /** Refuse the first place `value` departs from `node`; the message starts with the field's path. */
 function checkValue(value: Json, node: SchemaNode, path: string): void {
   const where = path || "items.json";
@@ -419,10 +530,9 @@ function checkValue(value: Json, node: SchemaNode, path: string): void {
     case "string":
       checkString(value, node, where);
       break;
+    case "text":
     case "integer":
-      if (typeof value !== "number" || !Number.isInteger(value)) {
-        fail(`${where}: must be an integer, got ${repr(value)}`);
-      }
+      checkScalar(value, node.kind, where);
       break;
     case "boolean":
       checkBoolean(value, where);
@@ -459,16 +569,71 @@ interface Unit {
   readonly part: number;
   readonly of: number;
 }
+interface TextField {
+  readonly label?: string;
+  readonly text: string;
+  readonly style?: string;
+}
+interface CodeLine {
+  readonly n: number;
+  readonly text: string;
+  readonly mark: boolean;
+}
+/** The content blocks (#380), each optional on any kind. */
+interface Blocks {
+  readonly situation?: { readonly summary: string; readonly question: string };
+  readonly excerpt?: {
+    readonly file?: string;
+    readonly url?: string;
+    readonly lines: readonly CodeLine[];
+    readonly caption?: string;
+    readonly mark_label?: string;
+  };
+  readonly references?: {
+    readonly summary: string;
+    readonly entries: readonly {
+      readonly label?: string;
+      readonly title: string;
+      readonly fields: readonly TextField[];
+      readonly url?: string;
+      readonly url_label?: string;
+    }[];
+  };
+  readonly more?: {
+    readonly summary: string;
+    readonly items: readonly string[];
+    readonly rest?: string;
+  };
+  readonly table?: {
+    readonly summary: string;
+    readonly note?: string;
+    readonly rows: readonly {
+      readonly label: string;
+      readonly value: string;
+      readonly plain?: string;
+      readonly mark?: { readonly tone: string; readonly text: string };
+    }[];
+  };
+  readonly repeat?: {
+    readonly group: string;
+    readonly index: number;
+    readonly of: number;
+  };
+}
 /** What a card shows, on an item and on a practice item alike. */
 type Card = {
   readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
-} & {
-  readonly body: string;
-  readonly rules?: readonly RuleRef[];
-  readonly unit?: Unit;
-  readonly readings?: { readonly a: string; readonly b: string };
+} & Blocks & {
+    readonly body: string;
+    readonly rules?: readonly RuleRef[];
+    readonly unit?: Unit;
+    readonly readings?: { readonly a: string; readonly b: string };
+  };
+type Item = Card & {
+  readonly source_id: string;
+  readonly group: string;
+  readonly answerers?: readonly string[];
 };
-type Item = Card & { readonly source_id: string; readonly group: string };
 type Practice = Card & {
   readonly expected: Readonly<Record<string, string>>;
   readonly why: string;
@@ -481,11 +646,14 @@ interface Config {
   readonly seed: number;
   readonly groups: Readonly<Record<string, string>>;
   readonly labeller_knows?: readonly string[];
+  readonly answerers?: readonly string[];
+  readonly min_seconds?: number;
   readonly familiarity?: boolean;
   readonly familiarity_question?: string;
   readonly questions: readonly Question[];
   readonly practice: readonly Practice[];
   readonly practice_round?: number;
+  readonly labels?: Readonly<Record<string, string>>;
   readonly items: readonly Item[];
 }
 /** The config is typed by passing CONFIG_SCHEMA: `checkValue` refuses (throws) on any departure. */
@@ -597,8 +765,37 @@ function checkPractice(cfg: Config): void {
       fail(`${where}.${missing}: every question needs its expected answer`);
   });
 }
+/** The first entry of `names` that repeats an earlier one, refused by its path. */
+function checkDistinct(names: readonly string[], where: string): void {
+  const at = names.findIndex((x, i) => names.indexOf(x) !== i);
+  if (at !== -1)
+    fail(`${where}[${String(at)}]: ${repr(names[at])} is repeated`);
+}
+/** Each answerer once; an item's own list a subset of the page's; a dwell of a second or more. */
+function checkAnswerers(cfg: Config): void {
+  if ((cfg.min_seconds ?? 1) < 1)
+    fail(`min_seconds: ${repr(cfg.min_seconds)} — must be 1 or more`);
+  const all = cfg.answerers;
+  if (all !== undefined) checkDistinct(all, "answerers");
+  cfg.items.forEach((item, n) => {
+    const where = `items[${String(n)}].answerers`;
+    const own = item.answerers;
+    if (own === undefined) return;
+    if (all === undefined)
+      return fail(
+        `${where}: the page has no \`answerers\` — add the page's list, or take this out`,
+      );
+    const k = own.findIndex((who) => !R.isIncludedIn(who, all));
+    if (k !== -1)
+      fail(
+        `${where}[${String(k)}]: ${repr(own[k])} is not in \`answerers\` (${all.join(", ")})`,
+      );
+    checkDistinct(own, where);
+  });
+}
 function checkConfig(cfg: Config): void {
   checkGroups(cfg);
+  checkAnswerers(cfg);
   if (!asksFamiliarity(cfg) && cfg.familiarity_question !== undefined) {
     fail(
       `familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is not true — remove it, or set "familiarity": true`,
@@ -688,6 +885,43 @@ function checkUnits(cfg: Config): void {
     });
   }
 }
+/**
+ * A situation's sentence or question may name the excerpt's marked line as `{line}`: the page writes
+ * «line N: » and the line's code there, so a question sits next to the code it is about.
+ */
+const LINE_TOKEN = "{line}";
+const SITUATION_TEXTS = ["summary", "question"] as const;
+/** The line `{line}` stands for: the first marked line, its number and its code without the indent. */
+const lineOf = (card: Card) =>
+  card.excerpt?.lines
+    .filter((l) => l.mark)
+    .map((l) => ({ n: l.n, text: l.text.trim() }))[0];
+const usesLine = (card: Card): boolean =>
+  SITUATION_TEXTS.some((f) => card.situation?.[f].includes(LINE_TOKEN));
+/**
+ * What the block schema cannot say: an excerpt marks a line, `{line}` has a marked line to stand for,
+ * and a repeat sits inside its count.
+ */
+function checkBlocks(cfg: Config): void {
+  cardsOf(cfg).forEach(([at, card]) => {
+    if (card.excerpt !== undefined && !card.excerpt.lines.some((l) => l.mark))
+      fail(
+        `${at}.excerpt.lines: no line is marked — mark the line the card is about (\`mark: true\`)`,
+      );
+    const token = SITUATION_TEXTS.find((f) =>
+      card.situation?.[f].includes(LINE_TOKEN),
+    );
+    if (token !== undefined && card.excerpt === undefined)
+      fail(
+        `${at}.situation.${token}: \`${LINE_TOKEN}\` names the excerpt's marked line, and the card has no \`excerpt\` — add it, or write the ${token} without \`${LINE_TOKEN}\``,
+      );
+    const r = card.repeat;
+    if (r !== undefined && (r.index < 1 || r.index > r.of))
+      fail(
+        `${at}.repeat.index: ${String(r.index)} is not between 1 and ${String(r.of)}`,
+      );
+  });
+}
 /** Every card of the config, items then practice, by path. */
 const cardsOf = (cfg: Config) => [
   ...cfg.items.map((i, n) => [`items[${String(n)}]`, i] as const),
@@ -715,12 +949,24 @@ function checkItemFields(cfg: Config): void {
       );
   });
 }
-/** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
-const visibleTexts = (item: Item): readonly (readonly [string, string])[] => [
-  ...PAGE_FIELDS.map((f): readonly [string, string] => [f, item[f] ?? ""]),
-  [UNIT_FIELD, item.unit?.text ?? ""],
-  [READINGS_FIELD, `${item.readings?.a ?? ""} ${item.readings?.b ?? ""}`],
-];
+/** Every string inside a value: each is tested on its own, as the page renders it, never a serialisation. */
+const stringsIn = (v: unknown): readonly string[] =>
+  typeof v === "string"
+    ? [v]
+    : Array.isArray(v)
+      ? v.flatMap(stringsIn)
+      : typeof v === "object" && v !== null
+        ? Object.values(v).flatMap(stringsIn)
+        : [];
+/**
+ * Every text of an item the labeller sees, by field: each string the page shows (the fields as
+ * `shownFields` passes them, so a repeat without its group), and every rule it names.
+ */
+const visibleTexts = (item: Item): readonly (readonly [string, string])[] =>
+  Object.entries({
+    ...shownFields(item),
+    [RULES_FIELD]: item.rules ?? [],
+  }).flatMap(([f, v]) => stringsIn(v).map((t) => [f, t] as const));
 const escapeRegExp = (s: string): string =>
   s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
@@ -752,6 +998,8 @@ interface KeyEntry {
   readonly source_id: string;
   readonly group: string;
   readonly on_page: boolean;
+  /** Who the item is shown to, when not every answerer of the page. */
+  readonly answerers?: readonly string[];
 }
 interface OldKey {
   readonly seed: number;
@@ -804,13 +1052,18 @@ function assignIds(
 }
 
 // ── a build, short of the page ──────────────────────────────────────────────────────────────────
-/** A unit as the page shows it: the line, its mark and its part, without the line's private id. */
-type ShownUnit = Omit<Unit, "id">;
-const shownFields = (
-  item: Card,
-): Readonly<
-  Record<string, string | ShownUnit | NonNullable<Card["readings"]>>
-> => ({
+/** A card's situation as the page shows it, with the line `{line}` stands for. */
+const situationShown = (item: Card) =>
+  item.situation === undefined
+    ? {}
+    : {
+        situation: {
+          summary: item.situation.summary,
+          question: item.situation.question,
+          ...(usesLine(item) ? { line: lineOf(item) } : {}),
+        },
+      };
+const shownFields = (item: Card): Readonly<Record<string, unknown>> => ({
   ...Object.fromEntries(
     PAGE_FIELDS.flatMap((f) => {
       const v = item[f];
@@ -828,6 +1081,15 @@ const shownFields = (
         },
       }),
   ...(item.readings === undefined ? {} : { [READINGS_FIELD]: item.readings }),
+  ...Object.fromEntries(
+    BLOCK_FIELDS.filter((f) => f !== "repeat" && f !== "situation").flatMap(
+      (f) => (item[f] === undefined ? [] : [[f, item[f]]]),
+    ),
+  ),
+  ...situationShown(item),
+  ...(item.repeat === undefined
+    ? {}
+    : { repeat: { index: item.repeat.index, of: item.repeat.of } }),
 });
 /** Rule → the linter's description (and a ruff rule's family), for every rule a card names. */
 type Described = ReadonlyMap<string, RuleText>;
@@ -836,14 +1098,16 @@ const ruleKey = (r: RuleRef): string => `${r.linter} ${r.id}`;
 function describeRules(cfg: Config, fromDir: string): Described {
   return new Map(
     cardsOf(cfg).flatMap(([at, card]) =>
-      (card.rules ?? []).map((r, k): readonly [string, RuleText] => {
-        const text = describeRule(r, fromDir);
-        return text === undefined
-          ? fail(
-              `${at}.rules[${String(k)}]: ${r.linter} ${repr(r.id)} has no description from the linter (${r.linter === "ruff" ? "`ruff rule` does not know it, or ruff is not on PATH" : "not a rule of the ESLint, or of a plugin, installed where items.json is"}) — check the id`,
-            )
-          : [ruleKey(r), text];
-      }),
+      (card.rules ?? []).flatMap(
+        (r, k): readonly (readonly [string, RuleText])[] => {
+          const text = describeRule(r, fromDir);
+          return text === undefined
+            ? fail(
+                `${at}.rules[${String(k)}]: ${r.linter} ${repr(r.id)} has no description from the linter (${r.linter === "ruff" ? "`ruff rule` does not know it, or ruff is not on PATH" : "not a rule of the ESLint, or of a plugin, installed where items.json is"}) — check the id`,
+              )
+            : [[ruleKey(r), text]];
+        },
+      ),
     ),
   );
 }
@@ -882,6 +1146,20 @@ const practiceShown = (cfg: Config, described: Described) =>
     ...shownFields(p),
     ...rulesShown(p, described),
   }));
+/** The page's own words where `labels` leaves one out (references/closed-choice-generator.md). */
+const DEFAULT_LABELS: Readonly<Record<string, string>> = {
+  place: "{id} · {n} of {total}",
+  line: "Line",
+  line_part: "{line} · part {part} of {of}",
+  repeat: "Card {index} of {of}",
+  practice_example: "",
+};
+/** The answerers and the dwell, only when items.json sets them: a page without them is as it was. */
+const twoKeys = (cfg: Config) =>
+  R.pickBy(
+    { answerers: cfg.answerers, min_seconds: cfg.min_seconds },
+    R.isDefined,
+  );
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
 function payloadOf(
   cfg: Config,
@@ -894,24 +1172,29 @@ function payloadOf(
   return {
     title: cfg.title,
     intro: cfg.intro ?? "",
+    labels: { ...DEFAULT_LABELS, ...cfg.labels },
     groups: used.map((g) => ({ id: g, label: String(cfg.groups[g]) })),
     familiarity_question: asksFamiliarity(cfg)
       ? (cfg.familiarity_question ?? "How well do you know {group}?")
       : "",
     familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
     allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
+    ...twoKeys(cfg),
     questions: cfg.questions,
     practice: {
       round: practiceRound(cfg),
       items: practiceShown(cfg, described),
     },
-    items: page.items.map((i) => ({
-      id: page.idOf(i),
-      ...shownFields(i),
-      ...rulesShown(i, described),
-    })),
+    items: page.items.map((i) => itemShown(i, page.idOf(i), described)),
   };
 }
+/** One item as its card shows it, and whom it is shown to when not every answerer. */
+const itemShown = (i: Item, id: string, described: Described) => ({
+  id,
+  ...shownFields(i),
+  ...rulesShown(i, described),
+  ...R.pickBy({ answerers: i.answerers }, R.isDefined),
+});
 export type Payload = ReturnType<typeof payloadOf>;
 /** Every id the key keeps (on the page now, or kept from an earlier build), with its source and group. */
 function idsOf(cfg: Config, page: ReturnType<typeof itemsOnPage>): JsonObject {
@@ -923,16 +1206,17 @@ function idsOf(cfg: Config, page: ReturnType<typeof itemsOnPage>): JsonObject {
     ]),
     ...cfg.items.map((i): [string, string] => [i.source_id, i.group]),
   ]);
+  const bySource = R.indexBy(cfg.items, (i) => i.source_id);
   const byId = [...page.ids].sort(([, a], [, b]) => byText(a, b));
-  return Object.fromEntries(
-    byId.map(([sid, nid]) => [
-      nid,
-      {
-        source_id: sid,
-        group: String(groupOf.get(sid)),
-        on_page: shown.has(nid),
-      },
-    ]),
+  return R.pullObject(
+    byId,
+    ([, nid]) => nid,
+    ([sid, nid]) => ({
+      source_id: sid,
+      group: String(groupOf.get(sid)),
+      on_page: shown.has(nid),
+      ...R.pickBy({ answerers: bySource[sid]?.answerers }, R.isDefined),
+    }),
   );
 }
 /** Round → its practice items' expected answers. */
@@ -957,6 +1241,7 @@ function keyOf(
   return {
     study: cfg.study,
     seed: cfg.seed,
+    ...twoKeys(cfg),
     questions: cfg.questions.map((q) => q.id),
     // What counts as an answer: the same lists the page was given (`allowedValues`). `export`
     // checks every stored answer and familiarity against them, so the build's options decide.
@@ -983,13 +1268,14 @@ function keyOf(
  * returns what the page shows. A page written by hand can take its blindness and its key from here.
  */
 export function prepareBuild(configPath: string, outDir: string) {
-  const cfg = readJson(configPath);
+  const cfg = withPreset(readJson(configPath));
   assertConfig(cfg);
   // Once its `kind` is known to be one, the fields that kind needs on every card.
   checkValue(cfg, configSchema(cfg.kind), "");
   checkConfig(cfg);
   checkItemFields(cfg);
   checkUnits(cfg);
+  checkBlocks(cfg);
   checkNoSourceShown(cfg);
   const described = describeRules(cfg, dirname(configPath));
   mkdirSync(outDir, { recursive: true });
@@ -1007,6 +1293,8 @@ export function prepareBuild(configPath: string, outDir: string) {
 interface Key {
   readonly study: string;
   readonly questions: readonly string[];
+  readonly answerers?: readonly string[];
+  readonly min_seconds?: number;
   readonly allowed?: Json;
   readonly practice?: {
     readonly round: number;
@@ -1024,6 +1312,11 @@ function assertKey(_value: Json): asserts _value is Json & Key {
 }
 
 const ANSWER_DOC_FIELDS = ["answers", "reasons", "savedAt", "source"];
+/** A page built with `min_seconds` also stores how long the item was on screen before its first save. */
+const answerDocFields = (key: Key): readonly string[] =>
+  key.min_seconds === undefined
+    ? ANSWER_DOC_FIELDS
+    : ["answers", "reasons", "savedAt", "seconds", "source"];
 const GROUP_DOC_FIELDS = ["familiarity", "savedAt", "source"];
 const DOC_FIELD_TYPES: readonly (readonly [
   string,
@@ -1042,6 +1335,12 @@ const DOC_FIELD_TYPES: readonly (readonly [
     (v) => v === null || typeof v === "string",
     "a timestamp string or null",
   ],
+  [
+    "seconds",
+    (v) =>
+      v === null || (typeof v === "number" && Number.isInteger(v) && v >= 0),
+    "a whole number of seconds or null",
+  ],
 ];
 const COLLECTIONS = ["answers", "groups", "practice"] as const;
 type Collection = (typeof COLLECTIONS)[number];
@@ -1075,15 +1374,29 @@ interface Names {
   readonly onPage: readonly string[];
   readonly fields: readonly string[];
 }
-function knownNames(key: Key): Readonly<Record<Collection, Names>> {
-  const entries = Object.entries(key.ids);
+/** Who an item is shown to: its own list, else every answerer of the page. */
+const shownTo = (all: readonly string[], meta: KeyEntry): readonly string[] =>
+  meta.answerers ?? all;
+/** A document's answerer, and the page's answerers; none on a page without them. */
+type Whose =
+  | { readonly who?: undefined }
+  | { readonly who: string; readonly all: readonly string[] };
+/** The names of a page without answerers, or those of one answerer's documents. */
+function knownNames(
+  key: Key,
+  whose: Whose,
+): Readonly<Record<Collection, Names>> {
+  const entries = Object.entries(key.ids).filter(
+    ([, m]) =>
+      whose.who === undefined || shownTo(whose.all, m).includes(whose.who),
+  );
   const shown = entries.filter(([, m]) => m.on_page);
   const practice = practiceDocs(key);
   return {
     answers: {
       known: entries.map(([nid]) => [nid, key.questions] as const),
       onPage: shown.map(([nid]) => nid),
-      fields: ANSWER_DOC_FIELDS,
+      fields: answerDocFields(key),
     },
     groups: {
       known: entries.map(([, m]) => [m.group, key.questions] as const),
@@ -1093,7 +1406,7 @@ function knownNames(key: Key): Readonly<Record<Collection, Names>> {
     practice: {
       known: practice,
       onPage: practice.map(([n]) => n),
-      fields: ANSWER_DOC_FIELDS,
+      fields: answerDocFields(key),
     },
   };
 }
@@ -1118,16 +1431,43 @@ function checkDumpShape(dump: Json): asserts dump is JsonObject {
       `${stray}: the store has no such collection (expected ${COLLECTIONS.join(", ")})`,
     );
 }
+/**
+ * A document's answerer and its name without it. A page without answerers has none; with them, an
+ * id without `~`, or before it a name the page does not have, is refused.
+ */
+function answererOf(
+  where: string,
+  docId: string,
+  key: Key,
+): Whose & { readonly name: string } {
+  const all = key.answerers;
+  if (all === undefined) return { name: docId };
+  const at = docId.indexOf(SEP);
+  if (at === -1)
+    return fail(
+      `${where}: this page has answerers (${all.join(", ")}), so a document's id is <answerer>${SEP}<id>`,
+    );
+  const who = docId.slice(0, at);
+  if (!all.includes(who))
+    fail(
+      `${where}: ${repr(who)} is not an answerer of this page (${all.join(", ")})`,
+    );
+  return { who, all, name: docId.slice(at + 1) };
+}
 function checkDocName(
   where: string,
-  name: string,
+  { who, name }: Whose & { readonly name: string },
   kind: Collection,
   names: Names,
 ): readonly string[] {
   const hit = names.known.find(([n]) => n === name);
   if (hit === undefined) {
     return fail(
-      `${where}: the key does not know this ${NOUN[kind]} (${[...new Set(names.known.map(([n]) => n))].sort().join(", ")})`,
+      `${where}: the key does not know this ${NOUN[kind]}${who === undefined ? "" : ` for ${who}`} (${R.unique(
+        names.known.map(([n]) => n),
+      )
+        .sort()
+        .join(", ")})`,
     );
   }
   if (!names.onPage.includes(name)) {
@@ -1206,15 +1546,20 @@ function checkDocAnswers(
  */
 function checkDump(dump: Json, key: Key): asserts dump is JsonObject {
   checkDumpShape(dump);
-  const names = knownNames(key);
+  // A page without answerers knows one set of names; each answerer has their own.
+  const plain = knownNames(key, {});
   for (const kind of COLLECTIONS) {
     const collection = dump[kind];
-    for (const [name, doc] of sortedEntries(
+    for (const [docId, doc] of sortedEntries(
       isObject(collection) ? collection : {},
     )) {
-      const where = `${kind}/${name}`;
-      const questions = checkDocName(where, name, kind, names[kind]);
-      checkDocFields(where, doc, kind, names[kind].fields);
+      const where = `${kind}/${docId}`;
+      const named = answererOf(where, docId, key);
+      const names = (named.who === undefined ? plain : knownNames(key, named))[
+        kind
+      ];
+      const questions = checkDocName(where, named, kind, names);
+      checkDocFields(where, doc, kind, names.fields);
       checkDocAnswers(where, doc, questions);
     }
   }
@@ -1302,8 +1647,8 @@ function answersOf(doc: JsonObject, ctx: Ctx) {
   );
   return { given, invalid };
 }
-/** One item of the labels file: its answers, what is invalid, the reasons, and whether it is done. */
-function labelOf(nid: string, meta: KeyEntry, doc: JsonObject, ctx: Ctx) {
+/** One stored answer: its answers, what is invalid, the reasons, and whether it is done. */
+function answerOf(doc: JsonObject, ctx: Ctx) {
   const { given, invalid } = answersOf(doc, ctx);
   const reasons = Object.fromEntries(
     Object.entries(textsOf(doc["reasons"])).filter(([, r]) => r.trim()),
@@ -1315,9 +1660,6 @@ function labelOf(nid: string, meta: KeyEntry, doc: JsonObject, ctx: Ctx) {
     )
     .map(([q]) => q);
   return {
-    id: nid,
-    source_id: meta.source_id,
-    group: meta.group,
     answers: given,
     invalid_answers: invalid,
     reasons,
@@ -1326,19 +1668,32 @@ function labelOf(nid: string, meta: KeyEntry, doc: JsonObject, ctx: Ctx) {
       Object.values(given).every((v) => v !== null) && !unexplained.length,
     source: textOf(doc["source"]),
     saved_at: doc["savedAt"] ?? null,
+    // Only a page built with `min_seconds` stores how long the item was on screen.
+    ...R.pick({ seconds: doc["seconds"] ?? null }, secondsOf(ctx.key)),
   };
 }
-type Label = ReturnType<typeof labelOf>;
+type Answer = ReturnType<typeof answerOf>;
+/** The `seconds` field, on a page built with `min_seconds`; none on any other. */
+const secondsOf = (key: Key): readonly "seconds"[] =>
+  key.min_seconds === undefined ? [] : ["seconds"];
+/** One item of the labels file of a page without answerers. */
+const labelOf = (nid: string, meta: KeyEntry, doc: JsonObject, ctx: Ctx) => ({
+  id: nid,
+  source_id: meta.source_id,
+  group: meta.group,
+  ...answerOf(doc, ctx),
+});
 
 /** Same rule as for item answers: a familiarity outside the options is marked, not counted as rated. */
 function groupsOf(
   groupIds: readonly string[],
   groups: Json | undefined,
   allowed: Allowed,
+  prefix = "",
 ) {
   return Object.fromEntries(
     groupIds.map((g) => {
-      const doc = docOf(groups, g);
+      const doc = docOf(groups, `${prefix}${g}`);
       const fam = textOf(doc["familiarity"]);
       const bad = fam !== null && !allowed.familiarity.includes(fam);
       return [
@@ -1353,7 +1708,10 @@ function groupsOf(
     }),
   );
 }
-function reportLabels(items: readonly Label[], allowed: Allowed): void {
+function reportLabels(
+  items: readonly (Answer & { readonly id: string })[],
+  allowed: Allowed,
+): void {
   for (const i of items) {
     for (const [q, v] of Object.entries(i.invalid_answers)) {
       say(
@@ -1383,9 +1741,14 @@ function reportGroups(
   }
 }
 /** Each practice item of the key's round: what was answered first, what was expected, whether they match. */
-function scorePractice(dump: JsonObject, round: string, all: Expected) {
+function scorePractice(
+  dump: JsonObject,
+  round: string,
+  all: Expected,
+  prefix: string,
+) {
   return Object.entries(all).map(([pid, expected]) => {
-    const doc = docOf(dump["practice"], `r${round}-${pid}`);
+    const doc = docOf(dump["practice"], `${prefix}r${round}-${pid}`);
     const answers = isObject(doc["answers"]) ? doc["answers"] : {};
     const matched = Object.entries(expected).every(
       ([q, v]) => answers[q] === v,
@@ -1399,9 +1762,14 @@ function scorePractice(dump: JsonObject, round: string, all: Expected) {
     };
   });
 }
-/** One file per round: a second round exported the same day keeps the first. */
-const practiceFile = (study: string, round: number, day: string): string =>
-  `${study}-practice-r${String(round)}-${day}.json`;
+/** One file per round (and answerer): a second round exported the same day keeps the first. */
+const practiceFile = (
+  study: string,
+  round: number,
+  day: string,
+  who: string | undefined,
+): string =>
+  `${study}-practice-r${String(round)}${who === undefined ? "" : `-${who}`}-${day}.json`;
 /**
  * Every practice round the store holds answers for, each scored against its own expected answers
  * into its own file; never into the labels. The key's own round is reported even unanswered.
@@ -1414,79 +1782,169 @@ function exportPractice(
 ): void {
   const p = key.practice;
   if (p === undefined) return;
-  Object.entries(roundsIn(p))
-    .sort(([a], [b]) => Number(a) - Number(b))
-    .forEach(([round, expected]) => {
+  const rounds = R.sortBy(R.entries(roundsIn(p)), ([r]) => Number(r));
+  (key.answerers ?? [undefined]).forEach((who) => {
+    rounds.forEach(([round, expected]) => {
       exportRound(
         key.study,
         Number(round),
-        scorePractice(dump, round, expected),
-        {
-          target,
-          day,
-          current: Number(round) === p.round,
-        },
+        scorePractice(
+          dump,
+          round,
+          expected,
+          who === undefined ? "" : `${who}${SEP}`,
+        ),
+        { target, day, current: Number(round) === p.round, who },
       );
     });
+  });
+}
+/** Where a round's practice goes, and whose it is: no one's on a page without answerers. */
+interface RoundAt {
+  readonly target: string;
+  readonly day: string;
+  readonly current: boolean;
+  readonly who: string | undefined;
 }
 /** One round's scored practice to `<study>-practice-r<round>-<date>.json`, and one line about it. */
 function exportRound(
   study: string,
   round: number,
   items: ReturnType<typeof scorePractice>,
-  at: {
-    readonly target: string;
-    readonly day: string;
-    readonly current: boolean;
-  },
+  at: RoundAt,
 ): void {
+  const named = `practice round ${String(round)}${at.who === undefined ? "" : ` (${at.who})`}`;
   if (!items.some((i) => Object.keys(i.answers).length)) {
-    if (at.current) say(`practice round ${String(round)}: not answered`);
+    if (at.current) say(`${named}: not answered`);
     return;
   }
   const missed = items.filter((i) => !i.matched).map((i) => i.id);
   const matched = items.length - missed.length;
-  const path = join(at.target, practiceFile(study, round, at.day));
+  const path = join(at.target, practiceFile(study, round, at.day, at.who));
   writeJson(path, {
     study,
     round,
+    ...R.pickBy({ answerer: at.who }, R.isDefined),
     exported: at.day,
     matched,
     total: items.length,
     items,
   });
   say(
-    `practice round ${String(round)}: ${String(matched)} of ${String(items.length)} matched${missed.length ? `; missed ${missed.join(", ")}` : ""} -> ${path}`,
+    `${named}: ${String(matched)} of ${String(items.length)} matched${missed.length ? `; missed ${missed.join(", ")}` : ""} -> ${path}`,
   );
 }
+/** The counts of one set of answers and groups. */
+const tally = (
+  items: readonly Answer[],
+  groups: ReturnType<typeof groupsOf>,
+) => ({
+  groups,
+  complete_items: items.filter((i) => i.complete).length,
+  invalid_items: items.filter((i) => Object.keys(i.invalid_answers).length)
+    .length,
+  invalid_groups: Object.values(groups).filter(
+    (g) => g.invalid_familiarity !== null,
+  ).length,
+  total_items: items.length,
+});
+type Tally = ReturnType<typeof tally>;
+/** The familiarity of the groups of `onPage`, or none on a page that asks none. */
+const groupsFor = (
+  onPage: readonly (readonly [string, KeyEntry])[],
+  dump: JsonObject,
+  ctx: Ctx,
+  prefix = "",
+) =>
+  ctx.allowed.familiarity.length
+    ? groupsOf(
+        R.unique(onPage.map(([, m]) => m.group)),
+        dump["groups"],
+        ctx.allowed,
+        prefix,
+      )
+    : {};
 /** The labels file: every item on the page with its answers, the groups, and the counts. */
 function labelsOf(dump: JsonObject, ctx: Ctx, day: string) {
   const onPage = Object.entries(ctx.key.ids).filter(([, m]) => m.on_page);
   const items = onPage.map(([nid, meta]) =>
     labelOf(nid, meta, docOf(dump["answers"], nid), ctx),
   );
-  const groups = ctx.allowed.familiarity.length
-    ? groupsOf(
-        [...new Set(onPage.map(([, m]) => m.group))],
-        dump["groups"],
-        ctx.allowed,
-      )
-    : {};
   return {
     study: ctx.key.study,
     exported: day,
     questions: ctx.key.questions,
     items,
-    groups,
-    complete_items: items.filter((i) => i.complete).length,
-    invalid_items: items.filter((i) => Object.keys(i.invalid_answers).length)
-      .length,
-    invalid_groups: Object.values(groups).filter(
-      (g) => g.invalid_familiarity !== null,
-    ).length,
-    total_items: items.length,
+    ...tally(items, groupsFor(onPage, dump, ctx)),
+  };
+}
+/**
+ * The labels file of a page with answerers: each item with every answerer it is shown to and their
+ * answers apart (`by_answerer`), and each answerer's groups and counts (`by_answerer` at the top).
+ */
+function answererLabelsOf(
+  dump: JsonObject,
+  ctx: Ctx,
+  day: string,
+  all: readonly string[],
+) {
+  const onPage = Object.entries(ctx.key.ids).filter(([, m]) => m.on_page);
+  const docFor = (who: string, nid: string) =>
+    answerOf(docOf(dump["answers"], `${who}${SEP}${nid}`), ctx);
+  const items = onPage.map(([nid, meta]) => ({
+    id: nid,
+    source_id: meta.source_id,
+    group: meta.group,
+    answerers: shownTo(all, meta),
+    by_answerer: R.fromKeys(shownTo(all, meta), (who) => docFor(who, nid)),
+  }));
+  return {
+    study: ctx.key.study,
+    exported: day,
+    questions: ctx.key.questions,
+    answerers: all,
+    items,
+    by_answerer: R.fromKeys(all, (who) =>
+      tallyOf({ who, all }, onPage, dump, ctx),
+    ),
   };
 }
+/** One answerer's groups and counts, over the items shown to them. */
+function tallyOf(
+  { who, all }: { readonly who: string; readonly all: readonly string[] },
+  onPage: readonly (readonly [string, KeyEntry])[],
+  dump: JsonObject,
+  ctx: Ctx,
+): Tally {
+  const mine = onPage.filter(([, m]) => shownTo(all, m).includes(who));
+  return tally(
+    mine.map(([nid]) =>
+      answerOf(docOf(dump["answers"], `${who}${SEP}${nid}`), ctx),
+    ),
+    groupsFor(mine, dump, ctx, `${who}${SEP}`),
+  );
+}
+/** Each answerer's items and groups, named `<answerer>~<id>` in the report, as in the store. */
+function reportAnswerers(
+  out: ReturnType<typeof answererLabelsOf>,
+  allowed: Allowed,
+): void {
+  R.forEachObj(out.by_answerer, (t, who) => {
+    reportLabels(
+      out.items.flatMap((i) => {
+        const a = i.by_answerer[who];
+        return a === undefined ? [] : [{ id: `${who}${SEP}${i.id}`, ...a }];
+      }),
+      allowed,
+    );
+    reportGroups(
+      R.mapKeys(t.groups, (g) => `${who}${SEP}${g}`),
+      allowed,
+    );
+  });
+}
+const completeLine = (t: Tally): string =>
+  `${String(t.complete_items)} of ${String(t.total_items)} items complete`;
 export function exportLabels(
   dumpPath: string,
   keyPath: string,
@@ -1500,14 +1958,34 @@ export function exportLabels(
   assertAllowed(allowed, key, keyPath);
   checkDump(dump, key);
   checkNoFamiliarity(dump, allowed);
-  const out = labelsOf(dump, { key, allowed }, day);
+  const ctx = { key, allowed };
+  const all = key.answerers;
+  const out =
+    all === undefined
+      ? labelsOf(dump, ctx, day)
+      : answererLabelsOf(dump, ctx, day, all);
   mkdirSync(outDir, { recursive: true });
   const path = join(outDir, `${key.study}-labels-${day}.json`);
   writeJson(path, out);
   exportPractice(dump, key, outDir, day);
-  say(
-    `wrote ${path}: ${String(out.complete_items)} of ${String(out.total_items)} items complete`,
-  );
-  reportLabels(out.items, allowed);
-  reportGroups(out.groups, allowed);
+  reportExport(path, out, allowed);
+}
+/** What the export wrote, and every item and group it did not count. */
+function reportExport(
+  path: string,
+  out: ReturnType<typeof labelsOf> | ReturnType<typeof answererLabelsOf>,
+  allowed: Allowed,
+): void {
+  if ("by_answerer" in out) {
+    say(
+      `wrote ${path}: ${R.entries(out.by_answerer)
+        .map(([who, t]) => `${who}: ${completeLine(t)}`)
+        .join("; ")}`,
+    );
+    reportAnswerers(out, allowed);
+  } else {
+    say(`wrote ${path}: ${completeLine(out)}`);
+    reportLabels(out.items, allowed);
+    reportGroups(out.groups, allowed);
+  }
 }