visualproof 0.0.0-stage → 0.1.0

package/dist/server/pipeline.js

@@ -0,0 +1,156 @@
+// From a project to what the page loads: extraction (or a saved one), then the view, both cached
+// in the project's cache directory by the extraction's fingerprint (server/dirs.ts); the memory of
+// the layout last served is the site's.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+import { LAYOUT_VERSION } from "../shared/graph.js";
+import { cachedExtraction, extract, loadSaved, prune } from "./extract.js";
+import { memoryOf } from "../shared/layout.js";
+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)), "..");
+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
+ *  installed package serves it as it is, and has no esbuild to make another. A checkout has none. */
+export const PREBUILT = join(WEB, "bundle");
+const prebuilt = existsSync(join(PREBUILT, "app.js"));
+/** The page's bundle under a cache root: one folder per checkout of the tool, so that two never
+ *  write over each other's. */
+export function bundleDirIn(cacheRoot) {
+    return join(cacheRoot, "web", createHash("sha1").update(SRC).digest("hex").slice(0, 8));
+}
+let bundle = null;
+/** Where the page's bundle is made and served from: set once at start, from `--cache`. */
+export function useBundleDir(dir) {
+    bundle = dir;
+}
+export function bundleDir() {
+    if (prebuilt)
+        return PREBUILT;
+    return (bundle ??= bundleDirIn(cacheHome()));
+}
+/** Bumped when the page data derived from an extraction changes shape or layout, so cached
+ *  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;
+function loadMemory(siteDir) {
+    try {
+        const mem = JSON.parse(readFileSync(join(siteDir, "layout-memory.json"), "utf8"));
+        return mem.version === LAYOUT_VERSION ? mem : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveMemory(siteDir, fingerprint, meta, before) {
+    const mem = { version: LAYOUT_VERSION, fingerprint, layouts: {}, ...(before !== undefined ? { before } : {}) };
+    for (const mode of ["namespace", "module"])
+        mem.layouts[mode] = memoryOf(meta.layouts[mode], meta.nodes);
+    mkdirSync(siteDir, { recursive: true });
+    writeFileSync(join(siteDir, "layout-memory.json"), JSON.stringify(mem));
+}
+export async function prepare(project, dirs, saved, log, opts = {}) {
+    // `reuse`: lay out an extraction already held, without reading the build (which may be
+    // half-written right now); `extraction`: one in hand (the usage pass's, merged); `provisional`:
+    // the graph waits for its usage pass; `completes`: the fingerprint of the build's extraction that
+    // this graph, the usage pass's merged, completes
+    const held = opts.extraction ?? (opts.reuse ? cachedExtraction(dirs.cache, opts.reuse) : null);
+    if (opts.reuse && !held)
+        throw new Error("the graph on screen is no longer cached; it is laid out afresh at the next build");
+    const ex = held ?? (saved ? loadSaved(saved) : await extract(project, dirs, log));
+    if (!opts.extraction)
+        log(ex.cached ? `extraction ${ex.fingerprint} reused` : `extraction ${ex.fingerprint} done`);
+    const usage = ex.graph.usage ?? null;
+    const viewDir = join(dirs.cache, "view");
+    mkdirSync(viewDir, { recursive: true });
+    const metaFile = join(viewDir, `${ex.fingerprint}-v${VIEW_VERSION}.meta.json.gz`);
+    const edgeFile = join(viewDir, `${ex.fingerprint}-v${VIEW_VERSION}.edges.bin.gz`);
+    const memory = opts.freshLayout ? null : loadMemory(dirs.site);
+    // a cached view is only right if it is the one this site last served (a cache may outlive its
+    // site, or serve another): otherwise lay out again, from the memory of what was last served
+    const current = memory !== null && memory.fingerprint === ex.fingerprint;
+    if (!opts.freshLayout && current && existsSync(metaFile) && existsSync(edgeFile)) {
+        return { fingerprint: ex.fingerprint, cached: ex.cached, metaGz: readFileSync(metaFile), edgesGz: readFileSync(edgeFile), usage };
+    }
+    // the usage pass completing the build last laid out: against what that provisional layout was
+    // laid out against, so that the build's graph is laid out as if the notation had come with it
+    const completing = memory !== null && opts.completes !== undefined && memory.fingerprint === opts.completes && memory.before !== undefined;
+    const against = completing ? (memory.before ?? null) : (memory?.layouts ?? null);
+    const view = await buildViewOffThread(project, ex, log, against);
+    saveMemory(dirs.site, ex.fingerprint, view.meta, opts.provisional ? against : undefined);
+    const metaGz = gzipSync(JSON.stringify(view.meta));
+    const edgesGz = gzipSync(Buffer.from(view.edges.buffer, view.edges.byteOffset, view.edges.byteLength));
+    writeFileSync(metaFile, metaGz);
+    writeFileSync(edgeFile, edgesGz);
+    prune(viewDir, /\.meta\.json\.gz$/, 3);
+    prune(viewDir, /\.edges\.bin\.gz$/, 3);
+    return { fingerprint: ex.fingerprint, cached: ex.cached, metaGz, edgesGz, usage };
+}
+function readdirRec(dir) {
+    const out = [];
+    for (const ent of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, ent.name);
+        if (ent.isDirectory())
+            out.push(...readdirRec(p));
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** The page is bundled when its sources are newer than the bundle, so a checkout runs without a
+ *  separate build step; an installed package serves the bundle it was built with (`PREBUILT`).
+ *  What the page shares with the server (shared/) is its source too. Bundled into a folder of its
+ *  own beside the bundle's, then moved into it a file at a time: a server reading the bundle
+ *  meanwhile never reads a file half written. */
+export async function ensureBundle() {
+    if (prebuilt)
+        return;
+    const dist = bundleDir();
+    const out = join(dist, "app.js");
+    let newest = 0;
+    for (const f of [...readdirRec(join(WEB, "src")), ...readdirRec(join(SRC, "shared"))])
+        newest = Math.max(newest, statSync(f).mtimeMs);
+    const beside = ["layout.js", "edges.js", "pdfworker.js"].every((f) => existsSync(join(dist, f)));
+    if (existsSync(out) && beside && statSync(out).mtimeMs >= newest)
+        return;
+    mkdirSync(dirname(dist), { recursive: true });
+    const tmp = mkdtempSync(`${dist}.tmp-`);
+    try {
+        await bundlePage(tmp);
+        mkdirSync(dist, { recursive: true });
+        for (const f of readdirSync(tmp))
+            renameSync(join(tmp, f), join(dist, f));
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** The page's bundle, from `web/src/` of a checkout, into `outdir`: by `ensureBundle` at start, and
+ *  by scripts/build.mjs into the package. Beside the page, the workers that lay out the Time
+ *  Machine's past graphs (web/src/layoutworker.ts) and choose the overview's edges
+ *  (web/src/edgeworker.ts) off the page's thread. */
+export async function bundlePage(outdir, sourcemap = true) {
+    const esbuild = await import("esbuild");
+    const srcDir = join(WEB, "src");
+    await esbuild.build({
+        // pdf.js's worker, which reads the library's PDFs for the reference window (AttachmentSpec
+        // decision 11), is bundled beside the page's own workers and served as they are: no outside
+        // service. Its legacy build, as the page's, for browsers that lack what the modern one uses
+        entryPoints: { app: join(srcDir, "main.ts"), layout: join(srcDir, "layoutworker.ts"), edges: join(srcDir, "edgeworker.ts"), pdfworker: fileURLToPath(import.meta.resolve("pdfjs-dist/legacy/build/pdf.worker.min.mjs")) },
+        bundle: true,
+        format: "esm",
+        // the owner reads in Safari: what Safari 16 lacks of the syntax (pdf.js's class static blocks; a
+        // regular expression's lookbehind, read at run time instead) is lowered
+        target: ["es2022", "safari16"],
+        sourcemap,
+        outdir,
+        logLevel: "warning",
+    });
+}

package/dist/server/poppler.js

@@ -0,0 +1,251 @@
+// What the server reads of a PDF (AttachmentSpec, "Implementation notes"): poppler's tools, run on
+// the file in the library's store — `pdfinfo` for its title, its pages and their sizes,
+// `pdftotext -bbox-layout` for its words and where each is on its page, `pdftoppm` for a page as an
+// image and for a clip, a region of a page (what a note will carry, decision 12). The words are read
+// once per file, every page at a time, and kept; images are kept by file, page, region and width,
+// so that the same request is answered from the disk.
+//
+// Every place is in the page's own fractions (0–1, from its top left), as a link's region is
+// (shared/library.ts), so that nothing depends on how large the page is drawn. A PDF is untrusted
+// input: the tools are run without a shell, on a path of the server's own, with a time limit, and at
+// most two at once.
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { wordsText } from "../shared/library.js";
+/** the longest each tool may run, in ms */
+const INFO_MS = 20_000;
+const TEXT_MS = 120_000;
+const IMAGE_MS = 60_000;
+/** the most the tools' output is read, in bytes: the words of a long paper, a large page */
+const MAX_OUT = 256 * 1024 * 1024;
+/** how many of the tools run at once */
+const AT_ONCE = 2;
+let running = 0;
+const waiting = [];
+/** Run a tool, at most AT_ONCE at a time; its standard output, or why it failed. */
+async function run(cmd, args, ms) {
+    if (running >= AT_ONCE)
+        await new Promise((ok) => waiting.push(ok));
+    running++;
+    try {
+        return await new Promise((ok, no) => {
+            execFile(cmd, args, { timeout: ms, maxBuffer: MAX_OUT, encoding: "buffer", windowsHide: true }, (err, out, errOut) => {
+                if (err)
+                    no(new Error(`${cmd} failed: ${(errOut?.toString("utf8").trim().split("\n").pop() ?? "") || err.message}`));
+                else
+                    ok(out);
+            });
+        });
+    }
+    finally {
+        running--;
+        waiting.shift()?.();
+    }
+}
+/** A PDF's own title (where it has one that says something), its pages, and each page's size. */
+export async function pdfInfo(file) {
+    const first = (await run("pdfinfo", ["-enc", "UTF-8", file], INFO_MS)).toString("utf8");
+    const pages = Number(/^Pages:[ \t]+(\d+)/m.exec(first)?.[1] ?? "0");
+    const title = /^Title:[ \t]*(.*)$/m.exec(first)?.[1]?.trim() || null;
+    const sizes = [];
+    if (pages > 0) {
+        // every page's size and rotation, so that a region in a page's fractions is read on that page
+        const all = (await run("pdfinfo", ["-f", "1", "-l", String(pages), file], INFO_MS)).toString("utf8");
+        const size = new Map();
+        const rot = new Map();
+        for (const m of all.matchAll(/^Page\s+(\d+) size:\s+([\d.]+) x ([\d.]+) pts/gm))
+            size.set(Number(m[1]), { w: Number(m[2]), h: Number(m[3]) });
+        for (const m of all.matchAll(/^Page\s+(\d+) rot:\s+(\d+)/gm))
+            rot.set(Number(m[1]), Number(m[2]));
+        for (let p = 1; p <= pages; p++) {
+            const s = size.get(p) ?? size.get(1) ?? { w: 612, h: 792 };
+            sizes.push((rot.get(p) ?? 0) % 180 ? { w: s.h, h: s.w } : s);
+        }
+    }
+    return { title: usefulTitle(title), pages, sizes };
+}
+/** A title a PDF gives itself that says something: not empty, not a file name or a word-processor's
+ *  placeholder, nor only an identifier (an arXiv paper's, a DOI), which names a paper without saying
+ *  what it is. */
+export function usefulTitle(t) {
+    if (!t)
+        return null;
+    const s = t.replace(/\s+/g, " ").trim();
+    if (!s || /^(untitled|microsoft word - .*|.*\.(docx?|tex|dvi|pdf))$/i.test(s) || IDENTIFIER.test(s))
+        return null;
+    return s.length > 300 ? s.slice(0, 299) + "…" : s;
+}
+/** A paper's identifier alone: arXiv's, new style (`1910.09336`, `1910.09336v1`) or old
+ *  (`math/0211159v1`, `math.GT/0309136`), maybe as `arXiv:…` and with its category after it in
+ *  brackets, as arXiv stamps it; or a DOI, bare, as `doi:…` or as its address. */
+const IDENTIFIER = /^(?:(?:arxiv:\s*)?(?:\d{4}\.\d{4,5}|[a-z-]+(?:\.[a-z-]+)?\/\d{7})(?:v\d+)?(?:\s*\[[^\]]+\])?|(?:doi:\s*|https?:\/\/(?:dx\.)?doi\.org\/)?10\.\d{4,9}\/\S+)$/i;
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+const unescapeXml = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos);/gi, (_, e) => e[0] === "#" ? String.fromCodePoint(e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : Number(e.slice(1))) : ENTITIES[e.toLowerCase()] ?? "");
+const frac = (v) => Math.round(Math.min(1, Math.max(0, v)) * 1e4) / 1e4;
+/** `pdftotext -bbox-layout`'s XHTML, read: every page's words with their boxes. */
+export function parseBboxLayout(xhtml) {
+    const out = [];
+    const pageRe = /<page width="([\d.]+)" height="([\d.]+)">([\s\S]*?)<\/page>/g;
+    for (let m = pageRe.exec(xhtml), p = 1; m; m = pageRe.exec(xhtml), p++) {
+        const width = Number(m[1]), height = Number(m[2]);
+        const words = [];
+        const lines = [];
+        for (const line of m[3].matchAll(/<line[^>]*>([\s\S]*?)<\/line>/g)) {
+            lines.push(words.length);
+            for (const w of line[1].matchAll(/<word xMin="([\d.-]+)" yMin="([\d.-]+)" xMax="([\d.-]+)" yMax="([\d.-]+)">([\s\S]*?)<\/word>/g)) {
+                // a glyph its font maps to no character comes as a control character: no text
+                const text = unescapeXml(w[5]).replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+                if (text)
+                    words.push([text, frac(Number(w[1]) / width), frac(Number(w[2]) / height), frac(Number(w[3]) / width), frac(Number(w[4]) / height)]);
+            }
+        }
+        out.push({ page: p, width, height, words, lines });
+    }
+    return out;
+}
+/** A page's text as its words make it: a line's words joined by spaces, lines by line breaks; and
+ *  where each word starts in it. */
+export function pageText(p) {
+    return wordsText(p.words, p.lines);
+}
+/** Find `q` in every page's text: case and runs of white space read loosely; at most `most`
+ *  matches, in page order. */
+export function searchWords(pages, q, most = 100) {
+    const want = q.replace(/\s+/g, " ").trim().toLowerCase();
+    const matches = [];
+    if (!want)
+        return { matches, more: false };
+    for (const p of pages) {
+        const { text, starts } = pageText(p);
+        const flat = text.replace(/\n/g, " ").toLowerCase();
+        for (let at = flat.indexOf(want); at >= 0; at = flat.indexOf(want, at + 1)) {
+            if (matches.length >= most)
+                return { matches, more: true };
+            const end = at + want.length;
+            const first = Math.max(0, upper(starts, at));
+            const last = Math.max(first, upper(starts, end - 1));
+            const boxes = p.words.slice(first, last + 1).map(([, x0, y0, x1, y1]) => [x0, y0, x1, y1]);
+            matches.push({ page: p.page, boxes, text: text.slice(at, end), before: text.slice(Math.max(0, at - 60), at).replace(/\s+/g, " "), after: text.slice(end, end + 60).replace(/\s+/g, " ") });
+        }
+    }
+    return { matches, more: false };
+}
+/** The index of the last start at or before `at`. */
+function upper(starts, at) {
+    let lo = 0, hi = starts.length - 1, best = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (starts[mid] <= at) {
+            best = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    return best;
+}
+/** The widths a page or a clip is drawn at: a few, so that what is kept stays small. */
+const WIDTHS = [400, 800, 1200, 1600, 2000];
+export const clampWidth = (w) => WIDTHS.find((x) => x >= w) ?? WIDTHS[WIDTHS.length - 1];
+/** A PDF's words, pages and images, kept in `cacheDir/<sha>/`. */
+export class PdfReader {
+    cacheDir;
+    words = new Map();
+    infos = new Map();
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir;
+    }
+    dir(sha) {
+        const d = join(this.cacheDir, sha);
+        mkdirSync(d, { recursive: true });
+        return d;
+    }
+    /** What `pdfinfo` says of it, once per run. */
+    info(sha, file) {
+        let p = this.infos.get(sha);
+        if (!p) {
+            p = pdfInfo(file);
+            p.catch(() => this.infos.delete(sha));
+            this.infos.set(sha, p);
+        }
+        return p;
+    }
+    /** Every page's words: read once, kept on disk (gzipped JSON) and in memory for the last few. */
+    allWords(sha, file) {
+        let p = this.words.get(sha);
+        if (!p) {
+            p = (async () => {
+                const kept = join(this.dir(sha), "words.json.gz");
+                if (existsSync(kept)) {
+                    try {
+                        return JSON.parse(gunzipSync(readFileSync(kept)).toString("utf8"));
+                    }
+                    catch {
+                        // a file cut short: read again
+                    }
+                }
+                const xhtml = (await run("pdftotext", ["-bbox-layout", "-enc", "UTF-8", file, "-"], TEXT_MS)).toString("utf8");
+                const pages = parseBboxLayout(xhtml);
+                writeAtomic(kept, gzipSync(JSON.stringify(pages)));
+                return pages;
+            })();
+            p.catch(() => this.words.delete(sha));
+            if (this.words.size >= 8)
+                this.words.delete(this.words.keys().next().value);
+            this.words.set(sha, p);
+        }
+        return p;
+    }
+    /** A page drawn as a PNG `width` pixels wide (one of a few widths). */
+    async page(sha, file, page, width) {
+        const w = clampWidth(width);
+        const kept = join(this.dir(sha), `page-${page}-w${w}.png`);
+        if (existsSync(kept))
+            return readFileSync(kept);
+        const tmp = join(this.dir(sha), `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+        try {
+            await run("pdftoppm", ["-png", "-f", String(page), "-l", String(page), "-singlefile", "-scale-to-x", String(w), "-scale-to-y", "-1", file, tmp], IMAGE_MS);
+            renameSync(`${tmp}.png`, kept);
+        }
+        finally {
+            rmSync(`${tmp}.png`, { force: true });
+        }
+        return readFileSync(kept);
+    }
+    /** A region of a page drawn as a PNG about `width` pixels wide: what a clip shows. */
+    async clip(sha, file, page, size, region, width) {
+        const w = clampWidth(width);
+        const r = region.map((x) => Math.round(x * 1e4) / 1e4);
+        const kept = join(this.dir(sha), `clip-${page}-${r.join("_")}-w${w}.png`);
+        if (existsSync(kept))
+            return readFileSync(kept);
+        // the resolution at which the region is `w` pixels wide, within reason
+        const dpi = Math.min(600, Math.max(36, (w / ((r[2] - r[0]) * size.w)) * 72));
+        const px = (v, of) => Math.round((v * of * dpi) / 72);
+        const x = px(r[0], size.w), y = px(r[1], size.h);
+        const W = Math.max(1, px(r[2], size.w) - x), H = Math.max(1, px(r[3], size.h) - y);
+        const tmp = join(this.dir(sha), `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+        try {
+            await run("pdftoppm", ["-png", "-f", String(page), "-l", String(page), "-singlefile", "-r", dpi.toFixed(2), "-x", String(x), "-y", String(y), "-W", String(W), "-H", String(H), file, tmp], IMAGE_MS);
+            renameSync(`${tmp}.png`, kept);
+        }
+        finally {
+            rmSync(`${tmp}.png`, { force: true });
+        }
+        return readFileSync(kept);
+    }
+    /** What is kept of a file goes (its bytes purged). */
+    forget(sha) {
+        this.words.delete(sha);
+        this.infos.delete(sha);
+        rmSync(join(this.cacheDir, sha), { recursive: true, force: true });
+    }
+}
+/** Write a file whole or not at all: to a name of its own first, then renamed into place. */
+export function writeAtomic(path, data) {
+    const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+    writeFileSync(tmp, data);
+    renameSync(tmp, path);
+}

package/dist/server/presence.js

@@ -0,0 +1,252 @@
+// Who is here (CollabSpec decision 4): one entry per open page, kept by a heartbeat every ten
+// seconds and dropped when the page's event stream closes or its heartbeats stop. Every change goes
+// out to every page as the whole list — a few readers, so a few hundred bytes.
+//
+// A page's entry is its event stream's (server/live.ts): the server names each stream with a public
+// id, the one every page is told, and hands the page alone a secret its heartbeats carry. So no page
+// can speak for another, rename it or make it leave, and there are no more entries than streams.
+//
+// An agent (AgentSpec decision 1) has no page and no event stream: one entry per agent name, kept
+// by its requests. An agent thinks between them for longer than a page waits between heartbeats, so
+// it is shown away after a minute without one and gone after three, or when it says it leaves. At
+// most MAX_AGENTS are listed: a name beyond them is served, and listed once one goes.
+//
+// An agent with a token of its own (server/tokens.ts) is one entry by its token, not by the name it
+// acts under, so that nobody else can speak for it by giving that name; and it is listed as long as
+// its token is in force (AgentSpec decision 8), with its state as server/talk.ts infers it from what
+// it does — listening, thinking, working or offline — and when it was last seen. It is shown away
+// only while offline.
+//
+// A private page (CollabSpec decision 8) is an entry with nothing in it — no name, no place — and is
+// never listed: every page is told how many there are, and nothing else of them. Its stream is named
+// afresh when it goes private and when it shows itself again (server/live.ts), so its entries under
+// either id say nothing of the other.
+//
+// What an agent asks to follow the people it helps (GET /api/agent/companion) waits for the list to
+// change: `rev` counts the changes that matter to it — someone came, went, moved, went idle, an
+// agent went offline or came back — and leaves out a camera that moved, which a page reports
+// every second or two while one pans, and what an agent that is not offline does from one request
+// to the next.
+import { createHash } from "node:crypto";
+/** a page not heard from for this long has gone */
+const GONE_MS = 35_000;
+/** an agent without a token not heard from for this long is away, and then gone */
+const AGENT_IDLE_MS = 60_000;
+const AGENT_GONE_MS = 180_000;
+/** the most agents listed at once: every name an agent gives is an entry everyone is sent */
+export const MAX_AGENTS = 32;
+/** The entry an agent's requests stand for: one per name; its id, as pages are told it. */
+export function agentSession(name) {
+    return createHash("sha1").update(`agent\u0000${name}`).digest("hex");
+}
+/** The entry an agent stands for: its token's, or its name's. */
+export function agentKey(who) {
+    const w = typeof who === "string" ? { name: who } : who;
+    return w.token ? createHash("sha1").update(`agent token\u0000${w.token}`).digest("hex") : agentSession(w.name);
+}
+export class Presence {
+    sessions = new Map();
+    /** agents with a token in force, by the token's id */
+    tokens = new Map();
+    /** pages whose event stream closed, and when: a heartbeat sent as one closes (a reload) comes
+     *  after its stream ended, and would keep it on the list — and the views it had open alive
+     *  (server/views.ts) — until it times out */
+    closed = new Map();
+    send;
+    /** the changes an agent following people waits for (GET /api/agent/companion), counted */
+    rev = 0;
+    lastSig = "";
+    waiters = new Set();
+    constructor(send) {
+        this.send = send;
+        setInterval(() => this.expire(), 5000).unref();
+    }
+    /** The list changed: every page is sent it, and an agent waiting for a change that matters to
+     *  it is told. */
+    notify() {
+        const list = this.list();
+        this.send(list);
+        // neither a camera that pans nor what an agent does while online is a move; an agent going
+        // offline or coming back is, and so is a private reader coming or going
+        const sig = JSON.stringify([this.privateCount(), list.map((p) => ({ ...p, view: p.view ? { ...p.view, cam: null } : null, talk: p.talk ? p.talk.state === "offline" : undefined }))]);
+        if (sig === this.lastSig)
+            return;
+        this.lastSig = sig;
+        this.rev++;
+        for (const w of [...this.waiters])
+            w();
+    }
+    /** Resolves once `rev` is not `since` any more, or after `ms`. */
+    waitChange(since, ms) {
+        if (since !== this.rev || ms <= 0)
+            return Promise.resolve();
+        return new Promise((done) => {
+            const end = () => {
+                clearTimeout(timer);
+                this.waiters.delete(end);
+                done();
+            };
+            const timer = setTimeout(end, ms);
+            this.waiters.add(end);
+        });
+    }
+    /** A page says where it is (by its stream's id); or an agent, with each request (`agent`), where
+     *  `view` null keeps the view it gave last. `verified`: the page of someone invited by a personal
+     *  link, whose name is theirs. */
+    beat(id, name, view, idle, agent = false, verified = false) {
+        if (this.closed.has(id))
+            return;
+        const was = this.sessions.get(id);
+        if (!was && agent && [...this.sessions.values()].filter((e) => e.agent).length >= MAX_AGENTS)
+            return;
+        const next = { name, view: view ?? was?.view ?? null, idle, seen: Date.now(), agent, ...(verified && name ? { verified: true } : {}) };
+        this.sessions.set(id, next);
+        const same = was && !was.private && was.name === next.name && was.idle === next.idle && was.agent === next.agent && was.verified === next.verified && JSON.stringify(was.view) === JSON.stringify(next.view);
+        if (!same)
+            this.notify();
+    }
+    /** A private page's heartbeat (CollabSpec decision 8): it is here, and that is all that is kept
+     *  of it — no name, no place, never idle. */
+    beatPrivate(id) {
+        if (this.closed.has(id))
+            return;
+        const was = this.sessions.get(id);
+        this.sessions.set(id, { name: null, view: null, idle: false, seen: Date.now(), agent: false, private: true });
+        if (!was?.private)
+            this.notify();
+    }
+    /** A page named afresh as it went private or showed itself again (server/live.ts): its entry under
+     *  `old` goes, and comes back under `id` — counted, or listed with its name and place — as one
+     *  change, so that no list goes out with the page under both ids, or under neither. */
+    renamed(old, id, priv, name, view, idle, verified = false) {
+        this.sessions.delete(old);
+        this.closed.delete(id);
+        this.sessions.set(id, priv ? { name: null, view: null, idle: false, seen: Date.now(), agent: false, private: true } : { name, view, idle, seen: Date.now(), agent: false, ...(verified && name ? { verified: true } : {}) });
+        this.notify();
+    }
+    /** How many private pages are here: what every page and the agents' companion are told of them. */
+    privateCount() {
+        let n = 0;
+        for (const e of this.sessions.values())
+            if (e.private)
+                n++;
+        return n;
+    }
+    /** Where a page that is listed last said it was; null for any other. */
+    pageView(id) {
+        const e = this.sessions.get(id);
+        return e && !e.agent && !e.private ? e.view : null;
+    }
+    /** An agent's request: it is here, with the view it gave (or the one it gave last). */
+    agentBeat(who, view = null) {
+        if (typeof who !== "string" && who.token) {
+            // its state is server/talk.ts's to say (setTalk); a token that is not listed (ended) is not
+            // listed again
+            const t = this.tokens.get(who.token);
+            if (!t)
+                return;
+            const before = JSON.stringify(t.view);
+            t.view = view ?? t.view;
+            if (JSON.stringify(t.view) !== before)
+                this.notify();
+            return;
+        }
+        const key = agentKey(who);
+        // an agent that said it leaves is back with its next request: it has no stream to reopen
+        this.closed.delete(key);
+        this.beat(key, typeof who === "string" ? who : who.name, view, false, true);
+    }
+    /** What an agent last said it looks at; null when it is not here. */
+    agentView(who) {
+        if (typeof who !== "string" && who.token)
+            return this.tokens.get(who.token)?.view ?? null;
+        return this.sessions.get(agentKey(who))?.view ?? null;
+    }
+    /** A page closed (its event stream ended), or an agent left (its key, agentKey). An agent with a
+     *  token stays listed: it is no longer anywhere. */
+    drop(session) {
+        for (const [id, t] of this.tokens)
+            if (agentKey({ name: t.name, token: id }) === session) {
+                if (t.view) {
+                    t.view = null;
+                    this.notify();
+                }
+                return;
+            }
+        this.closed.set(session, Date.now());
+        if (this.sessions.delete(session))
+            this.notify();
+    }
+    /** The tokens in force (server/tokens.ts): each one's agent is listed, in the state `talkOf`
+     *  says (offline until it is seen), with when its token was last used until it is; an agent whose
+     *  token ended goes. */
+    setTokens(list, talkOf) {
+        let changed = false;
+        const ids = new Set(list.map((r) => r.id));
+        for (const id of [...this.tokens.keys()])
+            if (!ids.has(id)) {
+                this.tokens.delete(id);
+                changed = true;
+            }
+        for (const r of list) {
+            const t = this.tokens.get(r.id);
+            if (t) {
+                t.by = r.by;
+                continue;
+            }
+            const talk = talkOf?.(r.id) ?? { state: "offline", since: new Date().toISOString(), doing: null, status: null, read: 0, lastSeen: null };
+            this.tokens.set(r.id, { name: r.name, by: r.by, view: null, talk: { ...talk, lastSeen: talk.lastSeen ?? r.lastUsed ?? null } });
+            changed = true;
+        }
+        if (changed)
+            this.notify();
+    }
+    /** What an agent with a token does now changed (server/talk.ts). */
+    setTalk(id, talk) {
+        const t = this.tokens.get(id);
+        if (!t)
+            return;
+        t.talk = { ...talk, lastSeen: talk.lastSeen ?? t.talk.lastSeen };
+        this.notify();
+    }
+    /** The token of the agent pages know by `id` (a token agent's entry), or null. */
+    tokenOf(id) {
+        for (const [tok, t] of this.tokens)
+            if (agentKey({ name: t.name, token: tok }) === id)
+                return tok;
+        return null;
+    }
+    /** A page's event stream opened (again, after a lost connection): its heartbeats count. */
+    open(session) {
+        this.closed.delete(session);
+    }
+    /** Who is here, as every page is told: a private page is not (privateCount). */
+    list() {
+        const out = [...this.sessions]
+            .filter(([, e]) => !e.private)
+            .map(([id, e]) => ({ id, name: e.name, view: e.view, idle: e.idle, ...(e.agent ? { agent: true } : {}), ...(e.verified ? { verified: true } : {}) }));
+        for (const [tok, t] of this.tokens)
+            out.push({ id: agentKey({ name: t.name, token: tok }), name: t.name, view: t.view, idle: t.talk.state === "offline", agent: true, talk: t.talk, by: t.by });
+        return out;
+    }
+    /** Pages whose heartbeats stopped go; agents silent for a while are away, then go. */
+    expire(now = Date.now()) {
+        let changed = false;
+        for (const [s, at] of this.closed)
+            if (now - at > GONE_MS)
+                this.closed.delete(s);
+        for (const [s, e] of this.sessions) {
+            if (now - e.seen > (e.agent ? AGENT_GONE_MS : GONE_MS)) {
+                this.sessions.delete(s);
+                changed = true;
+            }
+            else if (e.agent && !e.idle && now - e.seen > AGENT_IDLE_MS) {
+                e.idle = true;
+                changed = true;
+            }
+        }
+        // an agent with a token is away while offline, which server/talk.ts says
+        if (changed)
+            this.notify();
+    }
+}