tosijs-ui 1.9.2 → 1.9.3

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 1.9.3
+
+Two adopter-reported fixes, both with the diagnosis largely done by the reporter.
+
+### The dev server crashed instead of exiting (#47)
+
+A long-lived `bun start` **segfaulted at the 8-hour idle timeout** rather than exiting —
+so a workspace left up for a working day went offline silently, and the first sign was a
+tunnel link failing. All six exit paths called `server.stop()` immediately before
+`process.exit()`; that buys nothing (the OS closes the sockets) and was exactly where it
+died. They now just exit.
+
+Note for anyone hitting this elsewhere: **`try/catch` is not a mitigation** — a segfault
+is not a catchable exception, so the only workaround is not calling the API. Filed
+upstream as [oven-sh/bun#36788](https://github.com/oven-sh/bun/issues/36788).
+
+### ePub volumes are now linkable (#46)
+
+The build wrote an ePub per volume and linked to none of them, so a reader had no route
+to a book that existed. The filename is *derived* (`<project>-<volume>.epub`), so
+hand-written links rot silently when a volume is renamed.
+
+Three ways to surface them, and the ePub build now names its output through the same
+helper, so a link cannot point at a name nothing wrote:
+
+```text
+<!-- epub-downloads -->        drop in any page → a link per volume
+/epub-volumes.json             manifest: book, title, filename, url
+listEpubVolumes()              exported from tosijs-ui/site
+```
+
+`epub.volumeTitles` renames what humans read without moving what published links point
+at.
+
+### Also
+
+- **A valid session now trumps a stale invite link** (#45). Clicking an older link while
+  already signed in — a second window, a link scrolled back to in chat, a bookmark —
+  walled you with "that invite link has been used". The stale token is simply irrelevant
+  to someone who already holds a session.
+- **`tosijs-tunnel --close` confirms identity before signalling.** It SIGTERMed every
+  `pgrep -f` match, and `pgrep -f` matches an argv *substring* — a shell echoing the
+  command or an editor holding a log path both matched. It now checks the process really
+  is `ssh`, says what it signalled, and names what it skipped. It also interpolated `host`
+  into a REGEX unescaped, so `me@a.b` matched `me@axb` and a host containing `+`, `(` or
+  `*` changed the pattern's meaning outright.
+
+### Internals, for anyone reading the source
+
+- One `shutdown(code)` helper replaces the six copy-pasted exit sites. The 1.9.0 review
+  had flagged that duplication as a tidiness follow-up; it turned out not to be untidy but
+  to be six copies of the crash above — you cannot fix a bug once if it exists six times.
+- `resolveLinkArrival()` joins `mayReadSite` / `isLockedDown` as a decision extracted from
+  the dev server's request closure, where nothing could test it. Each of these was
+  extracted only after shipping a bug in it.
+
 ## 1.9.2
 
 **Accessibility: every default color pair now meets WCAG AA.** Found by running

package/bin/tunnel.ts

@@ -108,8 +108,17 @@ if (!host) {
   process.exit(1)
 }
 
-/** pgrep pattern that matches only OUR forward, so --close can't kill someone else's. */
-const pattern = `ssh .*-R ${remotePort}:localhost:${tunnelLocalPort} ${host}`
+/*
+pgrep pattern that matches only OUR forward, so --close can't kill someone else's.
+
+`host` is interpolated into a REGEX, so it must be escaped: it is user config
+(`user@box.example.com`), and an unescaped `.` matches any character while `+`, `(` or
+`*` change the pattern's meaning outright. Unescaped, `me@a.b` also matches `me@axb`.
+*/
+const rx = (t: string) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const pattern = `ssh .*-R ${remotePort}:localhost:${tunnelLocalPort} ${rx(
+  String(host)
+)}`
 
 async function running(): Promise<number[]> {
   const out = await $`pgrep -f ${pattern}`.nothrow().quiet().text()
@@ -175,16 +184,43 @@ if (has('status')) {
 }
 
 if (has('close')) {
+  /*
+  Confirm identity before signalling, and leave a receipt.
+
+  `pgrep -f` matches an argv SUBSTRING, so anything whose command line happens to contain
+  this pattern matches — a shell running an `echo` of the command, an editor holding a log
+  path, another agent tailing output. Signalling on a substring match alone is how a tool
+  kills something it never started.
+
+  `killStrayServer` in dev-server.ts already set this norm ("reclaiming a port is
+  destructive, so the log says exactly which pid/comm"), but the discipline lived in
+  another file and did not travel. Same rule here: check `comm` is really ssh, say what
+  was signalled, and name what was skipped and why.
+  */
   const pids = await running()
+  const closed: number[] = []
   for (const pid of pids) {
+    const comm = (
+      await $`ps -p ${pid} -o comm=`.nothrow().quiet().text()
+    ).trim()
+    if (!/(^|\/)ssh$/.test(comm)) {
+      console.warn(
+        `⚠️  pid ${pid} matched the tunnel pattern but is ${
+          comm || 'unknown'
+        }, not ssh — leaving it alone.`
+      )
+      continue
+    }
     try {
       process.kill(pid, 'SIGTERM')
+      closed.push(pid)
+      console.log(`  SIGTERM → pid ${pid} (${comm})`)
     } catch {
-      /* already gone */
+      /* already gone between pgrep and here */
     }
   }
   console.log(
-    pids.length ? `closed (pid ${pids.join(', ')})` : 'nothing to close'
+    closed.length ? `closed (pid ${closed.join(', ')})` : 'nothing to close'
   )
   process.exit(0)
 }

package/dist/doc-system/site/dev-auth.d.ts

@@ -83,3 +83,9 @@ export declare function hasTunnel(config: {
         tunnel?: unknown;
     };
 }): boolean;
+export type LinkArrival = 'issue-session' | 'already-authenticated' | 'reject';
+export declare function resolveLinkArrival(opts: {
+    /** the session redeemLink() minted, or null if the token was invalid/spent */
+    redeemed: string | null;
+    hasValidSession: boolean;
+}): LinkArrival;

package/dist/doc-system/site/dev-auth.js

@@ -266,3 +266,10 @@ export function isLockedDown(config) {
 export function hasTunnel(config) {
     return Boolean(config.preview?.tunnel);
 }
+export function resolveLinkArrival(opts) {
+    if (opts.redeemed)
+        return 'issue-session';
+    if (opts.hasValidSession)
+        return 'already-authenticated';
+    return 'reject';
+}

package/dist/doc-system/site/dev-server.js

@@ -16,7 +16,7 @@ import { preflight } from './preflight.js';
 import { auditDependencies, reportAudit } from './audit-guard.js';
 import { openDevBrowser } from './open-browser.js';
 import { resolveTunnelLocalPort } from './site-config.js';
-import { TUNNEL_LINK_CMD, isLockedDown, hasTunnel, isLoopbackAddressForAuth as isLoopbackAddress, mayReadSite, shouldInterceptLinkToken, createAuthState, issueLink, readCookie, redeemLink, sessionCookie, urlWithoutToken, validSession, mayWriteSource, isProxiedRequest, SESSION_COOKIE, } from './dev-auth.js';
+import { TUNNEL_LINK_CMD, resolveLinkArrival, isLockedDown, hasTunnel, isLoopbackAddressForAuth as isLoopbackAddress, mayReadSite, shouldInterceptLinkToken, createAuthState, issueLink, readCookie, redeemLink, sessionCookie, urlWithoutToken, validSession, mayWriteSource, isProxiedRequest, SESSION_COOKIE, } from './dev-auth.js';
 const TEST_RESULTS_FILE = '.browser-tests.json';
 const DEFAULT_IDLE_HOURS = 8;
 /**
@@ -941,20 +941,37 @@ export async function devServer(config, opts = {}) {
                 'Referrer-Policy': 'no-referrer',
                 'Cache-Control': 'no-store',
             };
-            if (session) {
+            const heldCookie = readCookie(request.headers.get('cookie'), SESSION_COOKIE);
+            const arrival = resolveLinkArrival({
+                redeemed: session,
+                hasValidSession: validSession(auth, heldCookie, Date.now()),
+            });
+            if (arrival === 'issue-session') {
                 headers['Set-Cookie'] = sessionCookie(session);
                 console.log('🔓 edit link redeemed — session issued');
                 return new Response(null, { status: 302, headers });
             }
             /*
-            Invalid or ALREADY SPENT — and the likely culprit is not an attacker but a
+            A VALID SESSION TRUMPS A STALE LINK.
+      
+            The comment that used to sit here asserted that a session holder "never lands
+            here, their cookie is sent automatically" — and nothing enforced it. The token is
+            read before any session check, so anyone already signed in who clicks an older link
+            (a second window, a link scrolled back to in chat, a bookmark) got walled with
+            "that invite link has been used" while holding a perfectly good session. The stale
+            token is simply irrelevant to them.
+      
+            Strip it and carry on. No new session is issued: they already have one, and
+            re-issuing on a spent token would make expiry meaningless.
+            */
+            if (arrival === 'already-authenticated') {
+                return new Response(null, { status: 302, headers });
+            }
+            /*
+            Genuinely unauthenticated, and the likely culprit is not an attacker but a
             chat-app link-preview bot, whose GET *is* the first use. dev-auth.ts names
             unfurlers as a reason for single-use without handling the consequence: you click
             a dead link, get silently redirected, and the next signal is a save failing.
-      
-            An anonymous reader who already holds a session never lands here (their cookie is
-            sent automatically), so saying this out loud costs nothing and saves a confusing
-            hunt.
             */
             const spent = `<!doctype html><meta charset=utf-8><title>Link already used</title>` +
                 `<style>body{font:16px/1.6 system-ui;margin:15vh auto;max-width:32rem;padding:0 1.5rem;color:#222}` +
@@ -1072,7 +1089,12 @@ export async function devServer(config, opts = {}) {
         }
         return new Response('File not found', { status: 404 });
     };
-    const server = Bun.serve({
+    /*
+    Not bound to a name: nothing stops these listeners. `process.exit()` ends the process
+    and the OS closes the sockets, and calling `.stop()` first is what segfaulted on the
+    idle path (#47). A handle we would never legitimately use is an invitation to use it.
+    */
+    Bun.serve({
         port: PORT,
         tls: {
             key: Bun.file('./tls/key.pem'),
@@ -1108,10 +1130,9 @@ export async function devServer(config, opts = {}) {
         ? resolveTunnelLocalPort(config, process.env)
         : undefined;
     const configuredTunnelPort = config.preview?.tunnel?.localPort;
-    let tunnelServer;
     if (tunnelPort && !testMode && !process.env.DEV_NO_TUNNEL) {
         try {
-            tunnelServer = Bun.serve({
+            Bun.serve({
                 port: tunnelPort,
                 hostname: '127.0.0.1',
                 fetch: (request, srv) => handleRequest(request, srv, true),
@@ -1132,6 +1153,27 @@ export async function devServer(config, opts = {}) {
                 `${configuredTunnelPort ? '' : ' — it defaults to PORT + 1'}.`);
         }
     }
+    /*
+  Exit WITHOUT stopping the listeners first.
+
+  Every one of these six sites called `server.stop()` (and `tunnelServer?.stop()`)
+  immediately before `process.exit()`. That buys nothing — `process.exit` terminates the
+  process and the OS closes the listening sockets — and it is where the process was
+  dying: tosijs-3d reported a reproducible **segfault at ~7.95h** against the 8h idle
+  timer, twice, on the shutdown path, with flat 0.34GB RSS (so not the Bun.build native
+  leak) and a faulting address that decodes to ASCII text rather than a null — the shape
+  of a use-after-free inside Bun's own teardown. tosijs-ui#47.
+
+  A `try/catch` around the stops would NOT help: a segfault is not a JS exception. Not
+  making the call is the only fix available to us. Filed upstream separately, because
+  Bun should not crash here either.
+
+  Child processes we spawned are a different matter — those we must still reap, since the
+  OS will not do it for a detached Electron grandchild. Callers do that before calling in.
+  */
+    const shutdown = (code) => {
+        process.exit(code);
+    };
     console.log(`Listening on https://localhost:${PORT}`);
     // ── open (or bring to front) this project's browser tab ─────────────────────
     //
@@ -1183,9 +1225,7 @@ export async function devServer(config, opts = {}) {
                     `   updates, which a long-running process never does. Disable with\n` +
                     `   DEV_IDLE_TIMEOUT_HOURS=0 or idleTimeoutHours in your site config.\n`);
                 clearInterval(timer);
-                server.stop();
-                tunnelServer?.stop();
-                process.exit(0);
+                shutdown(0);
             }
             const ok = await preflight({
                 label: 'Dev server',
@@ -1194,9 +1234,7 @@ export async function devServer(config, opts = {}) {
             });
             if (!ok) {
                 clearInterval(timer);
-                server.stop();
-                tunnelServer?.stop();
-                process.exit(1);
+                shutdown(1);
             }
         }, TICK_MS);
         // Never let the health check itself be the thing keeping the process alive.
@@ -1315,8 +1353,7 @@ export async function devServer(config, opts = {}) {
             console.error(`haltija did not report a private port within 30s (${portFile}).\n` +
                 `  Is \`bunx ${HALTIJA_PKG}\` able to run? Try it by hand.`);
             await stopHaltija();
-            server.stop();
-            process.exit(1);
+            shutdown(1);
         }
         console.log(`  private haltija on port ${hjPort}`);
         console.log('Opening demo site...');
@@ -1332,21 +1369,18 @@ export async function devServer(config, opts = {}) {
         if (nav.exitCode !== 0) {
             console.error(`hj navigate failed (exit ${nav.exitCode}): ${nav.stderr.toString().trim() || 'no browser reachable'}`);
             await stopHaltija();
-            server.stop();
-            process.exit(1);
+            shutdown(1);
         }
         try {
             const results = await testResults;
             const exitCode = results.failed > 0 ? 1 : 0;
             await stopHaltija();
-            server.stop();
-            process.exit(exitCode);
+            shutdown(exitCode);
         }
         catch (e) {
             console.error(e.message);
             await stopHaltija();
-            server.stop();
-            process.exit(1);
+            shutdown(1);
         }
     }
 }

package/dist/doc-system/site/epub-volumes.d.ts

@@ -0,0 +1,49 @@
+export interface EpubVolume {
+    /** the `book` value, or '' for the default volume */
+    book: string;
+    /** human title — "<project>" or "<project> — <volume>", or an explicit override */
+    title: string;
+    /** output filename, e.g. `my-project-appendices.epub` */
+    filename: string;
+    /** served URL, honouring basePath */
+    url: string;
+}
+export interface VolumeNamingConfig {
+    name?: string;
+    basePath?: string;
+    epub?: boolean | {
+        title?: string;
+        volumeTitles?: Record<string, string>;
+    };
+}
+/**
+ * The identity of one volume. `bookTarget` undefined means the default volume.
+ *
+ * Kept deliberately pure and dependency-free so the ePub builder, the site build and an
+ * adopter's own script all agree by construction rather than by comment.
+ */
+export declare function epubVolumeIdentity(config: VolumeNamingConfig, bookTarget?: string): EpubVolume;
+/**
+ * Every volume this corpus will produce, default first.
+ *
+ * Empty when the corpus has no publishable docs at all — which is a real state (everything
+ * hidden, or everything `book: "none"`) and must not be reported as one nameless volume.
+ */
+export declare function listEpubVolumes(corpus: Array<{
+    filename: string;
+    title?: string;
+    parent?: string;
+    book?: string | string[];
+    hidden?: boolean;
+}>, config: VolumeNamingConfig): EpubVolume[];
+/** The marker a consumer drops into a page to get the download list. */
+export declare const EPUB_DOWNLOADS_MARKER: RegExp;
+/**
+ * Replace `<!-- epub-downloads -->` with a markdown list of the built volumes.
+ *
+ * Substituted at BUILD time, into the doc text, so the statically-rendered page and the
+ * hydrated SPA show the same thing and the client needs no new data source. A marker in a
+ * corpus that builds no ePub renders as nothing rather than an empty list or a stray
+ * comment.
+ */
+export declare function renderEpubDownloads(text: string, volumes: EpubVolume[]): string;

package/dist/doc-system/site/epub-volumes.js

@@ -0,0 +1,88 @@
+/*
+Which ePubs does this build produce, and where do they land?
+
+The output filename is DERIVED — from the project name and, for a named volume, the
+`book` value (`foresight-rpg` + `book: "foresight-1986"` →
+`foresight-rpg-foresight-1986.epub`). Nothing published that derivation, so a consumer
+wanting to link their own book had to reverse-engineer it from the source and re-derive it
+by hand every time a volume was renamed.
+
+That is not a documentation gap, it is a missing seam: foresight-rpg shipped a valid ePub
+that **nobody could download**, because the site built the file and then linked to nothing.
+It was caught on review rather than by anyone noticing — which is the tell. A build that
+produces an artifact should be able to say where it is.
+
+One definition, used by three callers: the ePub build names its output with it, the
+orchestrator writes a manifest from it, and `<!-- epub-downloads -->` in any page renders
+from it. Consumers can import it directly rather than hard-coding a filename.
+*/
+import { DEFAULT_BOOK, namedBooks, partitionByBook } from '../book-target.js';
+import { buildSlugMap } from '../routing.js';
+/** Lowercase, hyphenated — the same shape the ePub build uses for filenames. */
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * The identity of one volume. `bookTarget` undefined means the default volume.
+ *
+ * Kept deliberately pure and dependency-free so the ePub builder, the site build and an
+ * adopter's own script all agree by construction rather than by comment.
+ */
+export function epubVolumeIdentity(config, bookTarget) {
+    const epub = typeof config.epub === 'object' ? config.epub : {};
+    const baseTitle = epub.title ?? config.name ?? 'book';
+    const title = bookTarget
+        ? (epub.volumeTitles?.[bookTarget] ?? `${baseTitle} — ${bookTarget}`)
+        : baseTitle;
+    const filename = bookTarget
+        ? `${slugify(baseTitle)}-${slugify(bookTarget)}.epub`
+        : `${slugify(baseTitle)}.epub`;
+    const base = (config.basePath ?? '/').replace(/\/+$/, '');
+    return { book: bookTarget ?? DEFAULT_BOOK, title, filename, url: `${base}/${filename}` };
+}
+/**
+ * Every volume this corpus will produce, default first.
+ *
+ * Empty when the corpus has no publishable docs at all — which is a real state (everything
+ * hidden, or everything `book: "none"`) and must not be reported as one nameless volume.
+ */
+export function listEpubVolumes(corpus, config) {
+    const slugs = buildSlugMap(corpus);
+    const partitioned = partitionByBook(corpus, slugs);
+    const books = [
+        ...(partitioned.get(DEFAULT_BOOK)?.length ? [undefined] : []),
+        ...namedBooks(corpus, slugs),
+    ];
+    return books.map((b) => epubVolumeIdentity(config, b));
+}
+/** The marker a consumer drops into a page to get the download list. */
+export const EPUB_DOWNLOADS_MARKER = /<!--\s*epub-downloads\s*-->/g;
+/**
+ * Replace `<!-- epub-downloads -->` with a markdown list of the built volumes.
+ *
+ * Substituted at BUILD time, into the doc text, so the statically-rendered page and the
+ * hydrated SPA show the same thing and the client needs no new data source. A marker in a
+ * corpus that builds no ePub renders as nothing rather than an empty list or a stray
+ * comment.
+ */
+export function renderEpubDownloads(text, volumes) {
+    /*
+    No `.test()` guard — but as simplification, not a bug fix.
+  
+    A `/g` regex carries `lastIndex`, and `.test()` advances it, which LOOKS like it should
+    make a `test`-then-`replace` pair stateful. It does not: `String.replace` with `/g`
+    resets `lastIndex` to 0, and a failing `.test()` resets it too, so the pair is
+    self-correcting. (Verified rather than reasoned — an earlier version of this comment
+    confidently described an alternating no-op that mutation testing showed does not exist.)
+  
+    The guard is dropped because `replace` already returns the input unchanged when nothing
+    matches, so it only bought a redundant scan and a subtlety to explain.
+    */
+    const list = volumes
+        .map((v) => `- [${v.title}](${v.url}) *(ePub)*`)
+        .join('\n');
+    return text.replace(EPUB_DOWNLOADS_MARKER, list);
+}

package/dist/doc-system/site/epub.js

@@ -20,6 +20,7 @@ import { renderDocMarkdown } from '../render.js';
 import { buildSlugMap, pathForSlug, slugForPath } from '../routing.js';
 import { buildNavTree } from '../nav-tree.js';
 import { partitionByBook, DEFAULT_BOOK } from '../book-target.js';
+import { epubVolumeIdentity } from './epub-volumes.js';
 import { DEFAULT_BOOK_CSS, stripDocMeta, flatten, slugify } from '../book-html.js';
 import { selectBookDocs } from '../book-manifest.js';
 // Re-exported for back-compat (tosijs-ui/site's public surface + tests).
@@ -637,9 +638,9 @@ export async function buildEpub(config, opts = {}) {
     // An explicit `output` names ONE file, so it can only apply to the default volume —
     // otherwise every volume writes to it and you ship whichever bound last.
     (opts.bookTarget ? undefined : opts.output) ??
-        path.join(outDir, opts.bookTarget
-            ? `${slugify(baseTitle)}-${slugify(opts.bookTarget)}.epub`
-            : `${slugify(baseTitle)}.epub`));
+        // Named through the SHARED helper, so the manifest, the download links and the file
+        // on disk all derive from one function. A link cannot point at a name nothing wrote.
+        path.join(outDir, epubVolumeIdentity({ name: baseTitle, epub: { title: baseTitle } }, opts.bookTarget).filename));
     await zipEpub(buildDir, output);
     fs.rmSync(buildDir, { recursive: true, force: true });
     // Release the parser window: an unclosed happy-dom Window holds its whole

package/dist/doc-system/site/index.d.ts

@@ -14,3 +14,4 @@ export { buildEpub, DEFAULT_BOOK_CSS } from './epub.js';
 export type { BuildEpubOptions, BookMeta } from './epub.js';
 export { selectBookDocs } from '../book-manifest.js';
 export type { BookManifest } from '../book-manifest.js';
+export { listEpubVolumes, epubVolumeIdentity, renderEpubDownloads, type EpubVolume, } from './epub-volumes.js';

package/dist/doc-system/site/index.js

@@ -12,3 +12,4 @@ export { extractDocs, saveDocsJSON } from './docs.js';
 export { generateSite } from './generate-site.js';
 export { buildEpub, DEFAULT_BOOK_CSS } from './epub.js';
 export { selectBookDocs } from '../book-manifest.js';
+export { listEpubVolumes, epubVolumeIdentity, renderEpubDownloads, } from './epub-volumes.js';

package/dist/doc-system/site/orchestrator.js

@@ -13,6 +13,7 @@ cause an endless rebuild loop.
 */
 import * as path from 'path';
 import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
+import { listEpubVolumes, renderEpubDownloads, } from './epub-volumes.js';
 import { buildSlugMap } from '../routing.js';
 import { existsSync, mkdirSync, unlinkSync } from 'fs';
 import { tmpdir } from 'os';
@@ -288,6 +289,39 @@ export async function buildSite(config, opts = {}) {
             output: DOCS_JSON,
         });
         extract();
+        /*
+        Fill `<!-- epub-downloads -->` and publish a manifest of the volumes this build makes.
+    
+        Substituted into the corpus HERE, before pages are generated, so the static page and
+        the hydrated SPA render the same list and the client needs no new data source. The
+        volume set is computed from the corpus itself, so it is known before the ePubs are
+        built — the links and the files derive from one function and cannot disagree.
+    
+        Why this exists: the build produced a valid ePub and linked to nothing, so a reader had
+        no route to it. A build that makes an artifact should be able to say where it is
+        (tosijs-ui#46).
+        */
+        const publishVolumeLinks = async () => {
+            if (!config.epub)
+                return;
+            const corpus = JSON.parse(await Bun.file(DOCS_JSON).text());
+            const volumes = listEpubVolumes(corpus, config);
+            if (!volumes.length)
+                return;
+            let touched = 0;
+            for (const doc of corpus) {
+                const filled = renderEpubDownloads(doc.text ?? '', volumes);
+                if (filled !== doc.text) {
+                    doc.text = filled;
+                    touched++;
+                }
+            }
+            if (touched)
+                await Bun.write(DOCS_JSON, JSON.stringify(corpus, null, 2));
+            // A stable, machine-readable list so a consumer can link the books without
+            // re-deriving the filename — the "documented helper" half of #46.
+            await Bun.write(`${PUBLIC}/epub-volumes.json`, JSON.stringify(volumes, null, 2));
+        };
         // Auto-create missing section docs + regenerate their TOC blocks, then
         // re-extract so the corpus reflects the on-disk changes.
         ensureSections({
@@ -676,6 +710,9 @@ export async function buildSite(config, opts = {}) {
                 console.warn(`import-resolver: could not set it up (${String(e)}) — skipping`);
             }
         }
+        // Fill the download marker and write the volume manifest before pages are rendered,
+        // so the static HTML and the SPA agree. PUBLIC exists by now (static assets copied).
+        await publishVolumeLinks();
         // Generate the static, pre-rendered doc site (one /slug/index.html per doc).
         // Runs after the static-asset copy so the generated index.html (README) wins,
         // and after the bundle copy so every page's <script src> resolves.