visualproof 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/README.md +2 -2
  2. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  3. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  4. package/dist/assets/tips/tour-agent.webp +0 -0
  5. package/dist/assets/tips/tour-arrange.webp +0 -0
  6. package/dist/assets/tips/tour-artwork.webp +0 -0
  7. package/dist/assets/tips/tour-checks.webp +0 -0
  8. package/dist/assets/tips/tour-export.webp +0 -0
  9. package/dist/assets/tips/tour-keys.webp +0 -0
  10. package/dist/assets/tips/tour-library.webp +0 -0
  11. package/dist/assets/tips/tour-project.webp +0 -0
  12. package/dist/assets/tips/tour-review.webp +0 -0
  13. package/dist/assets/tips/tour-share.webp +0 -0
  14. package/dist/assets/tips/tour-source.webp +0 -0
  15. package/dist/assets/tips/tour-target.webp +0 -0
  16. package/dist/assets/tips/tour-view.webp +0 -0
  17. package/dist/assets/tips/tour.json +90 -90
  18. package/dist/assets/tips/tour.webp +0 -0
  19. package/dist/extractor/Extract.lean +13 -3
  20. package/dist/server/agent.js +104 -2881
  21. package/dist/server/agentactivity.js +72 -0
  22. package/dist/server/agentadvice.js +128 -0
  23. package/dist/server/agentdocs.js +1 -1
  24. package/dist/server/agententry.js +180 -0
  25. package/dist/server/agentexport.js +469 -0
  26. package/dist/server/agentfollow.js +412 -0
  27. package/dist/server/agentgraph.js +128 -0
  28. package/dist/server/agentlean.js +144 -0
  29. package/dist/server/agentlibrary.js +1 -1
  30. package/dist/server/agentplaces.js +242 -0
  31. package/dist/server/agentread.js +569 -0
  32. package/dist/server/agenttalk.js +282 -0
  33. package/dist/server/agenttcb.js +378 -0
  34. package/dist/server/agentviews.js +3 -3
  35. package/dist/server/app.js +379 -0
  36. package/dist/server/appaccess.js +127 -0
  37. package/dist/server/appagent.js +110 -0
  38. package/dist/server/appgraph.js +176 -0
  39. package/dist/server/appshare.js +179 -0
  40. package/dist/server/appsite.js +120 -0
  41. package/dist/server/apptalk.js +195 -0
  42. package/dist/server/artcmd.js +1 -1
  43. package/dist/server/events.js +1 -1
  44. package/dist/server/history.js +51 -3
  45. package/dist/server/historyapi.js +34 -2
  46. package/dist/server/hover.js +11 -7
  47. package/dist/server/identity.js +1 -1
  48. package/dist/server/libraryroute.js +3 -3
  49. package/dist/server/live.js +162 -12
  50. package/dist/server/main.js +17 -1746
  51. package/dist/server/mcptools.js +1 -1
  52. package/dist/server/options.js +350 -0
  53. package/dist/server/outside.js +311 -0
  54. package/dist/server/pastdoc.js +22 -3
  55. package/dist/server/presence.js +25 -8
  56. package/dist/server/project.js +28 -4
  57. package/dist/server/readonlygate.js +4 -0
  58. package/dist/server/reviewapi.js +10 -3
  59. package/dist/server/send.js +259 -0
  60. package/dist/server/talk.js +13 -7
  61. package/dist/server/tokens.js +3 -3
  62. package/dist/server/view.js +3 -1
  63. package/dist/server/views.js +1 -1
  64. package/dist/shared/artrecipe.js +3 -3
  65. package/dist/shared/board.js +9 -8
  66. package/dist/shared/collab.js +54 -7
  67. package/dist/shared/comment.js +1 -1
  68. package/dist/shared/doc/build.js +30 -14
  69. package/dist/shared/doc/latex.js +7 -2
  70. package/dist/shared/doc/model.js +4 -2
  71. package/dist/shared/doc/sections.js +21 -4
  72. package/dist/shared/outside.js +16 -0
  73. package/dist/shared/pastgraph.js +11 -2
  74. package/dist/shared/pointer.js +152 -0
  75. package/dist/shared/query.js +36 -5
  76. package/dist/shared/review.js +34 -2
  77. package/dist/shared/scope.js +1 -1
  78. package/dist/shared/sharesnap.js +15 -0
  79. package/dist/shared/titles.js +4 -0
  80. package/dist/web/bundle/app.js +51061 -49518
  81. package/dist/web/index.html +4 -0
  82. package/dist/web/src/canvas.js +16 -14
  83. package/dist/web/src/highlight.js +8 -3
  84. package/dist/web/src/reviewqueue.js +52 -10
  85. package/dist/web/src/selection.js +1 -1
  86. package/dist/web/src/status.js +65 -1
  87. package/dist/web/src/theme.js +1 -1
  88. package/dist/web/src/visitors.js +1 -1
  89. package/dist/web/style.css +121 -7
  90. package/docs/agent-api/advice.md +4 -1
  91. package/docs/agent-api/export.md +8 -5
  92. package/docs/agent-api/following.md +9 -3
  93. package/docs/agent-api/history.md +3 -1
  94. package/docs/agent-api/reading.md +8 -2
  95. package/docs/agent-api/views.md +3 -1
  96. package/package.json +1 -1
@@ -0,0 +1,195 @@
1
+ // People on the page with one another (the routes of server/app.ts): where each one is, which the
2
+ // others see (presence: CollabSpec decisions 4 and 8), asking others to follow (decision 10), and
3
+ // the conversations (decision 13, AgentSpec decision 8) — the public channel, each agent's private
4
+ // one with its maker, a new conversation there. Agents do all of it through their API.
5
+ import { agentPlace, cleanFollowing, cleanView, madeBy, nameKey } from "../shared/collab.js";
6
+ import { forPages, MAX_PERSON, PUBLIC, THREAD } from "./talk.js";
7
+ import { mentioned } from "../shared/mentions.js";
8
+ import { sendJson } from "./send.js";
9
+ import { placeOf } from "./agentfollow.js";
10
+ import { BODY_MAX } from "../shared/pointer.js";
11
+ /** where a reader is: the others see it (CollabSpec decision 4); of a private reader, only that
12
+ * they are here (decision 8) */
13
+ export async function presence(app, req, res, agent) {
14
+ const live = app.live;
15
+ const r = await app.json(req, 16384);
16
+ if (r.error !== undefined)
17
+ return sendJson(res, { error: r.error }, 400);
18
+ const b = (r.body ?? {});
19
+ // an agent is one entry by its name (server/presence.ts), never private; a page speaks for
20
+ // its own event stream only, by the secret the stream was given (`hello`)
21
+ const name = app.ids.who(req);
22
+ const priv = !agent && b.private === true;
23
+ // agents have no artwork (ExportSpec decision 19) nor Export window — the page draws them — and
24
+ // follow nobody; a private page says whom it follows and nothing else, so that the reader it
25
+ // follows is told it is followed, by someone (the owner's decision of 2026-10-20)
26
+ if (agent && name)
27
+ live.presence.agentBeat(name, agentPlace(cleanView(b.view)));
28
+ else if (!live.beat(b.token, priv ? null : name, priv ? null : cleanView(b.view), !priv && b.idle === true, priv, !!app.ids.person(req), name, priv ? cleanFollowing(b.following) : null))
29
+ return sendJson(res, { error: "This heartbeat is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
30
+ return sendJson(res, { ok: true });
31
+ }
32
+ /** Where a page's pointer is, and what text it has selected (CollabSpec decision 4, the owner's
33
+ * decisions of 2026-10-20; shared/pointer.ts): relayed to the pages of its room by its stream's
34
+ * secret, as a heartbeat is, and kept nowhere; a read-only page says whom it follows. 403 where no
35
+ * open stream has the secret (an agent has none). */
36
+ export async function pointer(app, req, res) {
37
+ const r = await app.json(req, BODY_MAX);
38
+ if (r.error !== undefined)
39
+ return sendJson(res, { error: r.error }, 400);
40
+ const b = (r.body && typeof r.body === "object" ? r.body : {});
41
+ const to = app.live.pointer(b.token, b);
42
+ if (to === null)
43
+ return sendJson(res, { error: "This pointer is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
44
+ return sendJson(res, { ok: true, to });
45
+ }
46
+ /** The conversations (CollabSpec decision 13, AgentSpec decision 8), for pages: a channel read
47
+ * (GET ?channel=public|<agent id>&before=<id>, the newest 200 first) and a message written in it
48
+ * (POST {channel, text, place}). Everyone with a name reads and writes the public channel; an
49
+ * agent's private channel is its maker's alone (shared/collab.ts, madeBy: 403 to anyone else).
50
+ * A read-only reader neither sees nor writes any (403), whatever the page sends; agents talk
51
+ * through their API. A private channel cannot be written to while its agent is offline (409); a
52
+ * mention of it in the public channel can, and is handed to it when it comes back. At most so
53
+ * many messages a minute, a person's in every channel together. */
54
+ export async function chat(app, req, res, url) {
55
+ const live = app.live;
56
+ if (req.method !== "GET" && req.method !== "POST")
57
+ return sendJson(res, { error: "/api/chat answers GET and POST." }, 405);
58
+ if (app.readOnlyOf.has(req))
59
+ return sendJson(res, { error: "This page is read-only.", readOnly: true }, 403);
60
+ if (app.ids.kind(req) === "agent")
61
+ return sendJson(res, { error: "Agents talk through their API.", hint: "GET /api/agent/channel, POST /api/agent/reply." }, 403);
62
+ const me = app.ids.who(req);
63
+ if (!me)
64
+ return sendJson(res, { error: "Say who you are first: the conversations are for people with a name, and a message is sent under yours.", who: true }, 401);
65
+ const who = { name: me, person: app.ids.person(req)?.id ?? null };
66
+ /** the channel a request names: the public one, or an agent's private one that is this
67
+ * reader's — 404 where there is no such agent, 403 where it is someone else's */
68
+ const channelOf = (raw) => {
69
+ if (raw === "public" || raw === undefined || raw === null || raw === "")
70
+ return { key: PUBLIC, agent: null };
71
+ const tok = typeof raw === "string" ? live.presence.tokenOf(raw) : null;
72
+ const record = tok ? live.tokens.get(tok) : undefined;
73
+ if (!tok || !record)
74
+ return { status: 404, body: { error: "There is no such channel: public, or the id of an agent with a token of its own." } };
75
+ if (!madeBy(record, who))
76
+ return { status: 403, body: { error: `${record.name}'s private channel is ${record.by}'s, who made its token: nobody else reads or writes it.`, private: true } };
77
+ return { key: tok, agent: { id: raw, record } };
78
+ };
79
+ if (req.method === "GET") {
80
+ const c = channelOf(url.searchParams.get("channel") ?? url.searchParams.get("agent"));
81
+ if ("status" in c)
82
+ return sendJson(res, c.body, c.status);
83
+ const raw = url.searchParams.get("before");
84
+ const before = raw && /^\d{1,9}$/.test(raw) ? Number(raw) : null;
85
+ const messages = live.talk.thread(c.key, THREAD, before).map(forPages);
86
+ if (!c.agent)
87
+ return sendJson(res, { channel: PUBLIC, messages });
88
+ return sendJson(res, { channel: c.agent.id, agent: { id: c.agent.id, name: c.agent.record.name, talk: live.talk.talk(c.key) }, messages });
89
+ }
90
+ const r = await app.json(req, 1 << 16);
91
+ if (r.error !== undefined)
92
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
93
+ const b = (r.body ?? {});
94
+ const c = channelOf(b.channel ?? b.agent);
95
+ if ("status" in c)
96
+ return sendJson(res, c.body, c.status);
97
+ if (c.agent && live.talk.state(c.key) === "offline")
98
+ return sendJson(res, { error: "offline", message: `${c.agent.record.name} is offline: it can be written to once it listens again.` }, 409);
99
+ const text = typeof b.text === "string" ? b.text.trim() : "";
100
+ if (!text)
101
+ return sendJson(res, { error: "The message is empty." }, 400);
102
+ if (text.length > MAX_PERSON)
103
+ return sendJson(res, { error: `A message is at most ${MAX_PERSON.toLocaleString("en")} characters.` }, 400);
104
+ const wait = live.talk.allow("person", who.person ? `p:${who.person}` : `n:${nameKey(me)}`);
105
+ if (wait)
106
+ return sendJson(res, { error: `Too many messages at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
107
+ // where the writer was, as the page says it, bounded: a selection can be a long query; a private
108
+ // reader's message says nothing of where they are (CollabSpec decision 8), only who wrote it
109
+ const view = app.ids.privateOf(req) === null ? cleanView(b.place) : null;
110
+ const at = view ? placeOf(app.agents, view) : null;
111
+ const clip = (x, n) => (x !== null && x.length > n ? x.slice(0, n - 1) + "…" : x);
112
+ const where = at ? { inWords: clip(at.inWords, 600), view: at.view, declaration: clip(at.declaration, 300), selection: clip(at.selection, 300) } : null;
113
+ // the names it mentions; in the public channel, the agents among them are handed it
114
+ const can = live.mentionable();
115
+ const mentions = mentioned(text, can.names);
116
+ const to = c.agent ? [] : [...new Set(mentions.flatMap((n) => can.agents.get(nameKey(n)) ?? []))];
117
+ const message = live.talk.post(c.key, { from: me, kind: "person", text, ...(mentions.length ? { mentions } : {}), where, to });
118
+ return sendJson(res, { ok: true, channel: c.agent?.id ?? PUBLIC, message: forPages(message) });
119
+ }
120
+ /** A new conversation in an agent's private channel (AgentSpec decision 8, the owner's decisions
121
+ * of 2026-10-11 and 2026-10-19): a divider, from its maker alone, held to the rate of their
122
+ * messages; an offline agent's too, so that its next session starts clean. One right after
123
+ * another divides nothing: it is answered `unchanged`, and neither written nor counted. */
124
+ export async function chatNew(app, req, res) {
125
+ const live = app.live;
126
+ if (req.method !== "POST")
127
+ return sendJson(res, { error: "/api/chat/new answers POST." }, 405);
128
+ if (app.readOnlyOf.has(req))
129
+ return sendJson(res, { error: "This page is read-only.", readOnly: true }, 403);
130
+ if (app.ids.kind(req) === "agent")
131
+ return sendJson(res, { error: "A new conversation is for people to start." }, 403);
132
+ const me = app.ids.who(req);
133
+ if (!me)
134
+ return sendJson(res, { error: "Say who you are first: a new conversation is started under your name.", who: true }, 401);
135
+ const r = await app.json(req, 1 << 12);
136
+ if (r.error !== undefined)
137
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
138
+ const b = (r.body ?? {});
139
+ const tok = typeof b.agent === "string" ? live.presence.tokenOf(b.agent) : null;
140
+ const record = tok ? live.tokens.get(tok) : undefined;
141
+ if (!tok || !record)
142
+ return sendJson(res, { error: "There is no such agent: only an agent with a token of its own has a private channel." }, 404);
143
+ const person = app.ids.person(req)?.id ?? null;
144
+ if (!madeBy(record, { name: me, person }))
145
+ return sendJson(res, { error: `Only ${record.by}, who made ${record.name}'s token, starts a new conversation with it.`, private: true }, 403);
146
+ if (live.talk.fresh(tok))
147
+ return sendJson(res, { ok: true, unchanged: true, divider: null, message: "Nothing was said since the conversation began: it is new already." });
148
+ const wait = live.talk.allow("person", person ? `p:${person}` : `n:${nameKey(me)}`);
149
+ if (wait)
150
+ return sendJson(res, { error: `Too many at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
151
+ const divider = live.talk.restart(tok, me);
152
+ return sendJson(res, { ok: true, divider: divider && forPages(divider) });
153
+ }
154
+ /** Asking others to follow (CollabSpec decision 10, the owner's decision of 2026-10-12), for pages:
155
+ * POST /api/ask {token, to?} — the page whose event stream holds `token` asks everyone on the
156
+ * server, or the person whose page is listed as `to`, to follow its reader, who has a name and is
157
+ * visible: a private reader cannot be followed; POST /api/ask/answer {token, id, answer} — a page
158
+ * asked answers, whoever its reader is. The server relays both (server/askfollow.ts); agents ask
159
+ * through their API (POST /api/agent/ask-follow). */
160
+ export async function ask(app, req, res, url) {
161
+ const live = app.live;
162
+ if (req.method !== "POST")
163
+ return sendJson(res, { error: `${url.pathname} answers POST.` }, 405);
164
+ if (app.ids.kind(req) === "agent")
165
+ return sendJson(res, { error: "Agents ask through their API.", hint: "POST /api/agent/ask-follow." }, 403);
166
+ const r = await app.json(req, 4096);
167
+ if (r.error !== undefined)
168
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
169
+ const b = (r.body ?? {});
170
+ const page = live.pageStream(b.token);
171
+ if (!page)
172
+ return sendJson(res, { error: "This request is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
173
+ if (url.pathname === "/api/ask/answer") {
174
+ const a = live.asks.answer(b.token, b.id, b.answer);
175
+ return sendJson(res, a.body, a.status);
176
+ }
177
+ if (url.pathname !== "/api/ask")
178
+ return sendJson(res, { error: "not found" }, 404);
179
+ const me = app.ids.who(req);
180
+ if (!me)
181
+ return sendJson(res, app.nameless(req, "a request to follow you says who asks"), 401);
182
+ if (page.private || app.ids.privateOf(req) !== null)
183
+ return sendJson(res, { error: "You are private: nobody can follow you. Go visible (the menu under your name) to ask." }, 409);
184
+ if (b.to !== undefined && b.to !== null && typeof b.to !== "string")
185
+ return sendJson(res, { error: "to is a reader's id, as presence lists them; left out, everyone." }, 400);
186
+ const person = app.ids.person(req);
187
+ // one request every 30 s per person — their personal link, else their name — and per page
188
+ const key = person ? `p:${person.id}` : `n:${nameKey(me)}`;
189
+ const a = live.asks.ask({ name: me, verified: !!person, agent: false, from: page.id, stream: b.token, rate: [key, `s:${b.token}`] }, typeof b.to === "string" ? { page: b.to } : { everyone: true });
190
+ if ("ok" in a) {
191
+ const { report: _, ...sent } = a.ok;
192
+ return sendJson(res, { ok: true, ...sent });
193
+ }
194
+ return sendJson(res, { error: a.error, ...(a.retryAfter ? { retryAfter: a.retryAfter } : {}) }, a.status, a.retryAfter ? { "retry-after": String(a.retryAfter) } : undefined);
195
+ }
@@ -118,7 +118,7 @@ export function makeArtwork(prep, review, project, ask) {
118
118
  if (problems.length)
119
119
  return { problems };
120
120
  const s = cleanSettings(res.look, { scheme: "kind", theme: "light" });
121
- // the theme as the mode sets it (web/src/main.ts, drawLook): the board's style in the artwork's,
121
+ // the theme as the mode sets it (web/src/pageart.ts, drawLook): the board's style in the artwork's,
122
122
  // the cells and the starfield in the dark one
123
123
  const css = readFileSync(join(WEB, "style.css"), "utf8");
124
124
  const v = cssTheme(css, s.style === "board" ? s.theme === "dark" : true);
@@ -4,7 +4,7 @@
4
4
  // target's TCB that changed (with the opinions that went stale by it) — and is told of re-layouts,
5
5
  // of targets taken off and of prefixes trusted or no longer trusted (the review's state keeps the
6
6
  // trusted list, not who changed it), and of what agents do beside their advice: notes, layout
7
- // batches and their undoing (server/agent.ts), and of views saved, renamed, deleted and laid out
7
+ // batches and their undoing (server/agentplaces.ts), and of views saved, renamed, deleted and laid out
8
8
  // afresh (server/views.ts). Opinions, targets and key marks are in the review's logs
9
9
  // (server/review.ts); the page reads them from there.
10
10
  //
@@ -19,6 +19,11 @@
19
19
  // history/sources/<sha256>.gz one text of a project file (server/sourcestore.ts)
20
20
  // history/snapshots/<id>.json.gz a snapshot's manifest: module → content hash, and module →
21
21
  // the text its build compiled (`sources`)
22
+ //
23
+ // The sources outside the project — the packages', Lean's core's — are not kept (HistorySpec
24
+ // decision 24, the owner's of 2026-10-20): a snapshot records each package's revision as the
25
+ // lake-manifest pinned it (`packages`; the core's is its toolchain), and a past build shows an
26
+ // outside declaration's source only where its package is at that revision now.
22
27
  // history/index.jsonl one line per snapshot (SnapshotInfo), appended; the last line
23
28
  // of an id is what it is (a build read again supersedes)
24
29
  //
@@ -72,6 +77,42 @@ export function commitNow(root) {
72
77
  const status = git(root, "status", "--porcelain", "--untracked-files=no", "--", "*.lean");
73
78
  return { hash, branch: branch && branch !== "HEAD" ? branch : null, ...(status ? { dirty: true } : {}) };
74
79
  }
80
+ /** Each package's revision as a lake-manifest's text pins it (a past build's, from its commit):
81
+ * name → rev; null where the text is not a manifest. */
82
+ export function manifestRevisions(text) {
83
+ try {
84
+ const m = JSON.parse(text);
85
+ if (!Array.isArray(m.packages))
86
+ return null;
87
+ const out = {};
88
+ for (const p of m.packages)
89
+ if (typeof p?.name === "string" && p.name && typeof p.rev === "string" && p.rev)
90
+ out[p.name] = p.rev;
91
+ return out;
92
+ }
93
+ catch {
94
+ return null;
95
+ }
96
+ }
97
+ /** Give the snapshots read before 0.7.0 recorded them their packages' revisions (HistorySpec
98
+ * decision 24): each one's commit's lake-manifest.json, where its commit is known (not guessed) and
99
+ * its `.lean` files were that commit's (not dirty); read-only git, once (a snapshot given them is
100
+ * not looked at again). How many were given theirs. */
101
+ export function backfillPackages(h, root) {
102
+ let n = 0;
103
+ for (const s of h.list()) {
104
+ const c = s.commit;
105
+ if (s.packages || !c || c.guessed || c.dirty || !/^[0-9a-f]{7,64}$/.test(c.hash))
106
+ continue;
107
+ const text = git(root, "show", `${c.hash}:./lake-manifest.json`);
108
+ const revs = text === null ? null : manifestRevisions(text);
109
+ if (!revs)
110
+ continue;
111
+ h.annotate(s.id, { packages: { revs, from: "commit" } });
112
+ n++;
113
+ }
114
+ return n;
115
+ }
75
116
  /** The project's git source and the commit checked out, as a page may show them (an artwork's foot,
76
117
  * ExportSpec decision 19): the remote's address (`origin`, else the first) with no user name or
77
118
  * password (sourceAddress); null where the project is not a git repository. Read-only, as `git`. */
@@ -213,7 +254,7 @@ function records(g) {
213
254
  r.out.push([src, at.get(dst), m]);
214
255
  }
215
256
  }
216
- const externals = g.externals.map((e) => ({ name: e.name, kind: e.kind, module: e.module, ax: axNames(e.ax) })).sort((a, b) => (a.name < b.name ? -1 : 1));
257
+ const externals = g.externals.map((e) => ({ name: e.name, kind: e.kind, module: e.module, ax: axNames(e.ax), ...(e.range ? { range: e.range } : {}) })).sort((a, b) => (a.name < b.name ? -1 : 1));
217
258
  return { modules: [...byModule.values()].sort((a, b) => (a.module < b.module ? -1 : 1)), externals, edges };
218
259
  }
219
260
  function snapNode(v, g, ax) {
@@ -419,6 +460,8 @@ export class History {
419
460
  ...(same?.renames ? { renames: same.renames } : {}),
420
461
  ...(texts ? { sources: texts } : {}),
421
462
  ...(o.tool ? { tool: o.tool } : {}),
463
+ // the packages' revisions as read now; a build read again before 0.7.0 keeps what was found
464
+ ...(o.packages ? { packages: { revs: o.packages, from: "read" } } : same?.packages ? { packages: same.packages } : {}),
422
465
  };
423
466
  this.save(info);
424
467
  this.readOf(id).add(o.fingerprint);
@@ -474,6 +517,11 @@ export class History {
474
517
  const text = ref.blob ? this.sources.text(ref.blob) : null;
475
518
  return { ref: ref.blob && text === null ? { ...ref, blob: undefined, why: "its kept text cannot be read" } : ref, text };
476
519
  }
520
+ /** The modules snapshot `id`'s outside declarations are in. */
521
+ outsideModulesOf(id) {
522
+ const g = this.graph(id);
523
+ return new Set(g ? g.nodes.slice(g.projectCount).map((v) => v.module) : []);
524
+ }
477
525
  /** The modules snapshot `id` holds. */
478
526
  modulesOf(id) {
479
527
  return Object.keys(this.manifest(id)?.modules ?? {}).sort();
@@ -523,7 +571,7 @@ export class History {
523
571
  }
524
572
  const projectCount = nodes.length;
525
573
  for (const e of externals)
526
- nodes.push({ name: e.name, kind: e.kind, module: e.module, type: "", ax: e.ax, hash: "", ext: true });
574
+ nodes.push({ name: e.name, kind: e.kind, module: e.module, type: "", ax: e.ax, hash: "", ext: true, ...(e.range ? { range: e.range } : {}) });
527
575
  const index = new Map(nodes.map((v, i) => [v.name, i]));
528
576
  const edges = [];
529
577
  recs.forEach((r, k) => {
@@ -770,7 +818,7 @@ export function pageGraph(g, identity) {
770
818
  };
771
819
  const nodes = g.nodes.map((v) => {
772
820
  if (v.ext)
773
- return { name: v.name, kind: v.kind, module: v.module, ax: axOf(v.ax), ext: true };
821
+ return { name: v.name, kind: v.kind, module: v.module, ax: axOf(v.ax), ext: true, ...(v.range ? { range: v.range } : {}) };
774
822
  const { ax, hash, shape: _s, refs: _r, ...rest } = v;
775
823
  return { ...rest, ax: axOf(ax), hash: snapVersion(v, identity), ...(v.shape ? { kernel: hash } : {}) };
776
824
  });
@@ -18,6 +18,7 @@
18
18
  import { dirname } from "node:path";
19
19
  import { MAX_ARCHIVE_KEYS, validKey } from "./lostfound.js";
20
20
  import { offThread, runJob } from "./historythread.js";
21
+ import { outsideSource } from "./outside.js";
21
22
  const no = (status, error) => ({ status, body: { error } });
22
23
  const ok = (body) => ({ status: 200, body });
23
24
  /** the parts of the last snapshots asked, per history, by snapshot, build read and renames */
@@ -87,10 +88,13 @@ export async function snapshotParts(w, id) {
87
88
  /** Module `module`'s text at snapshot `id`'s build (GET /source; HistorySpec decision 23): the
88
89
  * text its build was compiled from, with its Lake hash and how it was matched to the build, or
89
90
  * why it is not kept. Never another text. */
90
- export function pastSource(h, id, module) {
91
+ export function pastSource(h, id, module, outsideNow) {
91
92
  const s = h.get(id);
92
93
  const t = h.textOf(id, module);
93
94
  const build = { snapshot: id, at: s.at, commit: s.commit };
95
+ // a module of the outside world that build referred to (HistorySpec decision 24)
96
+ if (!t && outsideNow && !h.modulesOf(id).includes(module) && h.outsideModulesOf(id).has(module))
97
+ return pastOutside(s, module, outsideNow);
94
98
  if (!t) {
95
99
  const why = h.sourcesOf(id) === null ? "the texts of this build are still being looked for" : h.modulesOf(id).includes(module) ? "its module has no file of the project" : `the build has no module ${module.slice(0, 300)}`;
96
100
  return { status: 404, body: { error: `The text of ${module.slice(0, 300)} at this build is not kept: ${why}.`, kept: false, why, ...build } };
@@ -99,6 +103,32 @@ export function pastSource(h, id, module) {
99
103
  return { status: 404, body: { error: `The text of ${module} at this build is not kept: ${t.ref.why ?? "it was not found"}.`, kept: false, why: t.ref.why ?? null, file: t.ref.file, ...build } };
100
104
  return { status: 200, body: { module, file: t.ref.file, text: t.text, lake: t.ref.lake ?? null, check: t.ref.check, from: t.ref.from ?? null, ...build } };
101
105
  }
106
+ /** A short revision, as the answers say it: a commit's first seven characters, a release whole. */
107
+ const shortRev = (r) => (!r ? "an unrecorded revision" : /^[0-9a-f]{40,64}$/.test(r) ? r.slice(0, 7) : r);
108
+ /** Outside module `module`'s text at snapshot `s`'s build (HistorySpec decision 24, the owner's of
109
+ * 2026-10-20): outside sources are not kept per build, so it is the file as it is now where its
110
+ * package is at the revision that build had — the lake-manifest's `rev` then, recorded with the
111
+ * snapshot; for Lean's core, its toolchain — and otherwise not kept, said so with both revisions.
112
+ * `check: "rev"`: matched to the build by its package's revision. */
113
+ export function pastOutside(s, module, outsideNow) {
114
+ const build = { snapshot: s.id, at: s.at, commit: s.commit };
115
+ const no = (why, file) => ({ status: 404, body: { error: `The text of ${module.slice(0, 300)} at this build was not kept: ${why}.`, kept: false, why, outside: true, ...(file ? { file } : {}), ...build } });
116
+ const now = outsideNow(module);
117
+ if (!now)
118
+ return no("outside sources are not kept per build, and its file is not found outside the project now");
119
+ const p = now.file.package;
120
+ const revs = s.packages?.revs;
121
+ const then = p.core ? s.toolchain : revs && Object.hasOwn(revs, p.name) ? revs[p.name] : null;
122
+ const rev = p.core ? now.toolchain : p.rev;
123
+ if (!p.core && !s.packages)
124
+ return no(`outside sources are not kept per build, and the revisions of this build's packages were not recorded`, now.file.file);
125
+ if (!then || !rev || then !== rev)
126
+ return no(`outside sources are not kept per build, and ${p.core ? `the toolchain, whose core it is in, was ${then} then and is ${rev} now` : `${p.name} was at ${shortRev(then)} then and is at ${shortRev(rev)} now`}`, now.file.file);
127
+ const src = outsideSource(now.file);
128
+ if (!src)
129
+ return no("outside sources are not kept per build, and its file cannot be read now", now.file.file);
130
+ return { status: 200, body: { module, file: src.file, text: src.text, lake: null, check: "rev", from: "outside", outside: src.outside, ...build } };
131
+ }
102
132
  /** A snapshot named in the query, `id` (or another key): the snapshot, or why not. The latest
103
133
  * build's where it is left out and `dflt` says so. */
104
134
  function snapshotOf(w, a, key, dflt) {
@@ -198,7 +228,8 @@ export async function historyAnswer(w, a, refuse = () => null) {
198
228
  const module = a.query.get("module") ?? "";
199
229
  if (!module || module.length > 2000)
200
230
  return no(400, "Say which module: module=<its name>.");
201
- return pastSource(h, id, module);
231
+ // asked of the world as a method: the live server's reads its own state
232
+ return pastSource(h, id, module, w.outsideNow && ((m) => w.outsideNow(m)));
202
233
  }
203
234
  if (path === "/diff") {
204
235
  const from = snapshotOf(w, a, "from", false);
@@ -273,6 +304,7 @@ export function historyWorld(world) {
273
304
  lastHad: (name) => world.lastHad?.(name) ?? null,
274
305
  archiveEntries: (keys, on, who) => world.archiveEntries?.(keys, on, who) ?? { status: 404, body: { error: "not found" } },
275
306
  following: () => world.following?.() ?? null,
307
+ outsideNow: (module) => world.outsideNow?.(module) ?? null,
276
308
  };
277
309
  }
278
310
  /** The same, as endpoints of the agents' API (server/agent.ts): reading only, at every level. */
@@ -6,7 +6,10 @@
6
6
  // lakefile in the directory it was started from. Started elsewhere with the project's LEAN_PATH,
7
7
  // it reads the `.olean` files the owner's builds left and writes nothing (SPEC.md: "No .lake
8
8
  // conflict"). It elaborates the file it is asked about once, then answers hovers in milliseconds.
9
- // At most two files are kept open; the server stops after ten idle minutes.
9
+ // At most two files are kept open; the server stops after ten idle minutes. A file outside the
10
+ // project — a package's, Lean's core's, whose source the window shows too (the owner's decision of
11
+ // 2026-10-20; server/outside.ts) — is opened by the same Lean in the same way: elaborated against
12
+ // the `.olean` files of what it imports, nothing built.
10
13
  //
11
14
  // A name in a hover card opens a card of its own: what Lean says about a declaration by name is
12
15
  // asked in a scratch file of VisualProof's (in the project's cache, never in the project) that
@@ -358,10 +361,11 @@ export class LeanHover {
358
361
  this.idle.unref();
359
362
  }
360
363
  /** Have Lean elaborate a file (its present text), keeping at most KEEP_OPEN open. */
361
- async open(rel, text, hash) {
364
+ async open(file, text, hash) {
362
365
  await this.start();
363
366
  this.touch();
364
- const uri = pathToFileURL(join(this.project.root, rel)).href;
367
+ const rel = typeof file === "string" ? file : file.name;
368
+ const uri = pathToFileURL(typeof file === "string" ? join(this.project.root, file) : file.path).href;
365
369
  let doc = this.docs.get(rel);
366
370
  if (doc)
367
371
  this.unstall(doc, doc.processing >= 0);
@@ -397,10 +401,10 @@ export class LeanHover {
397
401
  }
398
402
  /** What is at (line, character) of the file — UTF-16 columns, as the page counts them. Waits
399
403
  * up to `waitMs` for Lean to elaborate that far, then says how far it is. */
400
- async hover(rel, text, hash, line, character, waitMs) {
404
+ async hover(file, text, hash, line, character, waitMs) {
401
405
  let doc;
402
406
  try {
403
- doc = await this.open(rel, text, hash);
407
+ doc = await this.open(file, text, hash);
404
408
  }
405
409
  catch (e) {
406
410
  return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
@@ -417,10 +421,10 @@ export class LeanHover {
417
421
  * hover's code — a declaration's full name where the position refers to one, a variable's name
418
422
  * where it is one — or null where Lean has nothing to say. This is how the source window links
419
423
  * every name to what it means, dot notation and `open`s included, as go-to-definition would. */
420
- async names(rel, text, hash, positions, waitMs) {
424
+ async names(file, text, hash, positions, waitMs) {
421
425
  let doc;
422
426
  try {
423
- doc = await this.open(rel, text, hash);
427
+ doc = await this.open(file, text, hash);
424
428
  }
425
429
  catch (e) {
426
430
  return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
@@ -131,7 +131,7 @@ export function headerText(s) {
131
131
  * in the agents' answers. This is where a private reader's anonymity lives: whatever arranges a
132
132
  * board — pins, folds, re-layouts, scopes and clusterings, views made, renamed and deleted, notes
133
133
  * left on a board — takes its author from here, through server/views.ts (`handle`, whose `me` is
134
- * this) and main.ts (an undo). The review is not layout: opinions, targets, key marks and trust
134
+ * this) and appsite.ts (an undo). The review is not layout: opinions, targets, key marks and trust
135
135
  * take the caller's own name, and need one. */
136
136
  export function layoutAuthor(caller) {
137
137
  return caller.private ? null : caller.name;
@@ -1,5 +1,5 @@
1
1
  // The library's routes for pages (AttachmentSpec decisions 1–11): `/api/library/…`, behind the same
2
- // access check as the page (main.ts lets a request get here only once it is in). What they do is
2
+ // access check as the page (app.ts lets a request get here only once it is in). What they do is
3
3
  // server/library.ts's, which the agents' endpoints call too (server/agentlibrary.ts); here are only
4
4
  // what HTTP needs: who asks, the body — a file's bytes as they are, sent with the file's name in the
5
5
  // query, or JSON — and answers that are bytes (a file, a page, a clip), sent so that a browser never
@@ -55,7 +55,7 @@ function readBytes(req, limit) {
55
55
  });
56
56
  }
57
57
  /** An uploaded file's bytes, the body as it is; or null, the request answered already (413) where it
58
- * is larger than a file of the library may be. The agents' upload reads its body so too (main.ts). */
58
+ * is larger than a file of the library may be. The agents' upload reads its body so too (appagent.ts). */
59
59
  export async function readUpload(req, res) {
60
60
  try {
61
61
  return await readBytes(req, MAX_FILE);
@@ -63,7 +63,7 @@ export async function readUpload(req, res) {
63
63
  catch (e) {
64
64
  if (!(e instanceof TooLarge))
65
65
  throw e;
66
- // the rest is read and thrown away, and the answer goes once it has all come, as main.ts's
66
+ // the rest is read and thrown away, and the answer goes once it has all come, as send.ts's
67
67
  // tooLarge does: a connection closed while the client still sends is reset on some systems
68
68
  let done = false;
69
69
  const answer = () => {