paperlint 14.0.0 → 14.2.0

package/skills/build-label-page/scripts/page-template.html

@@ -82,6 +82,29 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
   background: var(--good); margin-right: 8px; vertical-align: middle; }
 .status.missing { color: var(--mark); }
 .status.failed { color: var(--bad); }
+/* The content blocks (#380): a code excerpt with its line numbers and the marked line lit, references,
+   lists and tables folded away. A long text shows three lines and a «more». */
+a { color: var(--accent); }
+summary { cursor: pointer; color: var(--accent); min-height: 44px; display: flex; align-items: center; gap: 8px; }
+.situation { color: var(--strong); font-weight: 500; }
+pre.numbered { white-space: normal; padding: 8px 0; }
+pre.numbered .line { display: grid; grid-template-columns: 2ch 5ch 1fr; white-space: pre-wrap; padding: 0 10px 0 0; }
+/* The marked line reads as marked without its colour: a marker in the gutter and a label after the code. */
+pre.numbered .g { color: var(--mark); text-align: center; user-select: none; }
+pre.numbered .this { color: var(--mark); font-weight: 700; margin-left: 1ch; white-space: nowrap; user-select: none; }
+pre.numbered .n { color: var(--muted); text-align: right; padding-right: 1.5ch; user-select: none; }
+pre.numbered .hit { background: var(--mark-bg); }
+pre.numbered .hit .n { color: var(--mark); font-weight: 700; }
+.rulebox { display: flex; flex-direction: column; gap: 8px; }
+.clamped { display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+/* The clamp cuts at the padding box, so a code block's bottom padding is a border: no fourth line peeks in. */
+pre.clamped { padding-bottom: 0; border-bottom: 10px solid var(--surface); box-shadow: 0 1px 0 var(--line); }
+button.more { width: auto; min-height: 44px; border: 0; color: var(--accent); padding: 0 4px; align-self: flex-start; }
+.setting { display: flex; flex-direction: column; gap: 2px; padding-top: 12px; border-top: 1px solid var(--line); }
+.match.yes { color: var(--good); }
+.match.no { color: var(--bad); }
+.who { display: flex; align-items: center; justify-content: space-between; gap: 12px; color: var(--muted); }
+.who button { width: auto; min-height: 44px; border: 0; color: var(--accent); padding: 0 4px; }
 </style>
 <main id="app"><p class="muted">Loading…</p></main>
 <script type="application/json" id="data">__DATA__</script>
@@ -100,24 +123,160 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     whyTimers: {},    // "<item id>|<question id>" -> the pending save of a reason being typed
     whyBoxes: {},     // "<item id>|<question id>" -> the reason box of the last render
     typingIn: null,   // the item whose reason box has the keyboard: shown even when complete
+    lastAnswered: null, // the item answered last: shown under "Next unanswered" until the next answer
+    pending: {},      // item id -> answers chosen whose reason is still empty: NOT in the store
+    refusedWhy: {},   // item id -> true when an empty reason was refused for its answer
     mine: {},         // item/group key -> the answers this page has just written (ahead of the store)
     inflight: {},     // item/group key -> writes not yet confirmed
     failed: {},       // item/group key -> error code of the last refused write
     loaded: { answers: false, groups: false, practice: false },
     store: "loading", // loading | ok | none
-    filter: "all"
+    filter: "all",
+    who: null,        // the answerer picked, on a page with DATA.answerers; null until one is
+    raw: { answers: {}, groups: {}, practice: {} }, // every document of the store, every answerer's
+    dwell: {},        // item id -> ms its card was on screen, clocks stopped (DATA.min_seconds)
+    seenSince: {},    // item id -> when its card came on screen, while it is
+    firstSeconds: {}, // item id -> the seconds this page stored with the item's first save
+    gates: {}         // item id -> the locked buttons and the countdown of the last render
   };
   var db = null;
   var chains = {};
   var WHY_PAUSE_MS = 800;
 
   try { if (localStorage.getItem("label-filter") === "next") state.filter = "next"; } catch (e) {}
+  // ── who is answering (DATA.answerers): each answerer's documents are "<answerer>~<id>" ─────
+  // "~" is outside the build's name pattern, so no answerer, item, group or practice id holds it.
+  var SEP = "~";
+  var ANSWERERS = DATA.answerers || [];
+  var ASKS_WHO = ANSWERERS.length > 0;
+  try {
+    var remembered = localStorage.getItem("label-answerer");
+    if (ANSWERERS.indexOf(remembered) !== -1) state.who = remembered;
+  } catch (e) {}
+  // The store's id of one of this page's documents: as before on a page without answerers.
+  function docName(id) { return ASKS_WHO ? state.who + SEP + id : id; }
+  // The documents of the current answerer, by their names without the answerer.
+  function mineOf(docs) {
+    if (!ASKS_WHO) return docs;
+    var out = {}, prefix = state.who + SEP;
+    if (state.who) Object.keys(docs).forEach(function (k) { if (k.indexOf(prefix) === 0) out[k.slice(prefix.length)] = docs[k]; });
+    return out;
+  }
+  // The items shown to the current answerer: an item's own `answerers`, else everyone's.
+  function itemsShown() {
+    return DATA.items.filter(function (i) { return !i.answerers || i.answerers.indexOf(state.who) !== -1; });
+  }
+  function groupsShown() { return DATA.groups.filter(function (g) { return groupItems(g.id).length > 0; }); }
+  function busy() {
+    return Object.keys(state.inflight).some(function (k) { return state.inflight[k] > 0; }) || Object.keys(state.whyTimers).length > 0;
+  }
+  // Picking (or switching) the answerer: everything this page holds of the last one is dropped.
+  function choose(name) {
+    if (busy()) return;
+    Object.keys(state.seenSince).forEach(stopClock);
+    state.who = name;
+    try {
+      if (name) localStorage.setItem("label-answerer", name);
+      else localStorage.removeItem("label-answerer");
+    } catch (e) {}
+    ["editing", "mineWhy", "draftWhy", "pending", "refusedWhy", "mine", "failed", "dwell", "seenSince", "firstSeconds"]
+      .forEach(function (k) { state[k] = {}; });
+    state.lastAnswered = null;
+    ["answers", "groups", "practice"].forEach(function (c) { state[c] = mineOf(state.raw[c]); });
+    render();
+  }
+  // ── how long a card was on screen (DATA.min_seconds): its answer saves only after that long ──
+  // On screen: half the card in view, or half the viewport filled by a card taller than it.
+  var MIN_SECONDS = DATA.min_seconds || 0;
+  function dwellMs(id) {
+    var ms = state.dwell[id] || 0;
+    return state.seenSince[id] !== undefined ? ms + Date.now() - state.seenSince[id] : ms;
+  }
+  function stopClock(id) {
+    if (state.seenSince[id] === undefined) return;
+    state.dwell[id] = dwellMs(id);
+    delete state.seenSince[id];
+  }
+  function startClock(id) { if (state.seenSince[id] === undefined) state.seenSince[id] = Date.now(); }
+  // An item already saved (by this page or in the store) is never locked again.
+  function unsaved(id) { return !state.answers[id] && state.firstSeconds[id] === undefined; }
+  function locked(id) { return MIN_SECONDS > 0 && unsaved(id) && dwellMs(id) < MIN_SECONDS * 1000; }
+  function waitText(id) {
+    return "\u23f3 You can answer in " + Math.ceil((MIN_SECONDS * 1000 - dwellMs(id)) / 1000) + " s";
+  }
+  // The seconds stored with an item: those of its first save, kept on every later write.
+  function secondsOf(id) {
+    var d = state.answers[id];
+    if (d && typeof d.seconds === "number") return d.seconds;
+    if (state.firstSeconds[id] === undefined) state.firstSeconds[id] = Math.floor(dwellMs(id) / 1000);
+    return state.firstSeconds[id];
+  }
+  // An observer reports only when a card crosses one of its thresholds, so each card gets its own
+  // observer whose threshold is that card's share: half the card, or half the viewport for a card
+  // taller than it. The share follows the card's height and the viewport's: a card that changes
+  // size, or a resized window, is watched again with its new share.
+  var observers = [];
+  var sizes = null;
+  function share(h) { return h > 0 ? Math.min(h, window.innerHeight) / 2 / h : 0.5; }
+  function onScreen(entry) {
+    var h = entry.boundingClientRect.height;
+    return entry.isIntersecting && h > 0 &&
+      entry.intersectionRect.height >= Math.min(h, window.innerHeight) / 2 - 0.5;
+  }
+  function watchCard(card) {
+    var id = card.getAttribute("data-id");
+    var o = new IntersectionObserver(function (entries) {
+      entries.forEach(function (e) {
+        if (onScreen(e) && document.visibilityState !== "hidden") startClock(id);
+        else stopClock(id);
+      });
+    }, { threshold: [0, share(card.getBoundingClientRect().height)] });
+    o.observe(card);
+    return o;
+  }
+  // Every render draws new cards: the clocks stop, and the new cards are watched from scratch.
+  function watchCards() {
+    observers.forEach(function (o) { o.disconnect(); });
+    observers = [];
+    if (sizes) sizes.disconnect();
+    sizes = null;
+    var cards = Array.prototype.slice.call(document.querySelectorAll("article.item[data-id]"));
+    if (typeof IntersectionObserver !== "function") {
+      // No way to tell what is in view: a card counts as on screen from the moment it is drawn.
+      cards.forEach(function (c) { startClock(c.getAttribute("data-id")); });
+      return;
+    }
+    observers = cards.map(watchCard);
+    if (typeof ResizeObserver !== "function") return;
+    var heights = cards.map(function (c) { return c.getBoundingClientRect().height; });
+    sizes = new ResizeObserver(function (entries) {
+      entries.forEach(function (e) {
+        var i = cards.indexOf(e.target);
+        var h = e.target.getBoundingClientRect().height;
+        if (i === -1 || Math.abs(h - heights[i]) < 1) return;
+        heights[i] = h;
+        observers[i].disconnect();
+        observers[i] = watchCard(cards[i]);
+      });
+    });
+    cards.forEach(function (c) { sizes.observe(c); });
+  }
+  // The countdown on each locked card, and its buttons let go when its time is up; no render, so
+  // a section the labeller opened stays open.
+  function tick() {
+    Object.keys(state.gates).forEach(function (id) {
+      var g = state.gates[id];
+      if (locked(id)) { g.note.textContent = waitText(id); return; }
+      g.note.textContent = "";
+      g.buttons.forEach(function (b) { b.disabled = !canWrite(); });
+      delete state.gates[id];
+    });
+    setTimeout(tick, 250);
+  }
 
   // ── what "done" means ────────────────────────────────────────────────────────────────────
   function answersOf(id) {
-    if (state.mine[id]) return state.mine[id];
-    var d = state.answers[id];
-    return d && d.answers ? d.answers : {};
+    return state.pending[id] || savedOf(id);
   }
   // A stored value is an answer only if the build offers it (DATA.allowed, the same lists the
   // export reads from key.json): after a rebuild that removed an option, or a typo merged from chat,
@@ -141,6 +300,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     return d[qid];
   }
   function needsWhy(q, v) { return (DATA.allowed.needs_why[q.id] || []).indexOf(v) !== -1; }
+  function questionOf(qid) { return DATA.questions.filter(function (q) { return q.id === qid; })[0]; }
   // What an item still needs: an answer, or the reason its answer asks for (named "<short> (why)").
   function missingFor(id) {
     var a = answersOf(id), r = reasonsOf(id);
@@ -161,7 +321,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     var d = state.mine["group:" + g] || state.groups[g];
     return d && valid(DATA.allowed.familiarity, d.familiarity) ? d.familiarity : undefined;
   }
-  function groupItems(g) { return DATA.items.filter(function (i) { return i.group === g; }); }
+  function groupItems(g) { return itemsShown().filter(function (i) { return i.group === g; }); }
   // ── the practice (rule 8): known answers, before the real items ──────────────────────────
   function practiceDoc(pid) { return "r" + DATA.practice.round + "-" + pid; }
   function practiceAnswers(pid) {
@@ -186,7 +346,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
   function write(key, coll, docId, body) {
     state.inflight[key] = (state.inflight[key] || 0) + 1;
     delete state.failed[key];
-    var step = function () { return db.collection(coll).doc(docId).set(body); };
+    var step = function () { return db.collection(coll).doc(docName(docId)).set(body); };
     var run = (chains[key] || Promise.resolve()).then(step, step);
     chains[key] = run.then(function () {
       state.inflight[key] -= 1;
@@ -200,27 +360,76 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     });
   }
   function canWrite() {
-    return db && state.loaded.answers && state.loaded.groups && state.loaded.practice && state.store === "ok";
+    return db && state.loaded.answers && state.loaded.groups && state.loaded.practice && state.store === "ok" &&
+      (!ASKS_WHO || state.who !== null);
+  }
+  // An answer that asks why is not written while its reason is empty (#380): it waits on the page, and
+  // the store keeps what it had, so an export never meets an answer without the reason it needs. Every
+  // write leaves out each such answer, not only the one just picked: on a page of several questions the
+  // next answer would otherwise carry the waiting one into the store without its reason.
+  // A waiting answer that replaces a saved one leaves the saved one in the write until its reason comes.
+  // A stored answer to a question this page no longer asks (removed or renamed between builds) is kept
+  // as it was and never checked: the page has no question to check it against.
+  function resolved(answers, reasons, saved) {
+    var out = {}, waiting = false;
+    Object.keys(answers).forEach(function (q) {
+      var asked = questionOf(q);
+      if (!(asked && needsWhy(asked, answers[q]) && !(reasons[q] || "").trim())) out[q] = answers[q];
+      else {
+        waiting = true;
+        if (Object.prototype.hasOwnProperty.call(saved, q)) out[q] = saved[q];
+      }
+    });
+    return { ready: out, waiting: waiting };
+  }
+  // What the store holds for an item, or what this page last wrote to it ahead of the store.
+  function savedOf(id) {
+    if (state.mine[id]) return state.mine[id];
+    var d = state.answers[id];
+    return d && d.answers ? d.answers : {};
+  }
+  function keep(id, next, reasons) {
+    var r = resolved(next, reasons, savedOf(id)), ready = r.ready;
+    if (r.waiting) state.pending[id] = next;
+    else delete state.pending[id];
+    delete state.refusedWhy[id];
+    state.mine[id] = ready;
+    var body = { answers: ready, reasons: reasons, savedAt: new Date().toISOString(), source: "page" };
+    if (MIN_SECONDS) body.seconds = secondsOf(id);
+    write(id, "answers", id, body);
+    render();
   }
   function answer(id, qid, value) {
-    if (!canWrite()) return;
+    if (!canWrite() || locked(id)) return;
     var next = Object.assign({}, answersOf(id));
     next[qid] = value;
-    state.mine[id] = next;
-    write(id, "answers", id, { answers: next, reasons: reasonsOf(id), savedAt: new Date().toISOString(), source: "page" });
-    render();
+    state.lastAnswered = id;
+    var draft = draftOf(id, qid);
+    var why = draft !== undefined ? draft : reasonsOf(id)[qid] || "";
+    if (needsWhy(questionOf(qid), value) && !why.trim()) {
+      state.pending[id] = next;
+      render();
+      return;
+    }
+    var reasons = Object.assign({}, reasonsOf(id));
+    if (why.trim()) reasons[qid] = why;
+    keep(id, next, reasons);
   }
-  // A reason saves when the labeller leaves the box (the text equivalent of a tap).
+  // A reason saves when the labeller leaves the box (the text equivalent of a tap); an empty one is refused.
   function setReason(id, qid, text) {
     clearTimeout(state.whyTimers[id + "|" + qid]);
     delete state.whyTimers[id + "|" + qid];
     if (!canWrite()) return;
+    var a = answersOf(id);
+    if (needsWhy(questionOf(qid), a[qid]) && !text.trim()) {
+      state.refusedWhy[id] = true;
+      render();
+      return;
+    }
     var why = Object.assign({}, reasonsOf(id));
     why[qid] = text;
     state.mineWhy[id] = why;
-    state.mine[id] = Object.assign({}, answersOf(id));
-    write(id, "answers", id, { answers: answersOf(id), reasons: why, savedAt: new Date().toISOString(), source: "page" });
-    render();
+    keep(id, Object.assign({}, a), why);
   }
   // The first answer to a practice question is the one scored: it cannot be changed afterwards.
   function answerPractice(pid, qid, value) {
@@ -257,8 +466,8 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     });
     return n;
   }
-  // `withExamples`: the practice shows each answer's example on its button; the real items keep the buttons
-  // short, the examples stay on the first screen.
+  // `withExamples`: the practice shows each answer's example on its button, after `labels.practice_example`;
+  // the real items keep the buttons short, the examples stay on the first screen.
   // A code block shows what a labeller would otherwise count by eye: leading and trailing whitespace as
   // faint marks (a space as a middle dot, a tab as an arrow) and each line's length in characters.
   function visible(ws) { return ws.replace(/ /g, "\u00b7").replace(/\t/g, "\u2192"); }
@@ -281,7 +490,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
       var b = el("button", "");
       if (o.icon) b.appendChild(el("span", "icon", o.icon));
       b.appendChild(el("span", "label", o.label));
-      if (withExamples && o.example) b.appendChild(rich("span", "ex", o.example));
+      if (withExamples && o.example) b.appendChild(rich("span", "ex", DATA.labels.practice_example + o.example));
       b.type = "button";
       b.setAttribute("aria-pressed", String(current === o.value));
       b.disabled = disabled;
@@ -296,7 +505,10 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
   }
   function statusLine(key, missing, savedAt) {
     var s = el("p", "status");
-    if (state.failed[key]) {
+    if (state.pending[key] || state.refusedWhy[key]) {
+      s.className = "status missing";
+      s.textContent = "Not saved yet: this answer needs a reason. Write it above, or pick another answer.";
+    } else if (state.failed[key]) {
       s.className = "status failed";
       s.textContent = "Not saved (" + state.failed[key] + "). Tap the answer again.";
     } else if (state.inflight[key]) {
@@ -312,15 +524,21 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     return s;
   }
   function itemCard(item, off) {
-    var done = itemDone(item.id);
     var card = el("article", "item");
-    card.appendChild(el("div", "id", item.id));
+    var shown = itemsShown();
+    if (MIN_SECONDS && unsaved(item.id)) card.setAttribute("data-id", item.id);
+    card.appendChild(el("div", "id", fill(DATA.labels.place, { id: item.id, n: shown.indexOf(item) + 1, total: shown.length })));
     evidence(card, item);
     var a = answersOf(item.id);
-    askOne(card, a, state.editing[item.id], function (q, v) {
+    var gate = locked(item.id);
+    var ask = askOne(card, a, state.editing[item.id], function (q, v) {
       delete state.editing[item.id];
       answer(item.id, q.id, v);
-    }, function (q) { state.editing[item.id] = q.id; render(); }, off);
+    }, function (q) { state.editing[item.id] = q.id; render(); }, off || gate, false, item.situation);
+    if (gate && ask) {
+      var note = ask.appendChild(el("p", "status missing", waitText(item.id)));
+      state.gates[item.id] = { note: note, buttons: Array.prototype.slice.call(ask.querySelectorAll("button")) };
+    }
     DATA.questions.forEach(function (q) {
       var o = q.options.filter(function (x) { return x.value === a[q.id] && x.ask_why; })[0];
       if (!o) return;
@@ -344,6 +562,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     });
     var saved = state.answers[item.id] && state.answers[item.id].savedAt;
     card.appendChild(statusLine(item.id, missingFor(item.id), saved));
+    blocksBelow(card, item);
     return card;
   }
   // A labelled row: a short word, then what it labels.
@@ -361,17 +580,136 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     p.appendChild(rich("span", "", u.text.slice(at + u.mark.length)));
     return p;
   }
+  // A situation's text with each `{line}` written out: «line N: » and the marked line's code as code
+  // (the build passes `line` whenever the text holds the token).
+  function situated(tag, cls, text, line) {
+    var n = el(tag, cls);
+    String(text).split("{line}").forEach(function (part, i) {
+      if (i) {
+        n.appendChild(el("span", "", "line " + line.n + ": "));
+        n.appendChild(el("code", "", line.text));
+      }
+      if (part) n.appendChild(rich("span", "", part));
+    });
+    return n;
+  }
+  // A long text shows its first three lines and a «more» that opens the rest.
+  function clamp(node, text) {
+    if (String(text).length < 200 && String(text).split("\n").length <= 3) return node;
+    var wrap = el("div", "rulebox");
+    node.className += " clamped";
+    var more = el("button", "more", "more");
+    more.type = "button";
+    more.addEventListener("click", function () {
+      node.className = node.className.replace(" clamped", "");
+      wrap.removeChild(more);
+    });
+    wrap.appendChild(node);
+    wrap.appendChild(more);
+    return wrap;
+  }
+  function link(text, url) {
+    var a = el("a", "", text);
+    a.href = url;
+    a.target = "_blank";
+    a.rel = "noopener";
+    return a;
+  }
+  function plainCode(text, cls) {
+    var pre = el("pre", cls || "");
+    pre.textContent = text;
+    return pre;
+  }
+  // `{name}` in a page label, from `vars`.
+  function fill(text, vars) {
+    return String(text).replace(/\{(\w+)\}/g, function (m, k) { return k in vars ? String(vars[k]) : m; });
+  }
+  // A code excerpt: its file (a link when there is one), its lines numbered, the marked line with a
+  // gutter marker and a label besides its background, and the caption under it.
+  function excerptBlock(ex) {
+    var box = el("div", "rulebox");
+    if (ex.file) {
+      var name = el("p");
+      name.appendChild(ex.url ? link(ex.file, ex.url) : el("code", "", ex.file));
+      box.appendChild(name);
+    }
+    var pre = el("pre", "numbered");
+    ex.lines.forEach(function (l) {
+      var line = el("div", "line" + (l.mark ? " hit" : ""));
+      line.appendChild(el("span", "g", l.mark ? "\u25b6" : ""));
+      line.appendChild(el("span", "n", String(l.n)));
+      var code = line.appendChild(el("span", "", l.text));
+      if (l.mark) code.appendChild(el("span", "this", ex.mark_label || "\u25c0 this line"));
+      pre.appendChild(line);
+    });
+    box.appendChild(pre);
+    if (ex.caption) box.appendChild(rich("p", "said", ex.caption));
+    return box;
+  }
+  // A reference entry: its title, then each field (a paragraph, a code block on a labelled row, or a
+  // quiet note), then its link.
+  function referenceBlock(r) {
+    var box = el("div", "rulebox");
+    box.appendChild(rich("p", "", r.title));
+    r.fields.forEach(function (f) {
+      if (f.style === "note") box.appendChild(el("p", "muted", f.text));
+      else if (f.style === "code") box.appendChild(row(f.label || "", clamp(plainCode(f.text), f.text)));
+      else box.appendChild(clamp(rich("p", "", (f.label ? f.label + ": " : "") + f.text), f.text));
+    });
+    if (r.url) box.appendChild(el("p")).appendChild(link(r.url_label || r.url, r.url));
+    return box;
+  }
+  function folded(summary) {
+    var d = el("details");
+    d.appendChild(el("summary", "", summary));
+    return d;
+  }
+  function references(x) {
+    var d = folded(x.summary);
+    x.entries.forEach(function (r) { d.appendChild(row(r.label || "", referenceBlock(r))); });
+    return d;
+  }
+  function moreList(m) {
+    var d = folded(m.summary);
+    var ul = el("ul");
+    m.items.forEach(function (f) { ul.appendChild(rich("li", "", f)); });
+    if (m.rest) ul.appendChild(el("li", "muted", m.rest));
+    d.appendChild(ul);
+    return d;
+  }
+  // A folded table: its note, then each row in the order given: label, value as code, plain words, mark.
+  function table(t) {
+    var d = folded(t.summary);
+    if (t.note) d.appendChild(el("p", "muted", t.note));
+    t.rows.forEach(function (r) {
+      var s = el("div", "setting");
+      s.appendChild(el("span", "lbl", r.label));
+      s.appendChild(el("p")).appendChild(el("code", "", r.value));
+      if (r.plain) s.appendChild(rich("p", "", r.plain));
+      if (r.mark) s.appendChild(el("p", "match " + r.mark.tone, r.mark.text));
+      d.appendChild(s);
+    });
+    return d;
+  }
+  // Below the question and its answers: the references, the list of more like it and the table, each
+  // folded, so the question sits right under the code it names.
+  function blocksBelow(card, item) {
+    if (item.references) card.appendChild(references(item.references));
+    if (item.more) card.appendChild(moreList(item.more));
+    if (item.table) card.appendChild(table(item.table));
+  }
   // What a card shows above its question, one labelled row per field (an item and a practice item alike).
   function evidence(card, item) {
     if (item.title) card.appendChild(rich("h3", "", item.title));
-    card.appendChild(rich("p", "body", item.body));
+    var body = rich("p", "body", item.body);
+    card.appendChild(DATA.labels.body ? row(DATA.labels.body, body) : body);
+    if (item.repeat && item.repeat.of > 1) card.appendChild(el("p", "muted", fill(DATA.labels.repeat, item.repeat)));
     if (item.code) card.appendChild(codeBlock(item.code));
-    if (item.unit) card.appendChild(row(item.unit.of > 1 ? "Line · part " + item.unit.part + " of " + item.unit.of : "Line",
+    if (item.unit) card.appendChild(row(item.unit.of > 1 ? fill(DATA.labels.line_part, { line: DATA.labels.line, part: item.unit.part, of: item.unit.of }) : DATA.labels.line,
       markedLine(item.unit)));
     // A rule the item names, with what it does in the linter's own words (looked up at build time).
     (item.rules || []).forEach(function (r) {
-      card.appendChild(row("Rule", rich("p", "", r.linter + " `" + r.id + "`" + (r.family ? " (" + r.family + ")" : "") +
-        ": " + r.description)));
+      card.appendChild(row("Rule", rich("p", "", r.linter + " `" + r.id + "`" + (r.family ? " (" + r.family + ")" : "") + ": " + r.description)));
     });
     if (item.readings) {
       card.appendChild(row("Reading A", rich("p", "", item.readings.a), "reading a"));
@@ -379,6 +717,8 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     }
     if (item.file) card.appendChild(row("File", rich("p", "", item.file)));
     if (item.context) card.appendChild(rich("p", "muted", item.context));
+    if (item.situation) card.appendChild(situated("p", "situation", item.situation.summary, item.situation.line));
+    if (item.excerpt) card.appendChild(excerptBlock(item.excerpt));
   }
   function labelOf(q, v) {
     var o = q.options.filter(function (x) { return x.value === v; })[0];
@@ -386,7 +726,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
   }
   // One question per screen: the answered ones stay as a line (with "Change"), and only one question
   // is asked: the one being changed, else the first unanswered.
-  function askOne(card, a, editing, onPick, onChange, off, withExamples) {
+  function askOne(card, a, editing, onPick, onChange, off, withExamples, situation) {
     var open = DATA.questions.filter(function (q) { return !valid(DATA.allowed.questions[q.id], a[q.id]); });
     var asked = DATA.questions.filter(function (q) { return q.id === editing; })[0] || open[0];
     DATA.questions.forEach(function (q) {
@@ -401,17 +741,25 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
       }
       card.appendChild(line);
     });
-    if (!asked) return;
+    if (!asked) return null;
     var ask = el("div", "ask");
-    ask.appendChild(el("p", "q", asked.text));
+    // A card's situation asks the page's first question in its own words; the others keep theirs.
+    ask.appendChild(situation && asked === DATA.questions[0] ? situated("p", "q", situation.question, situation.line) : rich("p", "q", asked.text));
     ask.appendChild(options(asked.options, a[asked.id], function (v) { onPick(asked, v); }, off, withExamples));
     card.appendChild(ask);
+    return ask;
   }
+  // Open until the practice is done; then folded into a toggle, so the cards start near the top.
   function howTo() {
     var sec = el("section");
-    sec.appendChild(el("h2", "", "📖 How to answer"));
+    var body = sec;
+    if (practiceOpen()) sec.appendChild(el("h2", "", "📖 How to answer"));
+    else {
+      body = sec.appendChild(el("details"));
+      body.appendChild(el("summary", "", "📖 How to answer"));
+    }
     DATA.questions.forEach(function (q) {
-      sec.appendChild(el("p", "q", q.text));
+      body.appendChild(el("p", "q", q.text));
       var list = el("div", "examples");
       q.options.forEach(function (o) {
         var row = el("div", "example");
@@ -419,7 +767,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
         row.appendChild(rich("span", "muted", "For example: " + o.example));
         list.appendChild(row);
       });
-      sec.appendChild(list);
+      body.appendChild(list);
     });
     return sec;
   }
@@ -428,13 +776,14 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     card.appendChild(el("div", "id", "Practice " + p.id));
     evidence(card, p);
     var a = practiceAnswers(p.id);
-    askOne(card, a, undefined, function (q, v) { answerPractice(p.id, q.id, v); }, null, off, true);
+    askOne(card, a, undefined, function (q, v) { answerPractice(p.id, q.id, v); }, null, off, true, p.situation);
     if (practiceAnswered(p)) {
       var expected = DATA.questions.map(function (q) { return labelOf(q, p.expected[q.id]); }).join(" · ");
       card.appendChild(rich("p", practiceMatched(p) ? "status saved" : "quote",
-        (practiceMatched(p) ? "Matched. " : "Expected: " + expected + ". ") + p.why));
+        (practiceMatched(p) ? "Matched. " : "Not matched. Expected: " + expected + ". ") + p.why));
     }
     card.appendChild(statusLine("practice:" + p.id, [], null));
+    blocksBelow(card, p);
     return card;
   }
   function practiceBlock(off) {
@@ -470,7 +819,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
       sec.appendChild(fam);
     }
     groupItems(g.id).forEach(function (i) {
-      if (onlyOpen && itemDone(i.id) && i.id !== state.typingIn) return;
+      if (onlyOpen && itemDone(i.id) && i.id !== state.typingIn && i.id !== state.lastAnswered) return;
       sec.appendChild(itemCard(i, off));
     });
     return sec;
@@ -505,14 +854,43 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     // Under "Next unanswered" the save that completes an item would hide it, box and all, mid-sentence:
     // the item being typed in stays on the page until the labeller leaves its box.
     state.typingIn = typing ? typing.key.slice(0, typing.key.indexOf("|")) : null;
+    Object.keys(state.seenSince).forEach(stopClock);
+    state.gates = {};
     paint();
+    if (MIN_SECONDS) watchCards();
     var again = typing && state.whyBoxes[typing.key];
     if (again) { again.focus(); again.setSelectionRange(typing.start, typing.end); }
   }
+  // The answerer's choice, before anything else of the page.
+  function whoBlock() {
+    var sec = el("section");
+    sec.appendChild(el("h2", "", "Who is answering?"));
+    sec.appendChild(el("p", "muted", "Each person answers under their own name and sees only their own answers."));
+    var row = el("div", "opts");
+    ANSWERERS.forEach(function (name) {
+      var b = el("button", "", name);
+      b.type = "button";
+      b.addEventListener("click", function () { choose(name); });
+      row.appendChild(b);
+    });
+    sec.appendChild(row);
+    return sec;
+  }
+  function whoLine() {
+    var line = el("p", "who");
+    line.appendChild(el("span", "", "Answering as " + state.who));
+    var b = el("button", "", "Switch");
+    b.type = "button";
+    b.disabled = busy();
+    b.addEventListener("click", function () { choose(null); });
+    line.appendChild(b);
+    return line;
+  }
   function paint() {
     var off = !canWrite();
-    var done = DATA.items.filter(function (i) { return itemDone(i.id); }).length;
-    var total = DATA.items.length;
+    var items = itemsShown(), groups = groupsShown();
+    var done = items.filter(function (i) { return itemDone(i.id); }).length;
+    var total = items.length;
     app.textContent = "";
     var top = el("header", "top");
     app.appendChild(top);
@@ -525,6 +903,8 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     } else if (state.store === "loading" || !(state.loaded.answers && state.loaded.groups)) {
       top.appendChild(el("p", "muted", "Loading saved answers…"));
     }
+    if (ASKS_WHO && !state.who) { app.appendChild(whoBlock()); return; }
+    if (ASKS_WHO) top.appendChild(whoLine());
     app.appendChild(howTo());
     app.appendChild(practiceBlock(off));
     // Without the store nothing can be answered, practice included: show the real items read-only (rule 7).
@@ -536,6 +916,12 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     fill.style.width = (total ? (100 * done / total) : 0) + "%";
     bar.appendChild(fill);
     progress.appendChild(bar);
+    // Done means every item AND every group's familiarity, as «Next unanswered» counts it.
+    var rated = groups.every(function (g) { return familiarity(g.id) !== undefined; });
+    if (total && done === total && rated && state.filter === "all") {
+      progress.appendChild(el("p", "status saved", "All " + total + " items are complete. Tell the agent you are " +
+        "done; you can still change any answer."));
+    }
 
     var filters = el("div", "tabs");
     [["all", "All items"], ["next", "Next unanswered"]].forEach(function (f) {
@@ -553,8 +939,8 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
 
     var onlyOpen = state.filter === "next";
     if (onlyOpen) {
-      var rest = DATA.items.filter(function (i) { return !itemDone(i.id); });
-      var open = DATA.groups.filter(function (g) { return familiarity(g.id) === undefined; });
+      var rest = items.filter(function (i) { return !itemDone(i.id); });
+      var open = groups.filter(function (g) { return familiarity(g.id) === undefined; });
       var note = el("div", "muted");
       if (!rest.length && !open.length) {
         note.appendChild(el("p", "", "Nothing left. Every item and every group is answered."));
@@ -570,8 +956,8 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
       }
       progress.appendChild(note);
     }
-    DATA.groups.forEach(function (g) {
-      var typingHere = groupItems(g.id).some(function (i) { return i.id === state.typingIn; });
+    groups.forEach(function (g) {
+      var typingHere = groupItems(g.id).some(function (i) { return i.id === state.typingIn || i.id === state.lastAnswered; });
       if (onlyOpen && groupDone(g.id) && !typingHere) return;
       app.appendChild(groupBlock(g, off, onlyOpen));
     });
@@ -582,16 +968,24 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     return function (snap) {
       var next = {};
       snap.docs.forEach(function (d) { next[d.id] = d.data(); });
-      state[target] = next;
+      state.raw[target] = next;
+      state[target] = mineOf(next);
       state.loaded[loadedKey] = true;
       render();
     };
   }
   function broken() { state.store = "none"; render(); }
 
+  // Hidden: every clock stops. Back: the cards are watched afresh, because a change of tab alone
+  // fires no intersection, and a card drawn while the tab was hidden never started its clock.
   document.addEventListener("visibilitychange", function () {
-    if (document.visibilityState !== "visible") flushReasons();
+    if (document.visibilityState !== "visible") {
+      flushReasons();
+      Object.keys(state.seenSince).forEach(stopClock);
+    } else if (MIN_SECONDS) watchCards();
   });
+  window.addEventListener("resize", function () { if (MIN_SECONDS) watchCards(); });
+  if (MIN_SECONDS) tick();
   window.addEventListener("pagehide", flushReasons);
   render();
   if (!window.claude || typeof window.claude.use !== "function") { broken(); return; }