@justai/cuts 0.133.0 → 0.138.0

package/src/behaviour/catalogue.ts

@@ -0,0 +1,239 @@
+// queries: catalogue behaviour · catalogue script · where did Catalogue.astro's script go ·
+//          testing a component's behaviour · component script is not type checked
+//
+// The catalogue — live search, the URL filter, and the deep links a campaign lands on.
+//
+// Lifted out of `Catalogue.astro`, where it was TypeScript that nothing read: a hoisted Astro script
+// goes to esbuild, which strips annotations WITHOUT checking them, and this package had no tsconfig.
+// Out here a compiler can open it and a test can call it. What stays in the component is the markup
+// and the CSS, which is what a component is.
+// queries: how does a new app appear on app.zone · my app is not on app.zone · new app missing
+//          from app.zone · runtime append registry · app.zone card unstyled · data-astro-cid
+//          insertAdjacentHTML · app.zone grid not sorted · where does a runtime card's category
+//          come from · why is an app's icon fetched from its own host
+//
+// app.zone's catalog: SSR renders the curated apps (for SEO + design); at RUNTIME we fetch the live
+// registry (api.justai.pro/api/catalog) and APPEND any persona registered since the build — a
+// *.app.zone citizen not already on the page — so a new app appears with NO app.zone redeploy.
+//
+// Two traps live in here. (1) Nodes built with insertAdjacentHTML sit OUTSIDE Astro's scoped CSS,
+// so the scope attribute has to be copied off a real card onto every injected node — forget it and
+// nothing errors, the card just renders completely unstyled. (2) The whole grid is re-sorted after
+// the append, seeds and newcomers together, so ordering is a property of the merged list, not of
+// either source. Then a `zone:cards` event lets the URL filter re-run over the newcomers.
+(function () {
+  const grid = document.getElementById("grid");
+  if (!grid) return;
+  const locale = document.documentElement.lang || "en";
+  const NEW_MS = 7 * 864e5; // a persona wears NEW only for its first week (honest — from its createdAt)
+  const newLabel = grid.dataset.newLabel || "New";
+  // queries: which personas appear on this apex · runtime append kind · why is my game not listed
+  //
+  // WHICH CITIZENS THIS APEX LISTS — where the hostname test used to be. A bundled script cannot
+  // reach this component's props, so the two facts it needs ride the same data-attribute channel as
+  // newLabel and catMap. And `kind` is asked of the registry rather than inferred from a suffix: a
+  // persona's apex is a property of the persona, not a shape of its address.
+  const apexKind = grid.dataset.kind || "app";
+  const apexHost = grid.dataset.apex || "app.zone";
+  // The category label must be localized like the SSR path (catLabel), but the API returns the
+  // category in English regardless of ?locale=. So carry this page's cat dictionary through a data
+  // attribute (same channel as newLabel) and map through it — the English key stays the stable
+  // filter value in data-category, only the visible label is translated.
+  let catMap: Record<string, string> = {};
+  try { catMap = JSON.parse(grid.dataset.catMap || "{}"); } catch (e) {}
+  const catLabel = (c: string): string => catMap[c] ?? c;
+  // The card's line, in the storefront's voice rather than the persona's — same map the SSR path
+  // reads, arriving through the same channel as the two above. Keyed by host, which the API calls
+  // `home`. Missing entry falls through to the bio, so a locale with no taglines yet, or a persona
+  // that registered after they were written, simply keeps what it had.
+  let tagMap: Record<string, string> = {};
+  try { tagMap = JSON.parse(grid.dataset.taglines || "{}"); } catch (e) {}
+
+  // hosts already on the page (don't duplicate the SSR cards)
+  const have = new Set(
+    Array.from(grid.querySelectorAll<HTMLAnchorElement>("a.card")).map((a) => {
+      try { return new URL(a.href).host; } catch { return ""; }
+    }),
+  );
+  // The appended cards must inherit CatalogueCard's scoped styles → copy the cid off a real card, and
+  // fall back to the inert one in #cardscope when this apex ships no seed. Without that fallback an
+  // empty-seed storefront renders every runtime card as unstyled markup — measured on pin.games' first
+  // night, where the shelf's only game arrived as blue underlined links.
+  const scopeTpl = document.getElementById("cardscope") as HTMLTemplateElement | null;
+  const sample = grid.querySelector<HTMLElement>("a.card")
+    ?? scopeTpl?.content.querySelector<HTMLElement>("a.card")
+    ?? null;
+  const scopeAttr = sample ? sample.getAttributeNames().find((n) => n.startsWith("data-astro-cid-")) || null : null;
+
+  const esc = (s: unknown): string =>
+    String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] as string);
+
+  type Entry = { handle: string; home: string; bio: string | null; name: string | null; avatar: string | null; glyph: string | null; category: string | null; accent: string | null; qrIcon: boolean; badge: string | null; createdAt: string | null };
+  const cardHTML = (a: Entry): string => {
+    const url = `https://${a.home}`;
+    // the persona's canonical icon, served on its own host — one face everywhere (avatar wins; glyph is gone).
+    // NO inline style. It used to carry the whole .icon rule inline, on the grounds that a node inserted with
+    // insertAdjacentHTML sits outside Astro's scoped CSS — but the append copies the cid onto every injected
+    // node, including this img, so the class does apply. What the inline copy actually did was OVERRIDE it:
+    // when the icon grew from 60px to 72px in AppCard.astro, this stayed at 60 and won on specificity, so the
+    // three seeded cards rendered a fifth larger than the seven that arrive from the registry. Nobody saw it
+    // until a reorder put them next to each other. (72 did not last — the size is back to 60, see
+    // AppCard.astro — but the trap is the same at any value: these attributes and that rule move together.)
+    // It protected nothing either: if the cid copy ever failed, the whole card would be unstyled, not just
+    // this image. One rule, in AppCard.astro.
+    const icon = `<img class="icon" src="${esc(a.avatar || `${url}/icon.svg`)}" alt="" width="60" height="60" loading="lazy" decoding="async">`;
+    // NEW only for the first week from the persona's own createdAt — never the hardcoded a.badge / a.status.
+    const created = a.createdAt ? Date.parse(a.createdAt) : NaN;
+    const isNew = Number.isFinite(created) && created <= Date.now() && Date.now() - created < NEW_MS;
+    const badge = isNew ? `<span class="badge new">${esc(newLabel)}</span>` : "";
+    const name = a.name || a.handle;
+    const cat = a.category || "";
+    // Must stay in step with AppCard.astro — this is the same card, built twice. The category span is
+    // gone from both: it lives in the filter row above the grid now.
+    return `<a class="card" href="${esc(url)}" data-name="${esc(name.toLowerCase())}" data-category="${esc(cat)}" data-id="${esc((a.handle || "").toLowerCase())}" data-added="${esc(a.createdAt || "")}">${icon}<div class="meta"><div class="top"><h2>${esc(name)}</h2>${badge}</div><p>${esc(tagMap[a.home] ?? a.bio ?? "")}</p></div><svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 18l6-6-6-6"/></svg></a>`;
+  };
+
+  fetch(`https://api.justai.pro/api/catalog?locale=${encodeURIComponent(locale)}&kind=${encodeURIComponent(apexKind)}`)
+    .then((r) => (r.ok ? r.json() : null))
+    .then((data) => {
+      if (!data || !data.personas) return;
+      const newcomers = (data.personas as Entry[]).filter(
+        // The registry already returned only this apex's kind, so all that is left to exclude is the
+          // apex itself — a household head does not stand on its own shelf.
+          //
+          // queries: auth appeared on app.zone · a persona from another apex is listed · why both
+          //          kind and home · residency
+          //
+          // TWO QUESTIONS, AND THE OLD LINE ANSWERED BOTH AT ONCE. `home.endsWith(".app.zone")` read
+          // as "is it an app" and was also, silently, "does it live here" — so replacing it with
+          // `kind` alone put `auth.justai.pro` and `justai.pro` on app.zone's shelf, both being kind
+          // `app`. Caught by comparing against the live page before deploying: fifteen cards where
+          // there had been thirteen, and a category nobody had ever seen.
+          //
+          // Both are asked now. KIND is what a persona IS — the registry's own property, and the
+          // reason a second apex can exist. RESIDENCY is where it LIVES, which is still its address.
+          (p) => p.home
+            && p.home.endsWith("." + apexHost)
+            && p.home !== apexHost && p.handle !== apexHost
+            && !have.has(p.home),
+      );
+      for (const a of newcomers) {
+        grid.insertAdjacentHTML("beforeend", cardHTML(a));
+        const el = grid.lastElementChild as HTMLAnchorElement | null;
+        if (!el) continue;
+        if (scopeAttr) {
+          el.setAttribute(scopeAttr, "");
+          el.querySelectorAll("*").forEach((n) => n.setAttribute(scopeAttr, ""));
+        }
+        try { const u = new URL(el.href); u.searchParams.set("ref", apexHost); u.searchParams.set("lang", locale); el.href = u.toString(); } catch {}
+      }
+
+      // The filter panel is rendered from the build-time seed, so a persona that registered afterwards
+      // can arrive carrying a category no row exists for — and it would then be unreachable by filter
+      // and invisible in the counts. Reconcile the panel against what is actually in the grid: every
+      // category present gets a row, and every count is recomputed rather than incremented, so this is
+      // correct however many times it runs.
+      const fpanel = document.getElementById("fpanel");
+      if (fpanel) {
+        // CLONE a row the server rendered instead of building HTML. Astro scopes per COMPONENT, so a
+        // hand-built node needs Zone.astro's own data-astro-cid-* copied onto it AND every child —
+        // forget it and nothing errors, the row just renders naked. A clone carries the cid, the tick
+        // and the inner spans with it, so that whole class of bug is gone rather than commented.
+        const proto = fpanel.querySelector<HTMLElement>('.opt[data-cat=""]');
+        const counts = new Map<string, number>();
+        for (const c of grid.querySelectorAll<HTMLAnchorElement>("a.card")) {
+          const k = c.dataset.category || "";
+          if (k) counts.set(k, (counts.get(k) || 0) + 1);
+        }
+        const allN = fpanel.querySelector<HTMLElement>('.opt[data-cat=""] .n');
+        if (allN) allN.textContent = String(grid.querySelectorAll("a.card").length);
+        for (const [cat, n] of counts) {
+          let opt = fpanel.querySelector<HTMLElement>(`.opt[data-cat="${CSS.escape(cat)}"]`);
+          if (!opt && proto) {
+            opt = proto.cloneNode(true) as HTMLElement;
+            // the prototype is the ticked "All" row — a clone must arrive unticked
+            opt.classList.remove("active");
+            opt.setAttribute("aria-pressed", "false");
+            opt.dataset.cat = cat;
+            const lb = opt.querySelector<HTMLElement>(".lb");
+            if (lb) lb.textContent = catLabel(cat);
+            fpanel.appendChild(opt);
+          }
+          if (!opt) continue;
+          const num = opt.querySelector<HTMLElement>(".n");
+          if (num) num.textContent = String(n);
+        }
+
+        // Re-sort now, because the SSR order was decided from a seed that holds a fraction of the
+        // catalog — most personas arrive here, at runtime. "All" is pinned first; the rest go
+        // biggest-first, then alphabetical, so the fullest shelf is the first one read.
+        const ordered = Array.from(fpanel.querySelectorAll<HTMLElement>(".opt")).sort((x, y) => {
+          const cx = x.dataset.cat || "", cy = y.dataset.cat || "";
+          if (!cx) return -1;
+          if (!cy) return 1;
+          const nx = counts.get(cx) || 0, ny = counts.get(cy) || 0;
+          return ny - nx || cx.localeCompare(cy);
+        });
+        for (const c of ordered) fpanel.appendChild(c);
+      }
+      // One order for the whole grid, and it is CURATED now rather than chronological: src/data/order.ts
+      // lists hosts top to bottom, and that list is the grid. Anything NOT on the list goes ABOVE it, so
+      // a persona that registers with the platform announces itself at the top with no change to this
+      // repo — the list curates what is known, it does not gate what arrives. Several unlisted arrivals
+      // sort newest-first among themselves, which is the old rule, still doing the one job it is good at.
+      //
+      // Keyed by host on purpose. The same app reaches this grid by two routes with two different
+      // identifiers — Password Generator is id "password" in the seed and handle "password-generator" in
+      // the registry — and an identifier that only matches one route fails silently on the other. A card
+      // that fails to match reads as unlisted and jumps to the top, which is the worst possible failure
+      // for an ordering bug: it looks deliberate. The host is what both routes agree on.
+      // Anything that is not a list means "no curated order" — never an exception. This parsed a
+      // `{}` once and `{}.map is not a function` killed everything after it, including the event
+      // that tells the filter new cards exist: the shelf showed a card AND "the first games are on
+      // their way" underneath it.
+      const orderList: string[] = (() => {
+        try {
+          const parsed = JSON.parse(grid.dataset.order || "[]");
+          return Array.isArray(parsed) ? parsed : [];
+        } catch { return []; }
+      })();
+      const rank = new Map(orderList.map((h, i) => [h, i]));
+      const UNLISTED = -1;
+      Array.from(grid.querySelectorAll<HTMLAnchorElement>("a.card"))
+        .map((el) => {
+          let host = "";
+          try { host = new URL(el.href).host; } catch {}
+          return { el, r: rank.has(host) ? (rank.get(host) as number) : UNLISTED, added: el.getAttribute("data-added") || "" };
+        })
+        .sort((x, y) => {
+          if (x.r !== y.r) return x.r - y.r;      // listed follow the list; unlisted (-1) sort above all
+          if (x.r !== UNLISTED) return 0;         // two listed cards cannot share a rank
+          if (x.added === y.added) return 0;      // both unlisted → newest first, undated last
+          if (!x.added) return 1;
+          if (!y.added) return -1;
+          return x.added < y.added ? 1 : -1;
+        })
+        .forEach(({ el }) => grid.appendChild(el));
+      // queries: the empty message shows under a card · zone:cards never fired · the filter did not
+      //          see the new cards · silent catch
+      //
+      // IN A `finally`, BECAUSE EVERYTHING ABOVE IT IS ORNAMENT AND THIS IS NOT. Once cards are in
+      // the DOM, the filter has to be told — it owns which of them are visible and whether the
+      // "nothing here" line is showing. Sorting them is a nicety; leaving the page claiming to be
+      // empty while a card sits above the claim is a defect a visitor sees.
+      //
+      // It sat at the end of a promise chain ending in `.catch(() => {})`, so one TypeError in the
+      // sort silenced it with nothing logged anywhere. That combination — a throw between the work
+      // and its announcement, and a catch that says nothing — is how a page ends up confidently
+      // wrong. The `finally` fixes the ordering; the catch below now says what it swallowed.
+    })
+    .catch((err) => {
+      // Never fatal — a storefront must render without the registry. But it must not be SILENT:
+      // the seed and the build-time layer are already on the page, and a swallowed error here is
+      // the difference between "no new personas today" and "the append is broken".
+      console.warn("[catalogue] runtime append failed", err);
+    })
+    .finally(() => {
+      document.dispatchEvent(new Event("zone:cards")); // cards are in — let the filter catch them
+    });
+})();

package/src/behaviour/filePicker.ts

@@ -0,0 +1,372 @@
+// queries: filePicker behaviour · filepicker script · where did FilePicker.astro's script go ·
+//          testing a component's behaviour · component script is not type checked
+//
+// The file picker — the door to a persona's own file system.
+//
+// Lifted out of `FilePicker.astro`, where it was TypeScript that nothing read: a hoisted Astro script
+// goes to esbuild, which strips annotations WITHOUT checking them, and this package had no tsconfig.
+// Out here a compiler can open it and a test can call it. What stays in the component is the markup
+// and the CSS, which is what a component is.
+// queries: how do I ask for a file from a persona · FilePicker pick method · the file picker
+//          returns null · picker sheet does not open · atrium router for the picker
+//
+// ONE ROUTER PER PICKER, created on first open.
+//
+// The kernel in the frame discovers UPWARD — that is atrium's own rule, and it is what makes the
+// embed the invitation. So this page has to be a router before the frame can connect, and it names
+// its guest through `mount()` rather than trusting what the guest calls itself: a persona composing
+// two kernels at once would otherwise have both arrive calling themselves "files", and the second
+// would silently take the first one's place.
+import atrium from "@justai/atrium";
+import { PRESENTATION_PARAM, PRESENTATION_EMBEDDED } from "@justai/core";
+
+// queries: file id or path · which one should a persona remember · does renaming break a
+//          reference · the durable handle for a file
+//
+// A **path** is where a file is standing right now, and it is how a PERSON says where something
+// is. Rename it and every path to it is a dangling string that still looks perfectly valid. An
+// **id** is the file: the kernel has stamped a `crypto.randomUUID()` on every node since the
+// first write, and `mv` never touches it.
+//
+// So a caller reacting to something a person just did may use a path. A caller REMEMBERING a
+// file across time — a project pointing at its logo, a document being saved back — must use the
+// id, and both are handed over here so that choice is available rather than argued for.
+interface Picked {
+  path: string;
+  /** WHAT IT IS, not where it is standing. Survives a rename and a move — remember this one. */
+  id: string;
+  name: string;
+  mime: string;
+  bytes: ArrayBuffer;
+  /** The same file as a Blob — for URL.createObjectURL, an upload body, an <img> src. */
+  blob(): Blob;
+  /** The same file as a data: URL — for anything that must EMBED it (an SVG, a saved document). */
+  dataUrl(): Promise<string>;
+}
+interface PickRequest { accept?: string; title?: string; timeout?: number }
+/**
+ * What a persona hands over to be kept. `name` is a PROPOSAL — the person may rewrite it and
+ * will choose the folder — so give it the best default you have, extension included.
+ */
+interface SaveRequest {
+  /** A PROPOSAL. The person may rewrite it — the extension is shown beside the field, not in it. */
+  name?: string;
+  /** The persona's format. Kept out of the name box, the way a desktop save dialog keeps it out. */
+  ext?: string;
+  /** Save BACK to a file already saved once. NO QUESTION IS ASKED: it was answered the first time. */
+  id?: string;
+  bytes: ArrayBuffer | Uint8Array;
+  /**
+   * THE FILE'S FACE — the ecosystem's optional standard, and worth taking.
+   *
+   * Most files can show themselves; a persona's OWN format cannot, and the persona is the only
+   * thing in the system that knows what it looks like. Hand over a small render (a 256px PNG is
+   * plenty) and the file has a face in the list and in its detail sheet instead of a large empty
+   * box saying there is no preview for this kind. Say nothing and nothing is lost.
+   *
+   * Kept small on purpose: the kernel drops a face over 64 KB rather than let a thumbnail become
+   * a second copy of the work in an evictable quota. Over the ceiling the FILE is still written —
+   * a cosmetic loss must never become a refused save.
+   */
+  thumb?: ArrayBuffer | Uint8Array | Blob;
+  mime?: string;
+  title?: string;
+  timeout?: number;
+}
+interface Saved { path: string; id: string; name: string }
+
+for (const root of document.querySelectorAll<HTMLElement>("[data-picker]")) {
+  const id = root.dataset.picker!;
+  const host = document.getElementById(id) ?? root.closest("dialog");
+  const found = document.getElementById(`${id}-sheet`) as HTMLDialogElement | null;
+  const frame = root.querySelector<HTMLIFrameElement>("[data-frame]")!;
+  if (!found) continue;
+  const sheet = found;
+
+  let svc: any = null;
+  // THE GUEST HAS TO ARRIVE BEFORE ANYONE CAN BE ASKED ANYTHING.
+  //
+  // Caught by this cut's own spec on its first run, and it failed in the shape this ecosystem
+  // keeps naming: nothing threw where a person could see it. `proxy()` to a service that has not
+  // connected yet rejects immediately, the rejection was swallowed into `null`, and the sheet
+  // opened and closed again inside one frame — a picker that "just doesn't work", with a clean
+  // console. The frame is created on the first open, so the very first pick is ALWAYS the race.
+  //
+  // atrium already announces the arrival; this simply waits for it. Resolved once and kept: the
+  // guest connects once and stays.
+  let arrived: Promise<void> | null = null;
+  async function router() {
+    if (svc) return svc;
+    // A name of our own, so a persona already running atrium for something else is not disturbed.
+    //
+    // DERIVED FROM THE DOM id, AND SANITISED. atrium's ids are a grammar, not free text — "/"
+    // separates hops in a service path, so it rejects anything outside [a-z0-9._-]. A DOM id is
+    // free text, and `picker:logoPicker` threw on the very first run of this cut's own spec. The
+    // consumer must not have to know atrium's grammar to name a picker; that is the homework law.
+    svc = await atrium({
+      id: "picker-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "x"),
+      router: true,
+      mount: ({ source }: any) => (source === frame.contentWindow ? "files" : null),
+    });
+    arrived = new Promise<void>((resolve) => {
+      svc.on("connected", (e: any) => { if (e?.name === "files") resolve(); });
+    });
+    return svc;
+  }
+
+  // queries: the picker and the saver share one frame · why is save a method on the picker ·
+  //          asking the kernel over atrium · one sheet two questions
+  //
+  // ONE FRAME, ONE BUS, TWO QUESTIONS. Everything below the proxy call is identical for asking
+  // for a file and for handing one over — the lazy frame, the presentation declaration, the
+  // heading, the two ways a sheet can end. Extracted so the second question inherits the first
+  // one's scars instead of being written again and re-earning them.
+  // Set the frame's src on first use. THREE callers need it now, and the presentation declaration
+  // must be identical in all three — a fourth that copied it slightly wrong is how a page ends up
+  // announcing itself as standalone on the one path that forgot to say otherwise.
+  function ensureFrame() {
+    if (frame.getAttribute("src")) return;
+    // DECLARE THE PRESENTATION. A page opened by a person and a page opened by another persona
+    // are two different situations, and the same controls do not belong in both — standalone
+    // there is nothing to cancel. The frame is the slower truth (a handshake takes a beat), so
+    // the declaration rides in the URL and is available in the first paint. It is presentation
+    // only: nothing that must not be forged is decided by it.
+    const src = root.dataset.src!;
+    frame.setAttribute("src", src + (src.includes("?") ? "&" : "?") + PRESENTATION_PARAM + "=" + PRESENTATION_EMBEDDED);
+  }
+
+  async function ask<T>(
+    req: { title?: string },
+    invoke: (bus: any) => Promise<T>,
+  ): Promise<T | null> {
+    const bus = await router();
+    ensureFrame();
+    // ONE HEADING, and it is the sheet's. A per-call title retitles the sheet rather than being
+    // forwarded into the frame: the kernel renders a heading of its own for callers that have no
+    // sheet around them, and sending it one here printed "Upload logo" twice, one under the other.
+    const heading = sheet.querySelector<HTMLElement>(".sheet-title");
+    if (heading && req.title) heading.textContent = req.title;
+    sheet.showModal();
+
+    // TWO WAYS THIS ENDS, and only one of them is the kernel's.
+    //
+    // The person may answer inside the frame — that is the real reply. Or they may dismiss the
+    // sheet from OUT here, with Escape or the backdrop, which the kernel cannot see: it is a
+    // different document and nobody told it. So the dismissal resolves this promise with `null`
+    // and the kernel's later answer is dropped. Racing them is deliberate; the alternative is a
+    // caller left waiting on a sheet that is no longer on the screen.
+    const dismissed = new Promise<null>((resolve) => {
+      sheet.addEventListener("close", () => resolve(null), { once: true });
+    });
+    const answered = arrived!.then(() => invoke(bus)).catch(() => null);
+
+    const result = await Promise.race([answered, dismissed]);
+    if (sheet.open) sheet.close();
+    return (result as T) ?? null;
+  }
+
+  async function pick(req: PickRequest = {}): Promise<Picked | null> {
+    const result = await ask(req, (bus) =>
+      bus.proxy({
+        service: "files",
+        method: "pick",
+        // `hostExit`: this cut draws the way out in its own sheet's bar, so the kernel must not
+        // draw a second one in its footer beside the three sources. TOLD, never inferred — the
+        // kernel is also embedded by hosts that frame it bare and give it no chrome at all, and
+        // one that hid its own exit on a guess would leave that person unable to answer "nowhere".
+        args: { accept: req.accept, hostExit: true },
+        options: { timeout: req.timeout ?? 300000 },
+      }));
+    if (!result) return null;
+
+    // THE CUT BRINGS ITS OWN GROUND, and bytes are not ground. Every consumer of this needs the
+    // file in some other shape, and the obvious hand-written conversion is a trap:
+    //
+    //     btoa(String.fromCharCode(...new Uint8Array(bytes)))
+    //
+    // makes one argument per BYTE, so a 7.5 MB photo is a 7.5-million-argument call and the stack
+    // gives out — "Maximum call stack size exceeded", thrown far from anything that mentions size,
+    // and invisible to any test whose fixture image is small. qr wrote exactly that line and a
+    // person found it with a real photograph. It belongs here once, not in every persona.
+    const r = result as any;
+    const blob = () => new Blob([r.bytes], { type: r.mime });
+    return {
+      ...r,
+      blob,
+      dataUrl: () => new Promise<string>((resolve, reject) => {
+        const rd = new FileReader();
+        rd.onload = () => resolve(rd.result as string);
+        rd.onerror = () => reject(rd.error);
+        rd.readAsDataURL(blob());   // no ceiling, unlike the spread above
+      }),
+    } as Picked;
+  }
+
+  // queries: FilePicker save method · how does a persona keep what it made · save a project file ·
+  //          the persona project file · save returns null
+  //
+  // THE OTHER DIRECTION. A persona that makes something has, until now, had exactly two ways to
+  // give it to the person who made it: the operating system's download folder, or a link they
+  // must keep themselves. Both mean "you take it from here" — the persona forgets immediately,
+  // and coming back tomorrow starts from nothing.
+  //
+  // This is the third: hand it to the person's own files, in this persona's origin, under a name
+  // they chose. It is not `write` — the caller does not decide the name or the folder, because
+  // those are what make a saved thing findable later and they are the person's to answer.
+  //
+  //     await el.save({ name: "café wifi.qr", bytes, mime: "application/vnd.justai.qr+json" })
+  //     // → { path, name } | null
+  //
+  // `null` is a person declining, and it is not an error — the same posture a cancelled pick has.
+  async function save(req: SaveRequest): Promise<Saved | null> {
+    // THE CUT BRINGS ITS OWN GROUND. A caller holding a Uint8Array (which anything that encoded
+    // text does) would otherwise have to know that the kernel wants the buffer, and that a typed
+    // array's `.buffer` may be a larger pool it is only a window onto — a subtle way to save a
+    // file with somebody else's bytes stuck to the end of it.
+    // THE CUT BRINGS ITS OWN GROUND for both payloads. A caller holds whatever its work produced
+    // — a typed array from an encoder, a Blob from a canvas — and must not have to know that a
+    // typed array's `.buffer` may be a larger pool it is only a window onto, which is a subtle
+    // way to save a file with somebody else's bytes stuck to the end of it.
+    const buffer = async (v: any): Promise<ArrayBuffer | undefined> => {
+      if (!v) return undefined;
+      if (v instanceof ArrayBuffer) return v;
+      if (typeof Blob !== "undefined" && v instanceof Blob) return v.arrayBuffer();
+      return v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength);
+    };
+    const bytes = (await buffer(req.bytes))!;
+    const thumb = await buffer(req.thumb);
+    const args = { name: req.name, ext: req.ext, id: req.id, bytes, thumb, mime: req.mime };
+    // SAVING BACK OPENS NO SHEET, and that is the point rather than an optimisation. The person
+    // named this file the first time; asking again on every save is not care, it is a persona
+    // that cannot remember what it is working on. So this path never touches `ask`.
+    //
+    // BY ID AND NOT BY PATH: between opening a document and saving it, the person may have
+    // renamed or moved it in the very list they are looking at. A path captured at open time
+    // would then either miss — a second copy appearing under the old name — or land on whatever
+    // has since taken that name, which is worse and completely silent.
+    if (req.id) {
+      const bus = await router();
+      ensureFrame();
+      return arrived!
+        .then(() => bus.proxy({ service: "files", method: "save", args, options: { timeout: req.timeout ?? 60000 } }))
+        .catch(() => null) as Promise<Saved | null>;
+    }
+    return ask(req, (bus) =>
+      bus.proxy({ service: "files", method: "save", args, options: { timeout: req.timeout ?? 300000 } }));
+  }
+
+  // queries: read a file the persona already has a path to · FilePicker read · restore an asset a
+  //          project points at · read without asking the person · does read open the sheet
+  //
+  // THE ONE VERB THAT ASKS NOBODY, AND WHY THAT IS NOT A HOLE.
+  //
+  // `pick` and `save` are interactions: the person answers. `read` is not — it takes a path the
+  // person ALREADY gave, on an earlier pick, and it exists because of what the alternative costs.
+  //
+  // A project file that references an asset ("this code wears that logo") is small. One that
+  // swallows a copy is not: a 7.5 MB photograph is ~10 MB as base64, saved again on every edit,
+  // and the kernel keeps five versions — 50 MB of an evictable ~1 GB quota, for one logo. The
+  // kernel's own corpus warns that a full origin does not merely lose history, it loses the
+  // CURRENT file. So references are the correct shape, and a reference nobody can follow is not
+  // a reference.
+  //
+  // It opens no sheet, because there is no question. The policy still answers "who is asking" —
+  // same-origin only, exactly as every other capability — so this widens no door: a caller that
+  // could not read here a moment ago still cannot.
+  async function read(ref: string | { path?: string; id?: string }): Promise<{ bytes: ArrayBuffer; blob(): Blob; dataUrl(): Promise<string> } | null> {
+    // A bare string is a PATH, because that is what a string reads as. An id must be said out
+    // loud — `read({ id })` — so a caller holding one kind can never pass it as the other.
+    const where = typeof ref === "string" ? { path: ref } : ref;
+    const bus = await router();
+    ensureFrame();
+    const [bytes, stat] = await arrived!
+      .then(() => Promise.all([
+        bus.proxy({ service: "files", method: "read", args: where, options: { timeout: 30000 } }),
+        bus.proxy({ service: "files", method: "stat", args: where, options: { timeout: 30000 } }),
+      ]))
+      .catch(() => [null, null]);
+    // A file the person deleted since is simply gone. `null` rather than a throw: a caller
+    // restoring a project must be able to carry on without the asset, and an exception here
+    // would take the whole project down with the logo.
+    if (!bytes) return null;
+    const blob = () => new Blob([bytes as ArrayBuffer], { type: (stat as any)?.mime || "application/octet-stream" });
+    return {
+      bytes: bytes as ArrayBuffer,
+      blob,
+      dataUrl: () => new Promise<string>((resolve, reject) => {
+        const rd = new FileReader();
+        rd.onload = () => resolve(rd.result as string);
+        rd.onerror = () => reject(rd.error);
+        rd.readAsDataURL(blob());
+      }),
+    };
+  }
+
+  // queries: write a file without asking · FilePicker write · a persona's own cached asset ·
+  //          keep a dependency a project points at · write vs save · save asks and I do not want
+  //          to ask · store a file the person did not make · project dependency from outside files
+  //
+  // THE SECOND VERB THAT ASKS NOBODY, AND THE ONE THAT WAS MISSING.
+  //
+  // `save` is deliberately not a friendlier `write`. The kernel's own corpus states the split and
+  // it is not about permission — both write the same origin under the same policy:
+  //
+  //   `write` is arithmetic and keeps the PERSONA's things — a cached asset, a draft it will
+  //   reopen itself. `save` is an interaction and hands a person THEIRS, because the two questions
+  //   that make a saved document a document — what is it called, where does it go — are the
+  //   person's to answer.
+  //
+  // The service has had `write` since the beginning. This door did not expose it, and for fifteen
+  // personas that was invisible, because the only project dependency anybody had was `qr`'s logo —
+  // which arrives through `pick`, so it is already in files and already has an id.
+  //
+  // `3dviewer` is the first persona whose dependency comes from OUTSIDE: a model dragged off a
+  // desktop. Its project file must point at that model, so the model needs a home — and it is not
+  // a document the person made here, it is the asset this persona will reopen itself. Exactly the
+  // case the paragraph above describes, with no verb to express it. The persona was left choosing
+  // between a doctrine it could not follow and a second Save sheet asking somebody to name a file
+  // they did not create.
+  //
+  // ADDITIVE, and that matters: nothing that exists behaves differently. The policy still answers
+  // "who is asking" — same-origin only, exactly as `read` does — so this widens no door.
+  //
+  // It returns the NODE, because a caller writing a project dependency needs the `id`: a path is
+  // what a person renames and an id is what a thing IS.
+  async function write(
+    path: string,
+    bytes: ArrayBuffer | Uint8Array,
+    opts: { mime?: string; keepVersions?: number } = {},
+  ): Promise<{ id: string; name: string; path: string } | null> {
+    const bus = await router();
+    ensureFrame();
+    const body = bytes instanceof Uint8Array
+      ? (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+          ? bytes.buffer
+          : bytes.slice().buffer)
+      : bytes;
+    const node = await arrived!
+      .then(() => bus.proxy({
+        service: "files",
+        method: "write",
+        args: { path, bytes: body, mime: opts.mime, keepVersions: opts.keepVersions },
+        // The same 30s ceiling `read` uses. A model is tens of megabytes and a phone's storage is
+        // not fast; the default would time out on exactly the files this verb exists for.
+        options: { timeout: 30000 },
+      }))
+      .catch(() => null);
+    // A quota that is full, or a path the kernel refused. `null` rather than a throw, for the same
+    // reason `read` returns null: a caller must be able to carry on and say so.
+    if (!node) return null;
+    const n = node as { id: string; name: string };
+    return { id: n.id, name: n.name, path };
+  }
+
+  (host as any).pick = pick;
+  (sheet as any).pick = pick;
+  (host as any).save = save;
+  (sheet as any).save = save;
+  (host as any).read = read;
+  (sheet as any).read = read;
+  (host as any).write = write;
+  (sheet as any).write = write;
+}