brane 0.1.1 → 0.3.0

package/dist/session-affinity.js

@@ -0,0 +1,185 @@
+/** Session affinity: pin a narrative's LLM traffic to one backend replica by
+ *  attaching an `X-Session-Affinity: <nid>` header, so provider-side KV prefix
+ *  caches stay warm for the life of a narrative instead of thrashing on every
+ *  load-balanced hop. The narrative id is the right key: it survives revives,
+ *  and brane is the only layer that sees both the id and the spawn.
+ *
+ *  Only Claude Code needs brane's help, and only when it talks to Fireworks
+ *  (an `ANTHROPIC_BASE_URL` on a `fireworks.ai` host); every other claude spawn
+ *  launches exactly as it did before. Claude Code reads
+ *  `ANTHROPIC_CUSTOM_HEADERS` (newline-separated `Name: Value`) from its
+ *  environment, and the hard part is the layers between brane and that
+ *  environment:
+ *
+ *  - A settings file's `env` block is written *over* the inherited shell
+ *    value, and settings `env` values are not `${VAR}`-expanded (verified
+ *    against claude 2.1.278 with a SessionStart-hook probe) — so when a
+ *    settings file defines the variable, nothing in the shell can add to it,
+ *    and a shared fold file could only hold one literal nid. The punch-through
+ *    is `claude --settings <path>`, which outranks every settings file
+ *    (verified end-to-end against a header-logging listener), one file per
+ *    narrative at `~/.brane/session-affinity/<nid>.json` carrying the winning
+ *    file's blob plus the affinity line. The operator's own files are never
+ *    written.
+ *
+ *  - When no settings file defines it, the value Claude Code would use is
+ *    whatever the *session's* shell inherits — from the tmux server, which
+ *    need not share the daemon's environment. So brane must not read it from
+ *    `process.env` and pin it into a `--settings` file: that replaced headers
+ *    the session had and the daemon didn't (reproduced: an `X-Shell` header
+ *    exported where tmux started vanished from the wire). Instead the header is
+ *    appended in the tmux command's env prefix, where the session's own shell
+ *    expands whatever it inherited.
+ *
+ *  Crush is deliberately absent: it already sends `x-session-affinity` (a hash
+ *  of its own session id) and that value wins over configured `extra_headers`.
+ *  Other harnesses have no observed fireworks traffic.
+ *
+ *  Opt out with `brane config session-affinity.enabled false`. */
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { getConfig } from "./commands/config.js";
+import { getBraneDir } from "./db/schema.js";
+export const SESSION_AFFINITY_HEADER = "X-Session-Affinity";
+function noAffinity() {
+    return { args: [], env: "" };
+}
+/** Return `existing` (an `ANTHROPIC_CUSTOM_HEADERS` blob) with exactly one
+ *  session-affinity line: ours, at the end. Any prior affinity line (matched
+ *  case-insensitively on the header name, the same parse Claude Code performs)
+ *  is replaced; every other line is preserved verbatim and in order. Pure. */
+export function withSessionAffinity(existing, value) {
+    const lines = (existing ?? "").split(/\r?\n/).filter((line) => {
+        if (!line.trim())
+            return false;
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            return true; // not a header line; keep as found
+        return line.slice(0, colon).trim().toLowerCase() !== SESSION_AFFINITY_HEADER.toLowerCase();
+    });
+    lines.push(`${SESSION_AFFINITY_HEADER}: ${value}`);
+    return lines.join("\n");
+}
+/** Shell env assignment that appends the affinity line to whatever
+ *  `ANTHROPIC_CUSTOM_HEADERS` the session's shell inherited, with a newline
+ *  between them only when there was something to append to. The newline is
+ *  literal inside double quotes, which POSIX sh (tmux's `-c` shell) keeps.
+ *  Narrative ids are `[a-z]+-[0-9a-z]+`, so the value needs no escaping. */
+export function shellAffinityEnv(narrativeId) {
+    return `ANTHROPIC_CUSTOM_HEADERS="\${ANTHROPIC_CUSTOM_HEADERS:+\${ANTHROPIC_CUSTOM_HEADERS}\n}${SESSION_AFFINITY_HEADER}: ${narrativeId}"`;
+}
+/** Whether a base URL is Fireworks'. */
+export function isFireworksBaseUrl(url) {
+    if (!url)
+        return false;
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return host === "fireworks.ai" || host.endsWith(".fireworks.ai");
+    }
+    catch {
+        return false;
+    }
+}
+function readSettingsFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    try {
+        const config = JSON.parse(raw);
+        if (config && typeof config === "object" && !Array.isArray(config)) {
+            return { kind: "ok", config };
+        }
+        return { kind: "broken" };
+    }
+    catch {
+        return { kind: "broken" };
+    }
+}
+function envFrom(read, key) {
+    if (read.kind !== "ok")
+        return undefined;
+    const env = read.config.env;
+    if (!env || typeof env !== "object" || Array.isArray(env))
+        return undefined;
+    const value = env[key];
+    return typeof value === "string" ? value : undefined;
+}
+/** Claude Code's user-level settings directory honors CLAUDE_CONFIG_DIR. */
+function claudeConfigDir(homeDir) {
+    return process.env.CLAUDE_CONFIG_DIR ?? join(homeDir, ".claude");
+}
+/** Where the per-narrative `--settings` file lives. One file per nid,
+ *  rewritten on every launch that needs it. */
+export function claudeSessionAffinityPath(narrativeId, opts = {}) {
+    return join(opts.braneDir ?? getBraneDir(), "session-affinity", `${narrativeId}.json`);
+}
+/** Decide how a claude launch carries the affinity header, writing the
+ *  per-narrative `--settings` file when that is the way.
+ *
+ *  Settings files are consulted in Claude Code's precedence (local > project >
+ *  user). `ANTHROPIC_BASE_URL` falls back to the daemon's env for the gate
+ *  only: a URL the session inherits but the daemon doesn't is missed, which
+ *  costs affinity and nothing else.
+ *
+ *  - Not Fireworks → nothing.
+ *  - A settings file defines `ANTHROPIC_CUSTOM_HEADERS` → `--settings` with
+ *    that blob plus the affinity line. The file carries the operator's header
+ *    values, credentials included, so it is kept `0600` in a `0700` directory.
+ *  - Otherwise → the env prefix, expanded by the session's own shell. */
+export function ensureClaudeSessionAffinity(foldPath, narrativeId, opts = {}) {
+    const home = opts.homeDir ?? homedir();
+    const files = [
+        join(foldPath, ".claude", "settings.local.json"),
+        join(foldPath, ".claude", "settings.json"),
+        join(claudeConfigDir(home), "settings.json"),
+    ].map(readSettingsFile);
+    const firstDefined = (key) => {
+        for (const read of files) {
+            const value = envFrom(read, key);
+            if (value !== undefined)
+                return value;
+        }
+        return undefined;
+    };
+    const baseUrl = firstDefined("ANTHROPIC_BASE_URL") ?? process.env.ANTHROPIC_BASE_URL;
+    if (!isFireworksBaseUrl(baseUrl))
+        return noAffinity();
+    const fromSettings = firstDefined("ANTHROPIC_CUSTOM_HEADERS");
+    if (fromSettings === undefined)
+        return { args: [], env: shellAffinityEnv(narrativeId) };
+    const desired = withSessionAffinity(fromSettings, narrativeId);
+    const path = claudeSessionAffinityPath(narrativeId, opts);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(path), 0o700);
+    const existing = readSettingsFile(path);
+    if (existing.kind !== "ok" || envFrom(existing, "ANTHROPIC_CUSTOM_HEADERS") !== desired) {
+        writeFileSync(path, JSON.stringify({ env: { ANTHROPIC_CUSTOM_HEADERS: desired } }, null, 2) + "\n", {
+            mode: 0o600,
+        });
+    }
+    // `mode` applies only on creation; tighten a file or directory made before.
+    chmodSync(path, 0o600);
+    return { args: ["--settings", path], env: "" };
+}
+/** Spawn/revive entry point. Mirrors `ensureHookConfig`'s contract: best
+ *  effort, never fatal to a launch, idempotent across the spawns and revives
+ *  that call it. The caller puts `args` on the agent's command line and `env`
+ *  in the tmux command's env prefix. */
+export function ensureSessionAffinityConfig(agent, foldPath, narrativeId, opts = {}) {
+    const enabled = opts.enabled ?? getConfig("session-affinity.enabled", opts.db) !== "false";
+    if (!enabled || agent !== "claude")
+        return noAffinity();
+    try {
+        return ensureClaudeSessionAffinity(foldPath, narrativeId, opts);
+    }
+    catch (err) {
+        console.error(`Warning: could not write session affinity config: ${err}`);
+        return noAffinity();
+    }
+}
+//# sourceMappingURL=session-affinity.js.map

package/dist/shared/api-request.js

@@ -0,0 +1,124 @@
+/** The rules a daemon API request follows, kept away from `fetch` so they can
+ *  be tested without a browser — the same reason `view-url.ts` is window-free.
+ *
+ *  These are not stylistic preferences. Each one was a failure observed on a
+ *  741ms-RTT satellite link (`claude-4gqgp27l:9`), where the app's four
+ *  opening requests were aborted at exactly 10.00s having transferred zero
+ *  bytes, each still waiting on a CORS preflight that had never returned. The
+ *  reason the rules live here rather than inline is that **breaking them is
+ *  invisible on a fast network**: put an `Authorization` header back on a GET
+ *  and every LAN test still passes, while the app becomes unusable on a bad
+ *  link. A regression that only reproduces at 35,000 feet needs a unit test.
+ */
+/** Content types the CORS spec safelists. Anything else on a request makes it
+ *  "not simple" and forces a preflight round trip before the request may be
+ *  sent at all. `application/json` is famously absent. */
+const SAFELISTED_CONTENT_TYPES = [
+    "application/x-www-form-urlencoded",
+    "multipart/form-data",
+    "text/plain",
+];
+/** Header names a request may carry and still be CORS-simple. */
+const SAFELISTED_HEADERS = new Set([
+    "accept",
+    "accept-language",
+    "content-language",
+    "content-type", // only with a safelisted value — checked separately
+    "range",
+]);
+const SIMPLE_METHODS = new Set(["GET", "HEAD", "POST"]);
+/** Whether the browser must send a preflight `OPTIONS` and wait for its answer
+ *  before this cross-origin request may begin.
+ *
+ *  This is the whole cost model. A preflight is not "some overhead": it is a
+ *  full round trip — and, on a cold connection, its own TCP and TLS handshake
+ *  — that happens *before* the request you wanted exists on the wire. At LAN
+ *  latency it is unmeasurable. At 741ms it is the difference between an app
+ *  that loads and one that does not. */
+export function requiresPreflight(method, headers = {}) {
+    if (!SIMPLE_METHODS.has(method.toUpperCase()))
+        return true;
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (!SAFELISTED_HEADERS.has(lower))
+            return true;
+        if (lower === "content-type") {
+            const essence = value.split(";")[0].trim().toLowerCase();
+            if (!SAFELISTED_CONTENT_TYPES.includes(essence))
+                return true;
+        }
+    }
+    return false;
+}
+/** No headers, so a request stays CORS-simple. The emptiness is the point;
+ *  see `requiresPreflight`. */
+export const NO_HEADERS = {};
+/** For requests that carry a body. This preflights, and that is a considered
+ *  choice rather than an oversight: the alternative is labelling JSON as
+ *  `text/plain` to slip past CORS, and a Content-Type that lies is a trap for
+ *  whoever reads the code next. Bodied requests are also the rare ones — the
+ *  app reads far more than it writes — and the daemon's `Access-Control-Max-Age`
+ *  makes the preflight they do need a daily cost rather than a per-request one. */
+export const JSON_HEADERS = {
+    "Content-Type": "application/json",
+};
+/** Put the bearer token in the query string instead of an `Authorization`
+ *  header. The daemon has always accepted it there (`src/daemon/server.ts`,
+ *  checked immediately after the `Bearer` header), and it is what keeps a
+ *  bodiless request simple.
+ *
+ *  On the token being in a URL: it arrived in one. The meld URL that opens the
+ *  app carries `?token=`, so it is already in the address bar and in history,
+ *  and these requests address the operator's own daemon — there is no third
+ *  party to leak a Referer to. This moves the token nowhere it has not been. */
+export function withToken(path, token) {
+    const [base, hash] = splitHash(path);
+    const sep = base.includes("?") ? "&" : "?";
+    return `${base}${sep}token=${encodeURIComponent(token)}${hash}`;
+}
+/** A fragment is not sent to the server, so a token appended after one would
+ *  authenticate nothing. Split it off and put it back at the end. */
+function splitHash(path) {
+    const i = path.indexOf("#");
+    return i === -1 ? [path, ""] : [path.slice(0, i), path.slice(i)];
+}
+/** How long a request may take before it is abandoned.
+ *
+ *  Was 10s, which is generous on a LAN and unreachable on a satellite link: at
+ *  741ms RTT roughly 0.75s of TCP handshake and 1.5s of TLS elapse before a
+ *  request byte moves, and TCP needs about ten round trips to open its window.
+ *  60s costs a healthy network nothing — a fast request still returns fast,
+ *  since this is a ceiling and not a delay. */
+export const DEFAULT_TIMEOUT_MS = 60_000;
+export const MAX_ATTEMPTS = 3;
+const RETRY_BASE_MS = 500;
+/** Only replay requests that cannot have had an effect.
+ *
+ *  A timed-out POST is genuinely ambiguous: the daemon may have received it,
+ *  spawned the agent, and simply been too slow to say so. Retrying that
+ *  silently spawns a second one. Reporting the error is the lesser harm, and
+ *  it is the operator's call to make. */
+export function isRetryableMethod(method) {
+    const m = method.toUpperCase();
+    return m === "GET" || m === "HEAD";
+}
+/** Retry transport failures only — cases where no response ever arrived.
+ *
+ *  An HTTP error is an answer, not a failure to communicate: a 404 is a fact
+ *  that will not change on a second ask, and a 500 may have had effects. Only
+ *  a request that never landed is safe to send again. */
+export function isRetryableError(err) {
+    if (typeof DOMException !== "undefined" && err instanceof DOMException) {
+        return err.name === "AbortError";
+    }
+    if (err instanceof Error && err.name === "AbortError")
+        return true;
+    // `fetch` reports network failure as a bare TypeError.
+    return err instanceof TypeError;
+}
+/** Exponential backoff. A link that just dropped a request is often still
+ *  congested; retrying instantly mostly adds to the pile. */
+export function retryDelayMs(attempt) {
+    return RETRY_BASE_MS * 2 ** attempt;
+}
+//# sourceMappingURL=api-request.js.map

package/dist/shared/block-glyphs.js

@@ -0,0 +1,114 @@
+// Block elements (U+2580–U+259F), painted instead of typeset.
+//
+// A real terminal draws `▀ ▄ █` edge to edge in the cell. The mirror draws
+// them as text in a line box pinned at `line-height: 1.4`, and a font's block
+// glyph spans only its own ascent + descent — about 14px of a 16.8px row. So
+// every row of block art is striped with a dark gap, which is what turned
+// `brane meld`'s QR code into something that looked like a barcode and
+// scanned badly. The same gap runs through progress bars and htop meters.
+//
+// The fix is the one xterm.js calls "custom glyphs": wrap each block
+// character in a span exactly one cell wide and one line box tall, and paint
+// it as a background in `currentColor`. The glyph itself stays in the DOM,
+// hidden with `-webkit-text-fill-color: transparent` rather than `color`
+// (which would take `currentColor` with it), so selection and copy still
+// yield the real characters.
+//
+// Every paint is ONE full-tile image with hard stops — a linear gradient for
+// a bar, a conic one for quadrants — never a sized, positioned layer. A 16.8px
+// row puts cell edges on fractional pixels, and a layer sized to the cell
+// anti-aliases its own edges there, so two lit cells meeting across a row
+// each half-cover the boundary pixel and leave a faint hairline between them
+// (measured in headless Chromium at 1× and 3×: visible on every row of the
+// QR). A full-tile image's edges are the box's, which the browser snaps.
+//
+// Pure and window-free so `src/test/block-glyphs.test.ts` can pin the table.
+const C = "currentColor";
+const T = "transparent";
+/** A bar: lit for `fraction` of the cell, measured from the side `to` points away from. */
+function bar(to, fraction) {
+    const p = `${+(fraction * 100).toFixed(4)}%`;
+    return `linear-gradient(to ${to},${C} ${p},${T} ${p})`;
+}
+/**
+ * Quadrants by conic sweep from 12 o'clock, clockwise: upper-right, then
+ * lower-right, lower-left, upper-left.
+ */
+function quadrants(ur, lr, ll, ul) {
+    const q = (lit) => (lit ? C : T);
+    return (`conic-gradient(at 50% 50%,${q(ur)} 0 25%,${q(lr)} 0 50%,` +
+        `${q(ll)} 0 75%,${q(ul)} 0)`);
+}
+/** The background each block element paints, keyed by codepoint. */
+const PAINT = {
+    0x2580: bar("bottom", 1 / 2), // ▀ upper half
+    0x2581: bar("top", 1 / 8), // ▁ lower eighths …
+    0x2582: bar("top", 2 / 8), // ▂
+    0x2583: bar("top", 3 / 8), // ▃
+    0x2584: bar("top", 4 / 8), // ▄
+    0x2585: bar("top", 5 / 8), // ▅
+    0x2586: bar("top", 6 / 8), // ▆
+    0x2587: bar("top", 7 / 8), // ▇
+    0x2588: C, // █ full
+    0x2589: bar("right", 7 / 8), // ▉ left eighths …
+    0x258a: bar("right", 6 / 8), // ▊
+    0x258b: bar("right", 5 / 8), // ▋
+    0x258c: bar("right", 4 / 8), // ▌
+    0x258d: bar("right", 3 / 8), // ▍
+    0x258e: bar("right", 2 / 8), // ▎
+    0x258f: bar("right", 1 / 8), // ▏
+    0x2590: bar("left", 1 / 2), // ▐ right half
+    // ░ ▒ ▓ — a flat tint rather than a dither, which fills the cell the same way.
+    0x2591: `color-mix(in srgb,${C} 25%,${T})`,
+    0x2592: `color-mix(in srgb,${C} 50%,${T})`,
+    0x2593: `color-mix(in srgb,${C} 75%,${T})`,
+    0x2594: bar("bottom", 1 / 8), // ▔ upper eighth
+    0x2595: bar("left", 1 / 8), // ▕ right eighth
+    0x2596: quadrants(false, false, true, false), // ▖
+    0x2597: quadrants(false, true, false, false), // ▗
+    0x2598: quadrants(false, false, false, true), // ▘
+    0x2599: quadrants(false, true, true, true), // ▙
+    0x259a: quadrants(false, true, false, true), // ▚
+    0x259b: quadrants(true, false, true, true), // ▛
+    0x259c: quadrants(true, true, false, true), // ▜
+    0x259d: quadrants(true, false, false, false), // ▝
+    0x259e: quadrants(true, false, true, false), // ▞
+    0x259f: quadrants(true, true, true, false), // ▟
+};
+/** Every block element, U+2580–U+259F. */
+export const BLOCK_GLYPH_RE = /[▀-▟]/g;
+const HAS_BLOCK_GLYPH = /[▀-▟]/;
+/** The class a block glyph's span carries: `tb-2580` for `▀`. */
+export function blockGlyphClass(cp) {
+    return `tb-${cp.toString(16)}`;
+}
+/**
+ * Wrap each block element in `html` in its painted span. Lines without one
+ * — nearly all of them — cost a single regex test and come back unchanged.
+ *
+ * Safe on ansi_up output: block characters only ever appear there as text,
+ * never inside a tag or attribute.
+ */
+export function paintBlockGlyphs(html) {
+    if (!HAS_BLOCK_GLYPH.test(html))
+        return html;
+    return html.replace(BLOCK_GLYPH_RE, (ch) => `<span class="tb ${blockGlyphClass(ch.charCodeAt(0))}">${ch}</span>`);
+}
+/**
+ * The stylesheet behind `paintBlockGlyphs`, injected once per pane.
+ * `lineHeight` is the pane's unitless line-height, so `height: <n>em` is
+ * exactly the line box the rest of the mirror's row math divides by.
+ */
+export function blockGlyphStylesheet(lineHeight) {
+    const rules = [
+        // `width: 1ch` pins the cell to the font's advance even if a glyph falls
+        // back to a wider face; the glyph is invisible, so clipping it costs nothing.
+        `.tb{display:inline-block;width:1ch;height:${lineHeight}em;overflow:hidden;` +
+            `vertical-align:top;-webkit-text-fill-color:transparent}`,
+    ];
+    for (const [cp, paint] of Object.entries(PAINT)) {
+        rules.push(`.${blockGlyphClass(+cp)}{background:${paint}}`);
+    }
+    return rules.join("\n");
+}
+//# sourceMappingURL=block-glyphs.js.map

package/dist/shared/diagram-css.js

@@ -0,0 +1,17 @@
+/** The rule that makes a diagram's edge highlight layer visible.
+ *
+ *  `svg.ts` draws each edge a second time, on top, hidden by an `opacity`
+ *  attribute (see `edgeHighlight` there). Hover an arrow or its label, or tap
+ *  one (the group takes focus), and this reveals it. The SVG itself can't
+ *  carry the rule: an inline SVG's `<style>` is document-global. So the
+ *  export writes this string into its stylesheet and the app injects the same
+ *  string, the arrangement `MATH_BLOCK_CSS` has, so the two cannot drift.
+ *
+ *  Any CSS rule outranks a presentation attribute, which is what lets one
+ *  generic selector reveal any edge of any diagram. */
+export const DIAGRAM_EDGE_HIGHLIGHT_CSS = `
+.brane-diagram .brane-diagram-edge-hl { cursor: pointer; outline: none; }
+.brane-diagram .brane-diagram-edge-hl:hover,
+.brane-diagram .brane-diagram-edge-hl:focus { opacity: 1; }
+`;
+//# sourceMappingURL=diagram-css.js.map

package/dist/shared/export-selection.js

@@ -0,0 +1,101 @@
+/**
+ * The `seqs` export parameter — the chat's own message selection, on the wire.
+ *
+ * Both halves live here for the reason `view-url.ts` gives: a parameter whose
+ * writer and reader sit in different modules drifts. The app formats it
+ * (`expo/lib/api.ts`), the daemon parses it (`src/daemon/server.ts`), and
+ * `src/test/export-selection.test.ts` holds the two to the same grammar.
+ *
+ * The grammar is deliberately the dullest thing that works: ascending decimal
+ * seqs joined by commas, `12,14,19`. Not a range syntax — the selection is a
+ * set of taps, not an interval, and `12-19` would claim messages the operator
+ * never picked.
+ *
+ * `seqs_mode` says which side of the selection to export — the picks, or
+ * everything but them (see `SeqSelectionMode` below). It lives here rather
+ * than beside the route for the same reason `seqs` does: the two are read
+ * together or not at all.
+ */
+/** Selected seqs → the query-string value, or null when there is no selection
+ *  to send. Sorted ascending and deduped, so the same selection always
+ *  produces the same URL whatever order it was tapped in. */
+export function formatSeqParam(seqs) {
+    if (!seqs)
+        return null;
+    const clean = [...new Set(seqs)]
+        .filter((n) => Number.isInteger(n) && n > 0)
+        .sort((a, b) => a - b);
+    return clean.length > 0 ? clean.join(",") : null;
+}
+/** The query-string value → seqs. Anything unreadable is *no* selection, which
+ *  exports the whole conversation: an export is a read, and a malformed
+ *  parameter should hand the operator their transcript rather than a 400. */
+export function parseSeqParam(raw) {
+    if (!raw)
+        return [];
+    const out = new Set();
+    for (const part of raw.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        // Plain decimal digits and nothing else. `parseInt("12abc")` is 12, and
+        // `Number` is no stricter than it looks — `1e2` is 100, `0x10` is 16, `+4`
+        // is 4 — and each would silently export a message nobody asked for. The app
+        // only ever writes `formatSeqParam`'s digits, so this costs it nothing.
+        if (!/^\d+$/.test(trimmed))
+            continue;
+        const n = Number(trimmed);
+        if (Number.isSafeInteger(n) && n > 0)
+            out.add(n);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+/** The mode → its query-string value, or null when there is nothing to say.
+ *  `only` is the default the daemon already assumes, so it is left off the URL
+ *  entirely: a plain excerpt's link is byte-identical to the one brane built
+ *  before an inverse existed. */
+export function formatSeqModeParam(mode) {
+    return mode === "except" ? "except" : null;
+}
+/** The query-string value → the mode. Only the exact word `except` inverts an
+ *  export; absent, misspelled, or junk all mean `only`.
+ *
+ *  Asymmetric on purpose, and in the same direction as `parseSeqParam`'s
+ *  tolerance: an unreadable parameter must never hand the operator the
+ *  *complement* of the document they asked for. A garbled `only` costs them
+ *  nothing they can't see; a garbled `except` would silently export the
+ *  messages they were excluding. */
+export function parseSeqModeParam(raw) {
+    return raw?.trim() === "except" ? "except" : "only";
+}
+/** The file name an export saves under. A full export is `<nid>.html`, which is
+ *  also what sibling exports link to. An excerpt carries the count its header
+ *  discloses plus a short digest of exactly which seqs it holds —
+ *  `<nid>.3-of-47.9f2c1a.html` — so two different documents never share a
+ *  name. The count alone was not enough: `only` and `except` of a selection
+ *  that is half the conversation are both `2-of-4`, and that pair is the one a
+ *  redaction exists to keep apart. Browsers tend to uniquify a clashing
+ *  download rather than overwrite it, but `(1)` says nothing about which file
+ *  is the redacted one.
+ *
+ *  The count and a digest, not the mode, and for the header's reason: `only`
+ *  and `except` disclose identically, and a name reading "redacted" would tell
+ *  the reader which side of the line was taken — that something was
+ *  deliberately withheld — when the header is careful not to. */
+export function exportFileName(nid, excerpt) {
+    if (!excerpt)
+        return `${nid}.html`;
+    return `${nid}.${excerpt.seqs.length}-of-${excerpt.total}.${seqDigest(excerpt.seqs)}.html`;
+}
+/** Six hex digits naming a set of seqs: FNV-1a over the sorted list. Not a
+ *  security property — it only has to tell two excerpts of one narrative
+ *  apart — and dependency-free so this module stays importable anywhere. */
+export function seqDigest(seqs) {
+    let h = 0x811c9dc5;
+    for (const ch of [...seqs].sort((a, b) => a - b).join(",")) {
+        h ^= ch.charCodeAt(0);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return (h >>> 8).toString(16).padStart(6, "0");
+}
+//# sourceMappingURL=export-selection.js.map

package/dist/shared/find-in-text.js

@@ -0,0 +1,110 @@
+/** Find-in-file for the Files tab: the decisions, without the DOM.
+ *
+ *  The web hook (`expo/lib/findInFile.ts`) flattens a file body's text nodes
+ *  into one string, asks this module where the query occurs, and maps each
+ *  hit back onto the nodes it spans as a `Range`. Everything that is a rule
+ *  rather than a DOM call lives here, so `src/test/find-in-text.test.ts` can
+ *  pin it without a browser — smart-case, the `:N` line jump, which hit is
+ *  current after the query changes, and the offset → node mapping that has
+ *  to be exactly right for a highlight to land on the characters it names. */
+/** Hits past this are not collected: a one-letter query in a large file would
+ *  otherwise build tens of thousands of Ranges for a counter nobody reads. */
+export const MAX_FIND_MATCHES = 5000;
+/** Smart-case, as in vim and ripgrep: an all-lowercase query matches any case,
+ *  and a single uppercase letter makes the whole query exact. */
+export function isCaseSensitive(query) {
+    return query !== query.toLowerCase();
+}
+/** `:120` → 120. Anything else — `:`, `:0`, `: 12`, `12` — is not a jump and
+ *  is searched for literally. */
+export function parseLineJump(query) {
+    const m = /^:(\d+)$/.exec(query.trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return n > 0 ? n : null;
+}
+/** Every non-overlapping occurrence of `query` in `text`, in order. The query
+ *  is literal (no regex, no fuzziness) and is not trimmed: a trailing space is
+ *  how you ask for the word and not the prefix. */
+export function findMatches(text, query, limit = MAX_FIND_MATCHES) {
+    const matches = [];
+    if (!query)
+        return { matches, capped: false };
+    const sensitive = isCaseSensitive(query);
+    const hay = sensitive ? text : text.toLowerCase();
+    const needle = sensitive ? query : query.toLowerCase();
+    // toLowerCase can change a string's length (İ → i̇), which would shift every
+    // offset after it. Fall back to the exact-case search rather than highlight
+    // the wrong characters.
+    const [h, n] = hay.length === text.length ? [hay, needle] : [text, query];
+    let from = 0;
+    while (from <= h.length - n.length) {
+        const at = h.indexOf(n, from);
+        if (at < 0)
+            break;
+        if (matches.length >= limit)
+            return { matches, capped: true };
+        matches.push({ start: at, end: at + n.length });
+        from = at + n.length;
+    }
+    return { matches, capped: false };
+}
+/** The index of the first hit starting at or after `offset`, wrapping to 0 when
+ *  every hit is before it; -1 when there are none. This is how the current hit
+ *  stays put while the query is typed: each keystroke re-anchors on where the
+ *  last current hit started, so `use` → `useM` → `useMemo` walks forward
+ *  through the file instead of snapping back to its top. */
+export function firstAtOrAfter(matches, offset) {
+    if (matches.length === 0)
+        return -1;
+    let lo = 0;
+    let hi = matches.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (matches[mid].start < offset)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo < matches.length ? lo : 0;
+}
+/** Next (`+1`) or previous (`-1`) hit, wrapping at both ends. */
+export function stepMatch(current, count, dir) {
+    if (count <= 0)
+        return -1;
+    if (current < 0)
+        return dir > 0 ? 0 : count - 1;
+    return (current + dir + count) % count;
+}
+/** Map a span of the flattened text onto the nodes it covers, or null when an
+ *  end falls in a separator (which `findMatches` can only produce if the query
+ *  itself contains the separator character). `slots` must be in ascending,
+ *  non-overlapping order, which is how a tree walk produces them. */
+export function locateSpan(slots, span) {
+    const start = locatePoint(slots, span.start, false);
+    const end = locatePoint(slots, span.end, true);
+    return start && end ? { start, end } : null;
+}
+/** The slot containing `pos`. A position on the boundary between two slots
+ *  belongs to the later one as a start and to the earlier one as an end, so a
+ *  Range never begins at the very end of a node or finishes at the very start
+ *  of the next — both would be empty-looking edges on the highlight. */
+function locatePoint(slots, pos, isEnd) {
+    let lo = 0;
+    let hi = slots.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const s = slots[mid];
+        const lower = s.start;
+        const upper = s.start + s.length;
+        if (isEnd ? pos <= lower : pos < lower)
+            hi = mid - 1;
+        else if (isEnd ? pos > upper : pos >= upper)
+            lo = mid + 1;
+        else
+            return { node: mid, offset: pos - s.start };
+    }
+    return null;
+}
+//# sourceMappingURL=find-in-text.js.map