@justai/cuts 0.133.0 → 0.139.0

package/src/FilePicker.astro

@@ -124,368 +124,7 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
   }
 </style>
 
-<script>
-  // 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;
-  }
-</script>
+  <script>
+    // The behaviour lives in ./behaviour/filePicker.ts — see that file for why it is not in here.
+    import "./behaviour/filePicker";
+  </script>

package/src/LangPicker.astro

@@ -124,66 +124,7 @@ const ordered = orderLocales(locales);
   .item svg { width: 17px; height: 17px; flex: none; }
 </style>
 
-<script>
-  // What is left here is only what the LIST does: filter, and remember the choice. Opening,
-  // dismissing and dragging all belong to <Sheet>.
-  const picker = document.querySelector<HTMLElement>("[data-picker]");
-  if (picker) {
-    const trigger = picker.querySelector<HTMLButtonElement>("[data-trigger]")!;
-    const sheet = document.getElementById("lang-sheet") as HTMLDialogElement | null;
-    const search = picker.querySelector<HTMLInputElement>("[data-search]")!;
-    const items = Array.from(picker.querySelectorAll<HTMLAnchorElement>(".item"));
-
-    function filter() {
-      const q = search.value.trim().toLowerCase();
-      for (const it of items) {
-        it.style.display = (it.dataset.name ?? "").includes(q) ? "" : "none";
-      }
-    }
-    search.addEventListener("input", filter);
-
-    trigger.addEventListener("click", () => {
-      trigger.setAttribute("aria-expanded", "true");
-      search.value = "";
-      filter();
-      // Focus the search ONLY where a hardware keyboard is already present. On a touch device,
-      // focusing would throw the software keyboard over the list you opened the sheet to read — iOS
-      // shows the list first and lets you reach for search. This is NOT a desktop/mobile branch of
-      // the EXPERIENCE (the sheet is identical everywhere); it is a fact about input hardware, which
-      // is why it asks about the pointer rather than about the viewport.
-      if (matchMedia("(pointer: fine)").matches) setTimeout(() => search.focus(), 60);
-    });
-    sheet?.addEventListener("close", () => trigger.setAttribute("aria-expanded", "false"));
-
-    // queries: language picker does not close · choosing a language does nothing · route-less
-    //          locale switch · the sheet stays open after picking a language · /me /files language
-    //
-    // Remember the choice, then GO — and "go" has two shapes, because two kinds of consumer exist.
-    //
-    // A persona with per-locale routes navigates to /<lang>/, carrying the section it was on. A
-    // ROUTE-LESS surface — /me, /files: one bundle mounted at one path on thirteen hosts, translated
-    // in the browser — hands back the page it is already on, because there is nowhere else to go.
-    //
-    // The second case was broken from the day those surfaces adopted this cut, and it broke quietly:
-    // `location.assign("/me" + "#kernel")` on a page already at `/me#kernel` is the SAME URL, so the
-    // browser correctly does nothing. The choice was written to localStorage, no navigation
-    // happened, the sheet stayed open and the words stayed English. It looked like a picker that
-    // ignores you.
-    for (const it of items) {
-      it.addEventListener("click", (e) => {
-        try { localStorage.setItem("lang", it.dataset.lang ?? "en"); } catch { /* a locked jar is not a reason to refuse the click */ }
-        const href = it.getAttribute("href");
-        if (!href) return;
-        const to = new URL(href, location.href);
-        if (to.pathname === location.pathname && to.search === location.search) {
-          // Same document: the only way to re-render is to reload it.
-          e.preventDefault();
-          location.reload();
-          return;
-        }
-        // preserve the section you're viewing (Profile/Kernel/Posts) across the language switch
-        if (location.hash) { e.preventDefault(); location.assign(href + location.hash); }
-      });
-    }
-  }
-</script>
+  <script>
+    // The behaviour lives in ./behaviour/langPicker.ts — see that file for why it is not in here.
+    import "./behaviour/langPicker";
+  </script>