brane 0.1.1 → 0.3.1

package/dist/test/harness-cost.test.js

@@ -0,0 +1,423 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+import { createTestDb } from "./helpers.js";
+import { discoverGooseSession, readGooseUsage, discoverCrushSession, readCrushUsage, readClineSessionUsage, readCopilotUsage, getAgentAdapter, } from "../agents.js";
+import { maybeCaptureSessionId, getSessionIds } from "../daemon/server.js";
+import { priceMessage } from "../cost/pricing.js";
+const scratch = () => mkdtempSync(join(tmpdir(), "brane-harness-cost-"));
+// ---------------------------------------------------------------------------
+// Pricing
+// ---------------------------------------------------------------------------
+describe("Fireworks K3 pricing", () => {
+    const oneMEach = {
+        input: 1e6,
+        output: 1e6,
+        cacheRead: 0,
+        cacheWrite5m: 0,
+        cacheWrite1h: 0,
+    };
+    it("resolves the fast router to the fast tier, not the base tier", () => {
+        // Regression guard for the table's insertion order: priceForModel returns
+        // the FIRST substring hit, and "accounts/fireworks/routers/kimi-k3-fast"
+        // contains "kimi-k3" too. Listed the wrong way round this silently prices
+        // the fast router a third cheap, with nothing to notice it by.
+        assert.equal(priceMessage("accounts/fireworks/routers/kimi-k3-fast", oneMEach), 4.5 + 22.5);
+        assert.equal(priceMessage("accounts/fireworks/models/kimi-k3", oneMEach), 3 + 15);
+    });
+    it("prices cached input at Fireworks' 0.1x rate", () => {
+        const cacheOnly = {
+            input: 0,
+            output: 0,
+            cacheRead: 1e6,
+            cacheWrite5m: 0,
+            cacheWrite1h: 0,
+        };
+        // $0.30/M against a $3.00/M input price.
+        assert.equal(priceMessage("accounts/fireworks/models/kimi-k3", cacheOnly), 0.3);
+    });
+});
+// ---------------------------------------------------------------------------
+// goose — one shared SQLite store, a usage ledger brane has to price itself
+// ---------------------------------------------------------------------------
+function gooseFixture() {
+    const path = join(scratch(), "sessions.db");
+    const db = new Database(path);
+    db.exec(`
+    CREATE TABLE sessions (
+      id TEXT PRIMARY KEY, name TEXT NOT NULL DEFAULT '', working_dir TEXT NOT NULL,
+      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE TABLE usage_ledger (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL,
+      created_timestamp INTEGER NOT NULL, model TEXT,
+      input_tokens INTEGER, output_tokens INTEGER, total_tokens INTEGER,
+      cache_read_tokens INTEGER, cache_write_tokens INTEGER,
+      cost REAL, cost_source TEXT, is_compaction INTEGER DEFAULT 0
+    );
+  `);
+    const sess = db.prepare("INSERT INTO sessions (id, name, working_dir, created_at) VALUES (?,?,?,?)");
+    sess.run("20260816_1", "goose-alpha", "/work/fold", "2026-08-16 15:00:00");
+    sess.run("20260816_2", "goose-beta", "/work/fold", "2026-08-16 15:25:32");
+    // A second row sharing goose-alpha's name, created later — `name` carries no
+    // UNIQUE constraint, so newest must win.
+    sess.run("20260817_1", "goose-alpha", "/work/fold", "2026-08-17 09:00:00");
+    const led = db.prepare(`INSERT INTO usage_ledger
+       (session_id, created_timestamp, model, input_tokens, output_tokens,
+        cache_read_tokens, cache_write_tokens, cost, cost_source, is_compaction)
+     VALUES (?,?,?,?,?,?,?,NULL,NULL,?)`);
+    // input_tokens is INCLUSIVE of cache_read_tokens, as goose records it.
+    led.run("20260816_2", 1, "accounts/fireworks/models/kimi-k3", 100_000, 1_000, 90_000, 0, 0);
+    led.run("20260816_2", 2, "accounts/fireworks/models/kimi-k3", 50_000, 500, 40_000, 0, 1); // compaction
+    led.run("20260816_2", 3, "accounts/fireworks/routers/kimi-k3-fast", 10_000, 200, 0, 0, 0);
+    db.close();
+    return path;
+}
+describe("goose session discovery", () => {
+    it("looks the session up by the narrative id brane launched it under", () => {
+        const path = gooseFixture();
+        assert.equal(discoverGooseSession(path, "goose-beta"), "20260816_2");
+    });
+    it("takes the newest row when a name somehow repeats", () => {
+        const path = gooseFixture();
+        assert.equal(discoverGooseSession(path, "goose-alpha"), "20260817_1");
+    });
+    it("returns undefined for an unknown narrative or an unreadable store", () => {
+        const path = gooseFixture();
+        assert.equal(discoverGooseSession(path, "goose-nobody"), undefined);
+        assert.equal(discoverGooseSession(join(scratch(), "absent.db"), "goose-beta"), undefined);
+    });
+});
+describe("goose usage reading", () => {
+    it("prices the ledger, subtracting cache reads out of the inclusive input", () => {
+        const reading = readGooseUsage(gooseFixture(), "20260816_2");
+        // Rows 1+2 are base-tier kimi-k3, row 3 is the fast router — priced
+        // separately because the reader groups by model.
+        const base = priceMessage("accounts/fireworks/models/kimi-k3", {
+            input: 100_000 - 90_000 + (50_000 - 40_000),
+            output: 1_500,
+            cacheRead: 130_000,
+            cacheWrite5m: 0,
+            cacheWrite1h: 0,
+        });
+        const fast = priceMessage("accounts/fireworks/routers/kimi-k3-fast", {
+            input: 10_000,
+            output: 200,
+            cacheRead: 0,
+            cacheWrite5m: 0,
+            cacheWrite1h: 0,
+        });
+        assert.equal(reading.amount, Math.round((base + fast) * 1e4) / 1e4);
+        assert.equal(reading.unit, "USD");
+    });
+    it("counts compaction rows — they are real spend", () => {
+        // Row 2 is the only is_compaction row; dropping it would cost this much.
+        const reading = readGooseUsage(gooseFixture(), "20260816_2");
+        const withoutCompaction = priceMessage("accounts/fireworks/models/kimi-k3", {
+            input: 10_000,
+            output: 500,
+            cacheRead: 40_000,
+            cacheWrite5m: 0,
+            cacheWrite1h: 0,
+        });
+        assert.ok(withoutCompaction > 0);
+        assert.ok(reading.amount > withoutCompaction);
+    });
+    it("reports goose's own inclusive input count in the token breakdown", () => {
+        const reading = readGooseUsage(gooseFixture(), "20260816_2");
+        assert.deepEqual(reading.tokens, {
+            input: 160_000,
+            output: 1_700,
+            cacheRead: 130_000,
+            cacheWrite: 0,
+        });
+    });
+    it("returns null for an unknown session and a missing database", () => {
+        const path = gooseFixture();
+        assert.equal(readGooseUsage(path, "no-such-session"), null);
+        assert.equal(readGooseUsage(join(scratch(), "absent.db"), "20260816_2"), null);
+    });
+});
+// ---------------------------------------------------------------------------
+// copilot — one local SQLite store with nano-AIU billing
+// ---------------------------------------------------------------------------
+function copilotFixture() {
+    const path = join(scratch(), "session-store.db");
+    const db = new Database(path);
+    db.exec(`
+    CREATE TABLE assistant_usage_events (
+      session_id TEXT NOT NULL, input_tokens INTEGER, output_tokens INTEGER,
+      cache_read_tokens INTEGER, cache_write_tokens INTEGER, total_nano_aiu INTEGER
+    );
+  `);
+    const usage = db.prepare("INSERT INTO assistant_usage_events VALUES (?, ?, ?, ?, ?, ?)");
+    usage.run("copilot-1", 100, 20, 80, 5, 1_250_000_000);
+    usage.run("copilot-1", 200, 30, 150, 10, 2_500_000_000);
+    db.close();
+    return path;
+}
+describe("copilot usage", () => {
+    it("converts nano AIU to AIC and retains Copilot's token breakdown", () => {
+        assert.deepEqual(readCopilotUsage(copilotFixture(), "copilot-1"), {
+            amount: 3.75,
+            unit: "AIC",
+            tokens: { input: 300, output: 50, cacheRead: 230, cacheWrite: 15 },
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// crush — per-fold store, cost pre-computed by the harness, second-precision
+// ---------------------------------------------------------------------------
+const SPAWN_MS = 1786899518031; // narrative created_at, milliseconds
+const SPAWN_S = 1786899518;
+function crushFixture(createdAt = (s) => s) {
+    const path = join(scratch(), "crush.db");
+    const db = new Database(path);
+    db.exec(`
+    CREATE TABLE sessions (
+      id TEXT PRIMARY KEY, parent_session_id TEXT, title TEXT NOT NULL,
+      message_count INTEGER NOT NULL DEFAULT 0,
+      prompt_tokens INTEGER NOT NULL DEFAULT 0,
+      completion_tokens INTEGER NOT NULL DEFAULT 0,
+      cost REAL NOT NULL DEFAULT 0.0,
+      updated_at INTEGER NOT NULL, created_at INTEGER NOT NULL
+    );
+  `);
+    const ins = db.prepare("INSERT INTO sessions (id, parent_session_id, title, prompt_tokens, completion_tokens, cost, updated_at, created_at) VALUES (?,?,?,?,?,?,?,?)");
+    const at = (s) => createdAt(s);
+    // Predates the spawn — a previous narrative sharing this fold.
+    ins.run("older-session", null, "old", 10, 10, 9.99, at(SPAWN_S - 500), at(SPAWN_S - 500));
+    // Ours.
+    ins.run("real-session", null, "ours", 67422, 118, 1.25, at(SPAWN_S + 2), at(SPAWN_S + 2));
+    // Synthetic children of ours: an agent-tool session and a title generator.
+    ins.run("abc$$agentic_fetch_68", "real-session", "sub", 19960, 1335, 0.5, at(SPAWN_S + 9), at(SPAWN_S + 9));
+    ins.run("title-real-session", null, "titler", 100, 20, 0.25, at(SPAWN_S + 3), at(SPAWN_S + 3));
+    // A later unrelated session in the same fold.
+    ins.run("newer-session", null, "later", 5, 5, 7.5, at(SPAWN_S + 9999), at(SPAWN_S + 9999));
+    db.close();
+    return path;
+}
+describe("crush session discovery", () => {
+    it("normalizes a millisecond `since` against crush's second-precision column", () => {
+        // The trap this exists for: crush's schema annotates created_at as
+        // milliseconds but writes seconds, so comparing the narrative's ms spawn
+        // time directly matches nothing at all — forever, and silently.
+        assert.equal(discoverCrushSession(crushFixture(), SPAWN_MS), "real-session");
+    });
+    it("works too if crush ever starts honouring its own millisecond comment", () => {
+        assert.equal(discoverCrushSession(crushFixture((s) => s * 1000), SPAWN_MS), "real-session");
+    });
+    it("takes the earliest session after the spawn, not the newest in the fold", () => {
+        assert.equal(discoverCrushSession(crushFixture(), SPAWN_MS), "real-session");
+    });
+    it("skips crush's synthetic title and agent-tool session rows", () => {
+        // With `since` dropped, the earliest real row wins and neither the
+        // `title-` nor the `$$` row is ever a candidate.
+        assert.equal(discoverCrushSession(crushFixture()), "older-session");
+    });
+    it("returns undefined when nothing started after the spawn, or the db is absent", () => {
+        assert.equal(discoverCrushSession(crushFixture(), (SPAWN_S + 99999) * 1000), undefined);
+        assert.equal(discoverCrushSession(join(scratch(), "absent.db"), SPAWN_MS), undefined);
+    });
+});
+describe("crush usage reading", () => {
+    it("sums the session's own cost with its agent-tool and title children", () => {
+        const reading = readCrushUsage(crushFixture(), "real-session");
+        assert.equal(reading.amount, 1.25 + 0.5 + 0.25);
+        assert.equal(reading.unit, "USD");
+    });
+    it("omits tokens — crush's columns are last-request snapshots, not totals", () => {
+        // prompt_tokens/completion_tokens are overwritten per request to gauge
+        // context size, so surfacing them as a session total would be a lie.
+        assert.equal(readCrushUsage(crushFixture(), "real-session").tokens, undefined);
+    });
+    it("reports a genuine $0 rather than null when the model is unpriced", () => {
+        // Crush defaults a custom provider's models to zero cost, so $0 means
+        // "config declares no rates", which is different from "unreadable".
+        const path = join(scratch(), "crush.db");
+        const db = new Database(path);
+        db.exec("CREATE TABLE sessions (id TEXT PRIMARY KEY, parent_session_id TEXT, cost REAL NOT NULL DEFAULT 0.0, created_at INTEGER NOT NULL)");
+        db.prepare("INSERT INTO sessions (id, parent_session_id, cost, created_at) VALUES ('s',NULL,0.0,1)").run();
+        db.close();
+        assert.deepEqual(readCrushUsage(path, "s"), { amount: 0, unit: "USD" });
+    });
+    it("returns null for an unknown session and a missing database", () => {
+        assert.equal(readCrushUsage(crushFixture(), "no-such-session"), null);
+        assert.equal(readCrushUsage(join(scratch(), "absent.db"), "real-session"), null);
+    });
+});
+// ---------------------------------------------------------------------------
+// cline — per-narrative store, cost pre-computed per message
+// ---------------------------------------------------------------------------
+function clineLog(dir, sessionId, messages) {
+    const sdir = join(dir, sessionId);
+    mkdirSync(sdir, { recursive: true });
+    const file = join(sdir, `${sessionId}.messages.json`);
+    writeFileSync(file, JSON.stringify({ sessionId, messages }));
+    return file;
+}
+const msg = (id, cost, input = 100, output = 10, cacheRead = 0) => ({
+    id,
+    role: "assistant",
+    metrics: { cost, inputTokens: input, outputTokens: output, cacheReadTokens: cacheRead, cacheWriteTokens: 0 },
+});
+describe("cline usage reading", () => {
+    it("sums per-message cost and the full token breakdown", () => {
+        const file = clineLog(scratch(), "1786899559349_f9dpo", [
+            { id: "u1", role: "user" }, // no metrics — skipped
+            msg("m1", 0.25, 1000, 30, 900),
+            msg("m2", 0.5, 2000, 40, 1800),
+        ]);
+        assert.deepEqual(readClineSessionUsage(file), {
+            amount: 0.75,
+            unit: "USD",
+            tokens: { input: 3000, output: 70, cacheRead: 2700, cacheWrite: 0 },
+        });
+    });
+    it("counts an errored turn's cost, which metadata.totalCost would drop", () => {
+        // Cline accumulates metadata.totalCost only on the turn-success path, so a
+        // session with a failed turn persists that message's metrics but not its
+        // cost. Summing the messages is what makes the badge whole.
+        const file = clineLog(scratch(), "sess-err", [msg("ok", 0.25), msg("failed", 0.28)]);
+        assert.equal(readClineSessionUsage(file).amount, 0.53);
+    });
+    it("dedupes a message id repeated within one file", () => {
+        const file = clineLog(scratch(), "sess-dup", [msg("m1", 0.25), msg("m1", 0.25), msg("m2", 0.5)]);
+        assert.equal(readClineSessionUsage(file).amount, 0.75);
+    });
+    it("returns null for a missing or malformed log", () => {
+        const dir = scratch();
+        assert.equal(readClineSessionUsage(join(dir, "gone.messages.json")), null);
+        const bad = join(dir, "bad.messages.json");
+        writeFileSync(bad, "{not json");
+        assert.equal(readClineSessionUsage(bad), null);
+    });
+});
+describe("cline adapter over its private per-narrative store", () => {
+    // The store lives at a fixed /tmp/brane-cline-<nid> path (brane writes it at
+    // spawn), so these use a throwaway narrative id under the same root.
+    const nid = `cline-test-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+    const sessionsDir = join("/tmp", `brane-cline-${nid}`, "data", "sessions");
+    const cline = getAgentAdapter("cline");
+    it("discovers the newest session in the narrative's own directory", () => {
+        clineLog(sessionsDir, "1786898522696_gg36a", []);
+        clineLog(sessionsDir, "1786899559349_f9dpo", [msg("m1", 2.0)]);
+        assert.equal(cline.discoverSessionId("/work/fold", 0, nid), "1786899559349_f9dpo");
+    });
+    it("sums sessions present on disk that brane never recorded", () => {
+        // Every dir under the narrative's private store is that narrative's spend.
+        // The five dead 401-revive sessions observed live are exactly this case:
+        // real launches whose ids the daemon never captured.
+        clineLog(sessionsDir, "1786898667854_rf6n9", [msg("m2", 0.5)]);
+        const reading = cline.readUsageMany({ sessionIds: [], foldPath: "/work/fold", narrativeId: nid });
+        assert.equal(reading.amount, 2.5);
+    });
+    it("excludes sessions that predate `since`, so a revive can't re-adopt the incumbent", () => {
+        // Cline ids carry their own start time (`<epochMs>_<rand5>`). Without this
+        // filter, discovery in the window between a revive and the new session dir
+        // appearing returns the previous session — which then reads as the
+        // successor and pins the pointer to a session that stopped spending.
+        const afterEverything = 1786899559350;
+        assert.equal(cline.discoverSessionId("/work/fold", afterEverything, nid), undefined);
+        assert.equal(cline.discoverSessionId("/work/fold", 1786899559349, nid), "1786899559349_f9dpo");
+    });
+    it("still honours recorded ids, and needs a narrative id to read anything", () => {
+        const both = cline.readUsageMany({
+            sessionIds: ["1786899559349_f9dpo"],
+            foldPath: "/work/fold",
+            narrativeId: nid,
+        });
+        assert.equal(both.amount, 2.5); // union, not double-counted
+        assert.equal(cline.readUsageMany({ sessionIds: [], foldPath: "/work/fold" }), null);
+        assert.equal(cline.readUsage({ sessionId: "x", foldPath: "/work/fold" }), null);
+    });
+});
+// ---------------------------------------------------------------------------
+// Revive re-capture
+// ---------------------------------------------------------------------------
+describe("maybeCaptureSessionId across revives", () => {
+    function seed(id, agent, sessionId) {
+        const db = createTestDb();
+        db.prepare(`INSERT INTO narratives (id, brane_id, agent_type, role, created_at, status, fold_path, agent_session_id)
+       VALUES (?, 'brane-test', ?, 'worker', 1000, 'active', '~/work', ?)`).run(id, agent, sessionId);
+        return db;
+    }
+    const restart = (db, id, seq, time) => db
+        .prepare("INSERT INTO events (narrative_id, seq, time, type, content) VALUES (?,?,?,'restarted','r')")
+        .run(id, seq, time);
+    it("captures on the first bind, anchored at the narrative's spawn time", () => {
+        const db = seed("crush-a", "crush", null);
+        const seen = [];
+        const got = maybeCaptureSessionId(db, "crush-a", "crush", "~/work", 1000, null, (_fp, since) => {
+            seen.push(since);
+            return "sess-1";
+        });
+        assert.equal(got, "sess-1");
+        assert.deepEqual(seen, [1000]);
+        assert.deepEqual(getSessionIds(db, "crush-a"), ["sess-1"]);
+    });
+    it("leaves a captured pointer alone while the narrative has never been revived", () => {
+        const db = seed("crush-b", "crush", "sess-1");
+        let called = false;
+        const got = maybeCaptureSessionId(db, "crush-b", "crush", "~/work", 1000, "sess-1", () => {
+            called = true;
+            return "sess-2";
+        });
+        assert.equal(got, undefined);
+        assert.equal(called, false, "discovery must not even run for a settled pointer");
+    });
+    it("re-anchors at the last revive and adopts the session that launch minted", () => {
+        // Crush has no resume and cline writes a fresh session dir per start, so
+        // without this every post-revive dollar goes unread against a pointer that
+        // names a session which stopped spending.
+        const db = seed("crush-c", "crush", "sess-1");
+        restart(db, "crush-c", 1, 5000);
+        restart(db, "crush-c", 2, 9000);
+        const seen = [];
+        const got = maybeCaptureSessionId(db, "crush-c", "crush", "~/work", 1000, "sess-1", (_fp, since) => {
+            seen.push(since);
+            return "sess-3";
+        });
+        assert.equal(got, "sess-3");
+        assert.deepEqual(seen, [9000], "anchored at the latest revive, not the spawn");
+        // Both sessions are retained, so cost spans the whole narrative.
+        assert.deepEqual(getSessionIds(db, "crush-c"), ["sess-1", "sess-3"]);
+    });
+    it("is idempotent when the agent resumed its session in place", () => {
+        // Goose re-attaches to the row named after the narrative, so discovery
+        // returns the same id and nothing is written.
+        const db = seed("goose-d", "goose", "20260816_2");
+        restart(db, "goose-d", 1, 5000);
+        const got = maybeCaptureSessionId(db, "goose-d", "goose", "~/work", 1000, "20260816_2", () => "20260816_2");
+        assert.equal(got, undefined);
+        assert.deepEqual(getSessionIds(db, "goose-d"), ["20260816_2"]);
+    });
+    it("does not let the discovery cache pin a stale pointer after a revive", () => {
+        // Exercises the real (uninjected) discovery path, so the production cache
+        // is live — the injected-`discover` tests above bypass it by design.
+        // Sequence: revive, then a tick landing before the new session dir exists,
+        // then the dir appears. The first tick must not cache the incumbent
+        // against the new anchor, or the successor is never adopted.
+        const nid = `cline-cache-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+        const dir = join("/tmp", `brane-cline-${nid}`, "data", "sessions");
+        const before = "1000000000000_aaaaa";
+        const after = "1000000009000_bbbbb";
+        clineLog(dir, before, [msg("m1", 1)]);
+        const db = seed(nid, "cline", before);
+        restart(db, nid, 1, 1000000005000);
+        // Tick one: only the pre-revive session exists.
+        assert.equal(maybeCaptureSessionId(db, nid, "cline", "~/work", 1, before), undefined, "the incumbent is not re-adopted as its own successor");
+        // Tick two: cline has now written the session this revive minted.
+        clineLog(dir, after, [msg("m2", 2)]);
+        assert.equal(maybeCaptureSessionId(db, nid, "cline", "~/work", 1, before), after);
+        assert.deepEqual(getSessionIds(db, nid), [before, after]);
+    });
+    it("ignores agents whose session id the daemon assigns or does not own", () => {
+        const db = seed("claude-e", "claude", null);
+        assert.equal(maybeCaptureSessionId(db, "claude-e", "claude", "~/work", 1000, null, () => "nope"), undefined);
+    });
+});
+//# sourceMappingURL=harness-cost.test.js.map

package/dist/test/helpers.js

@@ -0,0 +1,21 @@
+import Database from "better-sqlite3";
+import { SCHEMA_SQL, applyMigrations } from "../db/schema.js";
+/**
+ * Create a fresh in-memory database with the brane schema applied.
+ * Each test gets its own isolated DB instance.
+ *
+ * Built the same way `openDatabase()` builds the real one — `SCHEMA_SQL` then
+ * the migration ladder — so a column added by migration (cost_amount, archived,
+ * …) is present here too, and tests can't pass against a shape production never
+ * has.
+ */
+export function createTestDb() {
+    const db = new Database(":memory:");
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    db.exec(SCHEMA_SQL);
+    applyMigrations(db);
+    db.prepare("INSERT INTO meta (key, value) VALUES ('brane_id', 'brane-test')").run();
+    return db;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/test/hex-pages.test.js

@@ -0,0 +1,68 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { hexColumnOf, hexDumpRows, hexRows } from "../shared/hex-dump.js";
+import { hexSegments, pageOf, pagesOfHit, rowSpans } from "../shared/hex-pages.js";
+// The hex view draws whichever pages are loaded, in place, and 🔎 paints a
+// hit by row and column. Each rule here is one a highlight or a gap row would
+// be visibly wrong without.
+describe("hexSegments", () => {
+    it("is one page for a file that fits in one", () => {
+        assert.deepEqual(hexSegments([{ offset: 0, length: 100, eof: true }], 100), [{ kind: "page", offset: 0 }]);
+    });
+    it("puts a gap between pages that don't touch, and after the last until the end", () => {
+        const segs = hexSegments([{ offset: 32, length: 16, eof: false }, { offset: 0, length: 16, eof: false }], 100);
+        assert.deepEqual(segs, [
+            { kind: "page", offset: 0 },
+            { kind: "gap", from: 16, to: 32 },
+            { kind: "page", offset: 32 },
+            { kind: "gap", from: 48, to: 100 },
+        ]);
+    });
+    it("joins adjacent pages with no gap", () => {
+        const segs = hexSegments([{ offset: 0, length: 16, eof: false }, { offset: 16, length: 4, eof: true }], 20);
+        assert.deepEqual(segs, [{ kind: "page", offset: 0 }, { kind: "page", offset: 16 }]);
+    });
+    it("leaves the end open while the size is unknown, and closes it at eof", () => {
+        assert.deepEqual(hexSegments([{ offset: 0, length: 16, eof: false }], null).at(-1), { kind: "gap", from: 16, to: null });
+        assert.deepEqual(hexSegments([{ offset: 0, length: 16, eof: false }, { offset: 48, length: 3, eof: true }], null).at(-1), { kind: "page", offset: 48 });
+    });
+    it("opens with a gap when the first page isn't loaded", () => {
+        assert.deepEqual(hexSegments([{ offset: 64, length: 16, eof: false }], 200)[0], { kind: "gap", from: 0, to: 64 });
+    });
+});
+describe("page and row arithmetic", () => {
+    it("places a byte on its page, and a hit on every page it touches", () => {
+        assert.equal(pageOf(0, 16), 0);
+        assert.equal(pageOf(31, 16), 16);
+        assert.deepEqual(pagesOfHit(14, 4, 16), [0, 16]);
+        assert.deepEqual(pagesOfHit(16, 16, 16), [16]);
+        assert.deepEqual(pagesOfHit(5, 0, 16), [0]);
+    });
+    it("splits a hit that wraps a row into one span per row", () => {
+        assert.deepEqual(rowSpans(14, 4, 16), [{ row: 0, first: 14, last: 15 }, { row: 16, first: 0, last: 1 }]);
+        assert.deepEqual(rowSpans(3, 2, 8), [{ row: 0, first: 3, last: 4 }]);
+        assert.deepEqual(rowSpans(6, 20, 8), [
+            { row: 0, first: 6, last: 7 },
+            { row: 8, first: 0, last: 7 },
+            { row: 16, first: 0, last: 7 },
+            { row: 24, first: 0, last: 1 },
+        ]);
+    });
+    it("finds every byte's digits where hexColumnOf says, at both widths", () => {
+        const bytes = Uint8Array.from({ length: 16 }, (_, i) => 0xa0 + i);
+        for (const rowBytes of [16, 8]) {
+            const [row] = hexRows(bytes, 0, rowBytes);
+            for (let j = 0; j < rowBytes; j++) {
+                const at = hexColumnOf(j, rowBytes);
+                assert.equal(row.hex.slice(at, at + 2), (0xa0 + j).toString(16), `byte ${j} at ${rowBytes}/row`);
+            }
+            assert.equal(row.ascii.length, rowBytes);
+        }
+    });
+    it("composes to the same row hexDumpRows always drew", () => {
+        const bytes = Buffer.from("Hello, world!\n\x00\x01ABC");
+        const composed = hexRows(bytes, 0x20).map((r) => `${r.offset}  ${r.hex} ${r.ascii}`);
+        assert.deepEqual(composed, hexDumpRows(bytes, 0x20));
+    });
+});
+//# sourceMappingURL=hex-pages.test.js.map

package/dist/test/highlight.test.js

@@ -0,0 +1,69 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { detectLanguage, resolveLang } from "../highlight.js";
+describe("detectLanguage", () => {
+    it("maps extensions that differ from the shiki language id", () => {
+        assert.equal(detectLanguage("src/daemon/server.ts"), "typescript");
+        assert.equal(detectLanguage("main.rs"), "rust");
+        assert.equal(detectLanguage("script.py"), "python");
+    });
+    it("falls back to the bare extension when shiki knows it as a language", () => {
+        // The bug this covers: `.lean` was absent from EXT_LANG, so a Lean file
+        // rendered as plain monochrome text even though shiki bundles the grammar.
+        assert.equal(detectLanguage("Mathlib/Order/Basic.lean"), "lean");
+        assert.equal(detectLanguage("build.zig"), "zig");
+        assert.equal(detectLanguage("paper.tex"), "tex");
+    });
+    it("prefers the explicit map over the extension fallback", () => {
+        // Shiki bundles no SVG grammar at all, so `.svg` has to name xml itself —
+        // the bare-extension fallback would find nothing. Same reason ```svg went
+        // unhighlighted in chat until resolveLang existed.
+        assert.equal(detectLanguage("logo.svg"), "xml");
+    });
+    it("returns null for markdown, which the client renders itself", () => {
+        assert.equal(detectLanguage("README.md"), null);
+        assert.equal(detectLanguage("notes.mdx"), null);
+    });
+    it("returns null for unknown and extensionless files", () => {
+        assert.equal(detectLanguage("data.unknownext"), null);
+        assert.equal(detectLanguage("LICENSE"), null);
+    });
+    it("matches basename rules, including suffixed variants", () => {
+        assert.equal(detectLanguage("Dockerfile"), "docker");
+        assert.equal(detectLanguage("deploy/Dockerfile.dev"), "docker");
+        assert.equal(detectLanguage("Makefile"), "make");
+    });
+});
+describe("resolveLang", () => {
+    it("passes through the ids and aliases shiki already knows", () => {
+        assert.equal(resolveLang("typescript"), "typescript");
+        assert.equal(resolveLang("js"), "js");
+        assert.equal(resolveLang("yml"), "yml");
+    });
+    it("resolves a tag shiki lacks by reading it as a file extension", () => {
+        // The bug: ```svg rendered as plain text in chat while the identical file
+        // highlighted in the Files tab, because only that path consulted EXT_LANG.
+        assert.equal(resolveLang("svg"), "xml");
+    });
+    it("covers the few tags that are neither grammars nor extensions", () => {
+        assert.equal(resolveLang("golang"), "go");
+        assert.equal(resolveLang("patch"), "diff");
+        assert.equal(resolveLang("plist"), "xml");
+    });
+    it("normalizes case and stray whitespace", () => {
+        assert.equal(resolveLang("SVG"), "xml");
+        assert.equal(resolveLang("  TypeScript "), "typescript");
+    });
+    it("returns null for nothing, blanks, and words no grammar answers to", () => {
+        assert.equal(resolveLang(null), null);
+        assert.equal(resolveLang(undefined), null);
+        assert.equal(resolveLang("   "), null);
+        assert.equal(resolveLang("nonsenselang"), null);
+    });
+    it("does not let markdown's client-side rendering leak into fences", () => {
+        // detectLanguage returns null for .md so FilesView renders it itself, but
+        // ```md in a chat bubble is a code listing and shiki has the grammar.
+        assert.equal(resolveLang("md"), "md");
+    });
+});
+//# sourceMappingURL=highlight.test.js.map

package/dist/test/hit-drum.test.js

@@ -0,0 +1,71 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { BUMP_VELOCITY, RUBBER_BAND_LIMIT, clampIndex, compactCount, releaseVelocity, rubberBand, springAtRest, springStep, throwTarget, } from "../shared/hit-drum.js";
+describe("hit drum", () => {
+    it("rests on the nearest hit, never past either end", () => {
+        assert.equal(clampIndex(2.4, 17), 2);
+        assert.equal(clampIndex(2.6, 17), 3);
+        assert.equal(clampIndex(-3, 17), 0);
+        assert.equal(clampIndex(40, 17), 16);
+        assert.equal(clampIndex(3, 0), -1);
+    });
+    it("resists more the further past an end it is pulled", () => {
+        assert.equal(rubberBand(5.5, 17), 5.5);
+        const a = 16 - rubberBand(16 - 0, 17);
+        assert.equal(a, 0);
+        const one = rubberBand(17, 17) - 16;
+        const four = rubberBand(20, 17) - 16;
+        assert.ok(one > 0 && one < 1, `one hit of pull stretches less than a hit (${one})`);
+        assert.ok(four > one && four < RUBBER_BAND_LIMIT, `and never reaches the limit (${four})`);
+        assert.ok(rubberBand(-1, 17) < 0 && rubberBand(-1, 17) > -RUBBER_BAND_LIMIT);
+    });
+    it("bumps a quarter-detent or so into the wall and settles back", () => {
+        let s = { x: 16, v: BUMP_VELOCITY };
+        let max = 16;
+        for (let i = 0; i < 120 && !springAtRest(s.x, s.v, 16); i++) {
+            s = springStep(s.x, s.v, 16, 1 / 60);
+            max = Math.max(max, s.x);
+        }
+        const bump = max - 16;
+        assert.ok(bump > 0.15 && bump < 0.5, `visible but small (${bump})`);
+        assert.ok(springAtRest(s.x, s.v, 16), "and comes to rest on the end");
+    });
+    it("lands on its target without overshooting", () => {
+        let s = { x: 0, v: 0 };
+        let max = 0;
+        let frames = 0;
+        while (!springAtRest(s.x, s.v, 1) && frames < 600) {
+            s = springStep(s.x, s.v, 1, 1 / 60);
+            max = Math.max(max, s.x);
+            frames++;
+        }
+        assert.ok(frames < 60, `settles within a second (took ${frames} frames)`);
+        assert.ok(max <= 1.002, `no overshoot (peaked at ${max})`);
+    });
+    it("carries a flick a few hits, stopping at the ends", () => {
+        assert.equal(throwTarget(3.2, 0, 17), 3);
+        assert.equal(throwTarget(3, 10, 17), 7);
+        assert.equal(throwTarget(3, -12, 17), 0);
+        assert.equal(throwTarget(3, 1000, 17), 16);
+    });
+    it("measures release velocity over the last moments only", () => {
+        const samples = [
+            { t: 0, y: 0 },
+            { t: 100, y: -100 },
+            { t: 150, y: -140 },
+            { t: 180, y: -160 },
+        ];
+        assert.ok(Math.abs(releaseVelocity(samples, 180) - -60 / 80) < 1e-9);
+        assert.equal(releaseVelocity(samples, 400), 0, "a finger that paused before lifting throws nothing");
+    });
+    it("shortens totals past 999, rounding down", () => {
+        assert.equal(compactCount(0), "0");
+        assert.equal(compactCount(999), "999");
+        assert.equal(compactCount(1000), "1k");
+        assert.equal(compactCount(1234), "1.2k");
+        assert.equal(compactCount(1999), "1.9k");
+        assert.equal(compactCount(5000), "5k");
+        assert.equal(compactCount(12345), "12k");
+    });
+});
+//# sourceMappingURL=hit-drum.test.js.map