paperlint 14.0.0 → 14.2.0

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

@@ -7,8 +7,10 @@
 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, } from "./rule-descriptions.js";
+import { applyPreset } from "./label-page-presets.js";
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
     exitCode;
@@ -74,6 +76,11 @@ const writeJson = (path, value) => {
     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) => {
+    const r = applyPreset(raw);
+    return r.ok ? JSON_VALUE.parse(r.value) : fail(r.message);
+};
 const readJson = (path) => {
     try {
         return JSON_VALUE.parse(JSON.parse(readFileSync(path, "utf8")));
@@ -91,6 +98,9 @@ const readJson = (path) => {
 // prettier-ignore
 const PAGE_FIELDS = ["group", "title", "body", "code", "context", "file"];
 const PRIVATE_FIELDS = ["source_id"];
+// 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";
@@ -99,11 +109,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",
+];
 const ALLOWED_FIELDS = [
     ...PAGE_FIELDS,
     RULES_FIELD,
     UNIT_FIELD,
     READINGS_FIELD,
+    ...BLOCK_FIELDS,
+    ANSWERERS_FIELD,
     ...PRIVATE_FIELDS,
 ];
 const FAMILIARITY = [
@@ -130,6 +152,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(", ")})`;
 const string = (required = true, pattern, why) => pattern === undefined
@@ -140,6 +167,8 @@ const string = (required = true, pattern, why) => pattern === undefined
         pattern,
         ...(why === undefined ? {} : { why }),
     };
+/** A string that may be empty: a blank line of code. */
+const text = () => ({ kind: "text", required: true });
 const integer = (required = true) => ({
     kind: "integer",
     required,
@@ -164,6 +193,13 @@ const mapping = (values, keyPattern, min = 0) => ({
 const obj = (fields, closed = true, required = true) => ({ kind: "object", required, closed, fields });
 // 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) => obj(fields, true, false);
+const TEXT_FIELD = obj({
+    label: string(false),
+    text: string(),
+    style: string(false, "code|note", "code or note"),
+});
 const CARD_FIELDS = {
     [RULES_FIELD]: array(obj({
         linter: string(true, "eslint|ruff", "eslint or ruff"),
@@ -180,6 +216,43 @@ const CARD_FIELDS = {
     }, true, false),
     [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() }),
 };
 const KINDS = {
     // keep or drop a drawn requirement: the line it came from, marked, and the rule read for it
@@ -212,6 +285,7 @@ const itemSchema = (kind) => obj({
         string(f === "group" || f === "body"),
     ])),
     ...cardFields(kind),
+    [ANSWERERS_FIELD]: array(string(true, NAME_PATTERN), false, 1),
 }, false);
 // `icon` (an emoji) tells the buttons apart at a glance. No coloured side stripe on a button: it
 // reads as decoration, not meaning (the build-label-page look test refuses one).
@@ -247,6 +321,10 @@ const configSchema = (kind) => obj({
     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),
@@ -254,6 +332,15 @@ const configSchema = (kind) => obj({
     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. */
@@ -310,6 +397,14 @@ function checkBoolean(value, where) {
     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, kind, where) {
+    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, node, path) {
     const where = path || "items.json";
@@ -317,10 +412,9 @@ function checkValue(value, node, path) {
         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);
@@ -416,8 +510,35 @@ function checkPractice(cfg) {
             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, where) {
+    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) {
+    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) {
     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`);
     }
@@ -469,6 +590,33 @@ function checkUnits(cfg) {
         });
     }
 }
+/**
+ * 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"];
+/** The line `{line}` stands for: the first marked line, its number and its code without the indent. */
+const lineOf = (card) => card.excerpt?.lines
+    .filter((l) => l.mark)
+    .map((l) => ({ n: l.n, text: l.text.trim() }))[0];
+const usesLine = (card) => 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) {
+    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) => [
     ...cfg.items.map((i, n) => [`items[${String(n)}]`, i]),
@@ -490,12 +638,22 @@ function checkItemFields(cfg) {
             fail(`items[${String(n)}].group: ${repr(item.group)} is not in \`groups\``);
     });
 }
-/** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
-const visibleTexts = (item) => [
-    ...PAGE_FIELDS.map((f) => [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) => 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) => Object.entries({
+    ...shownFields(item),
+    [RULES_FIELD]: item.rules ?? [],
+}).flatMap(([f, v]) => stringsIn(v).map((t) => [f, t]));
 const escapeRegExp = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
  * A source id typed into a visible field gives the source away as well as a field would. Short ids
@@ -549,6 +707,17 @@ function assignIds(items, seed, keyPath) {
     ]);
     return { ids, entries };
 }
+// ── a build, short of the page ──────────────────────────────────────────────────────────────────
+/** A card's situation as the page shows it, with the line `{line}` stands for. */
+const situationShown = (item) => item.situation === undefined
+    ? {}
+    : {
+        situation: {
+            summary: item.situation.summary,
+            question: item.situation.question,
+            ...(usesLine(item) ? { line: lineOf(item) } : {}),
+        },
+    };
 const shownFields = (item) => ({
     ...Object.fromEntries(PAGE_FIELDS.flatMap((f) => {
         const v = item[f];
@@ -565,15 +734,20 @@ const shownFields = (item) => ({
             },
         }),
     ...(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 } }),
 });
 const ruleKey = (r) => `${r.linter} ${r.id}`;
 /** Ask the linter for every rule named; refuse, by path, a rule it cannot describe. */
 function describeRules(cfg, fromDir) {
-    return new Map(cardsOf(cfg).flatMap(([at, card]) => (card.rules ?? []).map((r, k) => {
+    return new Map(cardsOf(cfg).flatMap(([at, card]) => (card.rules ?? []).flatMap((r, k) => {
         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];
+            : [[ruleKey(r), text]];
     })));
 }
 const rulesShown = (card, described) => card.rules === undefined
@@ -606,30 +780,45 @@ const practiceShown = (cfg, described) => practiceOf(cfg).map((p) => ({
     ...shownFields(p),
     ...rulesShown(p, described),
 }));
+/** The page's own words where `labels` leaves one out (references/closed-choice-generator.md). */
+const DEFAULT_LABELS = {
+    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) => 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, page, described) {
     const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
     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, id, described) => ({
+    id,
+    ...shownFields(i),
+    ...rulesShown(i, described),
+    ...R.pickBy({ answerers: i.answerers }, R.isDefined),
+});
 /** Every id the key keeps (on the page now, or kept from an earlier build), with its source and group. */
 function idsOf(cfg, page) {
     const shown = new Set(page.items.map(page.idOf));
@@ -640,15 +829,14 @@ function idsOf(cfg, page) {
         ]),
         ...cfg.items.map((i) => [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),
+    }));
 }
 /** Every round of a key's practice; a key from before `rounds` has only its own round. */
 const roundsIn = (p) => p.rounds ?? { [String(p.round)]: p.expected };
@@ -665,6 +853,7 @@ function keyOf(cfg, page, earlier) {
     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.
@@ -689,13 +878,14 @@ function keyOf(cfg, page, earlier) {
  * returns what the page shows. A page written by hand can take its blindness and its key from here.
  */
 export function prepareBuild(configPath, outDir) {
-    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 });
@@ -713,6 +903,10 @@ function assertKey(_value) {
     // key.json is this script's own output; what an older build left out is checked where it is read.
 }
 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.min_seconds === undefined
+    ? ANSWER_DOC_FIELDS
+    : ["answers", "reasons", "savedAt", "seconds", "source"];
 const GROUP_DOC_FIELDS = ["familiarity", "savedAt", "source"];
 const DOC_FIELD_TYPES = [
     ["answers", isObject, "an object {question: value}"],
@@ -727,6 +921,11 @@ const DOC_FIELD_TYPES = [
         (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"];
 const COLLECTION_NAMES = COLLECTIONS;
@@ -746,15 +945,18 @@ const practiceDocs = (key) => {
     // Each round's own questions: a later round may have dropped or renamed one.
     return Object.entries(roundsIn(p)).flatMap(([r, expected]) => Object.entries(expected).map(([pid, answers]) => [`r${r}-${pid}`, Object.keys(answers)]));
 };
-function knownNames(key) {
-    const entries = Object.entries(key.ids);
+/** Who an item is shown to: its own list, else every answerer of the page. */
+const shownTo = (all, meta) => meta.answerers ?? all;
+/** The names of a page without answerers, or those of one answerer's documents. */
+function knownNames(key, whose) {
+    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]),
             onPage: shown.map(([nid]) => nid),
-            fields: ANSWER_DOC_FIELDS,
+            fields: answerDocFields(key),
         },
         groups: {
             known: entries.map(([, m]) => [m.group, key.questions]),
@@ -764,7 +966,7 @@ function knownNames(key) {
         practice: {
             known: practice,
             onPage: practice.map(([n]) => n),
-            fields: ANSWER_DOC_FIELDS,
+            fields: answerDocFields(key),
         },
     };
 }
@@ -783,10 +985,28 @@ function checkDumpShape(dump) {
     if (stray !== undefined)
         fail(`${stray}: the store has no such collection (expected ${COLLECTIONS.join(", ")})`);
 }
-function checkDocName(where, name, kind, names) {
+/**
+ * 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, docId, key) {
+    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, { who, name }, kind, names) {
     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(", ")})`);
+        return fail(`${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)) {
         fail(`${where}: stored, but no longer on the page (a rebuild left it out), so the export would drop it; rebuild with it on the page, or take it out of the dump on purpose`);
@@ -841,13 +1061,16 @@ function checkDocAnswers(where, doc, questions) {
  */
 function checkDump(dump, key) {
     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(isObject(collection) ? collection : {})) {
-            const where = `${kind}/${name}`;
-            const questions = checkDocName(where, name, kind, names[kind]);
-            checkDocFields(where, doc, kind, names[kind].fields);
+        for (const [docId, doc] of sortedEntries(isObject(collection) ? collection : {})) {
+            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);
         }
     }
@@ -900,8 +1123,8 @@ function answersOf(doc, ctx) {
     const given = Object.fromEntries(raw.map(([q, v]) => [q, has(invalid, q) ? null : v]));
     return { given, invalid };
 }
-/** One item of the labels file: its answers, what is invalid, the reasons, and whether it is done. */
-function labelOf(nid, meta, doc, ctx) {
+/** One stored answer: its answers, what is invalid, the reasons, and whether it is done. */
+function answerOf(doc, ctx) {
     const { given, invalid } = answersOf(doc, ctx);
     const reasons = Object.fromEntries(Object.entries(textsOf(doc["reasons"])).filter(([, r]) => r.trim()));
     const needsWhy = ctx.allowed.needs_why ?? {};
@@ -909,9 +1132,6 @@ function labelOf(nid, meta, doc, ctx) {
         .filter(([q, v]) => v !== null && listed(needsWhy, q, v) && !has(reasons, q))
         .map(([q]) => q);
     return {
-        id: nid,
-        source_id: meta.source_id,
-        group: meta.group,
         answers: given,
         invalid_answers: invalid,
         reasons,
@@ -919,12 +1139,23 @@ function labelOf(nid, meta, doc, ctx) {
         complete: 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)),
     };
 }
+/** The `seconds` field, on a page built with `min_seconds`; none on any other. */
+const secondsOf = (key) => key.min_seconds === undefined ? [] : ["seconds"];
+/** One item of the labels file of a page without answerers. */
+const labelOf = (nid, meta, doc, 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, groups, allowed) {
+function groupsOf(groupIds, groups, 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 [
@@ -962,9 +1193,9 @@ function reportGroups(groups, allowed) {
     }
 }
 /** Each practice item of the key's round: what was answered first, what was expected, whether they match. */
-function scorePractice(dump, round, all) {
+function scorePractice(dump, round, all, prefix) {
     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);
         return {
@@ -976,8 +1207,8 @@ function scorePractice(dump, round, all) {
         };
     });
 }
-/** One file per round: a second round exported the same day keeps the first. */
-const practiceFile = (study, round, day) => `${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, round, day, who) => `${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.
@@ -986,56 +1217,99 @@ function exportPractice(dump, key, target, day) {
     const p = key.practice;
     if (p === undefined)
         return;
-    Object.entries(roundsIn(p))
-        .sort(([a], [b]) => Number(a) - Number(b))
-        .forEach(([round, expected]) => {
-        exportRound(key.study, Number(round), scorePractice(dump, round, expected), {
-            target,
-            day,
-            current: Number(round) === p.round,
+    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, who === undefined ? "" : `${who}${SEP}`), { target, day, current: Number(round) === p.round, who });
         });
     });
 }
 /** One round's scored practice to `<study>-practice-r<round>-<date>.json`, and one line about it. */
 function exportRound(study, round, items, at) {
+    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`);
+            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}`);
+    say(`${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, groups) => ({
+    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,
+});
+/** The familiarity of the groups of `onPage`, or none on a page that asks none. */
+const groupsFor = (onPage, dump, 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, ctx, day) {
     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, ctx, day, all) {
+    const onPage = Object.entries(ctx.key.ids).filter(([, m]) => m.on_page);
+    const docFor = (who, nid) => 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 }, onPage, dump, ctx) {
+    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, allowed) {
+    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) => `${String(t.complete_items)} of ${String(t.total_items)} items complete`;
 export function exportLabels(dumpPath, keyPath, outDir, day) {
     const dump = readJson(dumpPath);
     const key = readJson(keyPath);
@@ -1044,12 +1318,28 @@ export function exportLabels(dumpPath, keyPath, outDir, day) {
     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, out, allowed) {
+    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);
+    }
 }