brane 0.3.2 → 0.3.3

package/dist/test/membrane-quips.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { QuipLoop, shuffled } from "../shared/membrane-quips.js";
+// The caption's order: one shuffle per page load, then a fixed loop through
+// it — every line once before any line twice, the same order each time round.
+const list = ["a", "b", "c", "d", "e"];
+/** A seeded generator, so a "random" shuffle is the same on every run. */
+function seeded(seed) {
+    return () => {
+        seed = (seed * 1103515245 + 12345) % 2 ** 31;
+        return seed / 2 ** 31;
+    };
+}
+describe("shuffled", () => {
+    it("is a permutation, and leaves its input alone", () => {
+        const before = [...list];
+        const out = shuffled(list, seeded(7));
+        assert.deepEqual([...out].sort(), before);
+        assert.deepEqual(list, before);
+    });
+    it("can produce every order", () => {
+        const seen = new Set();
+        for (let s = 1; s < 2000; s++)
+            seen.add(shuffled(list.slice(0, 3), seeded(s)).join(""));
+        assert.equal(seen.size, 6);
+    });
+    it("clamps a rand that returns 1", () => {
+        assert.equal(shuffled(list, () => 1).length, list.length);
+    });
+});
+describe("QuipLoop", () => {
+    it("shows every line once per cycle, and the same cycle each time round", () => {
+        const loop = new QuipLoop(list, seeded(3));
+        const first = [loop.current()];
+        for (let i = 1; i < list.length; i++)
+            first.push(loop.next());
+        assert.equal(new Set(first).size, list.length);
+        const second = [loop.next()];
+        for (let i = 1; i < list.length; i++)
+            second.push(loop.next());
+        assert.deepEqual(second, first);
+    });
+    it("never shows the same line twice in a row", () => {
+        const loop = new QuipLoop(list, seeded(11));
+        let prev = loop.current();
+        for (let i = 0; i < list.length * 3; i++) {
+            const q = loop.next();
+            assert.notEqual(q, prev);
+            prev = q;
+        }
+    });
+    it("does not move until told to", () => {
+        const loop = new QuipLoop(list, seeded(5));
+        assert.equal(loop.current(), loop.current());
+    });
+    it("holds a single line", () => {
+        const one = ["solo"];
+        const loop = new QuipLoop(one);
+        assert.equal(loop.next(), one[0]);
+    });
+});
+//# sourceMappingURL=membrane-quips.test.js.map

package/dist/test/mo-glyph.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { MO_GLYPH_BOX, MO_GLYPH_PATH } from "../shared/mo-glyph.js";
+import { MO_GLYPH_BOX, MO_GLYPH_MARGIN, MO_GLYPH_PATH } from "../shared/mo-glyph.js";
 test("mo-glyph: closed subpaths, absolute commands only, every point inside the box", () => {
     assert.match(MO_GLYPH_PATH, /^M/);
     assert.match(MO_GLYPH_PATH, /Z$/);
@@ -18,5 +18,7 @@ test("mo-glyph: closed subpaths, absolute commands only, every point inside the
     const mid = MO_GLYPH_BOX / 2;
     assert.ok(Math.abs(Math.min(...xs) + Math.max(...xs) - 2 * mid) < 2);
     assert.ok(Math.abs(Math.min(...ys) + Math.max(...ys) - 2 * mid) < 2);
+    // The caption under the glyph is spaced by this (MembraneEmpty.web.tsx).
+    assert.ok(Math.abs(Math.min(...ys) - MO_GLYPH_MARGIN) < 0.01, `ink top is ${Math.min(...ys)}`);
 });
 //# sourceMappingURL=mo-glyph.test.js.map

package/dist/test/view-url.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { CANONICAL_TABS, isIsolated, parseActiveTab, parsePinnedTabs, serializePinned, viewParams, parseLineSpec, buildIsolateUrl, buildMeldUrl, terminalOnlyHref, withoutConnectionHash, withoutConnectionParams, connectionFragment, } from "../shared/view-url.js";
+import { CANONICAL_TABS, isIsolated, parseActiveTab, parsePinnedTabs, serializePinned, viewParams, parseLineSpec, buildIsolateUrl, buildMeldUrl, terminalOnlyHref, withoutConnectionHash, withoutConnectionParams, connectionFragment, withDaemonFragment, daemonFromHash, activeDaemonBraneId, daemonToAdopt, } from "../shared/view-url.js";
 // These pin the URL contract that the Isolate menu item depends on. It opens
 // the same narrative on the *other* origin — a shared app, or a daemon's own
 // bundle — and the tab layout and open file live in sessionStorage, which is
@@ -219,6 +219,9 @@ describe("withoutConnectionHash", () => {
             ["#other=1&token=t", "#other=1"],
             ["host=h:1&token=t", ""],
             ["#token=a&token=b&x=1", "#x=1"],
+            // `daemon` names which daemon too, so it is consumed like the token.
+            ["#daemon=brane-f66d2b", ""],
+            ["#host=h:1&daemon=brane-f66d2b&token=t&x=1", "#x=1"],
         ];
         for (const [input, expected] of cases) {
             assert.equal(withoutConnectionHash(input), expected, JSON.stringify(input));
@@ -624,4 +627,106 @@ describe("terminalOnlyHref", () => {
         assert.equal(parsePinnedTabs(url.searchParams.get("pinned") ?? undefined).size, 0);
     });
 });
+describe("withDaemonFragment", () => {
+    // A link opened in a new tab arrives with no active daemon in that tab's
+    // sessionStorage; the fragment is how it finds the one the link was written
+    // from. So the question each case asks: is the daemon named, in the
+    // fragment, and is the view the href's query already described left exactly
+    // as it was?
+    const BRANE = "brane-f66d2b";
+    it("names the daemon in the fragment of a bare path", () => {
+        assert.equal(withDaemonFragment("/", BRANE), `/#daemon=${BRANE}`);
+        assert.equal(withDaemonFragment(`/${NID}`, BRANE), `/${NID}#daemon=${BRANE}`);
+    });
+    it("leaves the query, the view, exactly as it was", () => {
+        const href = `/${NID}?tab=files&path=src%2Fa.ts&line=10-20`;
+        const url = new URL(withDaemonFragment(href, BRANE), "https://example.test");
+        assert.equal(url.pathname + url.search, href);
+        assert.equal(url.searchParams.get("daemon"), null);
+        assert.equal(daemonFromHash(url.hash), BRANE);
+    });
+    it("replaces a daemon already there, and keeps any other fragment param", () => {
+        const url = new URL(withDaemonFragment(`/${NID}?scrollToSeq=4#x=1&daemon=old`, BRANE), "https://example.test");
+        const frag = new URLSearchParams(url.hash.slice(1));
+        assert.deepEqual(frag.getAll("daemon"), [BRANE]);
+        assert.equal(frag.get("x"), "1");
+        assert.equal(url.searchParams.get("scrollToSeq"), "4");
+    });
+    it("returns the href unchanged when the daemon is not known", () => {
+        for (const none of [null, undefined, ""]) {
+            assert.equal(withDaemonFragment(`/${NID}?scrollToSeq=4`, none), `/${NID}?scrollToSeq=4`);
+        }
+    });
+    it("reads back through daemonFromHash, and is what the fragment cleaner removes", () => {
+        const url = new URL(withDaemonFragment(`/${NID}?scrollToSeq=4`, BRANE), "https://example.test");
+        assert.equal(daemonFromHash(url.hash), BRANE);
+        assert.equal(daemonFromHash(url.hash.slice(1)), BRANE);
+        assert.equal(withoutConnectionHash(url.hash), "");
+        assert.equal(withoutConnectionParams(url.search), "?scrollToSeq=4");
+    });
+    it("is absent from daemonFromHash when missing or empty", () => {
+        assert.equal(daemonFromHash(""), null);
+        assert.equal(daemonFromHash("#"), null);
+        assert.equal(daemonFromHash("#daemon="), null);
+        assert.equal(daemonFromHash("#token=t"), null);
+    });
+    it("is not carried by Isolate or Meld, whose token already names the daemon", () => {
+        // Isolate and Meld seed from the page's search string; a stray `daemon`
+        // there (an old link) must not ride along in either half of the URL.
+        const opts = {
+            host: SHARED_SPA_HOST,
+            protocol: "https:",
+            search: `?scrollToSeq=4&daemon=${BRANE}`,
+            path: `/${NID}`,
+            conn: CONN,
+            view: viewParams("chat", new Set()),
+        };
+        for (const built of [buildIsolateUrl(opts), buildMeldUrl(opts)]) {
+            const { params, conn } = open(built);
+            assert.equal(params.get("daemon"), null, built);
+            assert.equal(conn.get("daemon"), null, built);
+            assert.equal(params.get("scrollToSeq"), "4", built);
+            assert.equal(conn.get("token"), CONN.token, built);
+        }
+    });
+});
+describe("the daemon a tab names, and the one it adopts", () => {
+    // The registry entries these read, as `expo/lib/registry.ts` stores them:
+    // `id` is the display key the tab's slot holds, `brane_id` what a link names.
+    const CHALK = { id: "ben@chalk", brane_id: "brane-aaaaaa" };
+    const SLATE = { id: "ben@slate", brane_id: "brane-bbbbbb" };
+    const BOTH = [CHALK, SLATE];
+    it("a link names the tab's active daemon", () => {
+        assert.equal(activeDaemonBraneId(BOTH, SLATE.id), SLATE.brane_id);
+        assert.equal(activeDaemonBraneId(BOTH, CHALK.id), CHALK.brane_id);
+    });
+    it("falls back to the first entry when the active id is missing or stale, as the layout connects", () => {
+        assert.equal(activeDaemonBraneId(BOTH, null), CHALK.brane_id);
+        assert.equal(activeDaemonBraneId(BOTH, "ben@gone"), CHALK.brane_id);
+    });
+    it("names nothing with nothing melded, so the link stays bare", () => {
+        assert.equal(activeDaemonBraneId([], null), null);
+        assert.equal(withDaemonFragment("/", activeDaemonBraneId([], null)), "/");
+    });
+    it("a new tab, whose slot is empty, adopts the daemon its link named", () => {
+        assert.equal(daemonToAdopt(BOTH, null, SLATE.brane_id), SLATE.id);
+    });
+    it("a tab that already has a daemon keeps it, so a reload never undoes a switch", () => {
+        // The router restores the initial fragment on its first URL write, so a
+        // tab opened on SLATE and later switched to CHALK can still say SLATE.
+        assert.equal(daemonToAdopt(BOTH, CHALK.id, SLATE.brane_id), null);
+        assert.equal(daemonToAdopt(BOTH, SLATE.id, SLATE.brane_id), null);
+    });
+    it("a daemon this browser has not melded is no instruction at all", () => {
+        assert.equal(daemonToAdopt(BOTH, null, "brane-cccccc"), null);
+        assert.equal(daemonToAdopt([], null, SLATE.brane_id), null);
+    });
+    it("round-trips: what one tab names, a fresh tab adopts", () => {
+        for (const from of BOTH) {
+            const href = withDaemonFragment(`/${NID}`, activeDaemonBraneId(BOTH, from.id));
+            const named = daemonFromHash(new URL(href, "https://example.test").hash);
+            assert.equal(daemonToAdopt(BOTH, null, named), from.id);
+        }
+    });
+});
 //# sourceMappingURL=view-url.test.js.map

package/docs/math.md

@@ -7,6 +7,7 @@ LaTeX in narrative markdown renders through **KaTeX**, in the app and in the HTM
 | `renderMathHtml()` | `src/shared/markdown-math.ts` | The one KaTeX call. `htmlAndMathml`; unparseable LaTeX falls back to the literal source, not KaTeX's red error markup |
 | `prepareMathMarkdown()` | `src/shared/markdown-math.ts` | Pre-parse normalization, run by both sides before micromark/mdast |
 | `mathHtmlExtension()`, `katexStyleFor()` | `src/math.ts` | Export only: micromark hookup, and the inlined stylesheet |
+| `math()` | `src/math-syntax.ts` | Server only: the `$` syntax extension, vendored from `micromark-extension-math` (see below) |
 | `public/katex/` | `expo/` | The app's stylesheet + woff2, vendored by `npm run sync:katex` |
 | `diagnoseMarkdown()` | `src/markdown-diagnostics.ts` | The same pipeline run to *report* rather than render — see [Rendering Warnings](rendering-warnings.md) |
 
@@ -29,4 +30,6 @@ Two more things are less obvious than they look:
 
 **Fonts don't come along by themselves.** KaTeX lays its span tree out entirely in CSS and needs its woff2 faces; without them math is a pile of overlapping glyphs. The export inlines only the families the document reaches for (~166 KB of base64 for an equation-dense narrative, nothing at all for one with no math), derived from the stylesheet so a KaTeX upgrade can't silently drop a face. The app can't inline per document, so it serves `public/katex/` — vendored the way `pdf.min.mjs` already is, because metro bundles a CSS *import* but never copies the `url(fonts/…)` it points at. The `<link>` lives in **`public/index.html`**, which is the real HTML template; `app/+html.tsx` is kept in step but is not what ships.
 
+**The server vendors the syntax half of `micromark-extension-math`.** That package's index loads its own `mathHtml()` too, and with it `katex` at the range it pins (`^0.16.0`). Root `overrides` dedupe that onto our katex in a checkout, but npm ignores a dependency's `overrides`, so every `npm install brane` got a second, older katex — never called, since `src/math.ts` is our `mathHtml`, but loaded, and flagged by `npm audit`. `src/math-syntax.ts` is upstream 3.1.0's tokenizers with TypeScript annotations and nothing else changed (80,000 fuzzed parses matched upstream event for event); the package is no longer a root dependency. The app still imports the package: it ships prebuilt, built under `expo/`'s own overrides. If upstream ever changes how it tokenizes, the two parsers can drift, so carry the change into `src/math-syntax.ts` by hand.
+
 `src/shared/markdown-math.ts` is also the first shared module to import an npm package. Metro resolves a module's dependencies from its own directory and `src/shared` sits outside the expo project root, so `metro.config.js` maps `katex` explicitly — the next shared module with a bare import will need the same.

package/docs/view-urls.md

@@ -56,9 +56,15 @@ pins, Files path and line, the `?scrollToSeq=` selection) goes through
 since the stack did not grow. So the URL keeps that state and Back returns to
 it, but it never costs an extra Back: browsing ten files is one entry, not ten.
 A bare link to the narrative you are in, with no seq, goes nowhere. The list
-is a jump too: **All narratives** in the switcher pushes it, so Back returns
-to the narrative, whether or not a list was already beneath. So does a
-swipe down on the narrative's header card, which dismisses it. So does
+is a jump too: a swipe down on the narrative's header card dismisses it to
+a pushed list, so Back returns to the narrative, whether or not a list was
+already beneath. **All narratives** in the switcher, in a browser, does not
+navigate this tab at all: it is a link that opens the list in a new one, on
+the same daemon (see "A new tab names its daemon" below). On native, and in
+the web app launched from the home screen, it pushes like the swipe: there is
+no tab to open, and on iOS a `_blank` link from a home-screen app lands in a
+browser view that shares none of its storage, so it would open on the meld
+screen. So does
 **Archive** in the narrative's 🦠 menu, once the daemon has confirmed it (the
 pushed list fetches on mount, and nothing is broadcast to correct a fetch that
 raced the archive); Back returns to the archived narrative. Archiving from the
@@ -137,3 +143,30 @@ come back across an in-app card tap and two tab changes. So the module-level
 consume is what gets the credentials into storage early, `clearMeldUrl` is
 what actually clears the address bar, and `clearStoredConnection` still ends
 the flow.
+
+**A new tab names its daemon.** Which melded daemon a tab is on lives in that
+tab's `sessionStorage` (`expo/lib/registry.ts`), and a tab opened from a link
+starts with none: ⌘-click, middle-click, long-press "Open in New Tab" and
+`target="_blank"` are all `noopener`, which gets no copy. It falls back to
+this browser's *default* daemon, which on a shared app with several melded
+need not be the one the link came from. So every in-app anchor names it:
+`inAppLinkProps` (the `@nid`, `nid:seq` and file links in prose, the narrate
+rows in tool groups) and `newTabLinkProps` (**All narratives**) render their
+href with `#daemon=<home brane_id>` (`DAEMON_PARAM`, `withDaemonFragment`),
+while a plain click still navigates in place by the clean path. It goes in the
+fragment because it says which daemon, not what you are looking at: it is a
+connection param (`CONNECTION_PARAMS`), and like the token it never reaches the
+shared host's edge, a daemon's request log or a link unfurler. On arrival,
+`consumeConnectionFromLocation` in `expo/lib/api.ts` hands it to
+`adoptDaemonByBraneId` at module evaluation, before the root layout reads the
+registry, and cleans it off with the token. The rules are pure functions
+beside the param (`activeDaemonBraneId`, `daemonToAdopt`), tested in
+`src/test/view-url.test.ts`; `registry.ts` only reads and writes storage for
+them. Adoption fills only an **empty** slot. The router restores the initial fragment on its first URL write (see
+above), so the param can sit in the address bar after a daemon
+switched later in that tab, and a reload must not switch back; a tab that has
+a daemon, reloaded, restored or duplicated, keeps it. A brane_id this browser
+has not melded is ignored, and the default applies. It is `daemon`, not
+`brane`, because one daemon hosts several branes and the list already filters
+by one. It names a daemon and carries no credential, so it is safe to copy.
+Isolate and Meld never carry it: their token already picks the daemon.