tosijs-ui 1.9.1 → 1.9.3

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # 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
+`hj map` (haltija 1.11) over the doc site, which reports a measured contrast ratio per
+node — none of these were visible as wrong to the eye.
+
+| pair | was | now |
+| --- | --- | --- |
+| test widget, running | white on `#fa0` — **1.9:1** | `#2b1a00` on `#fa0` — 8.8:1 |
+| test widget, passed | white on `#0a0` — **3.1:1** | white on `#008a00` — 4.5:1 |
+| `--tosi-accent` as text | `#EE257B` — **4.05:1** on white, 4.3:1 on the page | `#d92270` — 4.6:1 |
+| `--tosi-accent` as a fill | white on `#EE257B` — **4.05:1** | white on `#d92270` — 4.8:1 |
+
+**The brand pink is 9% darker** (`#EE257B` → `#d92270`). It is imperceptible side by side
+and it was the only value that clears AA in *both* directions — as text on the page, and
+as a fill carrying white text. Override `--tosi-accent` if you want the original.
+
+Two more, found by sweeping wider — both in **example code we publish**, which matters
+more than a component default because people copy it: the `.-negative { color: #e44 }` we
+document for negative numbers in tables sat at **3.63:1** (now `#d32f2f`, 4.77:1), and
+`#007AFF` — the accent in every theming example in our docs — was **4.02:1** under white
+text (now `#0064d2`, 5.59:1).
+
+Also fixed: the doc-site brand bar's text was a hand-tuned warm off-white
+(`brandColor.rotate(30).brighten(0.9)` → `#fbeae9`) sitting at **4.09:1** on the brand —
+under AA for the normal-size nav links in it. Every brighten value short of pure white
+also misses, so it now uses `contrasting()`, which picks the readable extreme for whatever
+the brand currently is and cannot drift when the brand moves. Three stale `#EE257B` /
+`#007AFF` fallbacks were still live in `header.ts` and `doc-browser.ts` and now match.
+
+Verified across 8 pages in both themes on haltija 1.11.2: **0 failures, 0 uncertain**.
+
+**The browser-test lane now runs its own private haltija.** It used to reuse any running
+instance and otherwise spawn with `-f`, which reclaims haltija's shared default port and
+kills whatever held it. Both halves were wrong: adopting meant inheriting the *desktop
+app's* window, whose visibility depends on whatever else is on screen — and `hj` rightly
+refuses to drive a hidden tab, since a backgrounded tab throttles `requestAnimationFrame`
+and would produce plausible-but-wrong results. The lane failed roughly two runs in three
+with no programmatic way out. It now takes an isolated instance on an ephemeral port:
+**4/4 runs green**, and a concurrent haltija belonging to someone else survives untouched
+(verified both). Closes #18 and #21.
+
+The test widget's text color is now **paired** with its background rather than hardcoded
+to white. Amber is a genuinely light color: darkening it enough for white text turns it
+brown and stops reading as "in progress", so it keeps its hue and takes dark text, which
+is the conventional warning-badge treatment. New `--tosi-test-text-color-{pass,fail,running}`
+variables if you theme these.
+
+In dark mode the brand color is **brightened** rather than reused: `invertLuminance` flips
+the neutrals but leaves a saturated hue roughly where it was, so a pink dark enough for a
+near-white page landed at 4.4:1 on a near-black one. The hue is the brand; the luminance
+belongs to whatever it sits on.
+
 ## 1.9.1
 
 **`tosijs-ui` did not import under Node.** Shipped `dist/` used extensionless relative

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/data-table.js

@@ -221,7 +221,7 @@ Numeric types (`number`, `currency`, `fixed`, `percent`, `sci`, `eng`, `bytes`)
 by default; `boolean` centers and renders icons. An explicit `align` — or a `dataCell` —
 always wins. Formatting follows the app locale (`setLocale()`). Numeric cells also get a
 `-negative` or `-zero` state class by value sign, so the red "Change" values above come from
-one CSS rule (`.-negative { color: #e44 }`), no cell renderer.
+one CSS rule (`.-negative { color: #d32f2f }`), no cell renderer.
 
 ```js
 import { tosiTable } from 'tosijs-ui'
@@ -251,7 +251,7 @@ table.value = {
 preview.append(table)
 ```
 ```css
-.preview .-negative { color: #e44; }
+.preview .-negative { color: #d32f2f; }
 .preview .-zero { opacity: 0.45; }
 ```
 
@@ -687,10 +687,10 @@ export class TosiTable extends WebComponent {
             background: varDefault.tosiTableHeaderBg(varDefault.tosiTableBg('var(--tosi-bg, #fff)')),
         },
         ':host .tr[aria-selected] .td': {
-            background: varDefault.tosiTableSelectedBg('var(--tosi-accent, #007AFF22)'),
+            background: varDefault.tosiTableSelectedBg('var(--tosi-accent, #0064d222)'),
         },
         ':host .td:focus, :host .th:focus': {
-            outline: '2px solid var(--tosi-accent, #007AFF)',
+            outline: '2px solid var(--tosi-accent, #0064d2)',
             outlineOffset: '-2px',
             zIndex: '1',
         },

package/dist/doc-browser.js

@@ -164,12 +164,29 @@ import { popMenu } from './menu.js';
 import { codeEditor } from './code-editor.js';
 import { tosiDiff } from './diff.js';
 const { div, span, a, header, button, template, input, h2, img, details, summary, ul, li, } = elements;
-// Test colors
+/*
+Test colors, and the text color that goes ON each — because contrast is a PAIR.
+
+The widget used one hardcoded `color: white` and swapped only the background, so the
+amber running state rendered white-on-#fa0 at **1.9:1** and the green pass state at
+**3.1:1**, both well under WCAG AA's 4.5:1. (Found by `hj map`, which reports a
+`contrast` ratio per node — invisible to the eye until measured.)
+
+Amber is a genuinely light color: darkening it far enough for white text turns it brown
+(63% brightness) and stops reading as "in progress". So it keeps its hue and takes dark
+text at 11:1, which is the conventional warning-badge treatment. Green only needed a
+nudge (81% brightness) to carry white.
+*/
 const testColor = {
-    pass: varDefault.testColorPass('#0a0'),
+    pass: varDefault.testColorPass('#008a00'),
     fail: varDefault.testColorFail('#c00'),
     running: varDefault.testColorRunning('#fa0'),
 };
+const testTextColor = {
+    pass: varDefault.testTextColorPass('#fff'),
+    fail: varDefault.testTextColorFail('#fff'),
+    running: varDefault.testTextColorRunning('#2b1a00'),
+};
 // Test indicator styles - widget inherits button styles from base stylesheet
 const testIndicatorStyleSpec = {
     '.view-source': { opacity: '0.9' },
@@ -215,25 +232,30 @@ const testIndicatorStyleSpec = {
     // was overlaying this.
     '.test-widget': {
         _testBg: testColor.running,
+        _testFg: testTextColor.running,
         position: 'fixed',
         bottom: vars.spacing,
         left: vars.spacing,
         zIndex: '1000',
         background: vars.testBg,
-        color: 'white',
+        // Paired with the background, not fixed to white — see testTextColor above.
+        color: vars.testFg,
         gap: vars.spacing50,
     },
     '.test-widget[hidden]': { display: 'none' },
     '.test-widget.-running': {
         _testBg: testColor.running,
+        _testFg: testTextColor.running,
         animation: 'test-appear 0.3s ease-out, test-pulse 2s ease-in-out 0.3s infinite',
     },
     '.test-widget.-passed': {
         _testBg: testColor.pass,
+        _testFg: testTextColor.pass,
         animation: 'test-fade 3s ease-out forwards',
     },
     '.test-widget.-failed': {
         _testBg: testColor.fail,
+        _testFg: testTextColor.fail,
         animation: 'test-pulse 2s ease-in-out infinite',
     },
     // Count badge
@@ -250,7 +272,7 @@ const testIndicatorStyleSpec = {
     },
     // Deep-linked example (e.g. arriving at /slug/#example-2): brief highlight pulse
     '@keyframes example-target-pulse': {
-        from: { boxShadow: `0 0 0 3px ${varDefault.accent('#007aff')}` },
+        from: { boxShadow: `0 0 0 3px ${varDefault.accent('#0064d2')}` },
         to: { boxShadow: '0 0 0 3px transparent' },
     },
     '.example-target': {

package/dist/doc-system/doc-system-styles.js

@@ -20,7 +20,7 @@ export const SIDEBAR_WIDTH = 200;
 export const SIDEBAR_BREAKPOINT = 600;
 /** Compute the full set of `:root` color variables from a few base colors. */
 export function docSystemColors(theme = {}) {
-    const brandColor = Color.fromCss(theme.accent ?? '#EE257B');
+    const brandColor = Color.fromCss(theme.accent ?? '#d92270');
     return {
         _textColor: theme.text ?? '#222',
         _brandColor: brandColor,
@@ -32,7 +32,18 @@ export function docSystemColors(theme = {}) {
         _barColor: brandColor.opacity(0.4),
         _focusColor: brandColor.opacity(0.7),
         _placeholderColor: brandColor.opacity(0.4),
-        _brandTextColor: brandColor.rotate(30).brighten(0.9),
+        /*
+        `contrasting()` rather than a hand-tuned tint.
+    
+        `brandColor.rotate(30).brighten(0.9)` produced a warm off-white (#fbeae9) that sat at
+        **4.09:1** on the brand bar — under AA for the normal-size nav links in it. Every
+        brighten value short of pure white also misses (0.96 lands at 4.49), so the tint had
+        to go; it was imperceptible anyway. `contrasting()` picks the readable extreme for
+        whatever the brand currently is, so this cannot drift the next time the brand moves.
+        Dark mode is unaffected: invertLuminance flips this to near-black on the brightened
+        bar, which is already high-contrast.
+        */
+        _brandTextColor: brandColor.contrasting(),
         _insetBg: brandColor.rotate(45).brighten(0.8),
         // Neutral off-white (not brand-tinted); dark mode inverts its luminance to
         // off-black, so the editor surface stays a clean neutral in both themes.
@@ -55,7 +66,7 @@ export function docSystemColors(theme = {}) {
 /** Build the full doc-system stylesheet for a given base theme. */
 export function docSystemStyleSpec(theme = {}) {
     const colors = docSystemColors(theme);
-    const brandColor = Color.fromCss(theme.accent ?? '#EE257B');
+    const brandColor = Color.fromCss(theme.accent ?? '#d92270');
     return {
         '@import': 'https://fonts.googleapis.com/css2?family=Aleo:ital,wght@0,100..900;1,100..900&famiSpline+Sans+Mono:ital,wght@0,300..700;1,300..700&display=swap',
         ':root': {
@@ -89,6 +100,16 @@ export function docSystemStyleSpec(theme = {}) {
         },
         '.darkmode': {
             ...invertLuminance(colors),
+            /*
+            Lift the brand color for dark backgrounds.
+      
+            `invertLuminance` flips the neutrals but leaves a saturated brand hue roughly where
+            it was, so one accent has to serve both a near-white and a near-black page — and a
+            pink dark enough to clear AA on `#fafafa` (4.56:1) lands at 4.4:1 on `#050505`,
+            just under. Brightening it in dark mode is the standard resolution: the hue is the
+            brand, the luminance belongs to the background it sits on.
+            */
+            _brandColor: brandColor.brighten(0.18),
             _shadowColor: brandColor.opacity(0.5),
             _menuShadow: `0 0 0 2px ${brandColor.opacity(0.75)}`,
             _menuSeparatorColor: brandColor.opacity(0.5),

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

@@ -9,13 +9,14 @@ Build-time only (Bun APIs). Never import this from browser code.
 */
 import * as path from 'path';
 import { statSync } from 'fs';
+import { tmpdir } from 'os';
 import { $, spawn } from 'bun';
 import { buildSite } from './orchestrator.js';
 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;
 /**
@@ -940,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}` +
@@ -1071,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'),
@@ -1107,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),
@@ -1131,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 ─────────────────────
     //
@@ -1182,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',
@@ -1193,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.
@@ -1210,7 +1249,6 @@ export async function devServer(config, opts = {}) {
             testReportResolve = resolve;
             setTimeout(() => reject(new Error('Browser tests timed out')), testTimeout);
         });
-        let haltija;
         /**
          * Tear down the haltija WE started — including the Electron grandchild. Defined up
          * front so EVERY failure path can call it, including the start-timeout below, which
@@ -1270,72 +1308,54 @@ export async function devServer(config, opts = {}) {
     
         Declining to adopt is safe: we spawn with `-f`, which stomps the stale instance.
         */
-        const haltijaReachable = async () => {
+        /*
+        ALWAYS an isolated instance. Never adopt, never stomp.
+    
+        The lane used to reuse any reachable haltija and otherwise spawn with `-f`, which
+        reclaims the shared default port and SIGTERMs whatever held it — often another
+        project's session. Both halves were a problem:
+    
+          - adopting meant inheriting the DESKTOP app's window, whose visibility depends on
+            whatever else is on screen. `hj` refuses to drive a hidden tab (rightly — a
+            backgrounded tab throttles rAF, so results are plausible-but-wrong), so the lane
+            failed intermittently, roughly two runs in three, with no programmatic way out.
+          - `-f` made this project's test run destructive to everyone else's.
+    
+        `--private` gives us our own server on an EPHEMERAL port, so there is nothing to
+        contend for and nothing to kill. The port is written to a file rather than guessed.
+        (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], {
+            // 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
+            // long after it exited.
+            stdout: 'ignore',
+            stderr: 'ignore',
+        });
+        // Read the port it actually bound, rather than assuming one.
+        let hjPort = '';
+        for (let i = 0; i < 60; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 500));
             try {
-                /*
-                `--json`, and fail CLOSED.
-        
-                Bare `hj windows` appends a dim hint line to STDOUT after the JSON, so
-                `JSON.parse` throws and a `catch` that fell through to `return true` adopted the
-                very dead server this check exists to reject — the gate was inert on every
-                npm-installed CLI. It passed verification here only because this machine's `hj` is
-                a standalone bundle with no `hints.json` beside it, so the hint was never emitted:
-                a real behavioural test, run against an environment adopters do not have.
-        
-                Failing closed costs nothing: the spawn below uses `-f`, which stomps a stale
-                instance. Adopting a server we could not read is the expensive direction.
-                */
-                const out = await $ `hj windows --json`.quiet().text();
-                return haltijaIsDrivable(out);
+                const info = JSON.parse(await Bun.file(portFile).text());
+                hjPort = String(info.port ?? info.address?.port ?? '');
+                if (hjPort)
+                    break;
             }
             catch {
-                return false;
+                /* not written yet */
             }
-        };
-        const adoptable = await haltijaReachable();
-        if (!adoptable) {
-            /*
-            Leave a receipt: spawning with `-f` reclaims haltija's shared default port, which
-            SIGTERMs whatever was there — frequently another project's session, or the
-            developer's own. This file already sets that norm for killStrayServer; declining to
-            adopt makes the stomp MORE frequent, so it must be at least as loud.
-            */
-            console.log(`No drivable haltija (server absent, or up with no connected tab).\n` +
-                `  Starting one with -f, which reclaims the shared haltija port — any other\n` +
-                `  project's session on it will be stopped.  (cwd: ${process.cwd()})`);
         }
-        if (adoptable) {
-            console.log('Using existing haltija browser');
-        }
-        else {
-            console.log('Starting haltija...');
-            // 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',
-            });
-            const waitStarted = Date.now();
-            console.log('Waiting for haltija…');
-            let up = false;
-            for (let i = 0; i < 20; i++) {
-                await new Promise((resolve) => setTimeout(resolve, 500));
-                if (await haltijaReachable()) {
-                    up = true;
-                    break;
-                }
-            }
-            if (!up) {
-                console.error(`haltija did not become drivable within ${Math.round((Date.now() - waitStarted) / 1000)}s.\n` +
-                    `  A single \`hj windows\` can block for several seconds when a server is up\n` +
-                    `  with no tab, so this can take much longer than the poll count suggests.`);
-                await stopHaltija();
-                server.stop();
-                process.exit(1);
-            }
+        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.`);
+            await stopHaltija();
+            shutdown(1);
         }
+        console.log(`  private haltija on port ${hjPort}`);
         console.log('Opening demo site...');
         // 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
@@ -1343,25 +1363,24 @@ export async function devServer(config, opts = {}) {
         // 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();
+        const nav = await $ `hj --port ${hjPort} 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);
+            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);
         }
     }
 }