brane 0.1.1 → 0.3.1

package/dist/shared/speaker-color.js

@@ -0,0 +1,61 @@
+/**
+ * The color a foreign speaker's bubbles wear in a narrative — a hue hashed from
+ * its nid, so `claude-4c7289d1` is the same purple in every conversation it
+ * joins. That global stability is the feature, and it has one failure: two
+ * speakers in the *same* narrative can hash a few degrees apart, and a
+ * synthesis between two agents becomes a conversation between two purples.
+ *
+ * `salt` is the 🎨 Recolor escape hatch. Salt 0 is the palette every narrative
+ * has always had (the legacy hash, kept byte-for-byte so nothing already on
+ * screen shifts). A nonzero salt reshuffles *per speaker*: the legacy hash is
+ * pushed through a nonlinear finalizer, because merely seeding or prefixing the
+ * polynomial hash adds the same constant to every equal-length nid — a uniform
+ * rotation that leaves two close hues exactly as close as they were.
+ *
+ * Window-free, like `view-url.ts`, so `src/test/speaker-color.test.ts` can pin
+ * it; the salt itself lives in the app's storage (`expo/lib/recolor.ts`).
+ */
+/** The hash every brane app has used for speaker hues (matches Stolon). Kept
+ *  verbatim — including its overflow past int32 on the last character — so
+ *  salt 0 reproduces existing colors exactly. */
+function legacyHash(speaker) {
+    let hash = 0;
+    for (let i = 0; i < speaker.length; i++) {
+        hash = speaker.charCodeAt(i) + ((hash << 5) - hash);
+    }
+    return hash;
+}
+/** MurmurHash3's 32-bit finalizer: every input bit affects every output bit,
+ *  which is what makes the reshuffle per speaker rather than per palette. */
+function fmix32(h) {
+    h ^= h >>> 16;
+    h = Math.imul(h, 0x85ebca6b);
+    h ^= h >>> 13;
+    h = Math.imul(h, 0xc2b2ae35);
+    h ^= h >>> 16;
+    return h | 0;
+}
+export function speakerHue(speaker, salt = 0) {
+    let hash = legacyHash(speaker);
+    if (salt)
+        hash = fmix32(hash ^ Math.imul(salt, 0x9e3779b1));
+    return Math.abs(hash) % 360;
+}
+/** Attribution text: a light pastel. */
+export function speakerColor(speaker, salt = 0) {
+    return `hsl(${speakerHue(speaker, salt)}, 60%, 80%)`;
+}
+/** Bubble background: the same hue, dark. */
+export function speakerBgColor(speaker, salt = 0) {
+    return `hsl(${speakerHue(speaker, salt)}, 30%, 20%)`;
+}
+/** Where a narrative's salt is kept, per device. */
+export function recolorStorageKey(nid) {
+    return `brane:recolor:${nid}`;
+}
+/** Parse a stored salt; anything unreadable is the default palette. */
+export function parseRecolorSalt(raw) {
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : 0;
+}
+//# sourceMappingURL=speaker-color.js.map

package/dist/shared/token-rotation.js

@@ -0,0 +1,14 @@
+/**
+ * What the daemon and the app agree on about token rotation, window-free so
+ * both can import it. The mechanism itself lives in `src/daemon/token-ring.ts`.
+ */
+/** WebSocket close code the daemon sends to a viewer socket it is signing out
+ *  because the token it authenticated with has been retired. A client that
+ *  sees it must stop reconnecting — the credential it holds is dead, and a
+ *  2 s retry loop against a 401 would run forever and silently. Anything
+ *  else (1006 above all) is a network blip and reconnects as before. */
+export const WS_CLOSE_TOKEN_ROTATED = 4401;
+export function isSignedOutClose(code) {
+    return code === WS_CLOSE_TOKEN_ROTATED;
+}
+//# sourceMappingURL=token-rotation.js.map

package/dist/shared/view-url.js

@@ -0,0 +1,216 @@
+/** The URL contract for a narrative view: which tab is active, which tabs are
+ *  pinned beside it, and which file (and line range) the Files pane is showing.
+ *
+ *  This lives in `shared/` rather than in the screen that uses it because the
+ *  URL is the only carrier of view state between two *origins*. Tab layout and
+ *  last-visited file are also kept in `sessionStorage`, which is origin-scoped,
+ *  and the Isolate menu item hops between the shared app's origin and a
+ *  daemon's own host —
+ *  so whatever isn't in the query string does not survive the jump. Keeping
+ *  the serialization and the link builder in one pure module means the URL you
+ *  get from tapping around and the URL Isolate hands the other origin are the
+ *  same URL, and means both can be tested without a browser.
+ */
+/** Tab order, as rendered in the tab bar. Pins serialize in this order no
+ *  matter what order they were toggled in, so a URL is stable. */
+export const CANONICAL_TABS = ["chat", "terminal", "files"];
+const VALID_TABS = new Set(CANONICAL_TABS);
+/** True when this page is served by the daemon it is connected to — a
+ *  daemon's own bundle — so "isolated" is the *current* state and the menu
+ *  offers the way back out. Everything else is a shared app: the hosted
+ *  shell, a staging hostname, a fork's deployment, a dev server. The app
+ *  carries no host of its own, so this is a comparison with no constant in
+ *  it: `window.location.host` against the connection's host, which a
+ *  daemon's bundle fills from the same `location.host` (expo/lib/api.ts).
+ *  Hosts are case-insensitive; the port is part of the answer, since a
+ *  daemon's bundle is reached on its port. */
+export function isIsolated(pageHost, daemonHost) {
+    return pageHost.toLowerCase() === daemonHost.toLowerCase();
+}
+export function parseActiveTab(tab) {
+    return VALID_TABS.has(tab) ? tab : "chat";
+}
+export function parsePinnedTabs(pinned) {
+    if (!pinned)
+        return new Set();
+    return new Set(pinned.split(",").map((s) => s.trim()).filter((s) => VALID_TABS.has(s)));
+}
+export function serializePinned(pins) {
+    return CANONICAL_TABS.filter((t) => pins.has(t)).join(",");
+}
+/** The view-state query params as a plain record, with `undefined` for anything
+ *  at its default — which is both how `router.setParams` clears a param and how
+ *  `buildIsolateUrl` knows to drop a stale one. */
+export function viewParams(tab, pins, path, line, lineEnd) {
+    const pinsSerialized = serializePinned(pins);
+    const lineStr = line
+        ? (lineEnd && lineEnd > line ? `${line}-${lineEnd}` : String(line))
+        : undefined;
+    return {
+        tab: tab !== "chat" ? tab : undefined,
+        pinned: pinsSerialized || undefined,
+        path: path || undefined,
+        line: lineStr,
+    };
+}
+/** The narrative's terminal, alone — where the two lifecycle actions land.
+ *
+ *  Both Revive and End put you in front of a prompt you have to answer: a
+ *  resumed agent often comes up sitting on one, and a termination is just as
+ *  often *blocked* by one. So they navigate to a **view**, not merely to a
+ *  narrative.
+ *
+ *  It goes in the URL rather than being set after arrival because an explicit
+ *  `tab` param is what outranks the tab layout the screen would otherwise
+ *  restore from `sessionStorage`; state set on arrival would be racing that
+ *  restore. No pins, per the "alone" half: whatever was pinned belongs to the
+ *  view you were in, not to the prompt you now have to answer.
+ */
+export function terminalOnlyHref(nid) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(viewParams("terminal", new Set()))) {
+        if (value)
+            params.set(key, value);
+    }
+    return `/${nid}?${params.toString()}`;
+}
+/** Reads the `line` param back: `"10"` or `"10-20"`. The counterpart of the
+ *  `line` that `viewParams` writes, and the reason both live here — a param
+ *  whose writer and reader sit in different modules drifts.
+ *
+ *  Note the deliberate asymmetry at `lineEnd === line`: the writer collapses
+ *  that to a bare `"10"`, so it reads back as a single line rather than a
+ *  one-line range. Same selection either way. */
+export function parseLineSpec(s) {
+    if (!s)
+        return {};
+    const m = s.match(/^(\d+)(?:-(\d+))?$/);
+    if (!m)
+        return {};
+    const line = Number(m[1]);
+    const end = m[2] ? Number(m[2]) : undefined;
+    return end !== undefined && end >= line ? { line, lineEnd: end } : { line };
+}
+/** The params that describe *which daemon*, as opposed to what you are looking
+ *  at. They are origin-scoped: meaningful to the page that received them, never
+ *  to be carried onward. */
+export const CONNECTION_PARAMS = ["host", "token"];
+/** A search string with the connection params removed and everything else left
+ *  alone, ready to hand to `history.replaceState`.
+ *
+ *  The shared SPA cleans a meld URL as soon as it has used it, so the token
+ *  doesn't linger in the address bar or the back stack. Cleaning by resetting
+ *  to the bare pathname would take the view with it — tab, pins, open file,
+ *  scroll target — which is precisely what an Isolate hop just finished
+ *  carrying across. Returns `""` or a string with a leading `?`.
+ *
+ *  New links carry the connection in the fragment (see `connectionFragment`),
+ *  so this is the legacy half of the cleaner: old QR codes and bookmarks still
+ *  arrive with `?token=`, and they are still honored and still scrubbed.
+ */
+export function withoutConnectionParams(search) {
+    const params = new URLSearchParams(search);
+    for (const key of CONNECTION_PARAMS)
+        params.delete(key);
+    const rest = params.toString();
+    return rest ? `?${rest}` : "";
+}
+/** The fragment counterpart of `withoutConnectionParams`: a hash with the
+ *  connection params removed and anything else left alone. Returns `""` or a
+ *  string with a leading `#`. Accepts the hash with or without its `#`. */
+export function withoutConnectionHash(hash) {
+    const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+    if (!raw)
+        return "";
+    const params = new URLSearchParams(raw);
+    for (const key of CONNECTION_PARAMS)
+        params.delete(key);
+    const rest = params.toString();
+    return rest ? `#${rest}` : "";
+}
+/** Where a link puts the daemon's address and token: the URL **fragment**.
+ *
+ *  A query string is part of the HTTP request, so `?host=…&token=…` on a
+ *  shared-app link reached its host's edge with the daemon's
+ *  bearer token in it, landed in the daemon's own request log on an Isolate
+ *  hop, and was fetched by every chat app's link unfurler when a meld URL was
+ *  pasted. A fragment is never sent to any server: the browser keeps it, the
+ *  page reads it from `location.hash`, and the app strips it once consumed.
+ *
+ *  The shared SPA serves every daemon and must be told which one; a daemon's
+ *  own bundle already knows, so it gets the token alone.
+ */
+export function connectionFragment(conn, includeHost) {
+    const params = new URLSearchParams();
+    if (includeHost)
+        params.set("host", conn.host);
+    params.set("token", conn.token);
+    return `#${params.toString()}`;
+}
+/** The same narrative, in the same view, somewhere else — the one builder
+ *  behind both menu items.
+ *
+ *  Params come from two places, and the order matters. The current search
+ *  string seeds the set, which picks up params the screen doesn't model —
+ *  `scrollToSeq`, so the new page opens at the message you'd jumped to. Live
+ *  state is then overlaid and wins on everything it does own, because a layout
+ *  restored from `sessionStorage` never writes itself back to the URL: seeding
+ *  alone would miss exactly the case with the most to lose.
+ *
+ *  Connection params are always dropped and re-set, never carried: they
+ *  describe the origin building the link, and the target needs its own. The
+ *  view rides in the query string; the connection rides in the fragment, which
+ *  no server ever sees (`connectionFragment`).
+ */
+export function buildViewUrl(target, opts) {
+    const { protocol, search, path, conn, view } = opts;
+    const params = new URLSearchParams(search);
+    for (const [key, value] of Object.entries(view)) {
+        if (value)
+            params.set(key, value);
+        else
+            params.delete(key);
+    }
+    for (const key of CONNECTION_PARAMS)
+        params.delete(key);
+    const query = params.toString();
+    const rest = (query ? `?${query}` : "") + connectionFragment(conn, target === "shared");
+    if (target === "shared") {
+        // A shared app serves every daemon, so it has to be told which one.
+        const origin = sharedOrigin(opts);
+        return origin === null ? null : `${origin}${path}${rest}`;
+    }
+    // A daemon's own bundle already knows which daemon it is; only the token is
+    // needed. The scheme follows the page building the link, so a plain-http LAN
+    // session doesn't hand out https links that won't load.
+    return `${pageScheme(protocol)}://${conn.host}${path}${rest}`;
+}
+function pageScheme(protocol) {
+    return protocol === "https:" ? "https" : "http";
+}
+/** The shared app's origin, from where this page stands. On a shared app it
+ *  is this page's own origin, scheme included (a dev server is plain http).
+ *  On a daemon's own bundle it is whatever the daemon reports as its
+ *  `app_domain`, over https, since that is a hosted shell; with none
+ *  reported there is no shared origin to name, and the answer is null. */
+function sharedOrigin(opts) {
+    if (!isIsolated(opts.host, opts.conn.host))
+        return `${pageScheme(opts.protocol)}://${opts.host}`;
+    return opts.appHost ? `https://${opts.appHost}` : null;
+}
+/** Isolate / Unisolate: the same view, on the *other* kind of origin. Which
+ *  way it goes is just where you are now. Null only from a daemon's own
+ *  bundle that was told no `appHost`: there is nowhere to hop out to, and
+ *  the menu should say so rather than offer a link. */
+export function buildIsolateUrl(opts) {
+    return buildViewUrl(isIsolated(opts.host, opts.conn.host) ? "shared" : "daemon", opts);
+}
+/** Meld: the same view, on another *device*. The origin kind is the one thing
+ *  that must not change — someone reaching the daemon directly can't be handed
+ *  a shared-app link, and someone on a shared app expects to stay on *that*
+ *  one — so where Isolate flips, this stays put. It never needs `appHost`:
+ *  the shared origin it names is the page's own, so it is never null. */
+export function buildMeldUrl(opts) {
+    return buildViewUrl(isIsolated(opts.host, opts.conn.host) ? "daemon" : "shared", opts);
+}
+//# sourceMappingURL=view-url.js.map

package/dist/shared/wiki-links.js

@@ -0,0 +1,70 @@
+/** Link resolution for wiki pages, shared by the daemon and the web reader so
+ *  the two can never disagree about where a link points.
+ *
+ *  A fold's wiki is `wiki/` plus at most one subdirectory, `wiki/shared/`. A
+ *  page's *slug* is its path relative to `wiki/` — `foo.md` is local,
+ *  `shared/foo.md` is shared — so a citation means the same thing to every
+ *  reader. Markdown links inside a page are filesystem-relative, the way
+ *  GitHub and every editor already render them: from `shared/a.md`, `b.md` is
+ *  `shared/b.md` and `../c.md` is `c.md`; from local `c.md`, `shared/a.md` is
+ *  the shared page. This module is that arithmetic and nothing else — whether
+ *  the target exists, or is visible to the caller, is decided by whoever holds
+ *  the directory.
+ *
+ *  Window-free and dependency-free so `src/test/wiki-links.test.ts` can run it
+ *  over a grid, and so metro needs no alias for it.
+ */
+/** The one subdirectory a wiki may contain. Pages under it are visible from
+ *  other folds; everything directly under `wiki/` is fold-local. */
+export const WIKI_SHARED_DIR = "shared";
+/** Whether a slug (with or without `.md`) names a shared page. */
+export function isSharedSlug(slug) {
+    return slug.startsWith(`${WIKI_SHARED_DIR}/`);
+}
+/** Canonical slug form: no leading `/` or `./`, `.md` appended when the last
+ *  segment has no extension. Does not touch `..` — callers that need safety
+ *  go through {@link resolveWikiLink}, which rejects escapes. */
+export function normalizeWikiSlug(slug) {
+    let s = slug.trim().replace(/^\/+/, "");
+    while (s.startsWith("./"))
+        s = s.slice(2);
+    const last = s.split("/").pop() ?? "";
+    return last.includes(".") ? s : `${s}.md`;
+}
+/** Resolve a markdown `href` found in the page `fromSlug`. Returns the target
+ *  slug (canonical, relative to `wiki/`) and any `#anchor`, or `null` when the
+ *  link is not an intra-wiki page link: a URL with a scheme, an absolute
+ *  path, or a relative path that climbs above `wiki/`. A bare `#anchor` stays
+ *  on the current page. */
+export function resolveWikiLink(fromSlug, href) {
+    const raw = href.trim();
+    const hashIdx = raw.indexOf("#");
+    const pathPart = hashIdx >= 0 ? raw.slice(0, hashIdx) : raw;
+    const anchor = hashIdx >= 0 ? raw.slice(hashIdx + 1).trim() || undefined : undefined;
+    const from = normalizeWikiSlug(fromSlug);
+    if (pathPart === "") {
+        return anchor !== undefined ? { slug: from, anchor } : { slug: from };
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(pathPart))
+        return null;
+    if (pathPart.startsWith("/") || pathPart.startsWith("\\"))
+        return null;
+    const baseDir = from.includes("/") ? from.slice(0, from.lastIndexOf("/")).split("/") : [];
+    const stack = [...baseDir];
+    for (const seg of pathPart.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            if (stack.length === 0)
+                return null;
+            stack.pop();
+            continue;
+        }
+        stack.push(seg);
+    }
+    if (stack.length === 0)
+        return null;
+    const slug = normalizeWikiSlug(stack.join("/"));
+    return anchor !== undefined ? { slug, anchor } : { slug };
+}
+//# sourceMappingURL=wiki-links.js.map

package/dist/shared/wiki-window.js

@@ -0,0 +1,4 @@
+export function neighborColumns(prev, next) {
+    return { above: [...prev].reverse(), below: [...next] };
+}
+//# sourceMappingURL=wiki-window.js.map

package/dist/tailscale.js

@@ -0,0 +1,55 @@
+import { execFile, execSync } from "node:child_process";
+function getTailscaleStatus() {
+    try {
+        const json = execSync("tailscale status --json", {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3000,
+        }).toString();
+        const status = JSON.parse(json);
+        const dnsName = status?.Self?.DNSName?.replace(/\.$/, "");
+        return { dnsName, ips: parseTailscaleIps(json) };
+    }
+    catch {
+        // Tailscale not installed or not running
+        return {};
+    }
+}
+/** Try to get the Tailscale DNS name (e.g., "myhost.tailnet.ts.net") */
+export function getTailscaleHost() {
+    return getTailscaleStatus().dnsName;
+}
+/** Get Tailscale IPs for this machine (e.g., ["100.x.y.z", "fd7a:..."]) */
+export function getTailscaleIps() {
+    return getTailscaleStatus().ips ?? [];
+}
+/**
+ * `Self.TailscaleIPs` out of `tailscale status --json` output — or `[]`.
+ *
+ * Shared by the sync and async readers so they cannot disagree. Every way
+ * the input can be wrong (not JSON, no `Self`, `TailscaleIPs` missing or
+ * holding non-strings) yields an empty list rather than a throw: "no
+ * Tailscale" is an ordinary state the daemon handles, and a malformed answer
+ * must look like that state, never like a crash.
+ */
+export function parseTailscaleIps(stdout) {
+    try {
+        const status = JSON.parse(stdout);
+        const ips = status?.Self?.TailscaleIPs;
+        return Array.isArray(ips) ? ips.filter((x) => typeof x === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Async twin of `getTailscaleIps` for callers on the daemon's event loop.
+ * The sync form blocks for up to its 3 s timeout when the Tailscale
+ * extension is hung — acceptable once at startup, not every minute for the
+ * lifetime of the daemon. Resolves to `[]` on any failure, like the sync form.
+ */
+export function getTailscaleIpsAsync(timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        execFile("tailscale", ["status", "--json"], { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => resolve(err ? [] : parseTailscaleIps(String(stdout))));
+    });
+}
+//# sourceMappingURL=tailscale.js.map