tosijs-ui 1.9.2 → 1.9.4

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 1.9.4
+
+**The dev server now uses your own installed `haltija`** (#48, reported by tosijs-3d).
+
+It spawned its own channel via `bunx haltija@^1.6.1` and ignored the project's dependency
+entirely — and because **bunx caches the resolution**, a range that resolves forward never
+*re*-resolves once its cache key exists. So an adopter who bumped `haltija` to `^1.11.2`
+for a fix, restarted, and still didn't have the fix was running a cached 1.11.0: new
+enough to look current, old enough to lack it. `hj where` reports the *spawned* server, so
+the version indicator agreed with them.
+
+- Your `node_modules/.bin/haltija` is preferred when present. `HALTIJA_VERSION` still
+  overrides everything.
+- The fallback floor moves `^1.6.1` → `^1.11.2`. Its practical job is to make bunx
+  re-resolve, not to express a minimum — a stale cache key was half the bug.
+- **Both spawn sites now print which channel they used and where it came from** —
+  `1.11.2 (this project's dependency)`, `haltija@^1.11.2 (bunx)`,
+  `haltija@beta (HALTIJA_VERSION)`. The failure was never that a wrong version ran; it
+  was that nothing said so.
+
+If you were working around this with `HALTIJA_VERSION`, you can drop it.
+
+## 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.d.ts

@@ -3,6 +3,10 @@ import { isLoopbackAddressForAuth as isLoopbackAddress } from './dev-auth.js';
 declare global {
     var Bun: any;
 }
+export declare function resolveHaltijaChannel(cwd?: string, env?: Record<string, string | undefined>): {
+    argv: string[];
+    describe: string;
+};
 /**
  * Resolve the idle-exit timeout to milliseconds (0 = disabled).
  *

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

@@ -8,7 +8,7 @@ headless browser through the inline doc tests and exits with their pass/fail.
 Build-time only (Bun APIs). Never import this from browser code.
 */
 import * as path from 'path';
-import { statSync } from 'fs';
+import { statSync, existsSync, readFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { $, spawn } from 'bun';
 import { buildSite } from './orchestrator.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;
 /**
@@ -45,15 +45,62 @@ const DEFAULT_IDLE_HOURS = 8;
  *     test lane below can trust an exit code instead of racing to a timeout.
  */
 /*
-^1.6.1 — the first version reporting `ready` (haltija#11), which is what lets the lane
-tell "server up" from "there is a tab to drive".
+The FALLBACK channel, used only when the project has no haltija of its own.
 
-The previous floor said ^1.5.5 and cited the teardown fix landing there. **1.5.5 was never
-published** — the published line goes 1.5.4 → 1.6.0 — so that floor named a version that
-does not exist and silently resolved to whatever 1.6+ shipped. A pin whose justification
-cannot be checked is not a pin.
+`^1.11.2` because that is where the agent-facing fixes people upgrade for currently live;
+the floor's practical job is to make bunx re-resolve rather than to express a minimum. The
+floor before this was `^1.6.1`, and an adopter with `haltija@^1.11.2` in their own
+devDependencies still got **1.11.0** — new enough to look current, old enough to lack the
+fix they had just upgraded for (tosijs-ui#48).
+
+Two things conspired, and the second is the nasty one:
+
+  - we spawned our own channel and ignored theirs entirely, and
+  - **`bunx` caches the resolution**, so a range that resolves forward does not RE-resolve
+    once its cache key is populated. `^1.6.1` froze at whatever satisfied it first.
+
+That is the stale-but-satisfying-cache hazard this project filed against haltija (#11) and
+then shipped an instance of. A range is not a pin, and a cached range is not even a range.
+
+`resolveHaltijaChannel()` below prefers the project's own installed haltija, so the version
+is something an adopter controls with the tool they already use. `HALTIJA_VERSION` still
+overrides everything.
 */
-const HALTIJA_PKG = process.env.HALTIJA_VERSION ?? 'haltija@^1.6.1';
+const HALTIJA_PKG = process.env.HALTIJA_VERSION ?? 'haltija@^1.11.2';
+/*
+Which haltija do we actually run, and can we say so out loud?
+
+Prefer the one in the project's own node_modules. An adopter who bumps their haltija
+devDependency to get a fix expects that to be the haltija they get; anything else makes
+the upgrade look like it did nothing — with `hj where` agreeing, since it reports the
+SPAWNED server's version and therefore looks authoritative.
+
+Returns the argv prefix plus a human description, because an invisible divergence is the
+whole bug: one startup line naming the channel and where it came from turns "the fix
+doesn't work" into "oh, it's running a different one".
+*/
+export function resolveHaltijaChannel(cwd = process.cwd(), env = process.env) {
+    // An explicit override always wins, and is worth saying so.
+    if (env.HALTIJA_VERSION) {
+        return {
+            argv: ['bunx', env.HALTIJA_VERSION],
+            describe: `${env.HALTIJA_VERSION} (HALTIJA_VERSION)`,
+        };
+    }
+    const local = `${cwd}/node_modules/.bin/haltija`;
+    if (existsSync(local)) {
+        let version = 'unknown version';
+        try {
+            version =
+                JSON.parse(readFileSync(`${cwd}/node_modules/haltija/package.json`, 'utf8')).version ?? version;
+        }
+        catch {
+            /* installed but unreadable manifest — still prefer it, just unnamed */
+        }
+        return { argv: [local], describe: `${version} (this project's dependency)` };
+    }
+    return { argv: ['bunx', HALTIJA_PKG], describe: `${HALTIJA_PKG} (bunx)` };
+}
 /**
  * Resolve the idle-exit timeout to milliseconds (0 = disabled).
  *
@@ -256,8 +303,11 @@ async function ensureHaltijaChannel(port) {
         // HTTPS dev page has no mixed-content), while the `hj` CLI drives over its
         // default HTTP 8700 — one server, both transports, shared state. HTTPS cert
         // is mkcert-trusted. Output quiet so it doesn't drown the dev log.
-        // Version comes from HALTIJA_PKG — a pinned range, not `@latest`; see above.
-        spawn(['bunx', HALTIJA_PKG, '--server', '--both'], {
+        const channel = resolveHaltijaChannel();
+        // Name the channel: an adopter who upgraded their own haltija and got ours instead
+        // sees the divergence here rather than concluding the fix does not work (#48).
+        console.log(`haltija channel: ${channel.describe}`);
+        spawn([...channel.argv, '--server', '--both'], {
             stdout: 'ignore',
             stderr: 'ignore',
         });
@@ -941,20 +991,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 +1139,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 +1180,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 +1203,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 +1275,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 +1284,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.
@@ -1288,8 +1376,9 @@ export async function devServer(config, opts = {}) {
         (tosijs-ui#18, #21.)
         */
         const portFile = `${tmpdir()}/tosijs-haltija-${process.pid}.json`;
-        console.log('Starting a private haltija…');
-        const haltija = spawn(['bunx', HALTIJA_PKG, '--private', '--port-file', portFile], {
+        const channel = resolveHaltijaChannel();
+        console.log(`Starting a private haltija… (${channel.describe})`);
+        const haltija = spawn([...channel.argv, '--private', '--port-file', portFile], {
             // stdout/stderr are NOT inherited: `bunx haltija` launches Electron as a
             // grandchild, and killing the bunx wrapper does not kill it. An orphan holding
             // our inherited stdout keeps the pipe open forever, so the command looks hung
@@ -1313,10 +1402,9 @@ export async function devServer(config, opts = {}) {
         }
         if (!hjPort) {
             console.error(`haltija did not report a private port within 30s (${portFile}).\n` +
-                `  Is \`bunx ${HALTIJA_PKG}\` able to run? Try it by hand.`);
+                `  Is \`${channel.argv.join(' ')}\` 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 +1420,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';