tosijs-ui 1.6.21 → 1.6.23

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

@@ -12,13 +12,142 @@ import { statSync } from 'fs';
 import { watch } from 'chokidar';
 import { $, spawn } from 'bun';
 import { buildSite } from './orchestrator';
+import { preflight } from './preflight';
 const TEST_RESULTS_FILE = '.browser-tests.json';
+const DEFAULT_IDLE_HOURS = 8;
+/**
+ * The haltija the dev server spawns (`bunx <this>`).
+ *
+ * Pinned to a **range with a floor**, not `@latest`. This is library code: every
+ * adopter's dev server runs whatever this string resolves to, so `@latest` means a
+ * floating executable fetch — the tool can change under every consumer overnight,
+ * with haltija in nobody's lockfile and no version contract. A caret range still
+ * picks up fixes without letting a major land unannounced.
+ *
+ * Override with `HALTIJA_VERSION` (e.g. `HALTIJA_VERSION=haltija@beta` to test a
+ * pre-release, or a local path/tarball) — you should not have to edit library code
+ * to try a different haltija.
+ *
+ * Floor is **1.4.0** — the first release whose behavior this integration can rely on:
+ *   - `hj` routes to the server owning the current directory, so `hj` inside a project
+ *     drives THAT project's browser instead of falling back to a shared port and
+ *     silently driving whoever was focused there.
+ *   - a haltija server no longer overwrites the machine-wide `hj` binary with an older
+ *     copy on startup — so OUR spawning one can't downgrade the CLI for an unrelated,
+ *     up-to-date project (the exact "unpinned executable fetch from library code"
+ *     hazard this pin exists to bound).
+ *   - HTTPS-only servers stopped advertising an HTTP port they weren't listening on.
+ *   - `hj` action commands (`navigate`, `click`, …) exit NON-ZERO on failure, so the
+ *     test lane below can trust an exit code instead of racing to a timeout.
+ */
+const HALTIJA_PKG = process.env.HALTIJA_VERSION ?? 'haltija@^1.4.0';
+/**
+ * Resolve the idle-exit timeout to milliseconds (0 = disabled).
+ *
+ * Env wins over config, config over the default. An unparseable value falls back
+ * to the default rather than to 0: a typo'd `DEV_IDLE_TIMEOUT_HOURS=8h` must not
+ * silently turn the guard OFF — that is the exact failure it exists to prevent.
+ * Only an explicit non-positive number disables it.
+ */
+export function resolveIdleMs(configHours, envHours) {
+    const env = envHours?.trim();
+    const raw = env ? Number(env) : configHours ?? DEFAULT_IDLE_HOURS;
+    const hours = Number.isFinite(raw) ? raw : DEFAULT_IDLE_HOURS;
+    return hours > 0 ? hours * 3600_000 : 0;
+}
+const DEFAULT_LIMIT_MB = 4096;
+/**
+ * Resolve the RSS ceiling in MB (0 = disabled).
+ *
+ * Same rule as `resolveIdleMs`, and it was NOT being applied: the ceiling was read as
+ * `Number(env ?? config ?? 4096)`, which fails in both directions at once —
+ *
+ *   DEV_MEMORY_LIMIT_MB=''   → `??` passes '' through → Number('') === 0 → the ceiling
+ *                              is ZERO, so `rss >= limit` is true on the first sample
+ *                              and the dev server kills itself on every rebuild.
+ *   DEV_MEMORY_LIMIT_MB=4gb  → NaN → every `>=` comparison is false → the guard is
+ *                              silently OFF, on the machine of someone who was
+ *                              explicitly trying to configure it.
+ *
+ * An empty env var is *unset*, not zero. Garbage falls back to the default, never to
+ * off. Only an explicit non-positive number disables the ceiling.
+ */
+export function resolveLimitMb(configMb, envMb) {
+    const env = envMb?.trim();
+    const raw = env ? Number(env) : configMb ?? DEFAULT_LIMIT_MB;
+    const mb = Number.isFinite(raw) ? raw : DEFAULT_LIMIT_MB;
+    return mb > 0 ? mb : 0;
+}
+/**
+ * Reclaim the port we are about to bind, from the process LISTENING on it.
+ *
+ * That sentence is the predicate, and the old code did not implement it. It ran
+ * `lsof -ti:${port} | xargs kill -9`, and **`lsof -i:PORT` matches sockets whose
+ * LOCAL *or REMOTE* port is PORT** — so it returned every process merely *connected*
+ * to that port and SIGKILLed them all. Not theoretical: on this machine
+ * `lsof -ti:443` returns GitHub Desktop, Proton Bridge and two `claude` processes,
+ * none of which listen on 443. Aimed at our own dev port it would take out the
+ * browser reading the page, Playwright's browsers, the haltija Electron — anything
+ * with an open connection.
+ *
+ * We shipped that reasoning in this very file for `pkill -f haltija` ("a test lane
+ * that reaches outside the repo and kills the developer's tools presents as 'my tools
+ * got weird', never as a red test") and then failed to apply it here.
+ *
+ * So: listeners only; confirm each pid is actually a JS runtime before signalling
+ * (if something else owns our port, that is the user's business — say so, don't shoot
+ * it); SIGTERM first and give it a moment; SIGKILL only what refuses to die.
+ */
 async function killStrayServer(port) {
-    try {
-        await $ `lsof -ti:${port} | xargs kill -9 2>/dev/null`.quiet();
-    }
-    catch {
-        // No process on port, that's fine
+    // Number('') is 0, and `lsof -ti:0` matches sockets with an UNBOUND port — on this
+    // machine, system daemons. Never let a bad port become a kill list.
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return;
+    const pids = await $ `lsof -ti:${port} -sTCP:LISTEN`
+        .quiet()
+        .text()
+        .then((out) => out
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map(Number)
+        .filter((p) => Number.isInteger(p) && p > 0 && p !== process.pid))
+        .catch(() => []); // nothing listening — the normal case
+    for (const pid of pids) {
+        const comm = await $ `ps -p ${pid} -o comm=`
+            .quiet()
+            .text()
+            .then((s) => s.trim())
+            .catch(() => '');
+        if (!/\b(bun|node|deno)\b/.test(comm)) {
+            console.warn(`⚠️  port ${port} is held by pid ${pid} (${comm || 'unknown'}), which is not a\n` +
+                `    dev server — leaving it alone. Free the port, or set PORT to another one.`);
+            continue;
+        }
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            continue; // already gone
+        }
+        // Give it a moment to close the listener, then insist.
+        for (let i = 0; i < 20; i++) {
+            await Bun.sleep(50);
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                break; // exited
+            }
+            if (i === 19) {
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch {
+                    // gone between the check and the signal — fine
+                }
+            }
+        }
     }
 }
 /**
@@ -48,10 +177,8 @@ 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.
-        // `@latest` (1.3.2+): the widget-mode WebRTC screen capture (which makes the
-        // Electron app CI-only) is on the stable channel now, along with the fix for
-        // an accidental Electron launch. (Was pinned to `@beta` before 1.3.2.)
-        spawn(['bunx', 'haltija@latest', '--server', '--both'], {
+        // Version comes from HALTIJA_PKG — a pinned range, not `@latest`; see above.
+        spawn(['bunx', HALTIJA_PKG, '--server', '--both'], {
             stdout: 'ignore',
             stderr: 'ignore',
         });
@@ -80,17 +207,51 @@ async function ensureDevCerts() {
     process.exit(1);
 }
 export async function devServer(config, opts = {}) {
-    const PORT = config.port ?? 8787;
+    // PORT env wins over the config, so a test harness can bring up its own instance on
+    // its own port instead of adopting (or killing — killStrayServer takes the port)
+    // the dev server you already have running.
+    // `||`, not `??`: an EMPTY `PORT=` is unset, not "port zero". `??` only catches
+    // null/undefined, so `PORT=''` yielded `Number('') === 0` — and port 0 fed
+    // killStrayServer, whose `lsof -ti:0` matches sockets with an unbound port (system
+    // daemons, on this machine). An env var set to empty is the most ordinary shell
+    // accident there is; it must not become a kill list.
+    const PORT = Number(process.env.PORT || config.port || 8787);
     const PUBLIC = path.resolve('./', config.outputDir ?? 'docs');
     const isSPA = true;
     const testMode = !!opts.test;
+    // Don't add a days-long watch process to a machine that is already drowning — and
+    // don't quietly become the fourth stale dev server. `buildSite` preflights too, but a
+    // consumer's custom `build` need not go through it, and "on launch" is the moment a
+    // human is actually looking at the terminal.
+    //
+    // THROWS; does not `process.exit`. `devServer` is a public export, and library code
+    // killing the host process is not ours to do — the caller catches and decides. (The
+    // health tick below is different: by then we own a running server on a dying machine,
+    // and stopping it is the entire point of the guard.)
+    if (!(await preflight({
+        label: 'Dev server',
+        devLimitMb: config.memoryLimitMb,
+        mode: config.preflight,
+    }))) {
+        throw new Error('dev server: refusing to start — see the machine-health report above. ' +
+            'Override with DEV_SKIP_PREFLIGHT=1, or set `preflight: "warn"` in your site config.');
+    }
     // Haltija dev-channel — give a coding agent eyes on the running page. Opt-in
     // (config.haltijaDev or HALTIJA_DEV=1), never in test mode. The loader is a
     // localhost-gated runtime import() of the local channel's dev.js, so haltija
     // is never bundled and self-disables off-localhost; it's injected only at
     // serve time (below), so it never lands in the built output.
+    //
+    // Explicitly OFF under `HALTIJA_DEV=0` and in CI, which both override a config
+    // `haltijaDev: true`: the E2E lane starts this server, and there is no agent on
+    // the other end of the channel there — spawning it would only download an Electron
+    // app into the runner for nobody to look at.
     const HALTIJA_HTTPS_PORT = 8701;
+    const haltijaOff = process.env.HALTIJA_DEV === '0' ||
+        process.env.HALTIJA_DEV === 'false' ||
+        process.env.CI === 'true';
     const haltijaDev = !testMode &&
+        !haltijaOff &&
         (config.haltijaDev === true ||
             process.env.HALTIJA_DEV === '1' ||
             process.env.HALTIJA_DEV === 'true');
@@ -213,6 +374,85 @@ export async function devServer(config, opts = {}) {
             });
         }
     }
+    // Idle self-exit.
+    //
+    // The memory ceiling below bounds how bad one server gets; this bounds how many
+    // there are. A dev server is trivially forgotten — and a forgotten one is not
+    // inert, it is a days-old process still running the code it loaded at launch,
+    // leaking whatever that code leaked (updating the package does nothing for a
+    // process that is already running). Three of those, left over from before a leak
+    // fix landed, wedged a 32GB machine at ~210GB of demand. An idle server has no
+    // value to weigh against that, so it exits and lets you start a current one.
+    //
+    // Activity is a request served or a rebuild — i.e. someone is actually reading or
+    // editing. Off in test mode, which has its own timeout and exits on its own.
+    const idleMs = resolveIdleMs(config.idleTimeoutHours, process.env.DEV_IDLE_TIMEOUT_HOURS);
+    let lastActivity = Date.now();
+    const touch = () => {
+        lastActivity = Date.now();
+    };
+    // Memory watchdog.
+    //
+    // The build hands work to native code (the bundler, the HTML parser, the SVG
+    // rasterizer) which can strand memory the JS heap never sees — so nothing
+    // here can GC it away, and `heapUsed` stays flat while RSS climbs. A watch
+    // process lives for DAYS across thousands of rebuilds, so a per-rebuild leak
+    // compounds until the machine swaps itself to death. That is not
+    // hypothetical: a 2-day session reached 136GB RSS and took the machine down
+    // (Bun.build's native arena — see orchestrator.ts and oven-sh/bun#34053).
+    // Dying loudly beats being the reason a laptop overheats: the dev server is
+    // one keystroke to restart, the machine is not.
+    //
+    // Sampled after every rebuild AND on the periodic health tick below. The tick
+    // matters: a rebuild-only check is blind to a process that is already over the
+    // ceiling but has stopped rebuilding — which is exactly the shape of a server
+    // you have walked away from, i.e. the one that kills the machine.
+    const rssMb = () => Math.round(process.memoryUsage().rss / 1e6);
+    const limitMb = resolveLimitMb(config.memoryLimitMb, process.env.DEV_MEMORY_LIMIT_MB);
+    let baselineMb = 0;
+    let rebuilds = 0;
+    let warned = false;
+    const checkMemory = (fromRebuild = true) => {
+        if (limitMb <= 0)
+            return; // explicitly disabled
+        const mb = rssMb();
+        if (fromRebuild) {
+            rebuilds += 1;
+            if (!baselineMb)
+                baselineMb = mb;
+        }
+        if (!baselineMb)
+            baselineMb = mb;
+        const growth = mb - baselineMb;
+        const each = rebuilds > 1 ? growth / (rebuilds - 1) : 0;
+        if (mb >= limitMb) {
+            // Distinguish the two ways to get here, because the advice is opposite:
+            // memory that GREW across rebuilds is a leak (report it); a build that was
+            // simply born bigger than the ceiling just needs a bigger ceiling.
+            const leaking = rebuilds > 1 && each >= 1;
+            const diagnosis = leaking
+                ? `   ${rebuilds} rebuilds, +${growth}MB since the first ` +
+                    `(~${each.toFixed(1)}MB per rebuild).\n\n` +
+                    `   Growth per rebuild should be ~0, so this is a leak, not your project\n` +
+                    `   getting bigger. Restarting reclaims it — please report the numbers\n` +
+                    `   above. If this build genuinely needs the headroom, raise the ceiling\n` +
+                    `   with DEV_MEMORY_LIMIT_MB=<mb> or memoryLimitMb in your site config.\n`
+                : `   ${rebuilds} rebuild${rebuilds === 1 ? '' : 's'}, ` +
+                    `+${growth}MB since the first — i.e. it is not growing.\n\n` +
+                    `   This build's baseline footprint is simply above the ceiling, which is\n` +
+                    `   not a leak. Raise it with DEV_MEMORY_LIMIT_MB=<mb> or memoryLimitMb in\n` +
+                    `   your site config.\n`;
+            console.error(`\n🛑 dev server stopping: ${mb}MB RSS, over the ${limitMb}MB limit.\n\n` +
+                diagnosis);
+            process.exit(1);
+        }
+        if (!warned && mb > limitMb * 0.6) {
+            warned = true;
+            console.warn(`⚠️  dev server at ${mb}MB RSS after ${rebuilds} rebuilds (+${growth}MB, ` +
+                `~${each.toFixed(1)}MB each; limit ${limitMb}MB). Growth per rebuild ` +
+                `should be ~0 — if this keeps climbing, restart and report it.`);
+        }
+    };
     if (!testMode) {
         // Rebuild on any source change. By default that's just buildSite(), but a
         // consumer whose full build has steps BEYOND buildSite — e.g. a custom IIFE
@@ -223,6 +463,40 @@ export async function devServer(config, opts = {}) {
         // never regenerated — leaving the page's /iife.js to 404 into the SPA
         // fallback (it "loads as html"). Serialize builds and coalesce bursts.
         const runBuild = opts.build ?? (() => buildSite(config));
+        // Rebuild-storm detector.
+        //
+        // The other way this process eats the machine is not a leak but a LOOP: if the
+        // build writes a file that the watcher watches, every rebuild triggers the next
+        // one, forever. Each iteration spawns children (bundler, css, ePub), pegs the
+        // CPU, and adds the per-rebuild residual — so a loop is a leak with a throttle
+        // removed. The known self-writes (`version.ts`, `icon-data.ts`) are in `ignored`
+        // below, but `config.prebuild` is arbitrary consumer code: anything it writes
+        // into a watched path loops, and the failure looks like "my fan is on" rather
+        // than like a bug.
+        //
+        // RATE is the wrong signal, and it is worth saying why, because it is the obvious
+        // thing to reach for and it does not work: this project's build takes ~3s, so a
+        // real loop can only manage ~19 rebuilds a minute — under any "20 a minute" limit
+        // you would think to set. Meanwhile a 200ms build loops at 300 a minute. No single
+        // rate threshold is both blind to human editing and sensitive to a slow-build loop.
+        //
+        // The signal that actually separates them is that a loop is SELF-SUSTAINING: the
+        // next rebuild is always already queued the instant the current one ends. There is
+        // never a human-scale pause, because no human is involved. So count *consecutive
+        // immediate* rebuilds, and let any ordinary gap — someone pausing to think, even
+        // for two seconds — reset the count.
+        const IMMEDIATE_MS = 1500;
+        const LOOP_STREAK = 30; // fatal: 30 rebuilds with no human-scale gap between any
+        const LOOP_WARN = 15;
+        let lastBuildEnd = 0;
+        let streak = 0;
+        let stormWarned = false;
+        const triggers = new Map();
+        const topTriggers = () => [...triggers.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .map(([p, n]) => `   ${String(n).padStart(4)}x  ${p}`)
+            .join('\n');
         let building = false;
         let pending = false;
         const rebuild = async () => {
@@ -231,6 +505,11 @@ export async function devServer(config, opts = {}) {
                 return;
             }
             building = true;
+            // "Immediate" covers both shapes a loop takes: for a SLOW build the self-write
+            // lands mid-build and `pending` is already set when it ends (so the next rebuild
+            // starts at once); for a FAST build the watcher event arrives just after the end.
+            // Both look like: started again with no gap.
+            const immediate = lastBuildEnd > 0 && Date.now() - lastBuildEnd < IMMEDIATE_MS;
             try {
                 await runBuild();
             }
@@ -239,6 +518,26 @@ export async function devServer(config, opts = {}) {
             }
             finally {
                 building = false;
+                lastBuildEnd = Date.now();
+                streak = immediate ? streak + 1 : 0;
+                touch();
+                checkMemory();
+                if (streak >= LOOP_STREAK) {
+                    console.error(`\n🛑 dev server stopping: rebuild loop — ${streak} rebuilds back to back, ` +
+                        `with no pause between any of them.\n\n` +
+                        `   The files that keep triggering it:\n\n${topTriggers()}\n\n` +
+                        `   A build that writes a file it also watches rebuilds forever, spawning a\n` +
+                        `   bundler every time until the machine gives up — a loop is a leak with the\n` +
+                        `   throttle removed. If a file above is generated by your build, stop writing\n` +
+                        `   it into a watched path, or add it to the watcher's ignore list (\`ignored\`\n` +
+                        `   in dev-server.ts; see the \`prebuild\` notes in the doc-site-system docs).\n`);
+                    process.exit(1);
+                }
+                if (streak >= LOOP_WARN && !stormWarned) {
+                    stormWarned = true;
+                    console.warn(`⚠️  ${streak} rebuilds back to back with no pause — this looks like a rebuild\n` +
+                        `    loop (a build writing a file it also watches). Top triggers:\n${topTriggers()}`);
+                }
                 if (pending) {
                     pending = false;
                     void rebuild();
@@ -254,7 +553,12 @@ export async function devServer(config, opts = {}) {
             './icons',
             ...(config.watchPaths ?? []),
         ];
-        watch(watchPaths, { ignored, ignoreInitial: true }).on('all', () => void rebuild());
+        watch(watchPaths, { ignored, ignoreInitial: true }).on('all', (_event, changedPath) => {
+            if (changedPath) {
+                triggers.set(changedPath, (triggers.get(changedPath) ?? 0) + 1);
+            }
+            void rebuild();
+        });
     }
     await ensureDevCerts();
     const server = Bun.serve({
@@ -264,6 +568,7 @@ export async function devServer(config, opts = {}) {
             cert: Bun.file('./tls/certificate.pem'),
         },
         async fetch(request) {
+            touch();
             let reqPath = new URL(request.url).pathname;
             console.log(request.method, reqPath);
             if (request.method === 'POST' && reqPath === '/report') {
@@ -292,6 +597,60 @@ export async function devServer(config, opts = {}) {
         },
     });
     console.log(`Listening on https://localhost:${PORT}`);
+    // ── health tick ───────────────────────────────────────────────────────────
+    //
+    // Everything else in this file is edge-triggered: the RSS check fires after a
+    // rebuild, the preflight fires at launch. Both are blind to the state that
+    // actually kills machines — a server nobody is touching any more, sitting on
+    // gigabytes, on a box that is quietly filling up around it. Nothing rebuilds,
+    // so nothing looks. So look on a timer, not only on an event.
+    //
+    // Three checks, cheapest first:
+    //   1. RSS ceiling — catches a process already over the line that has stopped
+    //      rebuilding (the walked-away-from server).
+    //   2. Idle exit — bounds how MANY servers exist, not just how big one gets.
+    //   3. Machine preflight (every tick) — catches the box going bad around us,
+    //      including other projects' runaways. If the machine is dying we exit too, and
+    //      print the PIDs and the kill command on the way out. Exiting IS the guard here,
+    //      unlike at launch where we throw: by now we own a running server on a dying
+    //      machine, and the whole point is to stop being part of the problem.
+    if (!testMode) {
+        if (idleMs > 0) {
+            console.log(`Exits after ${idleMs / 3600_000}h idle (DEV_IDLE_TIMEOUT_HOURS=0 to disable).`);
+        }
+        // Every minute, not every five. The runaway that killed the machine went 0→100GB
+        // in about twenty minutes; on a box whose dev budget is a fraction of its RAM
+        // (most of it held by a resident model), the trip from healthy to unrecoverable
+        // fits comfortably inside a five-minute window — and with swap on a fast, large
+        // disk, macOS will thrash for a very long time before it gives up, which is more
+        // rope to hang the machine with, not less. A `ps` + `vm_stat` per minute is free.
+        const TICK_MS = 60_000;
+        const timer = setInterval(async () => {
+            checkMemory(false); // exits if we are over the ceiling
+            const idleFor = Date.now() - lastActivity;
+            if (idleMs > 0 && idleFor >= idleMs) {
+                console.log(`\n💤 dev server exiting: idle for ${Math.round(idleFor / 3600_000)}h — no requests, no rebuilds.\n\n` +
+                    `   Restart it when you need it; a fresh one also picks up any dependency\n` +
+                    `   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();
+                process.exit(0);
+            }
+            const ok = await preflight({
+                label: 'Dev server',
+                devLimitMb: config.memoryLimitMb,
+                mode: config.preflight,
+            });
+            if (!ok) {
+                clearInterval(timer);
+                server.stop();
+                process.exit(1);
+            }
+        }, TICK_MS);
+        // Never let the health check itself be the thing keeping the process alive.
+        timer.unref?.();
+    }
     if (haltijaDev) {
         await ensureHaltijaChannel(HALTIJA_HTTPS_PORT);
     }
@@ -313,9 +672,13 @@ export async function devServer(config, opts = {}) {
         }
         if (!hjAvailable) {
             console.log('Starting haltija...');
-            haltija = spawn(['bunx', 'haltija@latest', '-f'], {
-                stdout: 'inherit',
-                stderr: 'inherit',
+            // stdout/stderr are NOT inherited: `bunx haltija` launches an Electron app as a
+            // grandchild, and killing the bunx wrapper does not kill it. An orphaned Electron
+            // holding our inherited stdout keeps the pipe open forever, so a CI job or an
+            // agent capturing this command's output sees it hang long after it exited (0).
+            haltija = spawn(['bunx', HALTIJA_PKG, '-f'], {
+                stdout: 'ignore',
+                stderr: 'ignore',
             });
             console.log('Waiting for browser...');
             for (let i = 0; i < 20; i++) {
@@ -341,20 +704,82 @@ export async function devServer(config, opts = {}) {
         else {
             console.log('Using existing haltija browser');
         }
+        /**
+         * Tear down the haltija WE started — including the Electron grandchild.
+         *
+         * `haltija.kill()` only signals the `bunx` wrapper; the Electron app it launched
+         * survives. A surviving instance leaves stale windows behind, and the next
+         * `--test` run reuses any haltija reporting `windows.length > 0` — so the run
+         * after this one navigates a dead window, never POSTs /report, and fails with
+         * "Browser tests timed out" on a perfectly good codebase.
+         *
+         * The predicate is **descendants of the process we spawned** — NOT `pkill -f
+         * haltija/apps/desktop`, which is what this used to do while claiming in this very
+         * comment to leave your own haltija alone. `pkill -f` matches every process on the
+         * machine whose command line contains that string, so it killed the haltija YOU
+         * were running too. And it is the *test suite* that runs this: we spawn our own
+         * whenever yours reports zero windows, so "haltija open, no windows, run the doc
+         * tests" silently killed your browser. A test lane that reaches outside the repo
+         * and kills the developer's tools presents as "my tools got weird", never as a red
+         * test.
+         *
+         * The tree is collected BEFORE the wrapper dies: once it is gone, Electron is
+         * reparented to init and `pgrep -P` can no longer find it.
+         */
+        const descendantsOf = async (pid) => {
+            const out = await $ `pgrep -P ${pid}`
+                .quiet()
+                .text()
+                .catch(() => '');
+            const kids = out
+                .trim()
+                .split('\n')
+                .filter(Boolean)
+                .map(Number)
+                .filter((n) => Number.isInteger(n) && n > 0);
+            const all = [...kids];
+            for (const kid of kids)
+                all.push(...(await descendantsOf(kid)));
+            return all;
+        };
+        const stopHaltija = async () => {
+            if (!haltija?.pid)
+                return;
+            const tree = await descendantsOf(haltija.pid);
+            haltija.kill();
+            for (const pid of tree) {
+                try {
+                    process.kill(pid, 'SIGTERM');
+                }
+                catch {
+                    // already gone — fine
+                }
+            }
+        };
         console.log('Opening demo site...');
-        await $ `hj navigate https://localhost:${PORT}`;
+        // haltija 1.4: `hj navigate` exits NON-ZERO on failure (no browser reachable, a
+        // window that didn't take the URL, …). Before 1.4 it exited 0 regardless, so a
+        // failed navigate silently sailed on and the run died 120s later at the test
+        // timeout with a misleading "Browser tests timed out". Now we can read the exit
+        // code: fail immediately, say why, and tear down the haltija we spawned so the
+        // next run isn't inheriting a half-navigated browser.
+        const nav = await $ `hj navigate https://localhost:${PORT}`.nothrow().quiet();
+        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);
+        }
         try {
             const results = await testResults;
             const exitCode = results.failed > 0 ? 1 : 0;
-            if (haltija)
-                haltija.kill();
+            await stopHaltija();
             server.stop();
             process.exit(exitCode);
         }
         catch (e) {
             console.error(e.message);
-            if (haltija)
-                haltija.kill();
+            await stopHaltija();
             server.stop();
             process.exit(1);
         }

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,22 @@
+/*
+Standalone ePub build — the subprocess entry point for buildEpub().
+
+buildEpub() drives happy-dom (HTML→XHTML for 50+ chapters) and @resvg/resvg-js
+(cover rasterization). Both hold native/retained memory that the JS heap can't
+see, and the ePub is rebuilt on EVERY dev-server rebuild — so in-process it
+strands memory in a watch process that lives for days. Running it in a child
+hands all of it back to the OS on exit. Same reasoning as the bundle step; see
+the Bun.build note in orchestrator.ts.
+
+  bun epub-cli.ts <payload.json>     # payload = { config, opts }
+
+Build-time only. Never import this from browser code.
+*/
+import { buildEpub } from './epub';
+const payloadPath = process.argv[2];
+if (!payloadPath) {
+    console.error('epub-cli: expected a payload file path');
+    process.exit(1);
+}
+const { config, opts } = JSON.parse(await Bun.file(payloadPath).text());
+await buildEpub(config, opts ?? {});

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

@@ -535,6 +535,12 @@ export async function buildEpub(config, opts = {}) {
     const output = path.resolve(opts.output ?? path.join(outDir, `${slugify(meta.title)}.epub`));
     await zipEpub(buildDir, output);
     fs.rmSync(buildDir, { recursive: true, force: true });
+    // Release the parser window: an unclosed happy-dom Window holds its whole
+    // document (every chapter parsed) plus its timers. Hygiene, not a proven win —
+    // buildEpub still grows ~1.5MB per call with this in place, so something here
+    // is still retained. buildEpub now runs in a child process (see orchestrator),
+    // which is what actually bounds it.
+    win?.close?.();
     console.log(`epub: ${output} (${chapters.length} chapters)`);
     return output;
 }

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

@@ -10,6 +10,7 @@ the IIFE bundle loads.
 Build-time only (uses Bun.write). Shares slug + markdown rendering with the runtime
 component (src/doc-system/*) so static and hydrated output agree.
 */
+import { pageTitle } from '../doc-title';
 import { buildSlugMap, pathForSlug, rewriteDocLinks } from '../routing';
 import { buildNavTree, navOpenPath } from '../nav-tree';
 import { renderDocMarkdown, docDescription } from '../render';
@@ -80,12 +81,9 @@ function pageHtml(doc, config, slugMap, configAttr) {
     const localizedAttr = config.localizedStrings
         ? ` localized="${escapeAttr(withBase(basePath, localizedUrl))}"`
         : '';
-    // `headTitle` is the verbatim <title>; otherwise suffix the project name (unless
-    // the doc title already includes it).
-    const title = doc.headTitle ||
-        (projectName && !doc.title.includes(projectName)
-            ? `${doc.title} — ${projectName}`
-            : doc.title);
+    // ONE rule, shared with the doc-browser's hydration path — see doc-title.ts. Writing
+    // it twice is what made the title change on hydration (issue #6).
+    const title = pageTitle(doc, projectName);
     // Per-page metadata (from the doc's JSON block) wins; else derive, else site default.
     const description = doc.description || docDescription(doc.text) || config.description || '';
     const keywords = Array.isArray(doc.keywords)

package/dist/doc-system/site/make-llms-txt.js

@@ -102,21 +102,6 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
         console.warn('llms.txt: no readable package.json — using config values only');
     }
     const entries = corpus ? entriesFromCorpus(corpus, meta) : entriesFromSrcScan();
-    // Only orient agents about the live-example execution model when the corpus
-    // actually has live examples (a book / pure-docs site has none).
-    const exampleFence = /```(js|tjs|ts|html|css)\b/;
-    const hasLiveExamples = !!corpus && corpus.some((d) => exampleFence.test(d.text ?? ''));
-    const liveExampleNote = hasLiveExamples
-        ? [
-            'Live examples run inline on the shared page by default (not sandboxed):',
-            'each has its own `preview` element, but they share one tosijs module, so',
-            '`tosi()` state singletons are shared across every example on a page. This is',
-            'deliberate (it shows tosi isolation and lets you drive demos via the global',
-            'singleton). Namespace example state with unique top-level keys so examples',
-            "don't clobber each other; the `iframe` attribute isolates DOM/CSS, not state.",
-            '',
-        ]
-        : [];
     const name = meta.name ?? pkg.name ?? '';
     const description = meta.description ?? pkg.description ?? '';
     const links = [];
@@ -140,7 +125,6 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
         '',
         'Full documentation, with live code examples, is at the links below.',
         '',
-        ...liveExampleNote,
         '## Pages',
         '',
     ];