brane 0.0.2 → 0.3.0

package/dist/test/hook-config.test.js

@@ -0,0 +1,262 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, existsSync, writeFileSync, mkdirSync, statSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTestDb } from "./helpers.js";
+import { ensureClaudeHookConfig, ensureGooseHookConfig, ensureClineHookConfig, ensureHookConfig, } from "../commands/spawn.js";
+const HOOK_PATH = "/api/hooks/tool-use";
+function seedDaemon(db, port, httpPort) {
+    const rows = [
+        ["daemon_port", port],
+        ["daemon_token", "tok"],
+        // Our own pid is alive, so getDaemonInfo's liveness check passes.
+        ["daemon_pid", String(process.pid)],
+    ];
+    // The http-fallback row only routes hooks when TLS is live (the row
+    // survives shutdown as a hint, so presence alone must not be trusted).
+    rows.push(["daemon_tls", httpPort ? "true" : "false"]);
+    if (httpPort)
+        rows.push(["daemon_http_port", httpPort]);
+    for (const [key, value] of rows) {
+        db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run(key, value);
+    }
+}
+function readSettings(fold) {
+    return JSON.parse(readFileSync(join(fold, ".claude", "settings.local.json"), "utf-8"));
+}
+describe("ensureClaudeHookConfig", () => {
+    it("writes a PostToolUse entry pointed at the daemon, capturing every tool", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureClaudeHookConfig(db, fold);
+        const entry = readSettings(fold).hooks.PostToolUse[0];
+        assert.equal(entry.hooks[0].url, `http://127.0.0.1:4321${HOOK_PATH}`);
+        // Nothing is excluded at the hook: what the client shows is a render
+        // decision, and a call the hook never saw can't be recovered later.
+        const matcher = new RegExp(entry.matcher);
+        assert.ok(matcher.test("Bash"), "ordinary tools must match");
+        assert.ok(matcher.test("mcp__brane__whoami"), "other brane tools are captured, filtered at render");
+        assert.ok(matcher.test("mcp__brane__listen"), "listen is captured — idle time is worth showing");
+        assert.ok(matcher.test("mcp__brane__narrate"), "narrate is captured — foreign narration is invisible otherwise");
+    });
+    // Both ends of every call: PostToolUse can only report a call once it's
+    // over, so the chat stays silent while a long tool runs.
+    it("registers the same entry on PreToolUse so a call is visible as it starts", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureClaudeHookConfig(db, fold);
+        const settings = readSettings(fold);
+        assert.deepEqual(settings.hooks.PreToolUse[0], settings.hooks.PostToolUse[0]);
+    });
+    it("prefers the HTTP fallback port when TLS is active", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321", "8888");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureClaudeHookConfig(db, fold);
+        const entry = readSettings(fold).hooks.PostToolUse[0];
+        assert.equal(entry.hooks[0].url, `http://127.0.0.1:8888${HOOK_PATH}`);
+    });
+    it("ignores a surviving daemon_http_port row when TLS is off", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        // The row outlives shutdown as a stability hint for the next TLS run —
+        // its presence alone must not route hooks to a port nothing listens on.
+        db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('daemon_http_port', '9999')").run();
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureClaudeHookConfig(db, fold);
+        const entry = readSettings(fold).hooks.PostToolUse[0];
+        assert.equal(entry.hooks[0].url, `http://127.0.0.1:4321${HOOK_PATH}`);
+    });
+    it("is idempotent and heals port drift in place", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureClaudeHookConfig(db, fold);
+        ensureClaudeHookConfig(db, fold);
+        assert.equal(readSettings(fold).hooks.PostToolUse.length, 1);
+        assert.equal(readSettings(fold).hooks.PreToolUse.length, 1);
+        seedDaemon(db, "5555");
+        ensureClaudeHookConfig(db, fold);
+        for (const event of ["PreToolUse", "PostToolUse"]) {
+            const entries = readSettings(fold).hooks[event];
+            assert.equal(entries.length, 1, `${event}: stale entry is replaced, not duplicated`);
+            assert.equal(entries[0].hooks[0].url, `http://127.0.0.1:5555${HOOK_PATH}`);
+        }
+    });
+    it("merges around the user's own settings and hooks instead of clobbering them", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        mkdirSync(join(fold, ".claude"), { recursive: true });
+        writeFileSync(join(fold, ".claude", "settings.local.json"), JSON.stringify({
+            permissions: { allow: ["Bash(ls:*)"] },
+            hooks: { PostToolUse: [{ matcher: "Edit", hooks: [{ type: "command", command: "echo hi" }] }] },
+        }));
+        ensureClaudeHookConfig(db, fold);
+        const settings = readSettings(fold);
+        assert.deepEqual(settings.permissions, { allow: ["Bash(ls:*)"] });
+        assert.equal(settings.hooks.PostToolUse.length, 2);
+        assert.equal(settings.hooks.PostToolUse[0].matcher, "Edit");
+    });
+    it("degrades silently when no daemon is running", () => {
+        const db = createTestDb();
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureClaudeHookConfig(db, fold);
+        assert.ok(!existsSync(join(fold, ".claude", "settings.local.json")));
+    });
+});
+// The other harnesses execute commands rather than speaking HTTP themselves,
+// so their "hook" is a script brane writes. What the script must not do is the
+// interesting part — see braneHookScript.
+describe("the hook script the non-Claude harnesses run", () => {
+    function scriptFor(agent, fold, nid, port = "4321") {
+        const db = createTestDb();
+        seedDaemon(db, port);
+        ensureHookConfig(db, agent, fold, nid);
+        return readFileSync(agent === "goose"
+            ? join(fold, ".agents", "plugins", "brane", "hooks", "report-tool-use.sh")
+            : join("/tmp", `brane-cline-${nid}`, "hooks", "PreToolUse"), "utf-8");
+    }
+    it("exits 0 whatever curl does, so recording never vetoes a tool call", () => {
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        const script = scriptFor("goose", fold, "claude-nid00001");
+        // In goose and crush a hook's exit code is a verdict: 2 blocks the call, and
+        // crush reads 49 as halt-the-turn. curl's own failures live in that space
+        // (7 refused, 28 timeout), so an escaping status would let a daemon restart
+        // cancel an agent's work.
+        assert.match(script, /\nexit 0\n/);
+        assert.doesNotMatch(script, /\bexec curl/, "exec would hand curl's status to the harness");
+    });
+    it("says nothing on stdout, which cline parses as control output", () => {
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        const script = scriptFor("cline", fold, "claude-nid00002");
+        assert.match(script, />\/dev\/null 2>&1/);
+    });
+    it("reads auth from the environment, never the daemon's bearer token", () => {
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        const script = scriptFor("goose", fold, "claude-nid00003");
+        assert.match(script, /X-Brane-Narrative-Id: \$\{BRANE_NARRATIVE_ID\}/);
+        assert.match(script, /X-Brane-Narrative-Secret: \$\{BRANE_NARRATIVE_SECRET\}/);
+        assert.doesNotMatch(script, /\btok\b/, "the daemon token must never reach disk");
+    });
+    it("is executable, and stays executable when it is rewritten", () => {
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        scriptFor("goose", fold, "claude-nid00004");
+        const path = join(fold, ".agents", "plugins", "brane", "hooks", "report-tool-use.sh");
+        assert.equal(statSync(path).mode & 0o111, 0o111, "a hook the harness cannot execute is no hook");
+        // writeFileSync's `mode` applies only on creation, so every rewrite after
+        // the first — a port drift, a change to the script — lands on an existing
+        // file and silently ignores it. A script that lost its execute bit would
+        // never get it back, and the harness would just stop running the hook.
+        chmodSync(path, 0o644);
+        const db = createTestDb();
+        seedDaemon(db, "5555");
+        ensureGooseHookConfig(db, fold);
+        assert.equal(statSync(path).mode & 0o111, 0o111, "the rewrite restores the execute bit");
+        // And the same is true when only the mode is wrong: an unchanged script
+        // must still be repaired rather than short-circuited as already current.
+        chmodSync(path, 0o644);
+        ensureGooseHookConfig(db, fold);
+        assert.equal(statSync(path).mode & 0o111, 0o111);
+    });
+});
+describe("ensureGooseHookConfig", () => {
+    const pluginHooks = (fold) => join(fold, ".agents", "plugins", "brane", "hooks");
+    it("writes an Open Plugins hooks.json wired to the script beside it", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureGooseHookConfig(db, fold);
+        const config = JSON.parse(readFileSync(join(pluginHooks(fold), "hooks.json"), "utf-8"));
+        const rule = config.hooks.PreToolUse[0];
+        assert.equal(rule.matcher, ".*");
+        assert.equal(rule.hooks[0].type, "command", "goose has no HTTP hook type");
+        assert.equal(rule.hooks[0].command, join(pluginHooks(fold), "report-tool-use.sh"));
+        assert.ok(existsSync(rule.hooks[0].command), "the command it names must exist");
+    });
+    // goose reports a failed call as its own event rather than as a field on the
+    // ordinary one — the plain PostToolUse never fires — so a tool that failed
+    // would sit pending forever without this.
+    it("registers PostToolUseFailure, or failures never complete", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureGooseHookConfig(db, fold);
+        const config = JSON.parse(readFileSync(join(pluginHooks(fold), "hooks.json"), "utf-8"));
+        assert.deepEqual(Object.keys(config.hooks).sort(), [
+            "PostToolUse",
+            "PostToolUseFailure",
+            "PreToolUse",
+        ]);
+    });
+    it("heals port drift in the script and is otherwise idempotent", () => {
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        ensureGooseHookConfig(db, fold);
+        const first = statSync(join(pluginHooks(fold), "report-tool-use.sh")).mtimeMs;
+        ensureGooseHookConfig(db, fold);
+        assert.equal(statSync(join(pluginHooks(fold), "report-tool-use.sh")).mtimeMs, first, "an unchanged script is left alone — this runs on every spawn and revive");
+        seedDaemon(db, "5555");
+        ensureGooseHookConfig(db, fold);
+        assert.match(readFileSync(join(pluginHooks(fold), "report-tool-use.sh"), "utf-8"), /127\.0\.0\.1:5555/);
+    });
+    it("prefers the HTTP fallback port when TLS is active", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321", "8080");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureGooseHookConfig(db, fold);
+        assert.match(readFileSync(join(pluginHooks(fold), "report-tool-use.sh"), "utf-8"), new RegExp(`http://127\\.0\\.0\\.1:8080${HOOK_PATH}`));
+    });
+    it("degrades silently when no daemon is running", () => {
+        const db = createTestDb();
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        ensureGooseHookConfig(db, fold);
+        assert.ok(!existsSync(join(fold, ".agents")));
+    });
+});
+describe("ensureClineHookConfig", () => {
+    it("names one script per event in the config dir brane already owns", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const nid = `claude-t${Math.floor(Date.now() % 1e6)}`;
+        ensureClineHookConfig(db, nid);
+        // cline discovers hooks by filename, and its hooks dir follows --config —
+        // which brane sets to this per-narrative directory. Nothing in the
+        // operator's fold is touched.
+        for (const event of ["PreToolUse", "PostToolUse"]) {
+            assert.ok(existsSync(join("/tmp", `brane-cline-${nid}`, "hooks", event)));
+        }
+    });
+    it("degrades silently when no daemon is running", () => {
+        const db = createTestDb();
+        const nid = `claude-u${Math.floor(Date.now() % 1e6)}`;
+        ensureClineHookConfig(db, nid);
+        assert.ok(!existsSync(join("/tmp", `brane-cline-${nid}`, "hooks")));
+    });
+});
+describe("ensureHookConfig", () => {
+    it("installs nothing for an agent with no capture path", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        const fold = mkdtempSync(join(tmpdir(), "brane-hook-"));
+        // crush has a PreToolUse hook but no PostToolUse event, and its pre payload
+        // carries no call id to pair the halves with — so a hook here would strand
+        // every call pending. Its completions come from its session log instead.
+        for (const agent of ["crush", "codex", "gemini", "amp", "copilot"]) {
+            ensureHookConfig(db, agent, fold, "claude-nid00005");
+        }
+        assert.ok(!existsSync(join(fold, ".claude")));
+        assert.ok(!existsSync(join(fold, ".agents")));
+    });
+    it("never throws — capture is optional and must not fail a spawn", () => {
+        const db = createTestDb();
+        seedDaemon(db, "4321");
+        // A fold path that cannot be written to: the spawn still has to proceed.
+        assert.doesNotThrow(() => ensureHookConfig(db, "goose", "/dev/null/nope", "claude-nid00006"));
+    });
+});
+//# sourceMappingURL=hook-config.test.js.map

package/dist/test/json-gzip.test.js

@@ -0,0 +1,70 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { sendJson, trackRequest } from "../daemon/server.js";
+/** The daemon's JSON responses go out through one function, and until now
+ *  nothing tested it — `daemon-client.test.ts` stands up a *stub* server to
+ *  exercise the CLI side, so the real handler had no HTTP coverage at all
+ *  (claude-n1izig04:78). These tests drive the actual `sendJson` over a real
+ *  socket, because content negotiation is exactly the kind of thing that looks
+ *  right in review and is wrong on the wire. */
+describe("sendJson content negotiation", () => {
+    let server;
+    let base;
+    // Comfortably past the compress-it threshold, and repetitive enough that a
+    // failure to compress is unmistakable in the numbers.
+    const big = { rows: Array.from({ length: 400 }, (_, i) => ({ i, text: "brane ".repeat(20) })) };
+    const small = { ok: true };
+    before(async () => {
+        server = createServer((req, res) => {
+            trackRequest(res, req);
+            sendJson(res, 200, req.url === "/small" ? small : big);
+        });
+        await new Promise((r) => server.listen(0, "127.0.0.1", r));
+        base = `http://127.0.0.1:${server.address().port}`;
+    });
+    after(() => server.close());
+    it("gzips a large body for a client that accepts it, byte-identical after decoding", async () => {
+        const res = await fetch(`${base}/big`, { headers: { "accept-encoding": "gzip" } });
+        assert.equal(res.headers.get("content-encoding"), "gzip");
+        // Undici decodes transparently, so equality here proves the round trip.
+        assert.deepEqual(await res.json(), big);
+    });
+    it("sets Vary, so a cache can't hand a gzipped body to a client that can't read it", async () => {
+        const res = await fetch(`${base}/big`, { headers: { "accept-encoding": "gzip" } });
+        assert.equal(res.headers.get("vary"), "Accept-Encoding");
+        await res.arrayBuffer();
+    });
+    it("sends plain when the client didn't offer gzip", async () => {
+        const res = await fetch(`${base}/big`, { headers: { "accept-encoding": "identity" } });
+        assert.equal(res.headers.get("content-encoding"), null);
+        assert.deepEqual(await res.json(), big);
+    });
+    it("leaves a small body alone — the header costs more than the saving", async () => {
+        const res = await fetch(`${base}/small`, { headers: { "accept-encoding": "gzip" } });
+        assert.equal(res.headers.get("content-encoding"), null);
+        assert.deepEqual(await res.json(), small);
+    });
+    it("actually shrinks the bytes on the wire", async () => {
+        const [zipped, plain] = await Promise.all([
+            fetch(`${base}/big`, { headers: { "accept-encoding": "gzip" } }),
+            fetch(`${base}/big`, { headers: { "accept-encoding": "identity" } }),
+        ]);
+        // Undici decodes the gzip stream before handing it over, so the honest
+        // measure is what the server declared it was sending, not what the client
+        // ended up holding.
+        const zippedBytes = Number(zipped.headers.get("content-length"));
+        const plainBytes = Number(plain.headers.get("content-length"));
+        await Promise.all([zipped.arrayBuffer(), plain.arrayBuffer()]);
+        assert.ok(plainBytes > 10_000, `sanity: plain body was ${plainBytes} bytes`);
+        assert.ok(zippedBytes * 5 < plainBytes, `expected a real saving, got ${zippedBytes} vs ${plainBytes} bytes`);
+    });
+    it("gzips regardless of how the client spells its accept-encoding", async () => {
+        for (const header of ["gzip", "gzip, deflate", "deflate, gzip;q=1.0, *;q=0.5", "GZIP"]) {
+            const res = await fetch(`${base}/big`, { headers: { "accept-encoding": header } });
+            assert.equal(res.headers.get("content-encoding"), "gzip", `for "${header}"`);
+            await res.arrayBuffer();
+        }
+    });
+});
+//# sourceMappingURL=json-gzip.test.js.map

package/dist/test/key-routing.test.js

@@ -0,0 +1,58 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// Keystrokes in the web app are routed by ONE rule: the foreground route's
+// green tab owns the keyboard. Two document-level keydown listeners implement
+// it — the terminal's (TerminalPane.tsx) and the chat composer's funnel
+// ([nid].tsx) — and Expo Router keeps every visited [nid] screen mounted under
+// the top of the stack, so a listener gated only on its own screen's tab state
+// hears keys typed into a DIFFERENT narrative. #342 gated the terminal on
+// useIsFocused(); the chat funnel predates it and was never gated, which is
+// how typing into one narrative's terminal filled another narrative's
+// composer. This test reads the source because the failure is invisible on a
+// single-narrative page: it only reproduces with two screens on the stack.
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const read = (rel) => readFileSync(join(repoRoot, rel), "utf8");
+// These tests lint source the tarball doesn't ship (`expo/dist/` ships, the
+// `.tsx` doesn't). From an installed package — `brane doctor` — they skip
+// with a reason instead of failing on ENOENT.
+const sourceMissing = !existsSync(join(repoRoot, "expo", "app", "[nid].tsx"));
+const skip = sourceMissing ? "expo source not shipped" : false;
+const LISTENERS = [
+    { file: "expo/app/[nid].tsx", gate: "chatActiveRef.current" },
+    { file: "expo/components/TerminalPane.tsx", gate: "isFocusedRef.current" },
+    // The narrative list's scroll keys. It isn't a [nid] screen, but it sits
+    // under every one of them on the stack, so an ungated listener would scroll
+    // the hidden list while the operator pages through a chat.
+    { file: "expo/app/index.tsx", gate: "listOwnsKeysRef.current" },
+];
+describe("document-level keydown listeners are gated on route focus", () => {
+    for (const { file, gate } of LISTENERS) {
+        test(file, { skip }, () => {
+            const src = read(file);
+            assert.match(src, /useIsFocused\(\)/, `${file} must read useIsFocused()`);
+            const sites = [...src.matchAll(/document\.addEventListener\("keydown", (\w+)\)/g)];
+            assert.ok(sites.length > 0, `${file} should register a keydown listener`);
+            for (const m of sites) {
+                const name = m[1];
+                // Find the handler's body and require that it checks the route-focus
+                // ref before doing anything with the key.
+                const decl = src.indexOf(`const ${name} = (e: KeyboardEvent) => {`);
+                assert.notEqual(decl, -1, `handler ${name} not found in ${file}`);
+                const body = src.slice(decl, src.indexOf("document.addEventListener", decl));
+                // `if (!gate) return;` or `if (!x || !gate) return;` — either way the
+                // key is dropped before it is forwarded anywhere.
+                const bail = new RegExp(`if \\(([^)]*\\|\\| )?!${gate.replace(".", "\\.")}\\) return;`);
+                assert.match(body, bail, `${file}: keydown handler ${name} must bail when !${gate}`);
+            }
+        });
+    }
+    test("the chat gate carries route focus, not just the tab", { skip }, () => {
+        const src = read("expo/app/[nid].tsx");
+        assert.match(src, /const chatOwnsKeys = chatActive && isFocused;/);
+        assert.match(src, /chatActiveRef\.current = chatOwnsKeys;/);
+    });
+});
+//# sourceMappingURL=key-routing.test.js.map

package/dist/test/known-nids.test.js

@@ -0,0 +1,106 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmAutolinkLiteral } from "micromark-extension-gfm-autolink-literal";
+import { gfmAutolinkLiteralFromMarkdown } from "mdast-util-gfm-autolink-literal";
+import { narrativeIdLinks } from "../shared/markdown-nids.js";
+import { collectKnownNids } from "../shared/known-nids.js";
+// The bug these are written against, reproduced from a real report:
+//
+//   A twin's first message read "/twin from claude-l4qmxmpb:40" and did not
+//   linkify. Neither did the `crush-ci2eu0eb:N` references in its own bubble
+//   headers. `/review` in the very next message linkified fine.
+//
+// Nothing was wrong with the parser. The operator was on a slow network, the
+// one fetch that filled `knownNarrativeIds` failed, its rejection was
+// swallowed, the effect could not re-fire, and an empty set makes every
+// reference on the screen silently stop being a link.
+//
+// A parser test could never have caught that — the parser was right. What was
+// needed is a test of *where the ids come from*, which is why that decision now
+// lives in a module of its own.
+const VIEWING = "crush-ci2eu0eb";
+const PREDECESSOR = "claude-l4qmxmpb";
+const ALL = [{ id: VIEWING }, { id: PREDECESSOR }, { id: "goose-aa11bb22" }];
+/** The screen's markdown pipeline, over whatever ids it managed to collect. */
+function linksFor(md, known) {
+    const tree = fromMarkdown(md, {
+        extensions: [gfmAutolinkLiteral()],
+        mdastExtensions: [gfmAutolinkLiteralFromMarkdown(), narrativeIdLinks(known)],
+    });
+    const out = [];
+    const walk = (n) => {
+        if (n.type === "link") {
+            out.push(n.url);
+            return;
+        }
+        for (const c of n.children ?? [])
+            walk(c);
+    };
+    walk(tree);
+    return out;
+}
+describe("linkification survives the fetch that feeds it", () => {
+    it("still links when the list sweep never arrives — the reported bug", () => {
+        // Exactly the failure: `listed` is the request that died on a slow link.
+        const known = collectKnownNids({ viewing: VIEWING, pushed: ALL, listed: null });
+        assert.deepEqual(linksFor("/twin from claude-l4qmxmpb:40", known), [
+            "brane://nid/claude-l4qmxmpb/40",
+        ]);
+        assert.deepEqual(linksFor("see crush-ci2eu0eb:2", known), ["brane://nid/crush-ci2eu0eb/2"]);
+    });
+    it("links the narrative you are looking at even with no network at all", () => {
+        // The floor. The route param needs no request, so a reference to the
+        // narrative on screen can never be a dead link.
+        const known = collectKnownNids({ viewing: VIEWING, pushed: null, listed: null });
+        assert.deepEqual(linksFor("see crush-ci2eu0eb:2", known), ["brane://nid/crush-ci2eu0eb/2"]);
+    });
+    it("degrades rather than switching off", () => {
+        // The property the whole module exists for: losing a source costs you the
+        // ids only that source had, never the ones you already held.
+        const full = collectKnownNids({ viewing: VIEWING, pushed: ALL, listed: ALL });
+        const degraded = collectKnownNids({ viewing: VIEWING, pushed: null, listed: null });
+        assert.ok(degraded.size > 0, "a screen with no completed fetch must still link something");
+        for (const id of degraded) {
+            assert.ok(full.has(id), `${id} appeared only when sources were missing`);
+        }
+    });
+    it("does not link a well-shaped id nobody has heard of", () => {
+        // The degradation must not become permissiveness: the existence check is
+        // what stops arbitrary strings of that shape becoming dead links.
+        const known = collectKnownNids({ viewing: VIEWING, pushed: ALL, listed: ALL });
+        assert.deepEqual(linksFor("claude-deadbeef never existed", known), []);
+    });
+});
+describe("collectKnownNids", () => {
+    it("unions its sources rather than preferring one", () => {
+        // Each covers the other's gap: the `state` frame is a snapshot from connect
+        // and misses later spawns; the list sweep is a moment behind.
+        const known = collectKnownNids({
+            pushed: [{ id: "claude-11111111" }],
+            listed: [{ id: "claude-22222222" }],
+            viewing: "claude-33333333",
+        });
+        assert.deepEqual([...known].sort(), ["claude-11111111", "claude-22222222", "claude-33333333"]);
+    });
+    it("survives every source being absent, null, or empty", () => {
+        assert.equal(collectKnownNids({}).size, 0);
+        assert.equal(collectKnownNids({ viewing: null, pushed: null, listed: null }).size, 0);
+        assert.equal(collectKnownNids({ viewing: "", pushed: [], listed: [] }).size, 0);
+    });
+    it("ignores entries without a usable id", () => {
+        const known = collectKnownNids({
+            listed: [{ id: "" }, { id: undefined }, null, { id: "claude-44444444" }],
+        });
+        assert.deepEqual([...known], ["claude-44444444"]);
+    });
+    it("dedups across sources", () => {
+        const known = collectKnownNids({
+            viewing: VIEWING,
+            pushed: [{ id: VIEWING }],
+            listed: [{ id: VIEWING }],
+        });
+        assert.equal(known.size, 1);
+    });
+});
+//# sourceMappingURL=known-nids.test.js.map

package/dist/test/link-preview.test.js

@@ -0,0 +1,67 @@
+// The link preview card is three files that have to agree: the served HTML
+// (expo/public/index.html), its kept-in-step copy (expo/app/+html.tsx), and
+// the image the tags name. An unfurler that follows the og:image URL to a
+// 404, or reads a declared size the PNG doesn't have, shows no card at all —
+// and nothing in a local build would notice. This pins the agreement.
+//
+// Reads source, so it skips from an install, where expo/ is not shipped —
+// the same arrangement as api-request.test.ts.
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const publicDir = join(repoRoot, "expo", "public");
+const servedPath = join(publicDir, "index.html");
+const templatePath = join(repoRoot, "expo", "app", "+html.tsx");
+const layoutPath = join(repoRoot, "expo", "app", "_layout.tsx");
+const SHARED_HOST = "https://brane.organelle.dev";
+function tag(html, attr, key) {
+    const m = html.match(new RegExp(`<(?:meta|link)[^>]*\\b${attr}="${key}"[^>]*\\b(?:content|href)="([^"]*)"`));
+    return m?.[1];
+}
+/** Width and height from a PNG's IHDR chunk, which always follows the
+ *  8-byte signature: length(4) "IHDR"(4) width(4) height(4). */
+function pngSize(file) {
+    const b = readFileSync(file);
+    assert.equal(b.subarray(1, 4).toString("latin1"), "PNG", `${file} is not a PNG`);
+    return [b.readUInt32BE(16), b.readUInt32BE(20)];
+}
+describe("the link preview card", { skip: existsSync(servedPath) ? false : "expo source not shipped" }, () => {
+    const served = existsSync(servedPath) ? readFileSync(servedPath, "utf8") : "";
+    const template = existsSync(templatePath) ? readFileSync(templatePath, "utf8") : "";
+    const layout = existsSync(layoutPath) ? readFileSync(layoutPath, "utf8") : "";
+    test("the served HTML and its template carry the same card", () => {
+        for (const key of ["og:site_name", "og:title", "og:description", "og:image", "og:image:width", "og:image:height", "og:image:alt"]) {
+            assert.ok(tag(served, "property", key), `public/index.html lacks ${key}`);
+            assert.equal(tag(template, "property", key), tag(served, "property", key), `${key} differs in +html.tsx`);
+        }
+        assert.equal(tag(served, "name", "twitter:card"), "summary_large_image");
+        assert.equal(tag(template, "name", "twitter:card"), tag(served, "name", "twitter:card"));
+    });
+    test("og:image is absolute on the shared host, and names a file public/ ships at the declared size", () => {
+        const url = tag(served, "property", "og:image");
+        assert.ok(url.startsWith(`${SHARED_HOST}/`), `og:image must be absolute on ${SHARED_HOST}: ${url}`);
+        const file = join(publicDir, url.slice(SHARED_HOST.length + 1));
+        assert.ok(existsSync(file), `og:image points at ${file}, which does not exist`);
+        const [w, h] = pngSize(file);
+        assert.equal(String(w), tag(served, "property", "og:image:width"));
+        assert.equal(String(h), tag(served, "property", "og:image:height"));
+        // 1200×630 is the size every unfurler renders as a large card; smaller
+        // falls back to a thumbnail on some and to nothing on others.
+        assert.ok(w >= 1200 && h >= 630, `og:image is ${w}×${h}, below 1200×630`);
+    });
+    test("og:image is versioned, because iMessage caches a preview by URL", () => {
+        const url = tag(served, "property", "og:image");
+        assert.match(url, /\.v\d+\.png$/, `expected a .v<N>.png name: ${url}`);
+    });
+    test("the touch icon is linked from all three heads and is 180×180", () => {
+        const href = tag(served, "rel", "apple-touch-icon");
+        assert.equal(href, "/apple-touch-icon.png");
+        assert.equal(tag(template, "rel", "apple-touch-icon"), href);
+        assert.equal(tag(layout, "rel", "apple-touch-icon"), href);
+        assert.deepEqual(pngSize(join(publicDir, href.slice(1))), [180, 180]);
+    });
+});
+//# sourceMappingURL=link-preview.test.js.map

package/dist/test/list-scroll-keys.test.js

@@ -0,0 +1,66 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ARROW_STEP_PX, PAGE_FRACTION, isListScrollKey, listScrollTarget, } from "../shared/list-scroll-keys.js";
+// The narrative list scrolls itself for the browser's scroll keys when nothing
+// in it has focus. These tests pin the arithmetic. The routing (route focus,
+// modals, editables) is pinned in key-routing.test.ts.
+const bare = { metaKey: false, ctrlKey: false, altKey: false, shiftKey: false };
+const list = { clientHeight: 800, scrollHeight: 5000 }; // max scrollTop 4200
+describe("isListScrollKey", () => {
+    it("takes the six unmodified scroll keys", () => {
+        for (const key of ["PageUp", "PageDown", "Home", "End", "ArrowUp", "ArrowDown"]) {
+            assert.equal(isListScrollKey({ key, ...bare }), true, key);
+        }
+    });
+    it("leaves other keys alone", () => {
+        for (const key of ["ArrowLeft", "ArrowRight", " ", "a", "Enter", "Escape", "Tab"]) {
+            assert.equal(isListScrollKey({ key, ...bare }), false, JSON.stringify(key));
+        }
+    });
+    it("leaves modified scroll keys to the browser and OS", () => {
+        for (const mod of ["metaKey", "ctrlKey", "altKey", "shiftKey"]) {
+            assert.equal(isListScrollKey({ key: "ArrowDown", ...bare, [mod]: true }), false, mod);
+        }
+    });
+});
+describe("listScrollTarget", () => {
+    it("steps an arrow's worth", () => {
+        assert.equal(listScrollTarget("ArrowDown", 1000, list), 1000 + ARROW_STEP_PX);
+        assert.equal(listScrollTarget("ArrowUp", 1000, list), 1000 - ARROW_STEP_PX);
+    });
+    it("pages by most of the visible height, so a line of the old page stays", () => {
+        const page = 800 * PAGE_FRACTION;
+        assert.ok(page < 800);
+        assert.equal(listScrollTarget("PageDown", 1000, list), 1000 + page);
+        assert.equal(listScrollTarget("PageUp", 1000, list), 1000 - page);
+    });
+    it("jumps to the ends", () => {
+        assert.equal(listScrollTarget("Home", 1234, list), 0);
+        assert.equal(listScrollTarget("End", 1234, list), 4200);
+    });
+    it("clamps to the scrollable range", () => {
+        assert.equal(listScrollTarget("ArrowUp", 10, list), 0);
+        assert.equal(listScrollTarget("PageUp", 0, list), 0);
+        assert.equal(listScrollTarget("PageDown", 4000, list), 4200);
+        assert.equal(listScrollTarget("ArrowDown", 4200, list), 4200);
+    });
+    it("stays at 0 when the content fits", () => {
+        const short = { clientHeight: 800, scrollHeight: 300 };
+        for (const key of ["PageDown", "End", "ArrowDown", "PageUp", "Home"]) {
+            assert.equal(listScrollTarget(key, 0, short), 0, key);
+        }
+    });
+    it("stacks presses from the pending target, not the mid-glide position", () => {
+        // A smooth PageDown from 0 is heading for one page down and has covered a
+        // third of it when the second press lands. Starting from the target lands
+        // two full pages down, which is what two presses mean.
+        const page = 800 * PAGE_FRACTION;
+        const first = listScrollTarget("PageDown", 0, list);
+        assert.equal(listScrollTarget("PageDown", first, list), 2 * page);
+    });
+    it("returns null for keys that don't scroll", () => {
+        assert.equal(listScrollTarget("ArrowLeft", 100, list), null);
+        assert.equal(listScrollTarget("x", 100, list), null);
+    });
+});
+//# sourceMappingURL=list-scroll-keys.test.js.map