visualproof 0.3.0 → 0.4.1

package/dist/server/main.js

@@ -39,6 +39,12 @@ import { UPLOAD_PATH } from "./agentlibrary.js";
 import { DEFAULT_LIBRARY_LIMIT, validSha } from "../shared/library.js";
 import { doctor, packageVersion, printReport } from "./doctor.js";
 import { READONLY_PATH } from "./readonly.js";
+import { sendMedia, TIP_PATH, TIPS_DIR, tipClips, tourData, tourVtt } from "./media.js";
+import { withoutReasons } from "../shared/timeline.js";
+import { FROM_PACKAGE, PACKAGE_ROOT, UPDATE_MODES, Updates } from "./updates.js";
+import { RESTART_STATUS, supervise } from "./supervise.js";
+import { stopChildren } from "./children.js";
+import { filmStatus, serveFilm, useFilm } from "./film.js";
 import { finalAnswer, readOnlyAllows, ReadOnlyBounds } from "./readonlygate.js";
 /** The usage, to stderr with status 2 for a command line it cannot read; asked for (`--help`),
  *  to stdout with status 0. */
@@ -47,7 +53,7 @@ function usage(code = 2) {
                                          [--site dir] [--cache dir] [--graph saved.json]
                                          [--identity-header X-Forwarded-User] [--editor URL-template]
                                          [--agents read|advise|full] [--access-key-file file] [--public] [--jobs ${DEFAULT_JOBS}]
-                                         [--public-url https://host] [--library-limit GB]
+                                         [--public-url https://host] [--library-limit GB] [--updates auto|notify|off]
        visualproof purge-file <lean-project> <sha256> [--site dir] [--cache dir]
        visualproof export <lean-project> -o page.html [--label text] [--root Name]... [--graph saved.json]
                                          [--jobs ${DEFAULT_JOBS}] [--site dir] [--cache dir]
@@ -70,7 +76,10 @@ function usage(code = 2) {
   --cache  the root of the caches, which a rebuild makes again: the project's (extractions, the
            usage pass's results, prepared views, typeset documents, Lean's language server's
            folder) in projects/<project>-<hash>/, the Lean programs compiled per toolchain in
-           lean/, the page's bundle in web/. Default: ${cacheHome()}
+           lean/, the page's bundle in web/, VisualProof's own releases in updates.json and the
+           patches downloaded in versions/ (code the servers run: keep the root yours alone),
+           and the tips' tour film in media/.
+           Default: ${cacheHome()}
            (XDG_DATA_HOME and XDG_CACHE_HOME move both homes, on any platform)
 
   --graph  use a saved extraction (a projects/*/extract/*.json of the cache) instead of reading
@@ -127,6 +136,16 @@ function usage(code = 2) {
   --public-url  the address people reach this server at, when it is not the one their browser
            sends (a proxy in front): the prompt Share makes for an agent tells it this address.
 
+  --updates  what the server does with VisualProof's own releases, asked of the npm registry
+           (through npm) at start and once a day: auto (the default) — a patch of the version it
+           runs (0.4.x) is downloaded into the cache and taken at a quiet moment, nobody on a page,
+           open pages reloading where they were; a newer version (0.5.0) is told of, in the log
+           and the help, with the command that installs it, after which the server restarts into
+           it by itself; notify — told of, never downloaded; off — never asked (and no
+           supervisor process), and the tips' tour film never fetched: the server reaches the
+           network for nothing of its own. VISUALPROOF_UPDATES says the same. From a checkout,
+           never asked.
+
   --library-limit  the most the project's library of papers and images may take, in GB (default
            ${DEFAULT_LIBRARY_LIMIT / 1024 ** 3}); its files are kept in the site directory, by their hash.
 
@@ -149,7 +168,12 @@ function parseArgs(argv) {
     }
     if (cmd !== "serve" && cmd !== "export" && cmd !== "purge-file" && cmd !== "doctor" && cmd !== "artwork")
         usage();
-    const o = { cmd, path: "", roots: [], port: 4173, host: "127.0.0.1", site: null, cache: null, graph: null, out: null, label: "VisualProof", identityHeader: null, editor: null, agents: "full", accessKeyFile: null, jobs: DEFAULT_JOBS, publicUrl: null, libraryLimit: DEFAULT_LIBRARY_LIMIT, sha: null, publicRead: false, recipe: null, png: false, svg: false, screen: { w: 1920, h: 1200 } };
+    const fromEnv = process.env.VISUALPROOF_UPDATES;
+    if (cmd === "serve" && fromEnv !== undefined && !UPDATE_MODES.includes(fromEnv)) {
+        console.error(`visualproof: VISUALPROOF_UPDATES=${fromEnv}: say auto, notify or off`);
+        process.exit(2);
+    }
+    const o = { cmd, path: "", roots: [], port: 4173, host: "127.0.0.1", site: null, cache: null, graph: null, out: null, label: "VisualProof", identityHeader: null, editor: null, agents: "full", accessKeyFile: null, jobs: DEFAULT_JOBS, publicUrl: null, libraryLimit: DEFAULT_LIBRARY_LIMIT, sha: null, publicRead: false, recipe: null, png: false, svg: false, screen: { w: 1920, h: 1200 }, updates: UPDATE_MODES.includes(fromEnv) ? fromEnv : "auto" };
     for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
         const val = () => rest[++i] ?? usage();
@@ -203,6 +227,12 @@ function parseArgs(argv) {
                 usage();
             o.jobs = n;
         }
+        else if (a === "--updates" && cmd === "serve") {
+            const mode = val();
+            if (!UPDATE_MODES.includes(mode))
+                usage();
+            o.updates = mode;
+        }
         else if (a === "--agents") {
             const level = val();
             if (!AGENT_LEVELS.includes(level))
@@ -270,6 +300,9 @@ export class App {
     readOnlyOf = new WeakMap();
     /** what read-only readers may cost the server: Lean's answers, their documents */
     bounds;
+    /** VisualProof's own releases as this server follows them (server/updates.ts); null: the
+     *  version alone is told (a test's server) */
+    updates = null;
     constructor(live, hover, ids, agents, access, exporter = null, publicUrl = null, publicRead = false) {
         this.live = live;
         this.hover = hover;
@@ -286,6 +319,11 @@ export class App {
         this.publicRead = publicRead && access !== null;
         this.bounds = new ReadOnlyBounds((id) => this.exporter?.job(id)?.state === "running");
     }
+    /** Whether a request is told all of the server's own releases (UpdateSpec decision 11): someone
+     *  let in fully; not a read-only reader, nor an agent. */
+    toldAll(req) {
+        return this.readOnlyOf.get(req) === undefined && this.ids.kind(req) !== "agent";
+    }
     /** The exported document (ExportSpec decisions 5–16): POST /api/export starts typesetting the
      *  document of a view, `{view, settings, version?}` (a build the Time Machine shows the view at;
      *  left out, the view's own), and answers with its job at once; the page asks how the
@@ -858,6 +896,23 @@ export class App {
             // the fonts an artwork is drawn in (ExportSpec decision 19)
             if (FONT_PATH.test(path))
                 return sendFile(req, res, join(WEBFONTS, path.slice("/fonts/".length)));
+            // the tips' clips and their key frames (GuideSpec decision 6), and which there are
+            if (path === "/tips/index.json")
+                return sendJson(res, { clips: tipClips() });
+            // the tour film, fetched by this server on its first play and kept checked in the cache
+            // (server/film.ts, UpdateSpec decision 14): else 503 while it comes, or 404, and the page shows
+            // its stills and captions; and its captions as WebVTT, for assistive technology
+            if (path === "/tips/tour.mp4" && !refused.has(res))
+                return void serveFilm(req, res, sendMedia);
+            if (path === "/tips/tour.en.vtt") {
+                const vtt = tourVtt(tourData());
+                if (vtt === null)
+                    return sendJson(res, { error: "no captions" }, 404);
+                res.writeHead(200, { "content-type": "text/vtt; charset=utf-8", "cache-control": "no-cache" });
+                return void res.end(vtt);
+            }
+            if (TIP_PATH.test(path) && !refused.has(res))
+                return sendMedia(req, res, join(TIPS_DIR, path.slice("/tips/".length)));
             // the page, and its workers: the one that lays out the Time Machine's past graphs
             // (web/src/layoutworker.ts), the one that chooses the overview's edges (web/src/edgeworker.ts),
             // and pdf.js's, which reads the library's PDFs for the reference window (AttachmentSpec decision 11)
@@ -866,8 +921,19 @@ export class App {
             if (path.startsWith("/pdfjs/"))
                 return pdfjsAsset(res, path);
             // with Lean's language server as it is (server/hover.ts): what is open, what crashed
-            if (path === "/api/status")
-                return sendJson(res, { ...live.status(), lean: this.hover.state() });
+            // a read-only reader is told how the server is, not its log nor where its review is kept
+            if (path === "/api/status") {
+                const st = { ...live.status(), lean: this.hover.state() };
+                if (this.readOnlyOf.get(req) !== undefined) {
+                    delete st.log;
+                    st.review = { ...st.review, folder: undefined };
+                }
+                return sendJson(res, st);
+            }
+            // VisualProof's own version, and what of its releases those let in fully are told (UpdateSpec
+            // decision 11): a read-only reader and an agent are told the version alone
+            if (path === "/api/updates")
+                return sendJson(res, this.updates?.status(this.toldAll(req)) ?? { running: packageVersion() });
             // the link that lets someone in, for a page that shares where it is (web/src/share.ts); a
             // request gets here only once it is in
             // a read-only reader shares the link they came by, or the address alone (--public)
@@ -987,12 +1053,14 @@ export class App {
             }
             if (path === "/api/events") {
                 const session = url.searchParams.get("session");
-                return live.subscribe(res, validSession(session) ? session : null, this.ids.person(req)?.id ?? null, reader ?? null);
+                return live.subscribe(res, validSession(session) ? session : null, this.ids.person(req)?.id ?? null, reader ?? null, this.toldAll(req));
             }
             // what happened (CollabSpec decision 5): what the server stored; the review's own history the
             // page reads from the review
-            if (path === "/api/activity")
-                return sendJson(res, { events: live.timeline.events.slice(-2000) });
+            if (path === "/api/activity") {
+                const events = live.timeline.events.slice(-2000);
+                return sendJson(res, { events: this.toldAll(req) ? events : events.map(withoutReasons) });
+            }
             // a layout batch an agent made, undone (AgentSpec decision 4): from a page's Activity, by anyone;
             // by a private reader, without their name (CollabSpec decision 8)
             if (path === "/api/layout/undo" && req.method === "POST") {
@@ -1022,8 +1090,10 @@ export class App {
                     return sendJson(res, { error: "not ready" }, 503);
                 // a page asks for the version it was told about; an older one is gone
                 const want = url.searchParams.get("v");
-                if (want && Number(want) !== g.version)
-                    return sendJson(res, { error: "superseded", version: g.version }, 409);
+                // of this server's: one restarted since counts its versions again (UpdateSpec decision 8)
+                const of = url.searchParams.get("i");
+                if ((want && Number(want) !== g.version) || (of && of !== live.instance))
+                    return sendJson(res, { error: "superseded", version: g.version, instance: live.instance }, 409);
                 // a page asks for the edges packed (shared/edgecodec.ts; `pack=2` with the grammar site, a
                 // page from before it `pack=1`, which takes grammar for a proof); an agent gets them as they
                 // are
@@ -1327,8 +1397,21 @@ function packedGz(edgesGz, format) {
     }
     return p;
 }
+/** What a stop signal does to a server: end it at once, until it can stop gracefully (serve). */
+let stopNow = () => process.exit(0);
 async function main() {
     const o = parseArgs(process.argv.slice(2));
+    // an installed package's server runs under the supervisor, which stays while it restarts into
+    // another version (UpdateSpec decision 5); `--updates off`, and a checkout, run it as they are
+    if (o.cmd === "serve" && FROM_PACKAGE && o.updates !== "off" && process.env.VISUALPROOF_SUPERVISED !== "1") {
+        const site = projectDirs(resolve(o.path), o.site, o.cache).site;
+        process.exit(await supervise({ installedRoot: PACKAGE_ROOT, cacheRoot: o.cache ? resolve(o.cache) : cacheHome(), argv: process.argv.slice(2), site, mode: o.updates }));
+    }
+    // a stop asked before the server can stop gracefully (it reads the project, takes the site) ends
+    // it at once, with status 0; once it can, the graceful stop does (`stopNow`, below)
+    if (o.cmd === "serve")
+        for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+            process.on(sig, () => stopNow());
     if (o.cmd === "doctor") {
         const report = doctor({ path: o.path || null, roots: o.roots, site: o.site, cache: o.cache });
         console.log(printReport(report, o.path || null));
@@ -1345,7 +1428,7 @@ async function main() {
     catch (e) {
         if (e instanceof ProjectError) {
             console.error(`visualproof: ${e.message}`);
-            process.exit(1);
+            return endNotTheCode(1);
         }
         throw e;
     }
@@ -1365,7 +1448,7 @@ async function main() {
             if (!(e instanceof SiteBusy))
                 throw e;
             console.error(`visualproof: ${e.message}`);
-            process.exit(1);
+            return endNotTheCode(1);
         }
     }
     useBundleDir(bundleDirIn(o.cache ? resolve(o.cache) : cacheHome()));
@@ -1418,7 +1501,7 @@ async function main() {
     }
     catch (e) {
         console.error(`visualproof: --access-key-file: ${e instanceof Error ? e.message : String(e)}`);
-        process.exit(2);
+        return endNotTheCode(2);
     }
     process.on("exit", () => {
         hover.stop();
@@ -1429,10 +1512,77 @@ async function main() {
         live.invites.close();
         live.readOnly.close();
     });
-    for (const sig of ["SIGINT", "SIGTERM"])
-        process.on(sig, () => process.exit(0));
-    const app = new App(live, hover, ids, new AgentApi(live, hover, o.agents), key ? new Access(key.key) : null, new Exporter(dirs.cache), o.publicUrl, o.publicRead);
+    const exporter = new Exporter(dirs.cache);
+    const app = new App(live, hover, ids, new AgentApi(live, hover, o.agents), key ? new Access(key.key) : null, exporter, o.publicUrl, o.publicRead);
     const server = createServer((req, res) => app.handle(req, res));
+    const version = packageVersion();
+    // run by the supervisor, which starts it again in another version (UpdateSpec decision 5)
+    const supervised = typeof process.send === "function" && process.env.VISUALPROOF_SUPERVISED === "1";
+    /** Stop (UpdateSpec decision 9): no new requests, the pages told why and their streams ended, the
+     *  programs the server runs stopped, then the process ends: status 0, or RESTART_STATUS for the
+     *  supervisor to start it again in another version. A second signal meanwhile changes nothing;
+     *  whatever still waits, it ends within 5 s. */
+    let stopping = false;
+    /** the status the process ends with: a stop asked during a restart makes it a stop (0), so that
+     *  the supervisor does not start it again */
+    let exitStatus = 0;
+    const stop = (status, why) => {
+        if (stopping) {
+            if ("stopped" in why)
+                exitStatus = 0;
+            return;
+        }
+        stopping = true;
+        exitStatus = status;
+        updates.stop();
+        server.close();
+        live.end(why);
+        hover.stop();
+        live.usage.cancel();
+        server.closeIdleConnections();
+        setTimeout(() => process.exit(exitStatus), 5000);
+        void stopChildren(2000).then(() => {
+            server.closeAllConnections();
+            process.exit(exitStatus);
+        });
+    };
+    const cacheRoot = o.cache ? resolve(o.cache) : cacheHome();
+    const updates = new Updates({
+        mode: o.updates,
+        cacheRoot,
+        canRestart: supervised && FROM_PACKAGE,
+        check: FROM_PACKAGE,
+        checkout: !FROM_PACKAGE,
+        // nobody on a page, nothing running that a restart would cut short (UpdateSpec decision 6)
+        quiet: () => live.pages === 0 && !live.busy && !exporter.busy,
+        restart: (to) => {
+            process.send?.({ vp: "restart", to });
+            stop(RESTART_STATUS, { update: { from: version, to } });
+        },
+        // the server's console alone: the log pages read (GET /api/status) is no place for paths and
+        // commands of this machine
+        log: (l) => console.log(l),
+        changed: () => live.updatesChanged(),
+        running: version,
+        // the supervisor's word, believed only from it
+        installedRoot: (supervised && process.env.VISUALPROOF_INSTALLED) || PACKAGE_ROOT,
+        site: dirs.site,
+        // what the supervisor set aside without a record of it (a full disk), believed only from it
+        also: new Set(supervised ? unrecordedOf(process.env.VISUALPROOF_UNRECORDED) : []),
+        film: () => filmStatus(),
+    });
+    // the tips' tour film, fetched on its first play (UpdateSpec decision 14; never under --updates off)
+    useFilm({ cacheRoot, mode: o.updates, log: (l) => console.log(l) });
+    live.updateStatus = (full) => updates.status(full);
+    app.updates = updates;
+    stopNow = () => stop(0, { stopped: true });
+    // the supervisor went: this server goes with it rather than serve on alone
+    if (supervised)
+        process.on("disconnect", () => stop(0, { stopped: true }));
+    server.on("error", (e) => {
+        console.error(`visualproof: ${e.code === "EADDRINUSE" ? `${o.host}:${o.port} is in use already: give --port another` : e.message}`);
+        return endNotTheCode(1);
+    });
     server.listen(o.port, o.host, () => {
         console.log(`VisualProof — ${project.name} (${targetsInWords(project)})`);
         console.log(`  http://${o.host}:${o.port}/`);
@@ -1443,9 +1593,60 @@ async function main() {
         console.log(`  agents: ${o.agents} — their API is http://${o.host}:${o.port}/api/agent`);
         console.log(`  usage pass: ${o.graph ? "none for a saved graph" : o.jobs > 0 ? `${o.jobs} module(s) at a time` : "off (--jobs 0)"}`);
         console.log(`  access: ${key ? `by its link only, /k/<the key in ${o.accessKeyFile}>${key.made ? " (a new key was made there)" : ""}${o.publicRead ? "; anyone else read-only (--public)" : ""}` : "anyone who reaches the port"}`);
+        console.log(`  version: ${version}; updates ${updatesInWords(o.updates, version, supervised)}`);
+        recordVersion(live, version, supervised);
+        process.send?.({ vp: "listening", version });
+        updates.start();
     });
     live.start();
 }
+/** What the server does with its releases, for its first lines (UpdateSpec decisions 2–4, 13). */
+function updatesInWords(mode, version, supervised) {
+    if (mode === "off")
+        return "off (--updates off): the registry is never asked";
+    if (!FROM_PACKAGE)
+        return "none from a checkout";
+    const minor = version.split(".").slice(0, 2).join(".");
+    if (mode === "notify")
+        return `notify — newer versions told of, never downloaded${supervised ? "; one installed meanwhile is restarted into" : ""}`;
+    return supervised ? `auto — a patch of ${minor} taken by itself at a quiet moment; a newer version told of` : "auto, but without the supervisor: newer versions told of";
+}
+/** The versions the supervisor says it set aside without a record (VISUALPROOF_UNRECORDED). */
+function unrecordedOf(text) {
+    try {
+        const v = JSON.parse(text ?? "[]");
+        return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The version that serves the site, recorded in the timeline where it is another than the last one
+ *  recorded (UpdateSpec decision 10), with what the supervisor set aside before this one started. */
+function recordVersion(live, version, supervised) {
+    let setAside;
+    try {
+        const raw = JSON.parse((supervised && process.env.VISUALPROOF_SET_ASIDE) || "null");
+        if (raw && typeof raw.version === "string" && typeof raw.why === "string")
+            setAside = { version: raw.version, why: raw.why };
+    }
+    catch {
+        // nothing set aside that can be read
+    }
+    const was = live.timeline.lastVersion() ?? live.history?.lastVersion() ?? null;
+    if (was !== version || setAside)
+        live.timeline.add({ kind: "tool", from: was, to: version, ...(setAside ? { setAside } : {}) });
+}
+/** End the server with `status`, the supervisor told first that what ends it is not its code (the
+ *  site is busy, the port is taken, the project cannot be read): a patch that ends so is not set
+ *  aside (UpdateSpec decision 7). The message is sent before the process ends, not lost with it. */
+function endNotTheCode(status) {
+    process.exitCode = status;
+    if (process.send)
+        process.send({ vp: "environment" }, () => process.exit(status));
+    else
+        process.exit(status);
+}
 /** The artwork command (ExportSpec decision 21): the build read as an export reads it, the picture a
  *  recipe says made of it (server/artcmd.ts), its files written; what it named said as the agents'
  *  API says it; problems said, and exit status 1. */

package/dist/server/media.js

@@ -0,0 +1,114 @@
+// What the sheet's tips play (GuideSpec decision 6): the tour film's data, assets/tips/tour.json (the
+// film pinned by its sha256, its chapters, its captions), its poster tour.webp and each chapter's
+// still tour-<chapter>.webp; its captions as WebVTT, made from tour.json; the film itself,
+// /tips/tour.mp4, which is not in the package (server/film.ts fetches it); and the phone's gestures
+// (phone-fingers.light.mp4). Served as they are (they are compressed already) and with byte
+// ranges, which Safari needs to play a video at all; and which clips there are.
+import { closeSync, createReadStream, fstatSync, openSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream";
+import { WEBFONTS } from "./pipeline.js";
+/** where the clips are: beside the artworks' fonts, in the checkout's src/assets or the package's dist/assets */
+export const TIPS_DIR = join(dirname(WEBFONTS), "tips");
+/** a clip's or its key frame's address, the film's data, poster and stills */
+export const TIP_PATH = /^\/tips\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\.(?:light|dark)\.(?:mp4|webp)|tour(?:-[a-z0-9]+)?\.webp|tour\.json)$/;
+/** A time of a WebVTT cue: hh:mm:ss.mmm. */
+function vttTime(t) {
+    const ms = Math.max(0, Math.round(t * 1000));
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return `${p(Math.floor(ms / 3_600_000))}:${p(Math.floor(ms / 60_000) % 60)}:${p(Math.floor(ms / 1000) % 60)}.${p(ms % 1000, 3)}`;
+}
+/** The film's captions as WebVTT, for assistive technology (the page draws its own from
+ *  tour.json): each cue in order, its text on one line, nothing in it read as markup. Null where
+ *  tour.json says none. */
+export function tourVtt(raw) {
+    const caps = raw?.captions;
+    if (!Array.isArray(caps))
+        return null;
+    const cues = caps.filter((c) => !!c && typeof c.start === "number" && typeof c.end === "number" && c.end > c.start && typeof c.text === "string");
+    const text = (t) => t.replace(/[\r\n]+/g, " ").replace(/-->/g, "→").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    return "WEBVTT\n\n" + cues.map((c) => `${vttTime(c.start)} --> ${vttTime(c.end)}\n${text(c.text)}\n`).join("\n");
+}
+/** tour.json as the package holds it; null where there is none. */
+export function tourData(dir = TIPS_DIR) {
+    try {
+        return JSON.parse(readFileSync(join(dir, "tour.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const TYPES = { mp4: "video/mp4", webp: "image/webp", json: "application/json" };
+/** The clips there are: those recorded in the light theme (the film is light only). */
+export function tipClips(dir = TIPS_DIR) {
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return files.flatMap((f) => {
+        const m = /^([a-z0-9]+(?:-[a-z0-9]+)*)\.light\.mp4$/.exec(f);
+        return m ? [m[1]] : [];
+    });
+}
+/** Whether the request already has the content `etag` names. */
+function fresh(req, etag) {
+    const have = req.headers["if-none-match"];
+    return !!have && have.split(",").some((t) => t.trim().replace(/^W\//, "") === etag);
+}
+function answer(res, code, headers = {}) {
+    res.writeHead(code, headers);
+    res.end();
+}
+/** A clip or a key frame: the whole file, or the range asked for (206), or what cannot be given
+ *  (416). The file is opened before anything is answered, so that one that cannot be read is a
+ *  404 rather than a cut connection; it is closed however the answer ends — sent, refused, or the
+ *  reader gone in the middle of it. */
+export function sendMedia(req, res, file) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+    }
+    catch {
+        return answer(res, 404, { "content-type": "application/json", "cache-control": "no-store" });
+    }
+    let size, mtime;
+    try {
+        ({ size, mtimeMs: mtime } = fstatSync(fd));
+    }
+    catch {
+        closeSync(fd);
+        return answer(res, 404);
+    }
+    const etag = `"${size.toString(36)}-${Math.round(mtime).toString(36)}"`;
+    const head = { "content-type": TYPES[file.slice(file.lastIndexOf(".") + 1)] ?? "application/octet-stream", "cache-control": "no-cache", etag, "accept-ranges": "bytes" };
+    const done = (code, headers) => {
+        closeSync(fd);
+        answer(res, code, headers);
+    };
+    if (fresh(req, etag))
+        return done(304, head);
+    const m = /^bytes=(\d*)-(\d*)$/.exec(String(req.headers.range ?? "").trim());
+    let start = 0, end = size - 1;
+    if (m && (m[1] || m[2])) {
+        // from a byte to another (or to the end), or the last so many
+        if (m[1])
+            [start, end] = [Number(m[1]), m[2] ? Math.min(Number(m[2]), size - 1) : size - 1];
+        else
+            start = Math.max(0, size - Number(m[2]));
+        if (start > end)
+            return done(416, { "content-range": `bytes */${size}` });
+        res.writeHead(206, { ...head, "content-range": `bytes ${start}-${end}/${size}`, "content-length": end - start + 1 });
+    }
+    else
+        res.writeHead(200, { ...head, "content-length": size });
+    if (req.method === "HEAD" || size === 0) {
+        closeSync(fd);
+        return void res.end();
+    }
+    // the stream owns the descriptor from here: pipeline destroys it, and so closes the file, when
+    // the answer is sent, fails, or the reader goes away
+    pipeline(createReadStream(file, { fd, start, end, autoClose: true }), res, () => { });
+}

package/dist/server/pipeline.js

@@ -11,6 +11,7 @@ import { cachedExtraction, extract, loadSaved, prune } from "./extract.js";
 import { memoryOf } from "../shared/layout.js";
 import { buildViewOffThread } from "./view.js";
 import { cacheHome } from "./dirs.js";
+import { packageVersion } from "./version.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
@@ -124,7 +125,9 @@ export async function ensureBundle() {
     const dist = bundleDir();
     const out = join(dist, "app.js");
     let newest = 0;
-    for (const f of [...readdirRec(join(WEB, "src")), ...readdirRec(join(SRC, "shared"))])
+    // package.json too: the page is bundled with its version (UpdateSpec decision 8), which a page
+    // compares with its server's — a bundle of another version would have every new tab reload
+    for (const f of [...readdirRec(join(WEB, "src")), ...readdirRec(join(SRC, "shared")), join(REPO, "package.json")])
         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)
@@ -158,6 +161,8 @@ export async function bundlePage(outdir, sourcemap = true) {
         // 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"],
+        // the version the page is of, which it compares with its server's (UpdateSpec decision 8)
+        define: { __VP_VERSION__: JSON.stringify(packageVersion()) },
         sourcemap,
         outdir,
         logLevel: "warning",

package/dist/server/poppler.js

@@ -10,6 +10,7 @@
 // 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 { tracked } from "./children.js";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
@@ -31,12 +32,12 @@ async function run(cmd, args, ms) {
     running++;
     try {
         return await new Promise((ok, no) => {
-            execFile(cmd, args, { timeout: ms, maxBuffer: MAX_OUT, encoding: "buffer", windowsHide: true }, (err, out, errOut) => {
+            tracked(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 {

package/dist/server/readonlygate.js

@@ -6,13 +6,13 @@
 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/") || path.startsWith("/fonts/"))
+        // the page and its files: its fonts, the tips' clips (GuideSpec decision 6)
+        if (path === "/" || path === "/index.html" || path === "/style.css" || /^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path) || path.startsWith("/pdfjs/") || path.startsWith("/fonts/") || path.startsWith("/tips/"))
             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
-        // came by, and the event stream every change comes by
-        if (["/api/status", "/api/meta", "/api/edges", "/api/git", "/api/source", "/api/review", "/api/activity", "/api/identity", "/api/share"].includes(path))
+        // came by, VisualProof's version, and the event stream every change comes by
+        if (["/api/status", "/api/updates", "/api/meta", "/api/edges", "/api/git", "/api/source", "/api/review", "/api/activity", "/api/identity", "/api/share"].includes(path))
             return true;
         // a stream is opened by GET alone: a HEAD would take one of their places for nothing
         if (path === "/api/events")

package/dist/server/sourcestore.js

@@ -24,6 +24,7 @@
 // read-only: the build's commit, the commits made on top of it, the working tree and the blobs kept
 // already. Nothing is ever written into the project or its `.git`.
 import { spawn, spawnSync } from "node:child_process";
+import { childEnv, tracked } from "./children.js";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -156,13 +157,13 @@ const DECLARES = /^\s*(?:@\[[^\]]*\]\s*)*(?:(?:private|protected|noncomputable|p
 // ------------------------------------------------------------------------------------------- git
 /** Git, read-only and taking no lock, run from the project's folder: its output, or null. */
 function gitSync(root, args) {
-    const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 10_000, maxBuffer: 256 << 20, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, stdio: ["ignore", "pipe", "ignore"] });
+    const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 10_000, maxBuffer: 256 << 20, env: childEnv({ GIT_OPTIONAL_LOCKS: "0" }), stdio: ["ignore", "pipe", "ignore"] });
     return r.status === 0 ? r.stdout : null;
 }
 /** The same, off the event loop, with `input` on its standard input: its output as bytes, or null. */
 function git(root, args, input) {
     return new Promise((ok) => {
-        const p = spawn("git", ["-C", root, ...args], { env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, stdio: ["pipe", "pipe", "ignore"] });
+        const p = tracked(spawn("git", ["-C", root, ...args], { env: childEnv({ GIT_OPTIONAL_LOCKS: "0" }), stdio: ["pipe", "pipe", "ignore"] }));
         const out = [];
         p.stdout.on("data", (b) => out.push(b));
         p.on("error", () => ok(null));

package/dist/server/status.js

@@ -10,6 +10,7 @@
 //   - the trace records the hash of the source it was built from. Lake rebuilds when that hash
 //     changes, not when the mtime does, so "stale" here compares the same hash (`lakeTextHash`).
 import { execFile } from "node:child_process";
+import { tracked } from "./children.js";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 const IMPORT_RE = /^\s*(?:public\s+|private\s+)?(?:meta\s+)?import\s+(?:all\s+)?([^\s-]+)/;
@@ -84,7 +85,7 @@ export function scanModules(p) {
 /** Modules a lean process is compiling right now, for this project's build directory. */
 export function compiling(p) {
     return new Promise((resolve) => {
-        execFile("ps", ["axo", "command"], { maxBuffer: 16 << 20 }, (err, stdout) => {
+        tracked(execFile("ps", ["axo", "command"], { maxBuffer: 16 << 20 }, (err, stdout) => {
             const out = new Set();
             if (err)
                 return resolve(out);
@@ -99,7 +100,7 @@ export function compiling(p) {
                     out.add(path.split("/").join("."));
             }
             resolve(out);
-        });
+        }));
     });
 }
 const M = 0xc6a4a7935bd1e995n;