visualproof 0.0.0-stage → 0.2.0

package/dist/shared/doc/order.js

@@ -0,0 +1,124 @@
+// The exported document's order (the owner's decisions of 2026-10-12): the board is the outline of
+// the document. Within a section, everything the board draws in that cluster — its sub-clusters by
+// their circle's centre, its declarations by their point, its notes by their icon — comes in the
+// order of its height on the view's board, the lowest first, ties left to right; the top-level
+// sections are ordered so too, and so is what the document starts with, under no heading: the
+// declarations in no cluster and the notes on the ring or on the canvas outside every cluster. Since
+// the layout puts what is used more lower down (CanvasSpec, "Dependency order"), the default reads
+// foundations first; a reader reorders the document by dragging things on the board. Nothing here
+// reads what depends on what.
+//
+// Where each thing is drawn is the board's (server/boardspots.ts reads it as the page draws it: the
+// view's layout memory, its pins and its hidden levels); this file only orders what it is told, so
+// that the same positions always give the same document. A note attached to a declaration the
+// document prints goes right after it, as its explanation; a note in a cluster goes to the section
+// of the nearest cluster around it that the document prints; any other note, to the start.
+import { boardLayout, subgraph } from "../board.js";
+/** A height on the board, read to a tenth of a unit, which the layout rounds its places to: two
+ *  things on one row of a cluster's lattice are level, and go left to right. */
+const tenth = (v) => Math.round(v * 10);
+/** The board's order of things at `at` (null where the board does not say: last, as given): the
+ *  lowest first, ties left to right, then as given. */
+export function boardOrder(xs, at) {
+    const keyed = xs.map((x, k) => ({ x, k, p: at(x) }));
+    keyed.sort((a, b) => {
+        if (!a.p || !b.p)
+            return a.p ? -1 : b.p ? 1 : a.k - b.k;
+        return tenth(b.p[1]) - tenth(a.p[1]) || tenth(a.p[0]) - tenth(b.p[0]) || a.k - b.k;
+    });
+    return keyed.map((e) => e.x);
+}
+/** Where `a` goes on the board to come between `prev` and `next` in the board's order (`prev` read
+ *  before it, so lower; `next` after, higher), all three of one cluster: the linear form's drop
+ *  (ExportSpec decision 18, web/src/linear.ts). At a height between theirs where they are across,
+ *  where `a` is across; on their row, between them, where they are level; below the first, above
+ *  the last, clear of it. Null where neither is given. */
+export function spotBetween(a, prev, next) {
+    if (prev && next) {
+        if (Math.abs(prev.y - next.y) >= 1)
+            return [a.x, (prev.y + next.y) / 2];
+        return [(prev.x + next.x) / 2, prev.y];
+    }
+    if (next)
+        return [a.x, next.y + next.r + a.r + 2.5];
+    if (prev)
+        return [a.x, prev.y - prev.r - a.r - 2.5];
+    return null;
+}
+/** The outline of the document of `plan` (of graph `g`) in the order of the board `spots` describes. */
+export function orderDoc(plan, g, spots) {
+    // the declarations the document prints, by name: where an attached note goes
+    const printed = new Map();
+    const sectionOf = new Map();
+    const walk = (s) => {
+        for (const k of s.keys)
+            sectionOf.set(k, s);
+        for (const i of s.decls)
+            printed.set(g.nodes[i].name, i);
+        s.sections.forEach(walk);
+    };
+    plan.sections.forEach(walk);
+    for (const i of plan.decls)
+        printed.set(g.nodes[i].name, i);
+    const attached = new Map();
+    const inSection = new Map();
+    const atStart = [];
+    spots.notes.forEach((n, k) => {
+        const on = n.on !== undefined ? printed.get(n.on) : undefined;
+        if (on !== undefined) {
+            const list = attached.get(on) ?? [];
+            list.push(k);
+            attached.set(on, list);
+            return;
+        }
+        // the nearest cluster around it that the document prints; none, the start
+        const s = n.in.map((key) => sectionOf.get(key)).find((x) => x !== undefined);
+        if (!s) {
+            atStart.push(k);
+            return;
+        }
+        const list = inSection.get(s) ?? [];
+        list.push(k);
+        inSection.set(s, list);
+    });
+    for (const [i, ks] of attached)
+        attached.set(i, boardOrder(ks, (k) => spots.notes[k].at));
+    const declAt = (i) => spots.decls.get(g.nodes[i].name) ?? null;
+    // a section's circle; where the board names none (a board laid out otherwise), the middle of what
+    // it prints
+    const sectionAt = (s) => {
+        const c = spots.clusters.get(s.key);
+        if (c)
+            return c;
+        let x = 0, y = 0, n = 0;
+        const sum = (t) => {
+            for (const i of t.decls) {
+                const p = declAt(i);
+                if (p)
+                    [x, y, n] = [x + p[0], y + p[1], n + 1];
+            }
+            t.sections.forEach(sum);
+        };
+        sum(s);
+        return n ? [x / n, y / n] : null;
+    };
+    const at = (p) => (p.t === "decl" ? declAt(p.i) : p.t === "note" ? spots.notes[p.k].at : sectionAt(p.s.plan));
+    const section = (s) => ({
+        plan: s,
+        items: boardOrder([...s.decls.map((i) => ({ t: "decl", i })), ...(inSection.get(s) ?? []).map((k) => ({ t: "note", k })), ...s.sections.map((t) => ({ t: "section", s: section(t) }))], at),
+    });
+    // the start, then the top-level sections: the start has no heading of its own to come back to
+    const start = boardOrder([...plan.decls.map((i) => ({ t: "decl", i })), ...atStart.map((k) => ({ t: "note", k }))], at);
+    const sections = boardOrder(plan.sections.map((s) => ({ t: "section", s: section(s) })), at);
+    return { items: [...start, ...sections], attached };
+}
+/** The board of `set` (per node of `g`) by `mode` with the levels `hidden` hidden as a fresh layout
+ *  draws it, with nothing pinned and no notes: what a board nobody arranged looks like, laid out on
+ *  its own. What the builder orders by where it is told nothing of the board (shared/doc/build.ts). */
+export function freshSpots(g, set, mode, hidden) {
+    const sub = subgraph(g, set).graph;
+    const L = boardLayout(sub, mode, "fresh", null, hidden).layout;
+    const decls = new Map();
+    sub.nodes.forEach((v, i) => decls.set(v.name, [L.x[i], L.y[i]]));
+    return { decls, clusters: new Map(L.clusters.map((c) => [c.key, [c.x, c.y]])), notes: [] };
+}

package/dist/shared/doc/outline.js

@@ -0,0 +1,45 @@
+// The document's outline (ExportSpec decision 18, the linear form): what the document of a view
+// prints, in its order, without the text — its sections, numbered as the PDF numbers them, the
+// declarations and the notes in each, and the notes attached to a declaration after it. The page
+// draws the board as this outline (web/src/linear.ts); it is made from the same plan and the same
+// order the document is (shared/doc/sections.ts, shared/doc/order.ts), so that the two agree.
+import { orderDoc } from "./order.js";
+/** A note's first words: its first line, Markdown marks taken out, at most 60 characters. */
+export function firstWords(text) {
+    const line = text.split("\n").find((l) => l.trim()) ?? "";
+    const plain = line.replace(/[*_`#>]+/g, "").replace(/\s+/g, " ").trim();
+    return plain.length > 60 ? `${plain.slice(0, 59).trimEnd()}…` : plain;
+}
+/** The outline of the document of `plan` (of graph `g`) in the order of the board `spots` gives. */
+export function outlineOf(plan, g, spots) {
+    const order = orderDoc(plan, g, spots);
+    const note = (k) => {
+        const n = spots.notes[k];
+        return { t: "note", id: n.note.id, kind: n.kind, words: firstWords(n.note.text) };
+    };
+    const item = (p, prefix, at) => {
+        if (p.t === "note")
+            return note(p.k);
+        if (p.t === "decl") {
+            const ks = order.attached.get(p.i);
+            return { t: "decl", name: g.nodes[p.i].name, ...(ks?.length ? { notes: ks.map(note) } : {}) };
+        }
+        return section(p.s, prefix, at);
+    };
+    // numbered as the PDF numbers its headings (shared/doc/latex.ts): the first three levels, each
+    // within the one above; a paragraph-level heading has none
+    const section = (o, prefix, at) => {
+        const p = o.plan;
+        at.k++;
+        const number = p.level < 4 ? (prefix ? `${prefix}.${at.k}` : `${at.k}`) : null;
+        const inner = { k: 0 };
+        const items = o.items.map((x) => item(x, p.level < 3 ? (number ?? "") : "", inner));
+        return { t: "section", key: p.key, keys: [...p.keys], title: p.title, number, level: p.level, items };
+    };
+    const top = { k: 0 };
+    return {
+        items: order.items.map((x) => item(x, "", top)),
+        count: { declarations: plan.count, sections: plan.sectionCount },
+        ...(spots.fresh ? { fresh: true } : {}),
+    };
+}

package/dist/shared/doc/proof.js

@@ -0,0 +1,272 @@
+// Proofs are never exported (ExportSpec decision 8): a theorem's source is printed up to its
+// statement, and `:= …` stands for the rest. Where its value starts is read off its text here.
+//
+// The usage pass does not record where a value starts (extractor/Usage.lean tells a value's
+// syntax apart while it walks a command, but writes only the uses it found), so the text is read
+// as the tokenizer reads it (shared/lexer.ts): comments, docstrings, strings and attributes are
+// whole tokens and never searched, and brackets are followed, so that a `:=` inside a binder's
+// default value or an attribute's argument is not the value's. The value starts at the first `:=`
+// outside every bracket that no `let` or `have` in the statement claims, at a line that starts
+// with `|` and has `=>` on it (equations, `theorem f : ∀ n, P n | 0 => …`), or at a `where`. A
+// statement never holds a `by` outside brackets: one met before the value's start means the
+// reading went wrong (a `have` claimed the wrong `:=`), and nothing is found. Where nothing is
+// found, the caller prints the graph's statement instead: a proof is never printed for want of
+// finding where it starts.
+//
+// Proofs inside a definition's value are left out too, and the rest of the definition is always
+// printed (decided 2026-10-08). The usage pass records where they are (RawNode.proofs: `by` blocks
+// whose goal is a proposition, the tactics of `decreasing_by`, term-mode proofs written in the
+// text), and `cutProofs` puts `…` in the place of each. Those places are the compiled text's, so
+// the caller uses them only for a text the pass read. Elsewhere — the file changed since it was
+// compiled, or the pass is off, still running or failed on the module — `cutByText` finds them by
+// reading the text: every `by` block in the value, and the tactics of `decreasing_by`. That reading
+// cannot tell a `by` block that builds data from one that proves, and leaves out both; and it cannot
+// find a proof written as a term, which it keeps.
+import { tokenizeLean } from "../lexer.js";
+const OPEN = "([{⦃⟨⟦⟪⦅⦇⁅";
+const CLOSE = ")]}⦄⟩⟧⟫⦆⦈⁆";
+/** words in a statement's terms that bind with a `:=` of their own */
+const BINDS = new Set(["let", "have", "haveI", "letI"]);
+/** Where the value of a declaration whose text is `text` starts (an offset into `text`), or null
+ *  when it cannot be told: where a theorem's proof starts. */
+export function valueStart(text) {
+    let depth = 0;
+    let claimed = 0;
+    for (const t of tokenizeLean(text)) {
+        if (t.kind === "comment" || t.kind === "doc" || t.kind === "string" || t.kind === "attr")
+            continue;
+        if (t.kind === "keyword" || t.kind === "ident") {
+            if (depth === 0 && BINDS.has(t.text))
+                claimed++;
+            else if (depth === 0 && t.text === "where")
+                return t.at;
+            else if (depth === 0 && t.text === "by")
+                return null;
+            continue;
+        }
+        if (t.kind !== "text" && t.kind !== "op")
+            continue;
+        for (let k = 0; k < t.text.length; k++) {
+            const c = t.text[k];
+            const at = t.at + k;
+            if (OPEN.includes(c))
+                depth++;
+            else if (CLOSE.includes(c))
+                depth = Math.max(0, depth - 1);
+            else if (depth === 0 && c === ":" && t.text[k + 1] === "=") {
+                if (claimed > 0) {
+                    claimed--;
+                    k++;
+                    continue;
+                }
+                return at;
+            }
+            else if (depth === 0 && c === "|" && lineStart(text, at) && equation(text, at))
+                return at;
+        }
+    }
+    return null;
+}
+/** Whether only spaces come before `at` on its line. */
+function lineStart(text, at) {
+    const nl = text.lastIndexOf("\n", at - 1);
+    return nl >= 0 && /^[ \t]*$/.test(text.slice(nl + 1, at));
+}
+/** Whether the line from `at` is an equation's, `| pattern => value`: a `=>` on it. */
+function equation(text, at) {
+    const end = text.indexOf("\n", at);
+    return text.slice(at, end < 0 ? text.length : end).includes("=>");
+}
+/** A theorem's text without its proof: up to where its value starts, the spaces before it left
+ *  out; null where that place cannot be found. */
+export function statementOnly(text) {
+    const at = valueStart(text);
+    return at === null ? null : text.slice(0, at).replace(/\s+$/, "");
+}
+/** The UTF-16 offset of code point `col` of `line` (its end where the line is shorter). */
+function utf16At(line, col) {
+    let i = 0;
+    for (let cp = 0; cp < col && i < line.length; cp++)
+        i += (line.codePointAt(i) ?? 0) > 0xffff ? 2 : 1;
+    return i;
+}
+/** The file's lines `start`..`end` (0-based, inclusive) as highlighted code, each proof span in them
+ *  cut and `…` (an `elided` token) put in its place: `field := by decide` reads `field := …`; a
+ *  multi-line `by` block is `…` on its first line, the lines after it gone up to its end, where what
+ *  follows the proof on its last line joins the first; a `by` in the middle of a term is `…` there.
+ *  Everything else is kept as written, comments included, highlighted as the whole text is (the
+ *  text is tokenized before it is cut). Spans outside the lines are ignored, one that runs past them
+ *  is cut to their end. */
+export function cutProofs(lines, start, end, spans) {
+    const own = lines.slice(start, end + 1);
+    const text = own.join("\n");
+    const lineStart = [];
+    let at = 0;
+    for (const l of own) {
+        lineStart.push(at);
+        at += l.length + 1;
+    }
+    const offset = (line, col) => {
+        const k = line - 1 - start;
+        if (k < 0)
+            return 0;
+        if (k >= own.length)
+            return text.length;
+        return lineStart[k] + utf16At(own[k], col);
+    };
+    return cutAt(text, spans.map((sp) => [offset(sp[0], sp[1]), offset(sp[2], sp[3])]));
+}
+/** A definition's text with the proofs in it left out where reading the text finds them
+ *  (`textProofs`), cut as `cutProofs` cuts the usage pass's: for a text the pass has not read. */
+export function cutByText(text) {
+    return cutAt(text, textProofs(text));
+}
+/** `text` as highlighted code with the spans in it (offsets, end exclusive) cut, `…` in the place of
+ *  each. */
+function cutAt(text, spans) {
+    // the spans sorted and apart (the pass merges them; a span given twice is cut once)
+    const cuts = [];
+    for (const s of spans
+        .map(([a, b]) => [a, b])
+        .filter(([a, b]) => a < b)
+        .sort((x, y) => x[0] - y[0])) {
+        const last = cuts[cuts.length - 1];
+        if (last && s[0] <= last[1])
+            last[1] = Math.max(last[1], s[1]);
+        else
+            cuts.push(s);
+    }
+    // the tokens outside the cuts, an `elided` one at each cut's start
+    const kept = [];
+    let ci = 0;
+    for (const t of tokenizeLean(text)) {
+        let p = t.at;
+        const e = t.at + t.text.length;
+        while (p < e) {
+            while (ci < cuts.length && cuts[ci][1] <= p)
+                ci++;
+            const c = cuts[ci];
+            if (!c || e <= c[0]) {
+                kept.push({ kind: t.kind, text: text.slice(p, e) });
+                break;
+            }
+            if (p < c[0])
+                kept.push({ kind: t.kind, text: text.slice(p, c[0]) });
+            if (p <= c[0])
+                kept.push({ kind: "elided", text: "…" });
+            p = Math.min(e, c[1]);
+        }
+    }
+    // the lines, a new one at each line break that was kept
+    const out = [[]];
+    for (const t of kept)
+        t.text.split("\n").forEach((part, k) => {
+            if (k)
+                out.push([]);
+            if (part)
+                out[out.length - 1].push([t.kind, part]);
+        });
+    return { lines: out, cuts: cuts.length };
+}
+/** The words that end a tactic block where they stand at its depth: a definition's termination
+ *  clauses, its auxiliary definitions and its derived instances come after its value, and no
+ *  tactic is one of them. */
+const BLOCK_ENDS = new Set(["termination_by", "decreasing_by", "where", "deriving"]);
+/** The pieces of `text`, in order. */
+function pieces(text) {
+    const out = [];
+    let line = -1;
+    const push = (t, at, end) => {
+        const start = text.lastIndexOf("\n", at - 1) + 1;
+        out.push({ t, text: text.slice(at, end), at, end, quote: t === "open" && text[at - 1] === "`", col: start === line ? -1 : at - start });
+        line = start;
+    };
+    for (const t of tokenizeLean(text)) {
+        if (t.kind === "comment" || t.kind === "doc")
+            continue;
+        if (t.kind !== "text" && t.kind !== "op") {
+            push("word", t.at, t.at + t.text.length);
+            continue;
+        }
+        for (let k = 0; k < t.text.length;) {
+            const c = String.fromCodePoint(t.text.codePointAt(k));
+            const at = t.at + k;
+            k += c.length;
+            if (/\s/.test(c))
+                continue;
+            push(OPEN.includes(c) ? "open" : CLOSE.includes(c) ? "close" : c === "," ? "comma" : "mark", at, at + c.length);
+        }
+    }
+    return out;
+}
+/** Where the proofs in a definition's text are, read off the text alone (offsets, end exclusive):
+ *  each `by` block in its value, and the tactics of `decreasing_by` (the keyword stays). A `by` in
+ *  the signature is the statement's and stays, as the usage pass leaves it; where the value's start
+ *  cannot be read, the whole text is searched. A `by` inside a quotation is a macro's meaning and
+ *  stays. A `by` block that builds data is cut as well — the text cannot tell its goal — and a
+ *  proof written as a term is not found at all. */
+export function textProofs(text) {
+    const ps = pieces(text);
+    const from = valueStart(text) ?? 0;
+    const out = [];
+    // the brackets open where the reading is, each whether it is a quotation's
+    const open = [];
+    for (let k = 0; k < ps.length;) {
+        const p = ps[k];
+        if (p.t === "word" && (p.text === "by" || p.text === "decreasing_by") && p.at >= from && !open.includes(true)) {
+            const b = tacticBlock(text, ps, k, open.length > 0);
+            const start = p.text === "by" ? p.at : b.first;
+            if (start !== null && start < b.end)
+                out.push([start, b.end]);
+            k = b.next;
+            continue;
+        }
+        if (p.t === "open")
+            open.push(p.quote);
+        else if (p.t === "close")
+            open.pop();
+        k++;
+    }
+    return out;
+}
+/** The tactic block the `by` or `decreasing_by` at `ps[k]` opens, read as Lean lays it out: it runs
+ *  to the first piece, at its own bracket depth, that closes the bracket it is in, or is a comma in
+ *  that bracket (`enclosed`), a word of BLOCK_ENDS, a `then` or `else` of no `if` in the block, or
+ *  the first of a line that starts no further right than the line the block starts on (its tactics'
+ *  column less one, where they start on a line of their own further left than that). Where its last
+ *  piece ends, where its first piece after the keyword starts (null where it has none), and the
+ *  index of the first piece after it. */
+function tacticBlock(text, ps, k, enclosed) {
+    const key = ps[k];
+    const lineStart = text.lastIndexOf("\n", key.at - 1) + 1;
+    let edge = /^[ \t]*/.exec(text.slice(lineStart))[0].length;
+    let depth = 0;
+    let ifs = 0;
+    let end = key.end;
+    let first = null;
+    let j = k + 1;
+    for (; j < ps.length; j++) {
+        const p = ps[j];
+        if (first === null && p.col >= 0 && p.col <= edge)
+            edge = p.col - 1;
+        if (depth === 0) {
+            if (p.t === "close" || (p.t === "comma" && enclosed) || (p.col >= 0 && p.col <= edge))
+                break;
+            if (p.t === "word") {
+                if (BLOCK_ENDS.has(p.text) || ((p.text === "then" || p.text === "else") && !ifs))
+                    break;
+                if (p.text === "if")
+                    ifs++;
+                else if (p.text === "else")
+                    ifs--;
+            }
+        }
+        if (p.t === "open")
+            depth++;
+        else if (p.t === "close")
+            depth--;
+        first ??= p.at;
+        end = p.end;
+    }
+    return { end, first, next: j };
+}

package/dist/shared/doc/sections.js

@@ -0,0 +1,93 @@
+// The exported document's plan (ExportSpec decisions 12 and 13): what a view holds, as the document
+// prints it. Every declaration of the project the board holds is printed, whatever is folded; what
+// the view holds from outside the project is not, and is counted instead. The sections are the
+// view's cluster structure as the board shows it — its clustering, its hidden levels taken out
+// (ViewSpec decision 24; shared/layout.ts, clusterTree) — each cluster that holds something printed
+// a section, nested by its depth.
+//
+// The plan says what is printed, not in which order: the order is the board's (the owner's decisions
+// of 2026-10-12, shared/doc/order.ts), from where the view's board draws each thing, which only the
+// server and a page that lays the board out know. The builder (shared/doc/build.ts) prints from it
+// in that order, and the Export window (web/src/exportmodal.ts) says from it what the document will
+// hold, so that the two agree.
+import { clusterTree } from "../layout.js";
+/** Heading levels: section, subsection, subsubsection, then a paragraph-level heading, which every
+ *  deeper level takes too. */
+export const HEADING_LEVELS = 4;
+/** The most declarations one document prints: some 400 pages, typeset in well under the time
+ *  XeLaTeX is given (server/export.ts). A larger view is narrowed first. */
+export const MAX_DOC_DECLS = 2000;
+/** Why a view of `count` declarations of the project makes no document, or null. */
+export function tooMuch(count) {
+    if (!count)
+        return "This view holds no declaration of the project: there is nothing to print";
+    if (count > MAX_DOC_DECLS)
+        return `This view holds ${count.toLocaleString("en")} declarations of the project; a document prints at most ${MAX_DOC_DECLS.toLocaleString("en")}. Export a narrower view: a namespace or a folder, a target's Key view (key(T)) or the TCB of a target`;
+    return null;
+}
+/** The plan of the document of the board that holds `set` (per node of `g`) clustered by `mode`
+ *  with the levels `hidden` hidden. A cluster that holds no declaration of its own and one section
+ *  only is merged into it, its heading `A.B`, so that the document has no heading chains with
+ *  nothing under them; the board merges such a chain into one circle already where it holds nothing
+ *  else at all. On a board of a past build, `g` is its past graph (shared/pastgraph.ts), which holds
+ *  that build's declarations alone. */
+export function planDoc(g, set, mode, hidden) {
+    // the board's members in the whole graph's order, as a board's graph has them (shared/board.ts)
+    const members = [];
+    for (let i = 0; i < g.n; i++)
+        if (set[i])
+            members.push(i);
+    const tree = clusterTree(mode, members.map((i) => g.nodes[i]), hidden);
+    const own = tree.clusters.map(() => []);
+    const top = [];
+    const by = new Map();
+    let outside = 0;
+    members.forEach((i, k) => {
+        if (g.isExt(i)) {
+            outside++;
+            const lib = g.nodes[i].module.split(".")[0] || g.nodes[i].module;
+            by.set(lib, (by.get(lib) ?? 0) + 1);
+            return;
+        }
+        const c = tree.cluster[k];
+        (c >= 0 ? own[c] : top).push(i);
+    });
+    // how much each cluster's subtree prints
+    const kids = tree.clusters.map(() => []);
+    const roots = [];
+    tree.clusters.forEach((c, k) => (c.parent >= 0 ? kids[c.parent] : roots).push(k));
+    const printed = new Int32Array(tree.clusters.length);
+    for (let k = tree.clusters.length - 1; k >= 0; k--) {
+        printed[k] += own[k].length;
+        const p = tree.clusters[k].parent;
+        if (p >= 0)
+            printed[p] += printed[k];
+    }
+    const kept = (k) => kids[k].filter((j) => printed[j] > 0);
+    let sectionCount = 0;
+    const section = (k, depth, above) => {
+        let title = tree.clusters[k].label;
+        const keys = [tree.clusters[k].key];
+        // nothing of its own and one section: one heading
+        for (let next = kept(k); !own[k].length && next.length === 1; next = kept(k)) {
+            k = next[0];
+            title = `${title}.${tree.clusters[k].label}`;
+            keys.push(tree.clusters[k].key);
+        }
+        sectionCount++;
+        const level = Math.min(depth, HEADING_LEVELS);
+        if (depth > HEADING_LEVELS && above !== null)
+            title = `${above}.${title}`;
+        const s = { key: tree.clusters[k].key, title, level, depth, keys, decls: own[k], sections: [] };
+        s.sections = kept(k).map((j) => section(j, depth + 1, depth >= HEADING_LEVELS ? title : null));
+        return s;
+    };
+    const sections = roots.filter((k) => printed[k] > 0).map((k) => section(k, 1, null));
+    return {
+        decls: top,
+        sections,
+        count: top.length + own.reduce((a, d) => a + d.length, 0),
+        sectionCount,
+        outside: { count: outside, by: [...by].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || (a.name < b.name ? -1 : 1)) },
+    };
+}

package/dist/shared/doc/settings.js

@@ -0,0 +1,75 @@
+// The exported document's settings (ExportSpec decision 7): every option a user can set, with its
+// default, checked the same way wherever it comes from — the Export modal (web/src/exportmodal.ts),
+// POST /api/export, the agents' endpoints. The modal sets the common ones; the rest keep their
+// defaults. They are the document's style; what it holds is the view's (ExportSpec decision 12), and
+// so are its title and its author line (decisions 14 and 15): no setting gives them.
+// What a renderer does with them is its own business (shared/doc/latex.ts); the style file it loads
+// can go further (ExportSpec.md, "Customising the style").
+export const DEFAULT_SETTINGS = Object.freeze({
+    paper: "a4",
+    margin: 22,
+    fontSize: 11,
+    codeSize: 8.5,
+    contents: true,
+});
+/** Settings there were until 2026-10-08 (ExportSpec decision 7): the colour scheme, line numbers
+ *  and the context (none is printed), and the key graph's figure (the document has none); until
+ *  2026-10-09, the appendix (`supportIndex`: the document has none), and the title and the author
+ *  line (`title`, `author`: the view's title and the people who left a trace on it, decisions 14 and
+ *  15). A request that sends one is taken as before and the setting ignored, so that a page or an
+ *  agent made earlier still exports. */
+export const RETIRED_SETTINGS = ["scheme", "lineNumbers", "context", "figure", "supportIndex", "title", "author"];
+/** What each setting is, for the agents' index and the docs. */
+export const SETTINGS_HELP = {
+    paper: "a4 | letter",
+    margin: "millimetres on every side, 10–40",
+    fontSize: "the text's size in points: 10, 11 or 12",
+    codeSize: "the code's size in points, 6–12 in steps of 0.5",
+    contents: "true: a table of contents after the head card, in two columns (the sections, and the declarations where the document is short), the body following on the same page",
+};
+/** The settings a request asks for, over the defaults; or why they cannot be had. Unknown fields
+ *  are refused, so that a misspelt option is said rather than ignored; a retired one is ignored. */
+export function readSettings(raw) {
+    if (raw === undefined || raw === null)
+        return { settings: { ...DEFAULT_SETTINGS } };
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return { error: "settings is an object of options" };
+    const o = raw;
+    const s = { ...DEFAULT_SETTINGS };
+    for (const [k, v] of Object.entries(o)) {
+        if (RETIRED_SETTINGS.includes(k))
+            continue;
+        if (!Object.hasOwn(DEFAULT_SETTINGS, k))
+            return { error: `${k} is not a setting (${Object.keys(DEFAULT_SETTINGS).join(", ")})` };
+        if (v === undefined)
+            continue;
+        switch (k) {
+            case "paper":
+                if (v !== "a4" && v !== "letter")
+                    return { error: "paper is a4 or letter" };
+                s.paper = v;
+                break;
+            case "margin":
+                if (typeof v !== "number" || !Number.isFinite(v) || v < 10 || v > 40)
+                    return { error: "margin is in millimetres, 10–40" };
+                s.margin = Math.round(v);
+                break;
+            case "fontSize":
+                if (v !== 10 && v !== 11 && v !== 12)
+                    return { error: "fontSize is 10, 11 or 12" };
+                s.fontSize = v;
+                break;
+            case "codeSize":
+                if (typeof v !== "number" || !Number.isFinite(v) || v < 6 || v > 12)
+                    return { error: "codeSize is in points, 6–12" };
+                s.codeSize = Math.round(v * 2) / 2;
+                break;
+            case "contents":
+                if (typeof v !== "boolean")
+                    return { error: `${k} is true or false` };
+                s.contents = v;
+                break;
+        }
+    }
+    return { settings: s };
+}