visualproof 0.1.0 → 0.2.0

package/dist/server/pipeline.js

@@ -13,6 +13,9 @@ import { buildViewOffThread } from "./view.js";
 import { cacheHome } from "./dirs.js";
 /** the tool's own folder, `src/`; the repository is above it */
 export const SRC = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+/** the fonts the page draws an artwork's names and title in (ExportSpec decision 19): Source Sans 3
+ *  and Source Serif 4, their Latin and Greek, and Jost, its Latin, under the SIL Open Font License */
+export const WEBFONTS = join(SRC, "assets", "webfonts");
 export const REPO = resolve(SRC, "..");
 export const WEB = join(SRC, "web");
 /** The page's bundle made when the package was built (scripts/build.mjs), beside the page: an
@@ -38,8 +41,8 @@ export function bundleDir() {
  *  views from an older server are rebuilt rather than served. 7: a notation unit's statement is
  *  its command's text. 8: notation units carry their Lean constant, display form, what they
  *  interpret and their rules. 9: a node's hash is its version, beside the kernel's
- *  (server/versions.ts). */
-const VIEW_VERSION = 9;
+ *  (server/versions.ts). 10: the project's git source and commit (server/history.ts, gitSource). */
+const VIEW_VERSION = 10;
 function loadMemory(siteDir) {
     try {
         const mem = JSON.parse(readFileSync(join(siteDir, "layout-memory.json"), "utf8"));

package/dist/server/readonlygate.js

@@ -7,7 +7,7 @@ export function readOnlyAllows(method, path) {
     const read = method === "GET" || method === "HEAD";
     if (read) {
         // the page and its files
-        if (path === "/" || path === "/index.html" || path === "/style.css" || /^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path) || path.startsWith("/pdfjs/"))
+        if (path === "/" || path === "/index.html" || path === "/style.css" || /^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path) || path.startsWith("/pdfjs/") || path.startsWith("/fonts/"))
             return true;
         // the graph, its sources and Lean's answers, the review, what happened, the views, the history,
         // the library, the printed document's state and files, who the reader is and the link they

package/dist/server/snapshot.js

@@ -3,7 +3,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
-import { WEB, bundleDir } from "./pipeline.js";
+import { WEB, WEBFONTS, bundleDir } from "./pipeline.js";
 import { lakeTextHash } from "./status.js";
 /** Text that sits inside a <script> element must not close it. */
 function scriptSafe(s) {
@@ -28,7 +28,8 @@ export function writeSnapshot(project, prep, out, label, review, views) {
         }
     }
     const b64 = (buf) => buf.toString("base64");
-    const css = readFileSync(join(WEB, "style.css"), "utf8");
+    // the artwork's fonts within the page, which has no server to ask for them
+    const css = readFileSync(join(WEB, "style.css"), "utf8").replace(/url\("\/fonts\/([a-z0-9-]+\.woff2)"\)/g, (_, f) => `url("data:font/woff2;base64,${b64(readFileSync(join(WEBFONTS, f)))}")`);
     const js = readFileSync(join(bundleDir(), "app.js"), "utf8").replace(/\n\/\/# sourceMappingURL=.*$/m, "");
     const info = { createdAt: new Date().toISOString(), label };
     const html = readFileSync(join(WEB, "index.html"), "utf8")

package/dist/server/usage.js

@@ -11,7 +11,7 @@
 //
 // One process per module: a process cannot import twice. `jobs` run at once; import is bound by
 // memory bandwidth, and each worker holds hundreds of MB of its own besides the `.olean` files they
-// all map (on the showcase about 150 MB of its own, 1.2 to 1.6 GB resident with them). A module's result is cached in the
+// all map (on Sphere-Packing-Lean about 150 MB of its own, 1.2 to 1.6 GB resident with them). A module's result is cached in the
 // project's cache directory under a key
 // made of its `.olean` hash, the text it was compiled from, the options Lake compiled it with, and
 // the keys of the project modules it imports: after a build only the modules whose key changed run
@@ -25,7 +25,7 @@ import { SITE_BODY, SITE_GRAMMAR, SITE_PROOF, SITE_TCB } from "../shared/graph.j
 import { USAGE, USAGE_PROGRAM, leanProgram, prune } from "./extract.js";
 import { compiledTextHash, lakeTextHash } from "./status.js";
 /** How many workers run at once unless `--jobs` says otherwise: past about a quarter of the cores,
- *  more workers gain less and less (the showcase's cold pass on 32 cores: 320 s with 4, 195 s with
+ *  more workers gain less and less (Sphere-Packing-Lean's cold pass on 32 cores: 320 s with 4, 195 s with
  *  8, 148 s with 16). */
 export const DEFAULT_JOBS = 8;
 /** A worker still running after this long is stopped, and its module reported as failed. */

package/dist/server/view.js

@@ -3,6 +3,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { LAYOUT_VERSION } from "../shared/graph.js";
+import { gitSource } from "./history.js";
 import { layOutHere, layOutOffThread } from "./layoutthread.js";
 import { compiledTextHash } from "./status.js";
 import { versionBase, versions } from "./versions.js";
@@ -74,6 +75,11 @@ function viewParts(p, ex) {
     });
     return { nodes, edges };
 }
+/** The project's git source and commit as it is read, where it is a git repository. */
+function gitOf(root) {
+    const git = gitSource(root);
+    return git ? { git } : {};
+}
 function assemble(p, ex, nodes, edges, layouts) {
     const g = ex.graph;
     const meta = {
@@ -87,6 +93,7 @@ function assemble(p, ex, nodes, edges, layouts) {
             toolchain: p.toolchain,
             extractedAt: ex.at,
             extractMs: g.stats.ms,
+            ...gitOf(p.root),
         },
         modules: g.modules.map((m) => {
             const file = p.files.get(m.name) ?? null;

package/dist/server/views.js

@@ -59,7 +59,7 @@ const HOLD_MS = 60_000;
 /** the most views one private page holds */
 const MAX_HOLDS = 100;
 /** The most a board's layout memory may be when a page hands it over: room for a board of a large
- *  project's declarations many times over (the showcase's whole board, 7,851 declarations, is
+ *  project's declarations many times over (Sphere-Packing-Lean's whole board, 7,851 declarations, is
  *  1.8 MB; 50 MB is the owner's decision of 2026-10-14). */
 export const MAX_MEMORY_BYTES = 50 << 20;
 const isPins = (p) => {

package/dist/shared/collab.js

@@ -63,6 +63,98 @@ export function colorOf(name) {
 /** the most source windows a reader pins at once (web/src/sources.ts): a few declarations side by
  *  side, not a wall of them */
 export const MAX_PINNED = 6;
+/** An artwork's ways of being drawn (ArtworkLook `style`). */
+export const ART_STYLES = ["board", "cells", "stars"];
+/** the title's size, in hundredths of the picture's height: the least, the most, the first */
+export const TITLE_SIZE = { least: 3, most: 16, first: 7 };
+/** the foot's size, in hundredths of the picture's height: the least, the most, the first */
+export const FOOT_SIZE = { least: 0.8, most: 4, first: 1.6 };
+/** the most characters a title, or the line under it, has */
+export const TITLE_CHARS = 120;
+/** An artwork's title or its line as given: the reader's words, at most so long, or null (the
+ *  project's own). */
+export function cleanTitle(v) {
+    return typeof v === "string" ? v.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, TITLE_CHARS) : null;
+}
+/** An artwork's title size as given, within its bounds; the first where it is none. */
+export function cleanTitleSize(v) {
+    return typeof v === "number" && Number.isFinite(v) ? Math.min(TITLE_SIZE.most, Math.max(TITLE_SIZE.least, Math.round(v * 2) / 2)) : TITLE_SIZE.first;
+}
+/** An artwork's foot size as given, within its bounds, to a tenth; the first where it is none. */
+export function cleanFootSize(v) {
+    return typeof v === "number" && Number.isFinite(v) ? Math.min(FOOT_SIZE.most, Math.max(FOOT_SIZE.least, Math.round(v * 10) / 10)) : FOOT_SIZE.first;
+}
+/** What a name of an artwork's names (ArtworkLook `names`) names: a cluster, by its key, or a
+ *  declaration, by its full name. */
+export function artNameId(kind, s) {
+    return `${kind === "cluster" ? "c" : "d"}:${s}`;
+}
+/** The most an artwork's names hidden, its names shown, and its targets chosen each take in what
+ *  presence carries, in bytes of their JSON: a heartbeat is at most 16 KB (server/main.ts), and the
+ *  rest of where a reader is has room beside them. Names by selection are kept as what differs from
+ *  As shown, so that a few names hidden or added are a few names carried. */
+export const ART_NAMES_BYTES = 4500;
+export const ART_TARGETS_BYTES = 2500;
+/** What `x` adds to a list's JSON: itself, quoted, and a comma. */
+const jsonBytes = (x) => new TextEncoder().encode(JSON.stringify(x)).length + 1;
+/** A list of names as given, checked: strings, each once, none empty or longer than a name is (1,000
+ *  characters), each as `ok` says; kept in their order while their JSON stays within `budget` bytes,
+ *  the rest left out. */
+export function cleanNames(v, budget, ok = () => true) {
+    const out = [];
+    const seen = new Set();
+    let used = 2;
+    for (const x of Array.isArray(v) ? v : []) {
+        if (typeof x !== "string" || !x || x.length > 1000 || seen.has(x) || !ok(x))
+            continue;
+        const b = jsonBytes(x);
+        if (used + b > budget)
+            break;
+        used += b;
+        seen.add(x);
+        out.push(x);
+    }
+    return out;
+}
+/** a name of an artwork's names: a cluster's or a declaration's (artNameId) */
+export const isArtNameId = (s) => /^[cd]:./.test(s);
+/** the most pixels a side of an artwork has */
+export const ART_MAX_SIDE = 16384;
+/** A place with no artwork in it: an agent's (ExportSpec decision 19, agents have no artwork). */
+export function withoutArtwork(v) {
+    if (!v || !("artwork" in v))
+        return v;
+    const { artwork: _artwork, ...rest } = v;
+    return rest;
+}
+/** An artwork's settings as given, checked; null where they are not. */
+export function cleanArtwork(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const one = (xs, x) => (xs.includes(x) ? x : null);
+    const side = (x) => (Number.isInteger(x) && x >= 16 && x <= ART_MAX_SIDE ? x : null);
+    const r = Array.isArray(o.region) && o.region.length === 4 && o.region.every((n) => typeof n === "number" && Number.isFinite(n) && Math.abs(n) < 1e9) ? o.region : null;
+    const w = side(o.w), h = side(o.h), scheme = one(SCHEMES, o.scheme), theme = one(["light", "dark"], o.theme);
+    const background = one(["theme", "transparent"], o.background), labels = one(["board", "clusters", "none", "chosen"], o.labels);
+    const edges = one(["all", "selection", "none"], o.edges), targets = one(["marked", "plain", "highlight", "chosen"], o.targets);
+    if (!r || r[2] <= 0 || r[3] <= 0 || !w || !h || !scheme || !theme || !background || !labels || !edges || !targets)
+        return null;
+    // (a proof edges' switch, said until 2026-10-15, is no more: an artwork draws none)
+    if (typeof o.notes !== "boolean" || typeof o.selection !== "boolean")
+        return null;
+    // the source, said since 2026-10-15: off where a page does not say it. The names and targets chosen
+    // and the key marks' switch, said since the evening of that day: none chosen where a page does not
+    // say them, and the key marks as the targets drew them before (with their stars, unless As any)
+    const namesFrom = o.namesFrom === "none" ? "none" : "board";
+    const hiddenNames = cleanNames(o.hiddenNames, ART_NAMES_BYTES, isArtNameId), shownNames = cleanNames(o.shownNames, ART_NAMES_BYTES, isArtNameId);
+    const shownTargets = cleanNames(o.shownTargets, ART_TARGETS_BYTES);
+    const keys = typeof o.keys === "boolean" ? o.keys : targets !== "plain";
+    // the style and the title, said since that night: as the board, the project's own; the foot's
+    // size, said since later that night: the first
+    const style = one(ART_STYLES, o.style) ?? "board";
+    return { w, h, scheme, theme, background, labels, namesFrom, hiddenNames, shownNames, edges, notes: o.notes, targets, shownTargets, keys, selection: o.selection, source: o.source === true, style, title: cleanTitle(o.title), subtitle: cleanTitle(o.subtitle), titleSize: cleanTitleSize(o.titleSize), footSize: cleanFootSize(o.footSize), border: o.border === true, region: [...r] };
+}
 /** The legend's schemes (CanvasSpec, "Colour schemes"). */
 export const SCHEMES = ["kind", "status"];
 /** Activity's filters: the kind of event, and whose (web/src/activity.ts). */
@@ -143,6 +235,7 @@ export function cleanView(v) {
         ...(typeof lost === "boolean" ? { lostFound: { open: lost } } : {}),
         ...(scheme ? { scheme } : {}),
         ...(typeof o.edges === "boolean" ? { edges: o.edges } : {}),
-        ...(typeof o.proofEdges === "boolean" ? { proofEdges: o.proofEdges } : {}),
+        ...(typeof o.linear === "boolean" ? { linear: o.linear } : {}),
+        ...(o.artwork === null ? { artwork: null } : cleanArtwork(o.artwork) ? { artwork: cleanArtwork(o.artwork) } : {}),
     };
 }

package/dist/shared/doc/order.js

@@ -28,6 +28,23 @@ export function boardOrder(xs, at) {
     });
     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

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/keys.js

@@ -21,7 +21,7 @@
 //
 // A review holds many members and a target a dozen key declarations: after one walk over the
 // target's TCB, each walk reads the edges of the members and of what it passes through, never the
-// whole graph's (the showcase's `Dim24.MainTheorem`: its TCB of 226 in 72 ms, its keys in 1 ms).
+// whole graph's (Sphere-Packing-Lean's `Dim24.MainTheorem`: its TCB of 226 in 72 ms, its keys in 1 ms).
 import { keyMarks, statusOf } from "./review.js";
 import { TCB_SITES } from "./reviewqueue.js";
 /** The key declarations of `root` among the members of its review (`order`, the queue's order —

package/dist/shared/moves.js

@@ -209,7 +209,8 @@ export function renameInQuery(q, from, to) {
         }
         case "tcb":
         case "uses":
-        case "usedBy": {
+        case "usedBy":
+        case "refs": {
             if (q.of === "selection")
                 return q;
             if (Array.isArray(q.of)) {

package/dist/shared/pastgraph.js

@@ -21,6 +21,13 @@ export const PAST_GHOST = 1;
 export const PAST_CHANGED = 4;
 /** renamed since: shown under its name then */
 export const PAST_RENAMED = 8;
+/** The git source of a past build: the project's source, the build's own commit; none where the
+ *  build's commit is not known, or only guessed. */
+function gitThen(now, commit) {
+    if (!commit || commit.guessed)
+        return { git: undefined };
+    return { git: { source: now?.source ?? null, commit: commit.hash, branch: commit.branch, ...(commit.dirty ? { dirty: true } : {}) } };
+}
 /** The past graph of snapshot `snap` (its declarations and its edges, as /graph's parts give them),
  *  marked by `diff` (from it to the latest), with the project's description of `now`. */
 export function pastGraph(snap, edges, now, diff) {
@@ -33,7 +40,8 @@ export function pastGraph(snap, edges, now, diff) {
     const meta = {
         schema: 1,
         layoutVersion: now.meta.layoutVersion,
-        project: { ...now.meta.project, extractedAt: snap.snapshot.at },
+        // the commit of that build, where it is known; the source is the project's now
+        project: { ...now.meta.project, extractedAt: snap.snapshot.at, ...gitThen(now.meta.project.git, snap.snapshot.commit) },
         modules: snap.modules.map((m) => ({ name: m.name, file: null, imports: m.imports })),
         nodes,
         projectCount: P,

package/dist/shared/query.js

@@ -8,7 +8,7 @@
 //
 // The text form, left to right:
 //
-//   all | selection | decl(A, B) | tcb(A) | uses(A, B) | usedBy(selection)
+//   all | selection | decl(A, B) | tcb(A) | uses(A, B) | usedBy(selection) | refs(A)
 //   tcb(ns(Fermat42) except external)   a closure of the set a query holds
 //   ns(Fermat42)                 declarations whose name is under the prefix
 //   file(Mathlib.NumberTheory)   declarations of the modules under the prefix
@@ -27,7 +27,7 @@ import { adviceOf, keyMarks, STANDARD_AXIOMS, statusOf, trusted, under } from ".
 export const KINDS = ["theorem", "def", "abbrev", "instance", "structure", "class", "inductive", "opaque", "axiom", "quot", "constructor", "recursor", "notation", "unknown"];
 export const STATUSES = ["unreviewed", "approved", "commented", "stale"];
 const VERDICTS = ["approve", "comment"];
-const CLOSURES = ["tcb", "uses", "usedBy"];
+const CLOSURES = ["tcb", "uses", "usedBy", "refs"];
 const PLAIN = ["all", "selection", "trusted", "external", "sorry", "nonstandard"];
 const COMBINATORS = ["and", "or", "except"];
 /** words for the same thing, read as the first */
@@ -38,10 +38,11 @@ export const LIGHT = {
     plain: { op: "selection" },
     tcb: { op: "tcb", of: "selection" },
     deps: { op: "uses", of: "selection" },
+    refs: { op: "refs", of: "selection" },
     apps: { op: "usedBy", of: "selection" },
 };
-/** Which closure each closure word is, as the graph computes it (shared/viewgraph.ts). */
-const CLOSURE_MODE = { tcb: "tcb", uses: "deps", usedBy: "apps" };
+/** Which walk of the graph each closure word is (shared/viewgraph.ts); `refs` is one step. */
+const CLOSURE_MODE = { tcb: "tcb", uses: "deps", usedBy: "apps", refs: "refs" };
 // ---------------------------------------------------------------- how large a query may be
 /** How large a query may be: one set of bounds for its text and its JSON form, checked when either
  *  is read (parseQuery, cleanQuery), so that what one form takes the other takes too — a scope
@@ -61,7 +62,7 @@ export const QUERY_LIMITS = {
     names: 2_000,
     /** characters of one name or prefix */
     name: 2_000,
-    /** closures (tcb, uses, usedBy), each a walk of the graph; each target of a `key(…)` counts as
+    /** closures (tcb, uses, usedBy, refs), each a walk of the graph; each target of a `key(…)` counts as
      *  one too, since its review set is walked to keep only the marks still in it. `key(targets)`
      *  counts as one: how many targets there are is the project's, not the query's, and every
      *  `key(targets)` of a query shares the same walks (evaluateIn) */
@@ -88,6 +89,7 @@ export function beyondLimits(q) {
             case "tcb":
             case "uses":
             case "usedBy":
+            case "refs":
                 closures++;
                 if (x.of !== "selection" && !Array.isArray(x.of)) {
                     terms++;
@@ -131,7 +133,7 @@ export function beyondLimits(q) {
     if (longest > L.name)
         return `a name in the query is longer than ${L.name.toLocaleString("en")} characters`;
     if (closures > L.closures)
-        return `the query has ${closures} closures (tcb, uses, usedBy), more than ${L.closures}`;
+        return `the query has ${closures} closures (tcb, uses, usedBy, refs), more than ${L.closures}`;
     const length = printQuery(q).length;
     if (length > L.text)
         return `the query is ${length.toLocaleString("en")} characters long as printed, more than ${L.text.toLocaleString("en")}`;
@@ -286,7 +288,7 @@ function parse(text) {
         }
         const w = keyword(t);
         if (w === null)
-            throw new QueryError(t.t === "string" ? "a quoted name stands only inside decl(…), tcb(…), uses(…) or usedBy(…)" : `${t.t} is out of place`, t.at);
+            throw new QueryError(t.t === "string" ? "a quoted name stands only inside decl(…), tcb(…), uses(…), usedBy(…) or refs(…)" : `${t.t} is out of place`, t.at);
         if (++terms > QUERY_LIMITS.terms)
             throw new QueryError(`the query has more than ${QUERY_LIMITS.terms.toLocaleString("en")} parts`, t.at);
         k++;
@@ -338,7 +340,7 @@ function parse(text) {
             return { op: "status", statuses: choose(args(), STATUSES, "status") };
         if (w === "advice")
             return { op: "advice", verdicts: choose(args(), VERDICTS, "advice") };
-        throw new QueryError(`${text1(t)} is not a word of the query language (all, tcb, uses, usedBy, decl, key, ns, file, trusted, external, kind, status, advice, sorry, nonstandard)`, t.at);
+        throw new QueryError(`${text1(t)} is not a word of the query language (all, tcb, uses, usedBy, refs, decl, key, ns, file, trusted, external, kind, status, advice, sorry, nonstandard)`, t.at);
     };
     const expr = () => {
         let q = atom();
@@ -376,7 +378,8 @@ export function printQuery(q) {
             return `key(${q.of === "targets" ? "targets" : q.of.map((t) => (t === "targets" ? JSON.stringify(t) : arg(t))).join(", ")})`;
         case "tcb":
         case "uses":
-        case "usedBy": {
+        case "usedBy":
+        case "refs": {
             if (q.of === "selection" || Array.isArray(q.of))
                 return `${q.op}(${q.of === "selection" ? "selection" : q.of.map(arg).join(", ")})`;
             // a query of one plain word would read as a name
@@ -461,7 +464,8 @@ function readJson(x, why = false) {
                 return names(o.of) ? { op: "key", of: [...o.of] } : null;
             case "tcb":
             case "uses":
-            case "usedBy": {
+            case "usedBy":
+            case "refs": {
                 if (o.of === "selection")
                     return { op: o.op, of: "selection" };
                 if (o.of && typeof o.of === "object" && !Array.isArray(o.of)) {
@@ -531,7 +535,7 @@ export function namesIn(q) {
             x.names.forEach((n) => out.add(n));
         else if (x.op === "key" && x.of !== "targets")
             x.of.forEach((n) => out.add(n));
-        else if (x.op === "tcb" || x.op === "uses" || x.op === "usedBy") {
+        else if (x.op === "tcb" || x.op === "uses" || x.op === "usedBy" || x.op === "refs") {
             if (Array.isArray(x.of))
                 x.of.forEach((n) => out.add(n));
             else if (x.of !== "selection")
@@ -549,7 +553,7 @@ export function namesIn(q) {
 export function readsReview(q) {
     if (q.op === "trusted" || q.op === "status" || q.op === "advice" || q.op === "key")
         return true;
-    if ((q.op === "tcb" || q.op === "uses" || q.op === "usedBy") && q.of !== "selection" && !Array.isArray(q.of))
+    if ((q.op === "tcb" || q.op === "uses" || q.op === "usedBy" || q.op === "refs") && q.of !== "selection" && !Array.isArray(q.of))
         return readsReview(q.of);
     if (q.op === "and" || q.op === "or" || q.op === "except")
         return readsReview(q.a) || readsReview(q.b);
@@ -563,6 +567,7 @@ export function withSelection(q, names) {
         case "tcb":
         case "uses":
         case "usedBy":
+        case "refs":
             if (q.of === "selection")
                 return { op: q.op, of: [...names] };
             return Array.isArray(q.of) ? q : { op: q.op, of: withSelection(q.of, names) };
@@ -647,6 +652,8 @@ export function describe(q) {
             return `TCB of ${roots(q.of)}`;
         case "uses":
             return `what ${roots(q.of)} uses`;
+        case "refs":
+            return `what ${roots(q.of)} uses directly`;
         case "usedBy":
             return `what uses ${roots(q.of)}`;
         case "ns":
@@ -759,7 +766,8 @@ function evaluateIn(q, ctx, walks) {
             return out;
         case "tcb":
         case "uses":
-        case "usedBy": {
+        case "usedBy":
+        case "refs": {
             const key = `${q.op}\u0000${q.of === "selection" ? "\u0001" : Array.isArray(q.of) ? JSON.stringify(q.of) : printQuery(q.of)}`;
             let walked = walks.get(key);
             if (!walked) {

package/dist/shared/sharesnap.js

@@ -105,7 +105,8 @@ export const SNAPSHOT_FORMS = {
     lostFound: same("lostFound"),
     colouring: same("scheme"),
     edges: same("edges"),
-    proofEdges: same("proofEdges"),
+    linear: same("linear"),
+    artwork: same("artwork"),
 };
 /** The snapshot of where a page is (`v`, as presence carries it: the registry's parts, read by the
  *  page), as a link carries it after `snap=`. */

package/dist/shared/titles.js

@@ -224,6 +224,8 @@ function said(q, N) {
             return `TCB of ${roots(q.of, N)}`;
         case "uses":
             return `what ${roots(q.of, N)} uses`;
+        case "refs":
+            return `what ${roots(q.of, N)} uses directly`;
         case "usedBy":
             return `what uses ${roots(q.of, N)}`;
         case "ns":

package/dist/shared/viewgraph.js

@@ -9,6 +9,7 @@ export const MODE_SITES = {
     plain: ALL_SITES,
     tcb: SITE_STMT | SITE_BODY,
     deps: ALL_SITES,
+    refs: ALL_SITES,
     apps: ALL_SITES,
 };
 export class Graph {
@@ -69,6 +70,20 @@ export class Graph {
     isExt(i) {
         return i >= this.projectCount;
     }
+    /** `from` and what is one edge from it, along edges whose sites meet `sites`. */
+    step(from, sites, dir) {
+        const seen = new Uint8Array(this.n);
+        const start = dir === "out" ? this.outStart : this.inStart;
+        const adj = dir === "out" ? this.outDst : this.inSrc;
+        const site = dir === "out" ? this.outSite : this.inSite;
+        for (const u of from) {
+            seen[u] = 1;
+            for (let e = start[u]; e < start[u + 1]; e++)
+                if (site[e] & sites)
+                    seen[adj[e]] = 1;
+        }
+        return seen;
+    }
     /** Everything reachable from `from` (included) along edges whose sites meet `sites`. */
     reach(from, sites, dir) {
         const seen = new Uint8Array(this.n);
@@ -108,6 +123,9 @@ export class Graph {
                 return this.reach(focus, MODE_SITES.tcb, "out");
             case "deps":
                 return this.reach(focus, ALL_SITES, "out");
+            // Direct: what it uses directly, one step (ViewSpec decision 20, the owner's decision of 2026-10-14)
+            case "refs":
+                return this.step(focus, ALL_SITES, "out");
             case "apps":
                 return this.reach(focus, ALL_SITES, "in");
         }