handmux 0.23.0 → 0.25.0

package/dist/src/orphans.js

@@ -0,0 +1,167 @@
+// Detect "orphan" coding-agent sessions: a `claude`/`codex`/… process running on this host that is NOT
+// inside a tmux pane, so handmux can't see or steer it. We can't migrate a live process into tmux (reptyr
+// needs Linux ptrace+/proc — out on macOS — and breaks on multithreaded Node + child processes), so instead
+// we surface these in the Inbox and offer a "takeover": spawn the agent's `resume` command in a fresh tmux
+// pane (the agent's own persistence continues the conversation), then optionally kill the original.
+//
+// Detection is process-based, NOT a scan of the agents' session history (which is unbounded and can't tell
+// a live session from a dead one). Cost scales with the number of LIVE agent processes only.
+//
+// tmux membership is decided by TTY/PPID match against `tmux list-panes`, NOT by reading the process
+// environment: on macOS `ps eww` can't read another process's env (SIP), so `$TMUX` is a false signal.
+// A proc whose controlling tty is one of tmux's pane ttys (or whose parent is a pane's shell) is in tmux;
+// anything else with a real tty is an orphan.
+//
+// This module is now the agent-AGNOSTIC engine: which processes count, where a cwd's session lives, and how
+// to resume it all come from the driver descriptors in ./agents (parseAgentProcs tags each proc with its
+// agent; scan/takeover dispatch through getAgent). The pure parse/file helpers live in ./agents/scanUtils.
+import os from 'node:os';
+import path from 'node:path';
+import { AGENTS, getAgent } from './agents/index.js';
+import { isSessionId } from './tmux/commands.js';
+import { tmuxFormat } from './tmux/format.js';
+import { defaultRun, parseAgentProcs, parsePaneMembership, findOrphans, takeoverSessionName, sanitizeSessionName, freeSessionName, isShell, lsofCwd, isSessionUuid, } from './agents/scanUtils.js';
+const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : null);
+// Orphan candidates created before multi-Agent scanning had no `agent` field and were necessarily Claude.
+// Preserve only that absent-field format default; an explicit unknown id must still fail closed.
+function orphanAgent(id) {
+    return id === undefined ? getAgent('claude') : getAgent(id);
+}
+// Back-compat re-exports: these were originally defined here and are imported by tests and callers by this
+// path. They're all agent-agnostic (or Claude's, kept as the default) and now live in scanUtils / claude.
+export { parsePaneMembership, findOrphans, encodeProjectDir, isSessionUuid, lastUserSnippet, etimeToMs, takeoverSessionName, resolveEncodedDirSession as resolveSession, } from './agents/scanUtils.js';
+export { projectsDir as defaultProjectsDir } from './agents/claude.js';
+// Parse `ps …` to LIVE Claude CLI procs only — the original Claude-specific helper, kept for the tests.
+// The general engine uses parseAgentProcs(psOut, AGENTS) directly.
+export function parseClaudeProcs(psOut) {
+    const agent = getAgent('claude');
+    return agent ? parseAgentProcs(psOut, [agent]) : [];
+}
+// Take over an orphan: spawn the agent's `resume <sessionId>` in a fresh tmux session (target.mode 'new')
+// or a new window of an existing session ('window'), so handmux can steer the continued conversation.
+// Everything is re-verified server-side — the client's pid/sessionId are inputs to a fresh scan, never
+// trusted directly. The original process is SIGTERM'd only AFTER the resumed agent is confirmed up
+// (foreground command is no longer the shell) AND re-confirmed still the same orphan (guards pid reuse):
+// `<agent> resume` appends to the SAME session file with no OS lock (verified for Claude), so two live
+// writers corrupt history — killing guarantees a single writer. Injectable deps make it unit-testable.
+export async function takeoverOrphan({ commands, scanFn = scanOrphans, scanOpts = {}, killProc = (pid, sig) => process.kill(pid, sig), delay = (ms) => new Promise((r) => setTimeout(r, ms)), pollTries = 16, pollMs = 400, }, { pid, sessionId, target = { mode: 'new' }, kill = true, name: wantName } = {}) {
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+        return { error: 'bad pid', status: 400 };
+    // Both agents use UUID session ids; validate up front (takeover types the id into a shell via send-keys).
+    if (!isSessionUuid(sessionId))
+        return { error: 'bad session id', status: 400 };
+    const o = (await scanFn(scanOpts)).find((x) => x.pid === pid);
+    if (!o)
+        return { error: 'gone', status: 409 }; // no longer a live orphan
+    if (o.sessionId !== sessionId)
+        return { error: 'session changed', status: 409 };
+    if (!o.cwd)
+        return { error: 'no cwd', status: 409 };
+    const agent = orphanAgent(o.agent);
+    if (!agent)
+        return { error: 'unknown agent', status: 409 };
+    const cmd = agent.sessions.managedResumeCmd
+        ? agent.sessions.managedResumeCmd(sessionId)
+        : agent.sessions.resumeArgs(sessionId).join(' ');
+    let sid;
+    let wid;
+    let name = null; // the target session NAME — returned so the client can bind it into its session list
+    const targetRecord = record(target) || { mode: 'new' };
+    if (targetRecord.mode === 'window') {
+        if (!isSessionId(targetRecord.session))
+            return { error: 'bad target session', status: 400 };
+        sid = targetRecord.session;
+        name = (await commands.listSessions()).find((s) => s.id === sid)?.name || null;
+        wid = await commands.newWindow(sid, o.cwd, agent.procName, cmd);
+    }
+    else {
+        const existing = new Set((await commands.listSessions()).map((s) => s.name));
+        // Honour a user-typed name (sanitized to tmux rules, deduped with a numeric suffix); fall back to the
+        // generated `<prefix>-<dir>-<n>` when the client sent nothing.
+        const wanted = sanitizeSessionName(wantName);
+        if (wanted) {
+            name = freeSessionName(wanted, existing);
+        }
+        else {
+            for (let i = 1; i < 1000 && !name; i++) {
+                const cand = takeoverSessionName(o.cwdLabel, i, agent.takeoverPrefix);
+                if (!existing.has(cand))
+                    name = cand;
+            }
+        }
+        if (!name)
+            return { error: 'no free session name', status: 409 };
+        sid = await commands.newSession(name, o.cwd, cmd);
+        wid = (await commands.listWindows(sid))[0]?.id;
+    }
+    if (!wid)
+        return {
+            error: 'created window unavailable', status: 500, session: sid, name,
+        };
+    let up = false;
+    let pane = null;
+    for (let i = 0; i < pollTries && !up; i++) {
+        await delay(pollMs);
+        try {
+            const p = (await commands.listPanes(wid))[0];
+            if (p) {
+                pane = p.id;
+                if (!isShell(p.command))
+                    up = true;
+            }
+        }
+        catch { /* window/pane not ready yet */ }
+    }
+    let killed = false;
+    if (kill && up) {
+        const still = (await scanFn(scanOpts)).find((x) => x.pid === pid && x.sessionId === sessionId);
+        if (still) {
+            try {
+                killProc(pid, 'SIGTERM');
+                killed = true;
+            }
+            catch { /* already exited */ }
+        }
+    }
+    // claudeUp kept in the response for back-compat with the existing web client; agentUp is the neutral name.
+    return { session: sid, name, window: wid, pane, agentUp: up, claudeUp: up, killed, agent: agent.id };
+}
+// Scan the host for orphan agent sessions across every registered driver. Best-effort: any failing
+// sub-command degrades to fewer/no results rather than throwing. `projectsDir`/`sessionsDir` override a
+// specific agent's session dir (each driver declares which option key it reads — used by tests and the
+// server, which pin the dir off the resolved $HOME).
+export async function scanOrphans({ run = defaultRun, home = os.homedir(), busyMs = 8000, now = Date.now, agents = AGENTS, ...dirOverrides } = {}) {
+    const [psOut, tmuxOut] = await Promise.all([
+        run('ps', ['-Ao', 'pid=,ppid=,stat=,etime=,tty=,args=']),
+        run('tmux', ['list-panes', '-a', '-F', tmuxFormat(['pane_tty', 'pane_pid'])]),
+    ]);
+    const orphans = findOrphans(parseAgentProcs(psOut, agents), parsePaneMembership(tmuxOut));
+    const results = [];
+    for (const o of orphans) {
+        const agent = orphanAgent(o.agent);
+        if (!agent)
+            continue;
+        const cwd = await lsofCwd(run, o.pid);
+        const override = dirOverrides[agent.sessions.dirOptKey];
+        const dir = typeof override === 'string' && override ? override : agent.sessions.dir(home);
+        const meta = cwd ? await agent.sessions.resolve(dir, cwd, { busyMs, now }) : {};
+        const cwdLabel = cwd ? path.basename(cwd) : '';
+        results.push({
+            pid: o.pid,
+            agent: agent.id,
+            agentLabel: agent.label,
+            cwd: cwd || '',
+            cwdLabel,
+            // Default name the takeover sheet prefills (the same `<prefix>-<dir>-1` the server would auto-pick).
+            suggestedName: takeoverSessionName(cwdLabel, 1, agent.takeoverPrefix),
+            sessionId: meta.sessionId || null,
+            state: meta.state || 'unknown',
+            snippet: meta.snippet || '',
+            lastActivity: meta.lastActivity || 0,
+            startedAt: o.etimeMs ? Math.round(now() - o.etimeMs) : 0,
+        });
+    }
+    return results;
+}

package/dist/src/paneInput.js

@@ -0,0 +1,42 @@
+const SUBMIT_GAP_MS = 120;
+const paneInputTails = new Map();
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Every product surface that writes to a tmux pane shares this one per-pane critical section. Keeping
+// text + submit in the same operation prevents two clients from interleaving `paste-buffer` and Enter.
+export async function serializePaneInput(paneId, operation) {
+    const previous = paneInputTails.get(paneId) ?? Promise.resolve();
+    const current = previous.catch(() => { }).then(operation);
+    const tail = current.then(() => { }, () => { });
+    paneInputTails.set(paneId, tail);
+    try {
+        return await current;
+    }
+    finally {
+        if (paneInputTails.get(paneId) === tail)
+            paneInputTails.delete(paneId);
+    }
+}
+export function sendPanePrompt(commands, paneId, text, guard) {
+    return serializePaneInput(paneId, async () => {
+        if (guard && !await guard.validate())
+            return { nativeMutation: false };
+        await commands.exitCopyModeIfActive(paneId);
+        await commands.sendText(paneId, text);
+        if (text)
+            await delay(SUBMIT_GAP_MS);
+        await commands.sendEnter(paneId);
+        return { nativeMutation: true };
+    });
+}
+export function interruptPane(commands, paneId) {
+    return serializePaneInput(paneId, async () => {
+        await commands.exitCopyModeIfActive(paneId);
+        await commands.sendKey(paneId, 'C-c');
+    });
+}
+export function sendPaneChoice(commands, paneId, choice) {
+    return serializePaneInput(paneId, async () => {
+        await commands.exitCopyModeIfActive(paneId);
+        await commands.sendText(paneId, choice);
+    });
+}

package/dist/src/pendingPrompt.js

@@ -0,0 +1,194 @@
+// Parse a pending interactive PROMPT (an AskUserQuestion menu — single OR multi-question — or a tool-
+// permission menu) out of a Claude Code pane's `capture-pane` text. This is deliberately screen-scraping: a
+// pending prompt's options exist ONLY in the rendered TUI — they are NOT written to the session .jsonl until
+// AFTER the user answers (verified live), so the transcript can't be the source. Same approach amux/
+// VibeTunnel/Conductor use for the "attach to a running TUI" model; there is no structured channel short of
+// relaunching Claude via the SDK.
+//
+// Verified against a live Claude Code (2026-07-17):
+//
+//  SINGLE question / permission menu:            MULTI-question (tabbed):        REVIEW / submit screen:
+//    ☐ 颜色         ← header (optional)             ←  ☒ 水果  ☐ 颜色  ✔ Submit  →   ←  ☒ 水果  ☒ 颜色 ✔ Submit →
+//   你喜欢哪个?      ← question                      选个颜色?      ← current tab     Review your answers
+//   ❯ 1. 红色       ← ❯ marks the cursor            ❯ 1. 红                          ❯ 1. Submit answers
+//        热情、醒目   ← description (optional)          2. 蓝                            2. Cancel
+//     2. 蓝色                                       Enter to select · Tab/… · Esc    (NO footer line)
+//     4. Type something.  ← built-in meta (dropped)
+//   Enter to select · ↑/↓ to navigate · Esc to cancel
+//
+// Driving (verified live): sending the literal DIGIT of an option selects it. For a SINGLE question it
+// selects AND submits immediately; for MULTI it selects AND auto-advances to the next tab; on the review
+// screen digit 1 = "Submit answers". So the caller drives the whole flow by sending `String(option.n)` and
+// re-polling — each screen (Q1 → Q2 → review) is itself a parseable menu. Escape cancels.
+//
+// The parser ANCHORS on the ❯ cursor line, NOT a footer: the review screen has options but no footer.
+// Cursor-selected option line: ❯ (or ›»>) then "N.".
+const CURSOR_RE = /^\s*[❯›»>]\s*\d+\.\s/;
+// Any option row: optional cursor, then "N. label".
+const OPTION_RE = /^\s*[❯›»>]?\s*(\d+)\.\s+(.+?)\s*$/;
+// A description row: indented, not itself an option.
+const isDesc = (line) => /^\s{3,}\S/.test(line) && !OPTION_RE.test(line);
+// A horizontal rule Claude draws inside/around the card (kept within an option block so meta rows past it
+// are still seen and dropped).
+const RULE_RE = /^[\s─━—–\-_=·⎯]{8,}$/;
+// The multi-question tab strip: "←  ☒ 水果  ☐ 颜色  ✔ Submit  →".
+const TAB_BAR_RE = /✔\s*Submit|[☐☒].*[☐☒]/;
+// Claude's built-in trailing meta-options — not real answers.
+const META_LABELS = new Set(['type something', 'type something.', 'chat about this', 'chat about this.']);
+// Leading decoration on the header line.
+const HEADER_DECOR_RE = /^[\s☐☑☒◯●○·•\-*]+/;
+// A menu footer (single-question / permission), used only as a title boundary — NOT required to detect a menu.
+const FOOTER_RE = /enter to select|esc to (cancel|reject)/i;
+// A Claude activity/spinner line — the top edge of the card, above which is prior transcript.
+const ACTIVITY_RE = /^\s*[✻✳✶✽⏺]\s|worked for|cogitated|crafting|cooked for|crunched for|esc to interrupt/i;
+// The input cursor ❯ leading the user's echoed prompt (above the card).
+const PROMPT_ECHO_RE = /^\s*[❯›»>]\s*\D/; // ❯ NOT followed by a digit (that would be an option)
+const isTitleBoundary = (line) => ACTIVITY_RE.test(line) || RULE_RE.test(line) || TAB_BAR_RE.test(line) || FOOTER_RE.test(line) || PROMPT_ECHO_RE.test(line);
+const stripRight = (value) => String(value == null ? '' : value).replace(/\s+$/, '');
+// Strip ANSI/OSC escapes so a capture taken WITH `-e` (SGR) still parses — belt-and-suspenders even though
+// the endpoint captures plain.
+const stripAnsi = (value) => String(value || '').replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '').replace(/\x1b[[0-9;?]*[ -/]*[@-~]/g, '');
+// The assistant text immediately PRECEDING the menu, scraped because the turn (text + AskUserQuestion) is NOT
+// flushed to the session jsonl until AFTER the user answers (verified live: probe + out-of-order line
+// timestamps) — so the 对话 lens's transcript view structurally can't show it while the gate is up. The title
+// walk below stops at the first boundary (activity spinner / box rule / prompt echo), which is exactly where
+// the lead-in text usually sits. Walk on upward: skip boundary chrome, take the nearest content block, keep
+// its LAST lines (the freshest context, "问题的最后一行"). `fromIdx` = the first line NOT consumed by the
+// title walk, so adjacent lead-in the title already absorbed is never duplicated here.
+const LEADIN_MAX = 2;
+const MSG_MARK_RE = /^\s*⏺/; // ⏺ opens an assistant message in the scrollback — include it, stop there
+function extractLeadIn(lines, fromIdx) {
+    const block = [];
+    let i = fromIdx;
+    // Skip the chrome between the menu and the preceding text (spinner / rules / tab bar / stale footer /
+    // blanks) — but never past a ❯ prompt echo (above it is the PREVIOUS exchange, stale context) nor past a
+    // ⏺ message head (it IS the text's first line — the collect loop includes it).
+    while (i >= 0) {
+        const line = lines[i] ?? '';
+        if (line.trim() && (!isTitleBoundary(line) || PROMPT_ECHO_RE.test(line) || MSG_MARK_RE.test(line)))
+            break;
+        i--;
+    }
+    for (; i >= 0 && block.length < 12; i--) {
+        const line = lines[i] ?? '';
+        if (!line.trim())
+            break; // blank = the block's top (last paragraph)
+        if (MSG_MARK_RE.test(line)) {
+            block.unshift(line.trim());
+            break;
+        } // the ⏺ message head: include & stop
+        if (isTitleBoundary(line))
+            break; // hard chrome (incl. ❯ echo): stop
+        block.unshift(line.trim());
+    }
+    const tail = block.slice(-LEADIN_MAX).map((line) => line.replace(/^⏺\s*/, '').trim()).filter(Boolean);
+    return tail.length ? tail.join(' ') : null;
+}
+function parseTabs(line) {
+    const tabs = [];
+    const re = /([☐☒])\s*(\S+)/g;
+    let match;
+    while ((match = re.exec(line))) {
+        const mark = match[1];
+        const label = match[2];
+        if (mark && label)
+            tabs.push({ label, answered: mark === '☒' });
+    }
+    return tabs;
+}
+// capture-pane text → a normalized pending prompt, or null when no interactive menu is on screen.
+//   { kind:'question'|'permission', title, options:[{n,label,description}], cursor,
+//     multi, step, total, submit }
+// `n` is the digit to send to pick that option. For multi, `step`/`total` drive the "第 i/N 题" progress and
+// `submit` marks the final review screen (options are Submit answers / Cancel).
+export function parsePendingPrompt(text) {
+    const lines = stripAnsi(text).split('\n').map(stripRight);
+    // Anchor on the cursor-selected option (present in every menu: question, permission, review). Take the
+    // LAST one so stale menus higher in the scrollback are ignored — the live menu is at the bottom.
+    let anchor = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (CURSOR_RE.test(lines[i] ?? '')) {
+            anchor = i;
+            break;
+        }
+    }
+    if (anchor < 0)
+        return null;
+    // The option block = the contiguous run of option / description / rule lines around the anchor.
+    const inBlock = (line) => OPTION_RE.test(line) || isDesc(line) || RULE_RE.test(line);
+    let top = anchor;
+    let bot = anchor;
+    while (top - 1 >= 0 && inBlock(lines[top - 1] ?? ''))
+        top--;
+    while (bot + 1 < lines.length && inBlock(lines[bot + 1] ?? ''))
+        bot++;
+    const options = [];
+    let cursor = null;
+    for (let i = top; i <= bot; i++) {
+        const line = lines[i] ?? '';
+        const match = line.match(OPTION_RE);
+        const numberText = match?.[1];
+        const labelText = match?.[2];
+        if (!numberText || !labelText)
+            continue;
+        const n = Number(numberText);
+        const label = labelText.trim();
+        if (CURSOR_RE.test(line))
+            cursor = n;
+        let description = '';
+        for (let j = i + 1; j <= bot; j++) {
+            const candidate = lines[j] ?? '';
+            if (OPTION_RE.test(candidate))
+                break;
+            if (!isDesc(candidate))
+                break;
+            description += (description ? ' ' : '') + candidate.trim();
+        }
+        if (META_LABELS.has(label.toLowerCase()))
+            continue; // drop Claude's built-in meta-options
+        options.push({ n, label, description });
+    }
+    if (!options.length)
+        return null;
+    // Title = header/question text above the block, skipping in-card blanks, stopping at the card's top edge.
+    const head = [];
+    let headStop = top - 1;
+    for (let i = top - 1; i >= 0 && head.length < 5; i--) {
+        const line = lines[i] ?? '';
+        if (!line.trim()) {
+            headStop = i - 1;
+            continue;
+        }
+        if (isTitleBoundary(line)) {
+            headStop = i;
+            break;
+        }
+        head.unshift(line);
+        headStop = i - 1;
+    }
+    const title = head.map((line) => line.replace(HEADER_DECOR_RE, '').trim()).filter(Boolean).join(' — ') || '需要你选择';
+    // Multi-question: the tab strip drives progress. `answered` ☒ tabs → current step is the next unanswered.
+    const tabLine = lines.find((line) => TAB_BAR_RE.test(line));
+    const tabs = tabLine ? parseTabs(tabLine) : [];
+    const multi = tabs.length > 1;
+    const answered = tabs.filter((t) => t.answered).length;
+    const firstOption = options[0];
+    if (!firstOption)
+        return null;
+    const submit = /^submit answers?$/i.test(firstOption.label) || (multi && answered >= tabs.length);
+    const kind = /do you want to proceed/i.test(title) || /^yes\b/i.test(firstOption.label)
+        ? 'permission' : 'question';
+    const out = { kind, title, options, cursor };
+    // Lead-in context the title walk didn't absorb (it stopped at a boundary or its 5-line cap) — the
+    // assistant's last line(s) before the question, shown above the gate so the phone isn't asked blind.
+    const leadIn = extractLeadIn(lines, headStop);
+    if (leadIn)
+        out.leadIn = leadIn;
+    if (multi) {
+        out.multi = true;
+        out.total = tabs.length;
+        out.step = Math.min(answered + 1, tabs.length);
+        out.submit = submit;
+    }
+    return out;
+}

package/dist/src/previewServer.js

@@ -0,0 +1,202 @@
+// server/src/previewServer.js
+// Serves registered static-preview directories under a per-registration capability path. The main
+// Handmux token is never a preview credential. Absolute-rooted assets (/assets/...) are served from the
+// right preview dir via an authenticated Referer fallback (design's "方案 A").
+// Dynamic ports and arbitrary websites are handled by the built-in browser instead.
+import express from 'express';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { tokenEquals } from './auth.js';
+function credentialOk(provided, token) {
+    if (!provided)
+        return false;
+    try {
+        return tokenEquals(provided, token);
+    }
+    catch {
+        return false;
+    }
+}
+// Resolve the on-disk file for a request path under a preview: '' or '<dir>/' → its index.html.
+function fileFor(rest) { return (!rest || rest.endsWith('/')) ? `${rest}index.html` : rest; }
+function previewHeaders(res) {
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('Referrer-Policy', 'same-origin');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    // Keep preview code isolated even if its capability URL is opened outside the in-app iframe.
+    res.setHeader('Content-Security-Policy', 'sandbox allow-scripts allow-forms allow-downloads allow-modals allow-popups');
+    // A sandboxed static document intentionally has an opaque origin. Its capability path needs to remain
+    // readable by relative fetch(), module scripts, and fonts without restoring same-origin parent access.
+    res.setHeader('Access-Control-Allow-Origin', 'null');
+}
+function prefixedRoot(url, prefix) {
+    return url.startsWith('/') && !url.startsWith('//') ? `${prefix}${url.slice(1)}` : url;
+}
+function rewriteCssRoots(source, prefix) {
+    return source
+        .replace(/(url\(\s*["']?)\/(?!\/)/gi, `$1${prefix}`)
+        .replace(/(@import\s+["'])\/(?!\/)/gi, `$1${prefix}`);
+}
+function rewriteModuleRoots(source, prefix) {
+    return source.replace(/(\b(?:from|import)\s*(?:\(\s*)?)(["'])\/(?!\/)/g, `$1$2${prefix}`);
+}
+export function rewritePreviewText(source, extension, prefix) {
+    if (extension === '.css')
+        return rewriteCssRoots(source, prefix);
+    if (extension === '.js' || extension === '.mjs')
+        return rewriteModuleRoots(source, prefix);
+    if (extension !== '.html' && extension !== '.htm')
+        return source;
+    let output = source.replace(/(\b(?:src|href|action|poster|data|formaction)\s*=\s*)(["'])(\/[^"']*)\2/gi, (_match, start, quote, url) => `${start}${quote}${prefixedRoot(url, prefix)}${quote}`);
+    output = output.replace(/(\bsrcset\s*=\s*)(["'])([^"']*)\2/gi, (_match, start, quote, value) => {
+        const rewritten = value.split(',').map((candidate) => {
+            const match = /^(\s*)(\S+)(.*)$/.exec(candidate);
+            return match
+                ? `${match[1] ?? ''}${prefixedRoot(match[2] ?? '', prefix)}${match[3] ?? ''}`
+                : candidate;
+        }).join(',');
+        return `${start}${quote}${rewritten}${quote}`;
+    });
+    output = output.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (_match, open, css, close) => `${open}${rewriteCssRoots(css, prefix)}${close}`);
+    output = output.replace(/(\bstyle\s*=\s*)(["'])([^"']*)\2/gi, (_match, start, quote, css) => `${start}${quote}${rewriteCssRoots(css, prefix)}${quote}`);
+    return output.replace(/(<script\b[^>]*\btype\s*=\s*["']module["'][^>]*>)([\s\S]*?)(<\/script>)/gi, (_match, open, script, close) => `${open}${rewriteModuleRoots(script, prefix)}${close}`);
+}
+const errorStatus = (error, fallback) => {
+    if (typeof error === 'object' && error !== null && 'statusCode' in error) {
+        const statusCode = Number(error.statusCode);
+        if (Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599)
+            return statusCode;
+    }
+    return fallback;
+};
+const errorCode = (error) => {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return null;
+    return typeof error.code === 'string' ? error.code : null;
+};
+export function createPreview({ previews }) {
+    const router = express.Router();
+    function resolveEntry(name, accessToken, res) {
+        const lookup = previews.get(name);
+        if (lookup.state === 'missing') {
+            res.status(404).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览不存在</h1>');
+            return null;
+        }
+        if (lookup.state === 'expired') {
+            res.status(410).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览已过期</h1><p>请回到 app 重新启动预览。</p>');
+            return null;
+        }
+        if (!credentialOk(accessToken, lookup.entry.accessToken)) {
+            res.status(401).send('unauthorized');
+            return null;
+        }
+        return lookup.entry;
+    }
+    async function serve(entry, rest, prefix, res) {
+        previewHeaders(res);
+        const requested = fileFor(rest);
+        const segments = requested.split('/');
+        const target = path.resolve(entry.dir, requested);
+        const relative = path.relative(entry.dir, target);
+        if (!relative || relative.startsWith('..') || path.isAbsolute(relative)
+            || segments.some((segment) => segment.startsWith('.'))) {
+            if (!relative && requested === 'index.html') {
+                // The root index is the normal preview entry point.
+            }
+            else {
+                res.status(404).end();
+                return;
+            }
+        }
+        const extension = path.extname(target).toLowerCase();
+        if (['.html', '.htm', '.css', '.js', '.mjs'].includes(extension)) {
+            try {
+                const source = await fs.readFile(target, 'utf8');
+                res.type(extension).send(rewritePreviewText(source, extension, prefix));
+            }
+            catch (error) {
+                if (!res.headersSent)
+                    res.status(errorCode(error) === 'ENOENT' ? 404 : 500).end();
+            }
+            return;
+        }
+        res.sendFile(requested, { root: entry.dir, dotfiles: 'deny' }, (err) => {
+            if (err && !res.headersSent)
+                res.status(errorStatus(err, 404)).end();
+        });
+    }
+    // A name without its independent capability is never accepted, including the old ?token=<app-token>
+    // shape. Keeping this explicit makes the failure an authentication result instead of an SPA fallback.
+    router.get('/:name', (_req, res) => res.status(401).send('unauthorized'));
+    router.get('/:name/:accessToken', (req, res) => {
+        const name = req.params.name;
+        const accessToken = req.params.accessToken;
+        if (!name || !accessToken)
+            return res.status(401).send('unauthorized');
+        const entry = resolveEntry(name, accessToken, res);
+        if (!entry || res.headersSent)
+            return undefined;
+        const prefix = `/preview/${encodeURIComponent(name)}/${encodeURIComponent(accessToken)}/`;
+        if (!(req.url.split('?', 1)[0] ?? '').endsWith('/')) {
+            return res.redirect(301, prefix);
+        }
+        return void serve(entry, '', prefix, res);
+    });
+    router.get('/:name/:accessToken/*', (req, res) => {
+        const name = req.params.name;
+        const accessToken = req.params.accessToken;
+        if (!name || !accessToken)
+            return res.status(401).send('unauthorized');
+        const entry = resolveEntry(name, accessToken, res);
+        if (!entry || res.headersSent)
+            return undefined;
+        const prefix = `/preview/${encodeURIComponent(name)}/${encodeURIComponent(accessToken)}/`;
+        return void serve(entry, req.params[0] ?? '', prefix, res);
+    });
+    // Referer fallback (mount AFTER /preview, BEFORE express.static): an absolute /assets/... request
+    // whose Referer is a preview page is served from that preview's dir. Reuses credOk so it can never
+    // read a dir without a valid token/cookie. Misses fall through to the normal static/SPA layer.
+    function refererFallback(req, res, next) {
+        if (req.method !== 'GET')
+            return next();
+        if (req.path.startsWith('/api') || req.path.startsWith('/preview'))
+            return next();
+        const ref = req.headers.referer;
+        if (!ref)
+            return next();
+        let refPath;
+        try {
+            refPath = new URL(ref).pathname;
+        }
+        catch {
+            return next();
+        }
+        const m = /^\/preview\/([^/]+)\/([^/]+)\//.exec(refPath);
+        if (!m)
+            return next();
+        const encodedName = m[1];
+        const encodedToken = m[2];
+        if (!encodedName || !encodedToken)
+            return next();
+        let name;
+        let accessToken;
+        try {
+            name = decodeURIComponent(encodedName);
+            accessToken = decodeURIComponent(encodedToken);
+        }
+        catch {
+            return next();
+        }
+        const lookup = previews.get(name);
+        if (lookup.state !== 'active')
+            return next();
+        if (!credentialOk(accessToken, lookup.entry.accessToken))
+            return next();
+        previewHeaders(res);
+        res.sendFile(req.path, { root: lookup.entry.dir, dotfiles: 'deny' }, (err) => {
+            if (err && !res.headersSent)
+                next();
+        });
+    }
+    return { router, refererFallback };
+}