@justai/cuts 0.30.1 → 0.32.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justai/cuts",
-  "version": "0.30.1",
-  "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
+  "version": "0.32.0",
+  "description": "A persona's named parts \u2014 the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -21,7 +21,8 @@
     "./Profile.astro": "./src/Profile.astro",
     "./ConfirmSheet.astro": "./src/ConfirmSheet.astro",
     "./Sheet.astro": "./src/Sheet.astro",
-    "./ground.css": "./src/ground.css"
+    "./ground.css": "./src/ground.css",
+    "./FilePicker.astro": "./src/FilePicker.astro"
   },
   "peerDependencies": {
     "astro": ">=5"
@@ -31,6 +32,7 @@
   },
   "dependencies": {
     "@justai/core": "^0.5.0",
-    "@justai/ui": "^0.3.0"
+    "@justai/ui": "^0.3.0",
+    "@justai/atrium": "^0.1.9"
   }
 }

package/src/FilePicker.astro

@@ -0,0 +1,171 @@
+---
+// THE GROUND rides with the picker, same as every cut — law 1 is a file it imports, not a promise.
+import "./ground.css";
+import Sheet from "./Sheet.astro";
+/**
+ * <FilePicker> — ask the PERSON for a file, from the persona's own files or from the device.
+ *
+ * WHY THIS EXISTS (founder, 2026-07-26). Every persona that needs a file has been reaching for a
+ * bare `<input type="file">`, which is one source, no memory, and the operating system's dialog
+ * rather than the persona's. His framing was the phone's:
+ *
+ *     "bazen whatsapp dan bir resim paylasirken dogrudan ya camera ya da image listesini secmen
+ *      gibi birsey"
+ *
+ * Two sources offered together — what you already have, and where you can get more. That is the
+ * shape, and it is the shape because the alternative asks a person to remember where they put
+ * something before they are allowed to look for it.
+ *
+ * ── WHAT IT ACTUALLY IS ──────────────────────────────────────────────────────────────────────
+ *
+ * A sheet containing `<persona>/files` — the file kernel, mounted by the edge on every persona host,
+ * running in THIS persona's origin. The picker does not implement picking: it asks the kernel, over
+ * atrium, and the kernel asks the person. So the rows offered here are the same rows a person sees
+ * when they open `/files` themselves, and anything taken from the device is kept, which means the
+ * second time there is nothing to upload.
+ *
+ * The call is an ordinary request whose RESPONSE happens to be a human tapping a row. Nothing polls,
+ * nothing reaches back into this page, and a cancel resolves `null` rather than throwing — choosing
+ * nothing is a choice.
+ *
+ * ── NO HOMEWORK (law 1) ──────────────────────────────────────────────────────────────────────
+ *
+ * The consumer writes no atrium, no iframe, no router, no protocol:
+ *
+ *     <FilePicker id="logoPicker" />
+ *     const picked = await document.getElementById("logoPicker").pick({ accept: "image/*" });
+ *     // → { path, name, mime, bytes } | null
+ *
+ * A method on the element rather than a global, so two pickers on one page are two pickers and
+ * nothing has to be coordinated through a name only one of them can own.
+ *
+ * ── THE FRAME IS LAZY, AND THAT IS NOT ONLY ABOUT BYTES ──────────────────────────────────────
+ *
+ * `src` is set on first open. A persona that ships this cut and is never asked for a file therefore
+ * loads no second document — which matters for LCP (the fleet's red line), and matters more for the
+ * promise: a page that has not been asked for a file has not opened the room where the files are.
+ */
+interface Props {
+  /** DOM id — what `document.getElementById(...).pick()` is called on. */
+  id: string;
+  /** The sheet's heading. The per-call `title` overrides it, for a persona that asks for two things. */
+  title?: string;
+  /** Where the kernel is mounted. Only ever changed by a test. */
+  src?: string;
+}
+const { id, title = "Choose a file", src = "/files" } = Astro.props;
+---
+
+<Sheet id={`${id}-sheet`} title={title} detent="large">
+  <div class="jfp" id={id} data-picker={id} data-src={src}>
+    {/* Empty until the first open. `title` is the accessible name of the document inside — a frame
+        announced as "frame" is the one control on the page that says nothing about itself. */}
+    <iframe class="jfp-frame" title={title} data-frame loading="lazy" allow=""></iframe>
+  </div>
+</Sheet>
+
+<style>
+  /* The frame is given the sheet's height and takes it — the kernel inside drops its own full-screen
+     minimum when it is picking, precisely so it fits somebody else's sheet instead of scrolling
+     inside it. */
+  .jfp {
+    display: flex;
+    min-height: 62dvh;
+  }
+  .jfp-frame {
+    flex: 1;
+    width: 100%;
+    border: 0;
+    background: none;
+    color-scheme: light dark;
+  }
+</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";
+
+  interface Picked { path: string; name: string; mime: string; bytes: ArrayBuffer }
+  interface PickRequest { accept?: string; title?: string; timeout?: number }
+
+  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;
+    }
+
+    async function pick(req: PickRequest = {}): Promise<Picked | null> {
+      const bus = await router();
+      if (!frame.getAttribute("src")) frame.setAttribute("src", root.dataset.src!);
+      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(() => bus
+        .proxy({
+          service: "files",
+          method: "pick",
+          args: { accept: req.accept, title: req.title },
+          options: { timeout: req.timeout ?? 300000 },
+        }))
+        .catch(() => null);
+
+      const result = await Promise.race([answered, dismissed]);
+      if (sheet.open) sheet.close();
+      return (result as Picked) ?? null;
+    }
+
+    (host as any).pick = pick;
+    (sheet as any).pick = pick;
+  }
+</script>

package/src/LangPicker.astro

@@ -50,7 +50,11 @@ const ordered = orderLocales(locales);
         every page). `name` answers it without the one risk an `id` would carry — an id must be
         unique in a document. The value is never submitted: this input lives in no form and filters
         the list client-side. */}
-    <input type="search" class="search" name="lang-search" placeholder={searchLabel} autocomplete="off" spellcheck="false" data-search aria-label={searchLabel} />
+    {/* `id` as well as `name` now. The id is the runtime-i18n hook (see <Sheet>'s title): a
+        consumer that translates in the browser re-writes this placeholder from its own dictionary.
+        Safe because the picker already assumes one instance per page — <Sheet> requires a unique
+        id and this file hardcodes `lang-sheet`. */}
+    <input type="search" class="search" id="lang-search" name="lang-search" placeholder={searchLabel} autocomplete="off" spellcheck="false" data-search aria-label={searchLabel} />
     <div class="list" role="listbox" aria-label={label} data-list>
       {ordered.map((l) => (
         <a

package/src/Sheet.astro

@@ -61,7 +61,12 @@ interface Props {
 const { id, title, detent = "medium" } = Astro.props;
 ---
 
-<dialog class="sheet" id={id} data-detent={detent} aria-label={title}>
+{/* aria-labelledby over aria-label when there IS a title, so the accessible name and the visible
+    one are the same string — and `${id}-title` is a STABLE HOOK, the same contract ConfirmSheet
+    exposes. A surface that translates at RUNTIME (the vault, the feed — one bundle, thirteen
+    languages, no per-locale routes) renders this cut in English and re-labels it from its own
+    dictionary. Without the hook such a consumer cannot adopt the cut at all, and writes its own. */}
+<dialog class="sheet" id={id} data-detent={detent} aria-labelledby={title ? `${id}-title` : undefined} aria-label={title ? undefined : "Sheet"}>
   {/* tabindex="-1" so the PANEL can take the focus when the sheet opens. Without it, showModal()
       hands focus to the first focusable descendant — which for a picker is the search field, and on
       a phone that throws the software keyboard over the list the visitor opened the sheet to read.
@@ -72,7 +77,7 @@ const { id, title, detent = "medium" } = Astro.props;
         the thing you see is the thing you can grab. Hidden from AX: Escape and the backdrop are the
         keyboard/assistive paths, and a decorative pill announced as a control is noise. */}
     <div class="sheet-grip" data-grip aria-hidden="true"><span></span></div>
-    {title && <h2 class="sheet-title">{title}</h2>}
+    {title && <h2 class="sheet-title" id={`${id}-title`}>{title}</h2>}
     <div class="sheet-body"><slot /></div>
   </div>
 </dialog>
@@ -259,6 +264,17 @@ const { id, title, detent = "medium" } = Astro.props;
       grip?.addEventListener("pointercancel", release);
     }
 
+    // WIRED ON LOAD, not on the first trigger click.
+    //
+    // It used to be lazy, and the cost of that surfaced the moment a sheet was first opened by
+    // something other than a `data-sheet-open` trigger — <FilePicker> calls showModal() itself,
+    // because its sheet opens when a persona ASKS for a file rather than when a person presses a
+    // button. A sheet opened that way had no backdrop-dismiss and no drag: two of the three ways out
+    // of it, missing, with nothing to indicate it. The laziness saved nothing worth that.
+    const wireAll = () => document.querySelectorAll<HTMLDialogElement>("dialog.sheet").forEach(wire);
+    if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", wireAll);
+    else wireAll();
+
     document.addEventListener("click", (e) => {
       const t = (e.target as HTMLElement)?.closest?.("[data-sheet-open]");
       if (!t) return;