osborn 0.9.249 → 0.9.251

package/dist/content/period-run.js

@@ -0,0 +1,135 @@
+/**
+ * period-run.ts — run the PERIOD MAP for one session. Stages (each its own module,
+ * swappable / rerunnable alone):
+ *   1. block loader   lens-db.loadConversationRows + lens-period-block.selectBlock
+ *   2. strip/redact   lens-strip (inside loadConversationRows) + secret/client redaction
+ *   3. period map     lens-period (one OpenRouter call, quotes verified deterministically)
+ *   4. audio (opt.)   lens-audio AudioAdapter — offsets only when a recording exists
+ *   5. render         lens-period-render → review .md (redacted again)
+ * OpenRouter only. Hard cap: 1 call, $0.50. Never writes content-profile.md or the HWM.
+ *
+ * CLI: npx tsx agent/src/content/period-run.ts --session <id> --out <file.md>
+ *        [--since 24h|ISO] [--until ISO] [--from-row N] [--dry]
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadConversationRows, resolveSessionDb } from './lens-db.js';
+import { Budget, chat, getModelInfo, windowTokensFor } from './lens-model.js';
+import { loadClientRedactor } from './lens-redact.js';
+import { redactSecrets } from './transcript-sanitizer.js';
+import { readCompactionBoundaries } from './lens-period-boundaries.js';
+import { localRecordingAdapter } from './lens-audio.js';
+import { refuseOutPath } from './lens-paths.js';
+import { parseSince, selectBlock } from './lens-period-block.js';
+import { attachAudio, periodPrompt, readPeriodMap } from './lens-period.js';
+import { renderPeriodMd } from './lens-period-render.js';
+export const PERIOD_CAP_USD = 0.5;
+const MAX_OUT = 12_000;
+export async function runPeriodMap(o) {
+    const log = o.log ?? (() => { });
+    const db = resolveSessionDb(o.sessionId);
+    if (!db)
+        throw new Error(`no session.db for ${o.sessionId}`);
+    const projectDir = dirname(dirname(dirname(db)));
+    const refused = refuseOutPath(o.outPath, projectDir);
+    if (refused)
+        throw new Error(refused);
+    const key = process.env.OPENROUTER_API_KEY;
+    if (!key && !o.dry)
+        throw new Error('OPENROUTER_API_KEY not set');
+    const info = await getModelInfo(key ?? '');
+    if (!info)
+        throw new Error('model info unavailable (cannot enforce the cost cap)');
+    const capTokens = windowTokensFor(info);
+    const red = loadClientRedactor(projectDir);
+    // 1+2. block loader (strip + sanitize + secret/client redaction happen inside the load)
+    const all = loadConversationRows(db, 0, red.redact);
+    const sinceMs = o.since ? parseSince(o.since) : undefined;
+    const untilMs = o.until ? parseSince(o.until) : undefined;
+    if (sinceMs !== undefined && !Number.isFinite(sinceMs))
+        throw new Error(`bad --since ${o.since}`);
+    if (untilMs !== undefined && !Number.isFinite(untilMs))
+        throw new Error(`bad --until ${o.until}`);
+    const block = selectBlock(all.records, { boundaries: readCompactionBoundaries(db), fromRowId: o.fromRowId, toRowId: o.toRowId, sinceMs, untilMs, maxTokens: capTokens });
+    // Strip counts for exactly the block's row range (incl. rows dropped inside it).
+    const scoped = block ? loadConversationRows(db, block.firstRowId - 1, red.redact, block.lastRowId) : null;
+    const { records: _r, text: _t, ...blockMeta } = block ?? {};
+    const r = {
+        sessionId: o.sessionId, model: info.id, contextLength: info.contextLength, capTokens,
+        block: block ? blockMeta : null, stripped: scoped?.stats.stripped ?? {}, rowsRead: scoped?.stats.rowsRead ?? 0,
+        rowsKeptInSession: scoped?.records.length ?? 0, map: null, calls: 0, promptTokens: 0, completionTokens: 0, costUsd: 0,
+        capUsd: PERIOD_CAP_USD, finish: '', provider: '', audio: 'none (transcript only — row ranges, no clip offsets)', errors: [],
+    };
+    const finish = () => {
+        const md = redactSecrets(red.redact(renderPeriodMd(r)), { assistant: true });
+        mkdirSync(dirname(o.outPath), { recursive: true });
+        writeFileSync(o.outPath, md, 'utf-8');
+        log(`wrote ${o.outPath}`);
+        return r;
+    };
+    if (!block)
+        return (r.errors.push('empty block'), finish());
+    log(`block ${block.basis}: rows #${block.firstRowId}–#${block.lastRowId} (${block.records.length}), ~${block.estTokens} tok${block.leftOut ? `, left out ${block.leftOut.rows} rows` : ''}`);
+    if (o.dry)
+        return finish();
+    // 3. period map — ONE call, reasoning off (lens-model.chat), instructions after the transcript
+    const budget = new Budget(info, { maxCalls: 1, maxCostUsd: PERIOD_CAP_USD });
+    const prompt = periodPrompt(block.text, { from: block.from, to: block.to, rows: block.records.length });
+    try {
+        const res = await chat(budget, prompt, key, MAX_OUT);
+        if (!res)
+            r.errors.push('refused by the cost cap');
+        else {
+            Object.assign(r, { promptTokens: res.promptTokens, completionTokens: res.completionTokens, finish: res.finish, provider: res.provider });
+            log(`map: ${res.promptTokens}+${res.completionTokens} tok, $${res.costUsd.toFixed(4)}, finish=${res.finish}`);
+            if (res.finish === 'length')
+                r.errors.push('output cap hit (JSON may be truncated)');
+            r.map = readPeriodMap(res.content, block.records);
+            if (!r.map) {
+                // Keep the (redacted) raw reply next to the review file for debugging.
+                const rawPath = o.outPath.replace(/\.md$/, '') + '.raw.txt';
+                writeFileSync(rawPath, redactSecrets(red.redact(res.content), { assistant: true }), 'utf-8');
+                r.errors.push(`no parseable period map (raw reply: ${rawPath})`);
+            }
+        }
+    }
+    catch (e) {
+        r.errors.push(`model call failed: ${e?.message ?? e}`);
+    }
+    r.calls = budget.calls;
+    r.costUsd = +budget.spentUsd.toFixed(4);
+    // 4. optional audio adapter
+    const align = (o.audio ?? localRecordingAdapter).align(o.sessionId, projectDir, block.from);
+    if (align)
+        r.audio = `${align.path} (${align.approximate ? 'approximate' : 'exact'} start: ${align.basis})`;
+    if (r.map)
+        attachAudio(r.map, align);
+    return finish();
+}
+function arg(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > -1 ? process.argv[i + 1] : undefined;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    const sessionId = arg('session') ?? '';
+    const outPath = arg('out') ?? '';
+    const fromRow = arg('from-row');
+    runPeriodMap({
+        sessionId, outPath, since: arg('since'), until: arg('until'),
+        fromRowId: fromRow ? Number(fromRow) : undefined, dry: process.argv.includes('--dry'),
+        log: m => console.log(m),
+    })
+        .then(r => {
+        const m = r.map;
+        console.log(JSON.stringify({
+            block: r.block && { rows: r.block.periodRows - (r.block.leftOut?.rows ?? 0), estTokens: r.block.estTokens, leftOut: r.block.leftOut },
+            stripped: r.stripped, cost: r.costUsd, calls: r.calls, errors: r.errors,
+            map: m && { highLeverage: m.highLeverage.length, arc: m.arc.length, stories: m.stories.length, angles: m.angles.length, quotesKept: m.quotesKept, quoteDrops: m.drops.length, itemsDropped: m.itemsDropped.length },
+        }, null, 2));
+    })
+        .catch(e => {
+        console.error(`period map failed: ${e?.message ?? e}`);
+        process.exitCode = 1;
+    });
+}

package/dist/content/render-ws-data.d.ts

@@ -0,0 +1,8 @@
+export declare const SCRIPT: string[];
+export declare const CAPTIONS: string[];
+/** name -> svg. */
+export declare const SCREENS: Record<string, () => string>;
+/** Per narration line: the screens shown during it (split evenly across the line's duration). */
+export declare const LINE_SCREENS: string[][];
+/** Artifact provenance per screen (for the report / shotlist). */
+export declare const PROVENANCE: Record<string, string>;

package/dist/content/render-ws-data.js

@@ -0,0 +1,108 @@
+/**
+ * render-ws-data.ts — script, captions and screen definitions for render-ws-story.ts.
+ * Narration is TOPIC-ONLY (no first person), per user decision.
+ * Code lines: verbatim from agent/src/index.ts (before = git a4388ca^ i.e. 0.9.152; after = current tree).
+ * Log lines: verbatim from session recall rows (agent-ad1edf68 L98, agent-a346e43a L36), hostname -> <app>.
+ */
+import { codeScreen, termScreen, pathDiagram, compareDiagram, headerDiagram, editorScreen, lsScreen, endCard } from './render-ws-screens.js';
+// Voice text (numbers spelled for TTS). CAPTIONS below are the on-screen form of the same words.
+export const SCRIPT = [
+    'One missing header killed this terminal. The editor loaded, but the terminal and file tree died instantly. Error ten-oh-six.',
+    'Browser, Fly edge, a custom reverse proxy, then code-server.',
+    'A hand-rolled tunnel got swapped for http-proxy. Still ten-oh-six.',
+    'Yet a Cloudflare tunnel to code-server worked. So the proxy was the bug.',
+    "code-server checks the browser's Origin against its own host.",
+    "The proxy's changeOrigin rewrote Host to a local port, while Origin kept the public domain.",
+    'Mismatch: four-oh-three, which the browser shows as ten-oh-six.',
+    'code-server reads X-Forwarded-Host first. The proxy never sent it. The fix: set it to the original Host.',
+    'Four-oh-three became one-oh-one. The terminal opened, and ls ran.',
+    'The twist: tests without an Origin header passed, and fooled the debugging twice.',
+    'One missing header. Fixed in osborn zero point nine point one fifty-three.',
+];
+export const CAPTIONS = SCRIPT.map((s) => s.replace(/ten-oh-six/gi, '1006').replace(/four-oh-three/gi, '403').replace(/one-oh-one/gi, '101')
+    .replace('zero point nine point one fifty-three', '0.9.153'));
+const BEFORE = [
+    { n: 320, text: 'const wsProxy = httpProxy.createProxyServer({ target: IDE_TARGET, ws: true, changeOrigin: true })' },
+    { n: '', text: '' },
+    { n: 1610, text: "server.on('upgrade', (req: IncomingMessage, socket, head: Buffer) => {" },
+    { n: '…', text: '  // (path + agent-route checks)', hl: 'dim' },
+    { n: 1613, text: '  if (ideProxyEnabled && hasValidIdeCookie(req) && !isAgentRoute) {' },
+    { n: 1614, text: '    ideLastProxiedActivity = Date.now()' },
+    { n: 1615, text: '    wsProxy.ws(req, socket, head, { target: IDE_TARGET })' },
+    { n: 1616, text: '    return' },
+    { n: 1617, text: '  }' },
+    { n: 1618, text: '  socket.destroy()' },
+    { n: 1619, text: '})' },
+];
+const AFTER = (hl) => [
+    { n: 364, text: 'const wsProxy = httpProxy.createProxyServer({ target: IDE_TARGET, ws: true, changeOrigin: true })', hl: hl ? 'warn' : undefined },
+    { n: '', text: '' },
+    { n: 1813, text: '  if (ideProxyEnabled && hasValidIdeCookie(req) && !isAgentRoute) {' },
+    { n: 1814, text: '    ideLastProxiedActivity = Date.now()' },
+    { n: 1815, text: "    // code-server's authenticateOrigin() compares Origin against the effective host" },
+    { n: 1816, text: '    // (X-Forwarded-Host first). changeOrigin:true rewrites Host→127.0.0.1:8300 while the' },
+    { n: 1817, text: "    // browser's Origin stays the public hostname, causing a 403 → WS 1006. Preserve the" },
+    { n: 1818, text: '    // real public host so the origin check matches.' },
+    { n: 1819, text: "    if (!req.headers['x-forwarded-host'] && req.headers.host) {", hl: hl ? 'add' : undefined },
+    { n: 1820, text: "      req.headers['x-forwarded-host'] = req.headers.host", hl: hl ? 'add' : undefined },
+    { n: 1821, text: '    }', hl: hl ? 'add' : undefined },
+    { n: 1822, text: '    wsProxy.ws(req, socket, head, { target: IDE_TARGET })' },
+    { n: 1823, text: '    return' },
+];
+const RED = '#ff7b72', GREEN = '#3fb950', AMBER = '#d29922';
+const T_HEAD = { text: '=== WS host/origin matching tests ===', color: '#8b949e' };
+const T_A = [
+    { text: 'Test A: host=127.0.0.1:8300 (what our proxy sends), origin=fly.dev (what browser sends)' },
+    { text: "  Host='127.0.0.1:8300', X-Forwarded-Host=None: HTTP/1.1 403 Forbidden", color: RED, hl: 'bad' },
+];
+const T_B = [
+    { text: '' },
+    { text: 'Test B: host=127.0.0.1:8300, X-Forwarded-Host=<app>.fly.dev (proposed fix)' },
+    { text: "  Host='127.0.0.1:8300', X-Forwarded-Host='<app>.fly.dev': HTTP/1.1 101 Switching Protocols", color: GREEN, hl: 'add' },
+];
+const T_EDGE = [{ text: '' }, { n: '#', text: 'after deploy, live over the public Fly edge:' }, { text: 'FLY-EDGE HTTP status: 101', color: GREEN, hl: 'add' }];
+const T_D = [
+    { text: '' },
+    { text: 'Test D: no origin (should pass per code-server)' },
+    { text: "  Host='127.0.0.1:8300', X-Forwarded-Host=None: HTTP/1.1 101 Switching Protocols", color: AMBER, hl: 'warn' },
+    { text: '' }, { n: '#', text: 'no Origin header → passes → false "it works"' },
+];
+const LOGTAG = 'REAL LOG · hostname redacted';
+/** name -> svg. */
+export const SCREENS = {
+    editor: () => editorScreen(false),
+    editorErr: () => editorScreen(true),
+    path1: () => pathDiagram(1),
+    path2: () => pathDiagram(2),
+    before: () => codeScreen('agent/src/index.ts', 'before · 0.9.152 (http-proxy swap, still 1006)', BEFORE),
+    beforeHl: () => codeScreen('agent/src/index.ts', 'before · 0.9.152 (http-proxy swap, still 1006)', BEFORE.map((l) => (l.n === 1615 ? { ...l, hl: 'bad' } : l.n === 320 ? { ...l, hl: 'warn' } : l))),
+    compare: () => compareDiagram(),
+    hdr1: () => headerDiagram(1),
+    hdr2: () => headerDiagram(2),
+    hdr3: () => headerDiagram(3),
+    after: () => codeScreen('agent/src/index.ts', 'after · shipped in 0.9.153', AFTER(false)),
+    afterHl: () => codeScreen('agent/src/index.ts', 'after · shipped in 0.9.153', AFTER(true)),
+    termA: () => termScreen('verification run · node ws client', [T_HEAD, ...T_A], LOGTAG),
+    termB: () => termScreen('verification run · node ws client', [T_HEAD, ...T_A, ...T_B], LOGTAG),
+    termEdge: () => termScreen('verification run · node ws client', [T_HEAD, ...T_A, ...T_B, ...T_EDGE], LOGTAG),
+    ls: () => lsScreen(),
+    termD: () => termScreen('verification run · node ws client', [T_HEAD, ...T_A, ...T_D], LOGTAG),
+    end: () => endCard(),
+};
+/** Per narration line: the screens shown during it (split evenly across the line's duration). */
+export const LINE_SCREENS = [
+    ['editor', 'editorErr'], ['path1', 'path2'], ['before', 'beforeHl'], ['compare'], ['hdr1'], ['hdr2'], ['hdr3'],
+    ['after', 'afterHl', 'afterHl'], ['termA', 'termB', 'termEdge', 'ls'], ['termD'], ['end'],
+];
+/** Artifact provenance per screen (for the report / shotlist). */
+export const PROVENANCE = {
+    editor: 'REENACTMENT (abstract workbench)', editorErr: 'REENACTMENT, modal text verbatim from user screenshot (recall agent-ad1edf68 L119)',
+    path1: 'diagram of real topology (Fly edge -> agent :8741 -> code-server 127.0.0.1:8300)', path2: 'same',
+    before: 'REAL code: index.ts @ a4388ca^ (0.9.152) lines 320, 1610-1619', beforeHl: 'same, highlighted',
+    compare: 'diagram; Cloudflare-worked fact from editor-followups-and-origin-fix.md + code comment line 363',
+    hdr1: 'diagram of real headers (root cause in recall + note)', hdr2: 'same', hdr3: 'same',
+    after: 'REAL code: current index.ts lines 364, 1813-1823 (fix added in a4388ca)', afterHl: 'same, fix lines highlighted',
+    termA: 'REAL log: recall agent-ad1edf68 L98 (Test A)', termB: 'REAL log: Test A+B', termEdge: 'REAL log: + recall agent-a346e43a L36 FLY-EDGE 101',
+    ls: 'REENACTMENT: `$ ls` prompt only; outcome user-confirmed (editor-followups note), no output fabricated',
+    termD: 'REAL log: Test D (no-Origin false pass)', end: 'end card (fix line verbatim from index.ts 1820)',
+};

package/dist/content/render-ws-screens.d.ts

@@ -0,0 +1,25 @@
+export declare const W = 1080, H = 1920, OW = 1160, OH = 2062;
+type Hl = 'add' | 'bad' | 'warn' | 'dim' | undefined;
+export interface Line {
+    n?: number | string;
+    text: string;
+    hl?: Hl;
+    color?: string;
+}
+/** Editor-style code panel with optional per-line highlight. */
+export declare function codeScreen(file: string, sub: string, lines: Line[], tag?: string): string;
+/** Terminal panel. Lines with `color` are rendered as-is; `label` lines (n='#') are sans annotations outside the log. */
+export declare function termScreen(title: string, lines: Line[], tag: string, tagColor?: string): string;
+/** Request path diagram. step 1 = first two hops, 2 = all four hops. */
+export declare function pathDiagram(step: number): string;
+/** Cloudflare tunnel (worked) vs. the proxy path (1006). */
+export declare function compareDiagram(): string;
+/** Header drop. step 1 = browser headers, 2 = proxy rewrite, 3 = 403. */
+export declare function headerDiagram(step: number): string;
+/** Reenacted code-server workbench; modal text is verbatim from the user's screenshot. */
+export declare function editorScreen(modal: boolean): string;
+/** Reenacted terminal running ls (user-confirmed outcome; no output is shown because none was logged). */
+export declare function lsScreen(): string;
+export declare function endCard(): string;
+export declare const pngPath: (dir: string, name: string) => string;
+export {};

package/dist/content/render-ws-screens.js

@@ -0,0 +1,189 @@
+/**
+ * render-ws-screens.ts — builds the screen-style PNGs for render-ws-story.ts.
+ * Every code line / log line here is copied from a real artifact:
+ *   - code: agent/src/index.ts at a4388ca^ (0.9.152, before) and the current tree (after)
+ *   - logs: session recall rows (WS host/origin matching tests, FLY-EDGE status), hostname redacted
+ * Anything not backed by a real artifact carries a visible REENACTMENT corner tag.
+ * Requires FONTCONFIG_FILE pointing at a fonts.conf listing JetBrains Mono + Roboto (set by caller).
+ */
+import path from 'node:path';
+export const W = 1080, H = 1920, OW = 1160, OH = 2062; // render oversize for pan/zoom headroom
+const MONO = 'JetBrains Mono', SANS = 'Roboto';
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+function wrap(text, max) {
+    if (text.length <= max)
+        return [text];
+    const indent = (text.match(/^\s*/)?.[0] || '') + '    ';
+    const out = [];
+    let rest = text;
+    while (rest.length > max) {
+        let cut = rest.lastIndexOf(' ', max);
+        if (cut <= indent.length)
+            cut = max;
+        out.push(rest.slice(0, cut));
+        rest = indent + rest.slice(cut).trimStart();
+    }
+    out.push(rest);
+    return out;
+}
+// Minimal TS syntax colouring -> <tspan>s.
+function colorize(src) {
+    if (/^\s*\/\//.test(src))
+        return `<tspan fill="#6a9955">${esc(src)}</tspan>`;
+    const re = /('[^']*'|`[^`]*`|\b(?:const|if|return|true|new)\b|\b\d[\d.]*\b)/g;
+    let out = '', last = 0, m;
+    while ((m = re.exec(src))) {
+        out += esc(src.slice(last, m.index));
+        const t = m[0];
+        const c = /^['`]/.test(t) ? '#ce9178' : /^\d/.test(t) ? '#b5cea8' : '#569cd6';
+        out += `<tspan fill="${c}">${esc(t)}</tspan>`;
+        last = m.index + t.length;
+    }
+    return out + esc(src.slice(last));
+}
+const HL_FILL = {
+    add: 'rgba(46,160,67,0.28)', bad: 'rgba(248,81,73,0.26)', warn: 'rgba(210,153,34,0.28)',
+};
+function chrome(body, opts = {}) {
+    const tag = opts.tag
+        ? `<rect x="${W - 40 - opts.tag.length * 17 - 34}" y="150" width="${opts.tag.length * 17 + 34}" height="50" rx="8" fill="${opts.tagColor || '#d29922'}"/>` +
+            `<text x="${W - 55}" y="184" text-anchor="end" font-family="${SANS}" font-weight="500" font-size="26" fill="#0d1117">${esc(opts.tag)}</text>`
+        : '';
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${OW}" height="${OH}" viewBox="0 0 ${W} ${H}">` +
+        `<defs><linearGradient id="g" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#0d1117"/><stop offset="1" stop-color="#05070a"/></linearGradient></defs>` +
+        `<rect width="${W}" height="${H}" fill="url(#g)"/>` +
+        `<text x="48" y="110" font-family="${SANS}" font-weight="500" font-size="34" fill="#8b949e">${esc(opts.kicker || 'code-server  ·  WebSocket 1006')}</text>` +
+        tag + body + `</svg>`;
+}
+/** Editor-style code panel with optional per-line highlight. */
+export function codeScreen(file, sub, lines, tag) {
+    const FS = 28, LH = 46, MAX = 50, x0 = 40, top = 240;
+    const rows = [];
+    for (const l of lines)
+        wrap(l.text, MAX).forEach((t, i) => rows.push({ n: i ? '' : String(l.n ?? ''), t, hl: l.hl }));
+    const h = 120 + rows.length * LH + 40;
+    let body = `<rect x="${x0}" y="${top}" width="${W - 2 * x0}" height="${h}" rx="18" fill="#1e1e1e" stroke="#30363d" stroke-width="2"/>` +
+        [0, 1, 2].map((i) => `<circle cx="${x0 + 36 + i * 32}" cy="${top + 38}" r="10" fill="${['#f85149', '#d29922', '#3fb950'][i]}"/>`).join('') +
+        `<text x="${x0 + 140}" y="${top + 47}" font-family="${MONO}" font-size="26" fill="#c9d1d9">${esc(file)}</text>` +
+        `<text x="${x0 + 30}" y="${top + 98}" font-family="${SANS}" font-weight="500" font-size="28" fill="#8b949e">${esc(sub)}</text>`;
+    rows.forEach((r, i) => {
+        const y = top + 150 + i * LH;
+        if (r.hl && HL_FILL[r.hl])
+            body += `<rect x="${x0 + 2}" y="${y - 34}" width="${W - 2 * x0 - 4}" height="${LH}" fill="${HL_FILL[r.hl]}"/>`;
+        if (r.hl === 'add' && r.n)
+            body += `<text x="${x0 + 14}" y="${y}" font-family="${MONO}" font-size="${FS}" fill="#3fb950">+</text>`;
+        body += `<text x="${x0 + 92}" y="${y}" text-anchor="end" font-family="${MONO}" font-size="22" fill="#6e7681">${esc(r.n)}</text>`;
+        body += `<text x="${x0 + 108}" y="${y}" font-family="${MONO}" font-size="${FS}" fill="#d4d4d4" xml:space="preserve"${r.hl === 'dim' ? ' opacity="0.45"' : ''}>${colorize(r.t)}</text>`;
+    });
+    return chrome(body, { tag });
+}
+/** Terminal panel. Lines with `color` are rendered as-is; `label` lines (n='#') are sans annotations outside the log. */
+export function termScreen(title, lines, tag, tagColor) {
+    const FS = 28, LH = 46, MAX = 52, x0 = 40, top = 240;
+    const rows = [];
+    for (const l of lines) {
+        const label = l.n === '#';
+        (label ? [l.text] : wrap(l.text, MAX)).forEach((t) => rows.push({ t, c: l.color || '#c9d1d9', hl: l.hl, label }));
+    }
+    const h = 100 + rows.length * LH + 40;
+    let body = `<rect x="${x0}" y="${top}" width="${W - 2 * x0}" height="${h}" rx="18" fill="#010409" stroke="#30363d" stroke-width="2"/>` +
+        `<text x="${x0 + 30}" y="${top + 52}" font-family="${MONO}" font-size="24" fill="#8b949e">${esc(title)}</text>`;
+    rows.forEach((r, i) => {
+        const y = top + 120 + i * LH;
+        if (r.hl && HL_FILL[r.hl])
+            body += `<rect x="${x0 + 2}" y="${y - 34}" width="${W - 2 * x0 - 4}" height="${LH}" fill="${HL_FILL[r.hl]}"/>`;
+        body += r.label
+            ? `<text x="${x0 + 30}" y="${y}" font-family="${MONO}" font-size="26" fill="#d29922">${esc(r.t)}</text>`
+            : `<text x="${x0 + 30}" y="${y}" font-family="${MONO}" font-size="${FS}" fill="${r.c}" xml:space="preserve">${esc(r.t)}</text>`;
+    });
+    return chrome(body, { tag, tagColor });
+}
+function box(x, y, w, h, title, sub, stroke = '#30363d', fill = '#161b22') {
+    return `<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="18" fill="${fill}" stroke="${stroke}" stroke-width="3"/>` +
+        `<text x="${x + w / 2}" y="${y + h / 2 - 4}" text-anchor="middle" font-family="${SANS}" font-weight="500" font-size="40" fill="#e6edf3">${esc(title)}</text>` +
+        `<text x="${x + w / 2}" y="${y + h / 2 + 40}" text-anchor="middle" font-family="${MONO}" font-size="24" fill="#8b949e">${esc(sub)}</text>`;
+}
+function arrow(x, y1, y2, color = '#8b949e', label = '') {
+    return `<line x1="${x}" y1="${y1}" x2="${x}" y2="${y2 - 18}" stroke="${color}" stroke-width="5"/>` +
+        `<polygon points="${x - 16},${y2 - 22} ${x + 16},${y2 - 22} ${x},${y2}" fill="${color}"/>` +
+        (label ? `<text x="${x + 34}" y="${(y1 + y2) / 2 + 10}" font-family="${MONO}" font-size="24" fill="${color}">${esc(label)}</text>` : '');
+}
+const hdr = (x, y, s, c = '#c9d1d9', strike = false) => `<text x="${x}" y="${y}" font-family="${MONO}" font-size="27" fill="${c}"${strike ? ' text-decoration="line-through"' : ''}>${esc(s)}</text>`;
+/** Request path diagram. step 1 = first two hops, 2 = all four hops. */
+export function pathDiagram(step) {
+    const X = 190, BW = 700, BH = 170, ys = [250, 530, 810, 1090];
+    const nodes = [['Browser', 'Origin: https://<app>.fly.dev'], ['Fly edge', 'public TLS'], ['Agent reverse proxy', 'node http-proxy · :8741'], ['code-server', '127.0.0.1:8300']];
+    let b = '';
+    nodes.forEach(([t, s], i) => {
+        if (step === 1 && i > 1)
+            return;
+        b += box(X, ys[i], BW, BH, t, s);
+        if (i < 3 && !(step === 1 && i >= 1))
+            b += arrow(W / 2, ys[i] + BH, ys[i + 1], '#58a6ff', i === 2 ? 'WebSocket upgrade' : '');
+    });
+    return chrome(b, { kicker: 'the request path' });
+}
+/** Cloudflare tunnel (worked) vs. the proxy path (1006). */
+export function compareDiagram() {
+    const row = (y, label, hops, ok) => {
+        const c = ok ? '#3fb950' : '#f85149';
+        let s = `<text x="60" y="${y}" font-family="${SANS}" font-weight="500" font-size="36" fill="${c}">${esc(label)}</text>`;
+        hops.forEach((h, i) => { s += box(60, y + 40 + i * 140, 960, 110, h, '', ok ? '#238636' : '#30363d'); });
+        const endY = y + 40 + hops.length * 140;
+        s += `<rect x="60" y="${endY}" width="960" height="80" rx="14" fill="${ok ? 'rgba(46,160,67,0.2)' : 'rgba(248,81,73,0.2)'}"/>` +
+            `<text x="540" y="${endY + 54}" text-anchor="middle" font-family="${MONO}" font-size="34" fill="${c}">${ok ? 'terminal works' : 'WebSocket close 1006'}</text>`;
+        return s;
+    };
+    return chrome(row(250, 'Cloudflare quick tunnel', ['Browser', 'Cloudflare', 'code-server'], true) +
+        row(830, 'Own reverse proxy', ['Browser', 'Fly edge', 'Agent proxy', 'code-server'], false), { kicker: 'same code-server, two paths' });
+}
+/** Header drop. step 1 = browser headers, 2 = proxy rewrite, 3 = 403. */
+export function headerDiagram(step) {
+    let b = box(60, 240, 960, 110, 'Browser sends', '') +
+        hdr(100, 410, 'Origin: https://<app>.fly.dev', '#58a6ff') + hdr(100, 455, 'Host:   <app>.fly.dev');
+    if (step >= 2) {
+        b += arrow(W / 2, 480, 580, '#d29922', 'changeOrigin: true') + box(60, 580, 960, 110, 'Proxy forwards', '', '#d29922') +
+            hdr(100, 750, 'Origin: https://<app>.fly.dev', '#58a6ff') + hdr(100, 795, 'Host:   127.0.0.1:8300', '#d29922') +
+            hdr(100, 840, 'X-Forwarded-Host: (never sent)', '#f85149', true);
+    }
+    if (step >= 3) {
+        b += arrow(W / 2, 870, 970, '#f85149') + box(60, 970, 960, 140, 'code-server', 'authenticateOrigin()', '#f85149') +
+            `<text x="540" y="1200" text-anchor="middle" font-family="${MONO}" font-size="30" fill="#e6edf3">&lt;app&gt;.fly.dev  ≠  127.0.0.1:8300</text>` +
+            `<rect x="290" y="1240" width="500" height="110" rx="16" fill="#f85149"/>` +
+            `<text x="540" y="1313" text-anchor="middle" font-family="${MONO}" font-weight="700" font-size="54" fill="#0d1117">403 → 1006</text>`;
+    }
+    return chrome(b, { kicker: 'why the socket dies' });
+}
+/** Reenacted code-server workbench; modal text is verbatim from the user's screenshot. */
+export function editorScreen(modal) {
+    let b = `<rect x="40" y="240" width="1000" height="1150" rx="14" fill="#1e1e1e" stroke="#30363d" stroke-width="2"/>` +
+        `<rect x="40" y="240" width="70" height="1150" fill="#2c2c2c"/><rect x="110" y="240" width="260" height="1150" fill="#252526"/>` +
+        `<text x="130" y="290" font-family="${SANS}" font-size="22" fill="#8b949e">EXPLORER</text>` +
+        `<rect x="370" y="1000" width="670" height="390" fill="#181818"/><text x="390" y="1040" font-family="${SANS}" font-size="22" fill="#8b949e">TERMINAL</text>`;
+    for (let i = 0; i < 9; i++)
+        b += `<rect x="130" y="${320 + i * 46}" width="${120 + ((i * 53) % 110)}" height="18" rx="9" fill="#3a3a3a"/>`;
+    for (let i = 0; i < 12; i++)
+        b += `<rect x="400" y="${300 + i * 50}" width="${160 + ((i * 97) % 420)}" height="18" rx="9" fill="#333"/>`;
+    if (modal) {
+        b += `<rect x="40" y="240" width="1000" height="1150" fill="rgba(0,0,0,0.55)"/>` +
+            `<rect x="90" y="560" width="900" height="470" rx="16" fill="#252526" stroke="#f85149" stroke-width="3"/>`;
+        const t = ['An unexpected error occurred that requires a', 'reload of this page.', '', 'The workbench failed to connect to the server', '(Error: WebSocket close with status code 1006)'];
+        t.forEach((s, i) => { b += `<text x="130" y="${640 + i * 50}" font-family="${SANS}" font-size="${i > 2 ? 32 : 30}" fill="${i === 4 ? '#ff7b72' : '#e6edf3'}">${esc(s)}</text>`; });
+        b += `<rect x="770" y="930" width="180" height="64" rx="8" fill="#0e639c"/><text x="860" y="972" text-anchor="middle" font-family="${SANS}" font-size="28" fill="#fff">Reload</text>`;
+    }
+    return chrome(b, { tag: modal ? 'REENACTMENT · error text verbatim' : 'REENACTMENT', kicker: 'browser code editor (code-server)' });
+}
+/** Reenacted terminal running ls (user-confirmed outcome; no output is shown because none was logged). */
+export function lsScreen() {
+    return termScreen('code-server terminal', [{ text: '$ ls', color: '#3fb950' }, { text: '_', color: '#c9d1d9' }], 'REENACTMENT · outcome user-confirmed');
+}
+export function endCard() {
+    const b = `<text x="540" y="560" text-anchor="middle" font-family="${SANS}" font-weight="500" font-size="88" fill="#e6edf3">One missing header.</text>` +
+        `<rect x="60" y="680" width="960" height="150" rx="16" fill="#1e1e1e" stroke="#3fb950" stroke-width="3"/>` +
+        `<text x="540" y="745" text-anchor="middle" font-family="${MONO}" font-size="30" fill="#ce9178">req.headers['x-forwarded-host']</text>` +
+        `<text x="540" y="795" text-anchor="middle" font-family="${MONO}" font-size="30" fill="#d4d4d4">= req.headers.host</text>` +
+        `<text x="540" y="990" text-anchor="middle" font-family="${MONO}" font-weight="700" font-size="96"><tspan fill="#f85149">403</tspan><tspan fill="#8b949e"> → </tspan><tspan fill="#3fb950">101</tspan></text>` +
+        `<text x="540" y="1130" text-anchor="middle" font-family="${SANS}" font-weight="500" font-size="40" fill="#8b949e">fixed in osborn 0.9.153</text>`;
+    return chrome(b, { kicker: 'code-server behind a reverse proxy' });
+}
+export const pngPath = (dir, name) => path.join(dir, 'screens', `${name}.png`);

package/dist/content/render-ws-story.d.ts

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