brane 0.1.1 → 0.3.0

package/dist/shared/narrative-format.js

@@ -0,0 +1,237 @@
+/**
+ * Narrative meta formatting — the single source of truth for how a narrative's
+ * cost and activity span are worded, shared by every surface that renders them.
+ *
+ * Four consumers today: the Expo list card, the page header, and the switcher
+ * (all via `expo/components/NarrativeMeta.tsx` / `expo/lib/api.ts`), plus the
+ * server-side HTML export (`src/export.ts`). They must read alike — a narrative
+ * card that says "$6.81 /worker from 3d to 4h ago" in the app has to say the
+ * same thing in an export of that narrative.
+ *
+ * Deliberately dependency-free, framework-free (no React, no react-native, no
+ * node builtins) *and stateless* so both the tsc build and the metro bundler
+ * can consume it. Stateless is load-bearing, not stylistic: this file is
+ * compiled twice — once by the root tsc into `dist/shared/`, once inlined into
+ * the metro bundle — so the two builds hold separate copies. Pure functions
+ * don't care; a module-level cache or counter added here would silently
+ * diverge between the server and the app.
+ *
+ * Expo reaches this file through the `@shared/*` tsconfig path and the
+ * `watchFolders` entry in `expo/metro.config.js` — keep it that way.
+ */
+/** Event types that carry conversation: an agent's own voice, the operator's
+ *  signals, and foreign agents' signals. Exported as an array as well, because
+ *  `src/export.ts` asks SQLite the same question (`type IN (…)`) and a second
+ *  hand-written list of these three strings is a list that drifts. */
+export const CONVERSATIONAL_EVENT_TYPES_LIST = ["narration", "human_signal", "agent_signal"];
+const CONVERSATIONAL_EVENT_TYPES = new Set(CONVERSATIONAL_EVENT_TYPES_LIST);
+/** True for events the daemon wrote on its own behalf — `started` (spawn/twin/
+ *  external MCP client), `restarted` (revive), `binding_rejected`. They're part
+ *  of the record (a twin's `/twin from <nid>:<seq>` back-pointer lives here),
+ *  but nobody *said* them, so every surface renders them as a recessive system
+ *  line rather than as a speaker's bubble. */
+export function isSystemEvent(type) {
+    return !CONVERSATIONAL_EVENT_TYPES.has(type);
+}
+/*
+ * Lifecycle lines — the text of a `started` / `restarted` event.
+ *
+ * One shape, written the way the loop already speaks: a verb, the invocation
+ * as a code span, and the role as a `/protocol` command.
+ *
+ *   Spawned `claude --model opus-5` /worker
+ *   Spawned `claude` /twin from claude-abc:42
+ *   Revived `claude --dangerously-skip-permissions` /worker (forked — original still live)
+ *   Running `lazygit`
+ *
+ * The code span is what the operator chose — the binary, its model flag, and
+ * any passthrough args — never the daemon's plumbing (session ids, MCP config
+ * paths, the bind secret, the bootstrap prompt). The `/role` is the same token
+ * the card's meta line and the `/keeper` slash convention use, and the app's
+ * protocol linkifier turns it into a link to the role's protocol. The
+ * predecessor after `from` is a bare `nid:seq` on purpose: a backtick there
+ * would stop it linkifying, and that link is the whole point of the line.
+ *
+ * The fold is deliberately *not* in the stored text. It is a column on the
+ * narrative's own row — a twin's row carries the twin's fold, which is what
+ * makes it worth showing — and every renderer has that row, so `systemLine`
+ * appends it at render time from the column rather than from the string.
+ *
+ * Every writer (spawn, twin, revive, run, absorb) calls these so the stored
+ * text is already the final form; `formatSystemContent` below normalizes the
+ * rows written before this shape existed.
+ */
+/** A single argv word as a shell would want it typed: bare when it can be,
+ *  single-quoted when it holds whitespace or a quote. */
+function shellWord(arg) {
+    if (arg !== "" && !/[\s'"$`\\]/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+/** An invocation as a markdown code span. Backticks inside it widen the fence
+ *  rather than break it. */
+export function formatInvocation(command) {
+    const text = command.map(shellWord).join(" ");
+    const longest = Math.max(0, ...Array.from(text.matchAll(/`+/g), (m) => m[0].length));
+    const fence = "`".repeat(longest + 1);
+    return longest ? `${fence} ${text} ${fence}` : `${fence}${text}${fence}`;
+}
+/** `Spawned \`claude --model x\` /worker`, or with a predecessor,
+ *  `Spawned \`claude\` /twin from claude-abc:42`. */
+export function spawnedContent(agent, role, opts = {}) {
+    const line = `Spawned ${formatInvocation([agent, ...(opts.args ?? [])])} /${role}`;
+    return opts.from ? `${line} from ${opts.from}` : line;
+}
+/** `Revived \`claude\` /worker`, flagged when the resume forked a still-live
+ *  original — the one thing about a revive the arguments don't say. */
+export function revivedContent(agent, role, args = [], forked = false) {
+    const line = `Revived ${formatInvocation([agent, ...args])} /${role}`;
+    return forked ? `${line} (forked — original still live)` : line;
+}
+/** A utility narrative (`POST /api/run`) has no role and no agent: the line is the
+ *  command itself. */
+export function runningContent(command) {
+    return `Running ${formatInvocation(command)}`;
+}
+export function restartedContent(command) {
+    return `Restarted ${formatInvocation(command)}`;
+}
+/** The agent a narrative id was minted for: `claude-rfhbth2v` → `claude`.
+ *  Every brane-spawned id is `<agent>-<8 base36>`, so the prefix is exact for
+ *  them; an absorbed import's `organelle-…` id names the importer, which is
+ *  why callers prefer the row's `agent_type` and fall back to this. */
+export function agentTypeOf(nid) {
+    return nid.replace(/-[a-z0-9]{8}$/, "");
+}
+/** Bring a lifecycle line written before the invocation shape existed up to
+ *  it, at render time — changing the writers alone would fix narratives
+ *  spawned from then on and leave every existing one reading the old way:
+ *
+ *    Spawned claude (worker)        → Spawned `claude` /worker
+ *    Twinned from claude-abc:42     → Spawned `claude` /twin from claude-abc:42
+ *    Revived claude session (…)     → Revived `claude` (…)
+ *    Running lazygit                → Running `lazygit`
+ *
+ *  The old twin line never recorded which agent was spawned, so the caller
+ *  supplies it from the narrative row; without one the line falls back to
+ *  `/twin from …`.
+ *
+ *  A line already carrying a code span is in the new shape and passes through
+ *  untouched — a row written since this shape landed is never transformed. Deliberately no allowlist of known
+ *  roles: whatever a narrative was spawned as gets the same notation. Each
+ *  pattern is anchored to the whole line so ordinary prose that happens to
+ *  start with one of these verbs is left alone. */
+export function formatSystemContent(content, agent) {
+    const s = content.trimEnd();
+    if (s.includes("`"))
+        return s;
+    let m;
+    if ((m = /^Spawned (\S+) \(([A-Za-z0-9][\w.-]*)\)$/.exec(s))) {
+        return spawnedContent(m[1], m[2]);
+    }
+    if ((m = /^Twinned from (\S+)$/.exec(s))) {
+        return agent ? spawnedContent(agent, "twin", { from: m[1] }) : `/twin from ${m[1]}`;
+    }
+    if ((m = /^Revived (\S+) session( \(.*\))?$/.exec(s))) {
+        return `Revived \`${m[1]}\`${m[2] ?? ""}`;
+    }
+    if ((m = /^(Running|Restarted) (.+)$/.exec(s))) {
+        return `${m[1]} \`${m[2]}\``;
+    }
+    return s;
+}
+/** The href scheme a lifecycle line's fold is linked under, so a renderer can
+ *  pick it out and paint it the way the identity row paints a fold — green,
+ *  monospace — rather than link blue. It identifies; it does not navigate. */
+export const FOLD_LINK_SCHEME = "brane://fold/";
+/** The fold color the identity row uses (`NarrativeIdentity` in
+ *  `expo/components/NarrativeMeta.tsx`); the export's stylesheet reads it from
+ *  here so a system line's fold is the same green in both. */
+export const FOLD_COLOR = "#5e8a72";
+/** The markdown a renderer shows for a system event: the stored line (legacy
+ *  shapes normalized), and for a `started` event the narrative's fold appended
+ *  as `in [fold](brane://fold/fold)`. The fold comes from the row, and whether
+ *  to show it from the event type — nothing is read out of the text. A
+ *  `restarted` line omits it (a revive cannot move folds, and the header
+ *  already says where the narrative lives); an external narrative has no fold
+ *  and so shows none.
+ *
+ *  The one text comparison is an equality: for a few hours on 2026-09-08 the
+ *  writers baked ` in <fold>` into the content. A row from that window ends
+ *  with exactly its own `fold_path`, which is dropped so the fold isn't shown
+ *  twice. */
+export function systemLine(event, narrative = {}) {
+    let text = formatSystemContent(event.content, narrative.agent);
+    const fold = narrative.fold ?? null;
+    if (!fold)
+        return text;
+    const baked = ` in ${fold}`;
+    if (text.endsWith(baked))
+        text = text.slice(0, -baked.length);
+    return event.type === "started" ? `${text} in [${fold}](${FOLD_LINK_SCHEME}${fold})` : text;
+}
+/** One end of the activity span. `val` is the bare magnitude ("3d", "5m",
+ *  "30s") or an absolute date once older than a week; `ago` says whether an
+ *  "ago" suffix applies (so a span can share one "ago": "3d to 4h ago"). */
+export function relPart(ms, now = Date.now()) {
+    const sec = Math.floor((now - ms) / 1000);
+    if (sec < 60)
+        return { val: `${Math.max(1, sec)}s`, ago: true };
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return { val: `${min}m`, ago: true };
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return { val: `${hr}h`, ago: true };
+    const day = Math.floor(hr / 24);
+    if (day < 7)
+        return { val: `${day}d`, ago: true };
+    const d = new Date(ms);
+    const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+    const date = `${months[d.getMonth()]} ${d.getDate()}`;
+    return { val: d.getFullYear() === new Date(now).getFullYear() ? date : `${date}, ${d.getFullYear()}`, ago: false };
+}
+/** Humanized activity span "created-ago to last-active-ago" — e.g. "3d to 4h
+ *  ago". Collapses to a single value when there's no distinct last activity
+ *  (brand-new narrative, or before the daemon exposes last_activity).
+ *  When both ends are relative they share one "ago"; mixed/absolute ends are
+ *  spelled out per-end ("Jun 10 to 4 hours ago").
+ *
+ *  `now` is the instant the span is relative to. The live surfaces leave it at
+ *  the default; the HTML export pins it to the export timestamp so a static
+ *  document's "3d ago" stays anchored to the moment it was written. */
+export function formatActivitySpan(createdMs, lastMs, now = Date.now()) {
+    const c = relPart(createdMs, now);
+    const withAgo = (p) => (p.ago ? `${p.val} ago` : p.val);
+    const hasSpan = typeof lastMs === "number" && lastMs - createdMs > 60_000;
+    if (!hasSpan)
+        return withAgo(c);
+    const l = relPart(lastMs, now);
+    if (c.val === l.val)
+        return withAgo(c);
+    if (c.ago && l.ago)
+        return `${c.val} to ${l.val} ago`;
+    return `${withAgo(c)} to ${withAgo(l)}`;
+}
+/** Format a metered cost for display, generic across units. USD renders as
+ *  "$6.81"; any other unit (e.g. Copilot's "AIC" credits) renders as
+ *  "1,200 AIC". Returns null when there's nothing to show. */
+export function formatCost(amount, unit) {
+    if (amount == null || !unit)
+        return null;
+    if (unit === "USD")
+        return `$${amount.toFixed(2)}`;
+    const n = Number.isInteger(amount)
+        ? amount.toLocaleString()
+        : amount.toLocaleString(undefined, { maximumFractionDigits: 2 });
+    return `${n} ${unit}`;
+}
+/** Format a set of per-unit totals as one line: "$2,430.46 · 100.2 AIC".
+ *  Units are listed, never added. Returns null when there is nothing metered. */
+export function formatCostTotals(totals) {
+    if (!totals?.length)
+        return null;
+    const parts = totals.map((t) => formatCost(t.amount, t.unit)).filter((p) => !!p);
+    return parts.length ? parts.join(" · ") : null;
+}
+//# sourceMappingURL=narrative-format.js.map

package/dist/shared/narrative-menu.js

@@ -0,0 +1,82 @@
+/**
+ * The 🦠 menu's *shape* — icons, labels, and which items a given narrative
+ * gets — in one place, so the two surfaces that offer it (the detail header's
+ * 🦠 button and the list card's status badge) cannot drift apart. Adding an
+ * item here adds it to both; that is the whole point of the module.
+ *
+ * Lives in `shared/` rather than beside the components because it is pure: no
+ * React, no window, no network. That makes the "cannot drift" claim something
+ * the node suite can actually check (`src/test/narrative-menu.test.ts`) rather
+ * than something a comment asserts.
+ */
+/** Roles with no tmux process to resume: reviving them means twinning instead —
+ *  an external session (an MCP client that connected without `brane spawn`) or
+ *  an absorbed import, neither of which has an agent to restart.
+ *
+ *  Stated once because three places need to agree on it: the pane that turns
+ *  Revive into Twin, the detail screen that must not rewrite its view for a
+ *  revive that is really going to open a dialog, and the list that should ask
+ *  the same question the detail screen asks. */
+export function revivesAsTwin(role) {
+    return role === "external" || role === "absorbed";
+}
+export function narrativeMenuItems({ role, status, mcpConnected, archived = false, isIsolated = false, selectedCount = 0, onMeld, onIsolate, onExport, onRecolor, onTwin, onRevive, onEnd, onArchiveToggle, }) {
+    const isEnded = status === "ended" && !mcpConnected;
+    // External narratives have no tmux process — no in-place End/Revive applies;
+    // their only lifecycle action is Twin (continue into a brane-managed agent).
+    // Absorbed imports twin as well, but they reach it *through* Revive, which is
+    // why they keep the item and `external` does not: an import is a transcript
+    // you continue, an external session is one you can only fork.
+    const isExternal = role === "external";
+    return [
+        { icon: "🖖", label: "Meld", onPress: onMeld },
+        {
+            icon: isIsolated ? "🏘️" : "🏠",
+            label: isIsolated ? "Unisolate" : "Isolate",
+            onPress: onIsolate,
+        },
+        // With a selection, Export becomes two items — the picks, or everything but
+        // the picks — because a selection is as often "these are the interesting
+        // ones" as "these are the ones nobody else should read". Both items name
+        // the same N: it is the count the operator can see highlighted, and the
+        // complement's own message count exists only on the daemon.
+        //
+        // 📤 rather than ✂️ for the second: scissors in a menu that also holds
+        // Archive read as a deletion, and an export removes nothing from anything.
+        ...(selectedCount > 0
+            ? [
+                {
+                    icon: "📨",
+                    label: `Export ${selectedCount} selected`,
+                    onPress: () => onExport("selected"),
+                },
+                {
+                    icon: "📤",
+                    label: `Export ${selectedCount} excluded`,
+                    onPress: () => onExport("excluded"),
+                },
+            ]
+            : [{ icon: "📨", label: "Export", onPress: () => onExport("all") }]),
+        // Recolor sits with Export rather than the lifecycle verbs below it: both
+        // act on how the narrative is *seen*, and neither touches the daemon.
+        { icon: "🎨", label: "Recolor", onPress: onRecolor },
+        // Twin is available on every narrative — fork/continue it into a
+        // new brane-managed agent (UI-gated via the spawn dialog). A plain verb
+        // like its neighbors; the /twin protocol syntax belongs to the dialog the
+        // press opens and to the line the resulting narrative starts with.
+        { icon: "🧬", label: "Twin", onPress: onTwin },
+        ...(isExternal
+            ? []
+            : [
+                isEnded
+                    ? { icon: "🐦‍🔥", label: "Revive", onPress: onRevive }
+                    : { icon: "🫠", label: "End", onPress: onEnd },
+            ]),
+        {
+            icon: archived ? "📂" : "🗄️",
+            label: archived ? "Unarchive" : "Archive",
+            onPress: onArchiveToggle,
+        },
+    ];
+}
+//# sourceMappingURL=narrative-menu.js.map

package/dist/shared/narrative-sort.js

@@ -0,0 +1,47 @@
+/**
+ * Narrative list ordering — the single source of truth for the order narratives
+ * appear in, shared by every surface that shows more than one of them.
+ *
+ * Two consumers today: the list screen (`expo/app/index.tsx`) and the header's
+ * narrative switcher (`expo/app/[nid].tsx`). They have to agree. When this rule
+ * lived only in the list screen, the switcher kept the older three-way rank it
+ * had been copied from and went on rearranging itself under the operator's
+ * thumb — in the one place that hurts most, since the switcher is a modal you
+ * open in order to reach for a card.
+ *
+ * Deliberately dependency-free and framework-free, like its neighbors here, and
+ * structurally typed: `NarrativeInfo` lives in `expo/lib/api.ts`, which this
+ * file must not reach for. Ordering needs two fields, so it takes exactly those.
+ *
+ * Expo reaches this file through the `@shared/*` tsconfig path and the
+ * `watchFolders` entry in `expo/metro.config.js` — keep it that way.
+ */
+/** Sort narratives: DEAD below everything, LIVE and IDLE interleaved. Newest first
+ *  within each of the two groups.
+ *
+ *  Only the bottom edge is a partition, and that asymmetry is the point. DEAD is
+ *  a durable fact about a session — it stays dead until someone revives it — so
+ *  sinking it costs nobody a moving target. LIVE vs IDLE is not durable at all:
+ *  it tracks `mcp_connected`, which drops whenever an agent's own work blocks its
+ *  bridge, and comes back a moment later. Ranking on it made the list rearrange
+ *  itself under the operator's thumb for a distinction that had already expired
+ *  by the time the card landed. A card the operator is reaching for should not
+ *  move because the agent inside it got busy.
+ *
+ *  `created_at` is the tiebreak rather than last activity for the same reason:
+ *  it is the one key a status flip cannot touch, so within the live/idle block
+ *  nothing moves at all.
+ *
+ *  The dead predicate is `status === "ended"`, matching the badge exactly (see
+ *  `statusText` in `expo/app/index.tsx`) — the order on screen and the word on
+ *  the card are then answering the same question.
+ *
+ *  Returns a new array; the input is not mutated. */
+export function sortNarratives(narrs) {
+    return [...narrs].sort((a, b) => {
+        const rank = (n) => (n.status === "ended" ? 1 : 0);
+        const diff = rank(a) - rank(b);
+        return diff !== 0 ? diff : b.created_at - a.created_at;
+    });
+}
+//# sourceMappingURL=narrative-sort.js.map

package/dist/shared/narrative-status.js

@@ -0,0 +1,52 @@
+/**
+ * The awaiting glow: how a narrative whose agent is parked waiting for
+ * direction — a blocking `listen`, or a `narrate({ wait: true })` — shows it.
+ *
+ * It is deliberately not a status word. LIVE / IDLE / DEAD say what the
+ * session is; the glow says the agent is waiting on you, and it lights the
+ * whole row (list card, switcher row, narrative header) from the inside, the
+ * way padding would sit, so nothing moves when it comes and goes.
+ *
+ * The hue is allocated per device (`src/shared/glow-hues.ts`): chosen once,
+ * as far as it can be from the hues of the other recently glowing narratives,
+ * then kept, so the operator can learn sessions by color. 🎨 Recolor moves it
+ * to a random hue still clear of the others.
+ *
+ * The fact comes from the daemon's `awaiting` bit (src/daemon/awaiting.ts).
+ * It is only honoured while bridged: a parked call cannot outlive its socket,
+ * so an unbridged narrative claiming it is a stale client-side value.
+ */
+export function isAwaiting({ mcpConnected, awaiting }) {
+    return !!mcpConnected && !!awaiting;
+}
+/** An inset-only `box-shadow`, all glow and no line: every layer is blurred,
+ *  none is a solid edge. Inset shadows take no layout space and never spill
+ *  onto neighbours.
+ *
+ *  Near-opaque at the rim, fading inward. The hue is what tells sessions
+ *  apart, and translucency over a dark row mixes it toward the background:
+ *  the first version peaked at 0.45 alpha, and hues a quarter turn apart
+ *  read as the same dim tint. OKLCH rather than HSL because equal HSL
+ *  lightness is not equal brightness — yellow and cyan glared while blue and
+ *  violet sank — so each layer holds lightness and chroma fixed and only the
+ *  hue varies. */
+export function awaitingGlow(h) {
+    return [
+        `inset 0 0 3px 1px oklch(0.78 0.16 ${h} / 0.95)`,
+        `inset 0 0 18px 2px oklch(0.74 0.15 ${h} / 0.55)`,
+        `inset 0 0 40px 4px oklch(0.7 0.14 ${h} / 0.28)`,
+        // The top edge reads a pixel thinner than the bottom, which has the
+        // tab bar's hairline under it. A one-sided copy of the first layer
+        // thickens the top alone: the negative spread grows the shadow's hole
+        // past every edge, and the offset pulls it back to 1px below the top.
+        `inset 0 4px 3px -3px oklch(0.78 0.16 ${h} / 0.95)`,
+    ].join(", ");
+}
+/** The daemon reports the bit's edges as their own control message,
+ *  `{ type: "awaiting", narrative, awaiting }` — never as a `status`, which an
+ *  older app would read as the narrative's lifecycle status. Inside the app the
+ *  root layout forwards them to the status listeners as these two words, so a
+ *  screen needs one subscription for everything a row depends on. */
+export const AWAITING_STATUS = "awaiting";
+export const NOT_AWAITING_STATUS = "not_awaiting";
+//# sourceMappingURL=narrative-status.js.map

package/dist/shared/no-pan.js

@@ -0,0 +1,85 @@
+/** Rules that keep iOS Safari from moving the page under the app, window-free.
+ *
+ *  Every scroller in brane is an inner one; the page itself never scrolls.
+ *  iOS moves it anyway in two ways, and both hide the header:
+ *
+ *  1. **The focus pan.** Focusing an input the keyboard will cover scrolls
+ *     the page until the input clears it. Refused at the source: a tap on an
+ *     editable is taken over and focuses it with `preventScroll`, which iOS
+ *     honours for the keyboard too (measured on device, claude-3j4583pl:124).
+ *  2. **The drag pan.** With the keyboard up the visible area is shorter than
+ *     the page, and any drag the app doesn't scroll — on the header, on a bar,
+ *     or past the end of a list — pans the page within it. Refused by allowing
+ *     a vertical drag only where something under the finger can itself scroll
+ *     that way.
+ *
+ *  The layout, meanwhile, is sized to the visible area (`--brane-vvh`), so a
+ *  bottom bar sits on the keyboard without anything having to move. */
+/** Movement past this between touchstart and touchend makes it a drag, not a
+ *  tap: a scroll that happens to start on an input must not focus it. */
+export const TAP_SLOP_PX = 10;
+const NON_TEXT_INPUTS = new Set(["button", "checkbox", "color", "file", "hidden", "image", "radio", "range", "reset", "submit"]);
+/** Whether a tap on this element should be taken over to focus it without
+ *  the pan: text-entry controls that are enabled and writable. */
+export function isTextEntry(el) {
+    if (el.isContentEditable)
+        return true;
+    const tag = el.tagName.toUpperCase();
+    if (tag !== "INPUT" && tag !== "TEXTAREA")
+        return false;
+    if (el.disabled || el.readOnly)
+        return false;
+    return tag === "TEXTAREA" || !NON_TEXT_INPUTS.has((el.type ?? "text").toLowerCase());
+}
+/** A box's room each way from its raw scroll numbers. `reversed` is a
+ *  `column-reverse` flex container, whose scroll origin is its bottom. */
+export function scrollBoxOf(el) {
+    const range = el.scrollHeight - el.clientHeight;
+    const scrolls = (el.overflowY === "auto" || el.overflowY === "scroll") && range > 1;
+    if (!scrolls)
+        return { scrolls: false, roomAbove: 0, roomBelow: 0 };
+    const [min, max] = el.reversed ? [-range, 0] : [0, range];
+    return { scrolls: true, roomAbove: el.scrollTop - min, roomBelow: max - el.scrollTop };
+}
+/** Whether a drag may proceed. Horizontal drags always may — tab swipes and
+ *  wide code blocks are the app's, and the page never pans sideways. A
+ *  vertical one may only if some element under the finger (innermost first)
+ *  can scroll in its direction; otherwise it would move the page. `dy > 0`
+ *  is a finger moving down, which reveals what is above. */
+export function dragAllowed(dx, dy, chain) {
+    if (Math.abs(dx) > Math.abs(dy))
+        return true;
+    if (dy === 0)
+        return true;
+    for (const b of chain) {
+        if (!b.scrolls)
+            continue;
+        if (dy > 0 && b.roomAbove > 1)
+            return true;
+        if (dy < 0 && b.roomBelow > 1)
+            return true;
+    }
+    return false;
+}
+/** The layout height to use: the visible area's, except while pinch-zoomed,
+ *  when the visible area is a magnified piece of the page and the layout must
+ *  not change at all. */
+export function layoutHeight(vvHeight, scale, previous) {
+    if (Math.abs(scale - 1) > 0.01)
+        return previous;
+    return Math.round(vvHeight);
+}
+/** After our own tap focuses a field, the keyboard takes a moment to rise;
+ *  the field is not "focused with the keyboard down" during that window. */
+export const TAP_FOCUS_GRACE_MS = 1000;
+/** The invariant that keeps the focus pan from ever coming back: on a touch
+ *  screen, a text field may hold focus only while the soft keyboard is up,
+ *  or just after our own tap focused it. A field focused with the keyboard
+ *  down — swiped away, focused from code, autofocused on load — turns the
+ *  next tap into a native keyboard raise, and iOS pans for that one
+ *  (claude-3j4583pl:171, :176). Every such state is blurred, whoever made
+ *  it. Never on a fine pointer: there is no soft keyboard to wait for. */
+export function mustBlur(s) {
+    return s.touch && s.textEntryFocused && !s.keyboardUp && s.msSinceTapFocus > TAP_FOCUS_GRACE_MS;
+}
+//# sourceMappingURL=no-pan.js.map

package/dist/shared/pane-layout.js

@@ -0,0 +1,50 @@
+/** Which panes a narrative screen shows, and what tapping into one does to
+ *  that set.
+ *
+ *  The visible set is `active ∪ pinned` — one derived rule with two writers
+ *  (the tab bar's pin toggle, and every place that changes the active tab), so
+ *  it belongs somewhere both can reach. It lives in `shared/` for the same
+ *  reason `view-url.ts` does: being window-free is what makes the invariant
+ *  below testable without a browser, and the invariant is one a DOM test would
+ *  never have caught anyway.
+ *
+ *  Nothing here touches the URL; `viewParams` still serializes the pair.
+ */
+import { CANONICAL_TABS } from "./view-url.js";
+/** The panes rendered right now, in tab-bar order: the active one plus every
+ *  pinned one. A single-element result is the full-width case; two or three
+ *  split the row evenly. */
+export function visiblePanes(active, pinned) {
+    return CANONICAL_TABS.filter((t) => t === active || pinned.has(t));
+}
+/** Move the keyboard to `tapped` **without taking a pane away**.
+ *
+ *  Naively, selecting a pane is just `setActiveTab` — but the outgoing pane is
+ *  only visible because it was active, so unless it is pinned on the way past
+ *  it disappears, and the split collapses to one full-width pane. That is the
+ *  ordinary shape of a split (you are in Chat, you pin the Terminal), so the
+ *  naive version means tapping the terminal in a split drops Chat.
+ *
+ *  Collapsing does not just surprise; it eats the tap. Pane selection runs on
+ *  `pointerdown`, so the surviving pane doubles in width — sliding every
+ *  control inside it sideways — before the finger lifts. The pointerup lands
+ *  on some other element, no `click` is dispatched, and the button that was
+ *  pressed never fires. On the terminal quick bar, whose row is centered, this
+ *  is a quarter of the screen's travel and a keystroke silently lost.
+ *
+ *  So: pin the outgoing pane. The visible set is then unchanged whenever
+ *  `tapped` was already visible, and merely grows by `tapped` when it wasn't
+ *  (the reveal case — `revealTerminal`). It never shrinks.
+ *
+ *  Nor does the pin set. Tapping used to unpin the incoming pane too, on the
+ *  grounds that being active already shows it — true, but a pin is the
+ *  operator's statement, not bookkeeping: with Terminal and Files pinned,
+ *  tapping into Files cleared Files' pin, and the next tab change dropped a
+ *  pane the operator had asked to keep. A pin comes off only through its 📌.
+ */
+export function selectPane(active, pinned, tapped) {
+    const next = new Set(pinned);
+    next.add(active);
+    return { active: tapped, pinned: next };
+}
+//# sourceMappingURL=pane-layout.js.map

package/dist/shared/payload-inline.js

@@ -0,0 +1,83 @@
+/**
+ * What a payload is allowed to *become* in a browser.
+ *
+ * Every daemon URL carries `?token=` in its query string (see
+ * `api-request.ts` for why it is there rather than in a header). That is
+ * harmless while the response is data — an `<img>`, a `fetch` — and stops
+ * being harmless the moment the browser makes a *document* of it: the token
+ * is then in the address bar, in history, and in the base URL that "Save
+ * Page As" resolves the page's relative links against, which is how a daemon
+ * token gets written into a saved file.
+ *
+ * So there is one rule, and both halves of the system have to agree on it:
+ * the app renders image payloads inline and hands everything else over as a
+ * file, and the daemon serves everything else with
+ * `Content-Disposition: attachment` so a payload URL that reaches a browser
+ * some other way still cannot become a page.
+ */
+/** The extensions the app renders inline, with the type each is served and
+ *  embedded as. Everything else is a file to be handed over — including
+ *  formats a browser *could* display (`.pdf`, `.txt`, `.html`): "can the
+ *  browser render it" is not the question, "does brane render it inline" is.
+ *
+ *  One table rather than a predicate beside a lookup, because the HTML export
+ *  needs both answers and a disagreement between them is silent — an image
+ *  that passes the filter but misses the type is simply dropped from the
+ *  export with nothing said. */
+export const INLINE_PAYLOAD_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".avif": "image/avif",
+    ".svg": "image/svg+xml",
+};
+/** The lowercased extension of a path, `""` when it has none. Hand-rolled
+ *  because this module is shared with the app, where `node:path` is not. */
+export function payloadExtname(path) {
+    const dot = path.lastIndexOf(".");
+    if (dot < 0)
+        return "";
+    const ext = path.slice(dot).toLowerCase();
+    // A dot in a *directory* name is not this file's extension.
+    return ext.includes("/") ? "" : ext;
+}
+/** Whether this payload renders inline (an image) rather than downloading. */
+export function isInlinePayload(path) {
+    return payloadExtname(path) in INLINE_PAYLOAD_MIME;
+}
+/** Control characters, which a header has no way to carry: a CR would end
+ *  it outright. Stripped rather than escaped — none of them belong in a
+ *  filename in the first place. */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/g;
+/** The `Content-Disposition` value that hands a payload over as a file.
+ *
+ *  The header is a quoted-string, so a quote in a filename has to be escaped
+ *  or it ends the parameter early; anything non-ASCII additionally
+ *  gets the RFC 5987 `filename*` form, since the plain parameter has no
+ *  encoding of its own. Both parameters are sent together on purpose — a
+ *  browser that understands `filename*` prefers it, and one that doesn't
+ *  still gets a usable ASCII name. */
+export function attachmentDisposition(filename) {
+    // Path separators and control characters never belong in a download name;
+    // a payload filename comes from whoever narrated it.
+    const safe = filename.replace(/[\\/]/g, "_").replace(CONTROL_CHARS, "") || "download";
+    // Backslashes are gone with the separators above, so a quote is the only
+    // character left that could end the quoted string early.
+    const quoted = safe.replace(/"/g, '\\"');
+    const ascii = /^[\x20-\x7e]*$/.test(safe);
+    return ascii
+        ? `attachment; filename="${quoted}"`
+        : `attachment; filename="${asciiFallback(safe)}"; filename*=UTF-8''${encodeRFC5987(safe)}`;
+}
+/** A best-effort ASCII name for the plain `filename` parameter. */
+function asciiFallback(name) {
+    const stripped = name.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
+    return stripped.replace(/^_+$/, "") || "download";
+}
+function encodeRFC5987(value) {
+    return encodeURIComponent(value).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+//# sourceMappingURL=payload-inline.js.map