@justai/cuts 0.37.0 → 0.39.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justai/cuts",
-  "version": "0.37.0",
-  "description": "A persona's named parts \u2014 the page shell that holds them, and the cuts themselves.",
+  "version": "0.39.0",
+  "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",

package/src/FilePicker.astro

@@ -36,6 +36,21 @@ import Sheet from "./Sheet.astro";
  *     const picked = await document.getElementById("logoPicker").pick({ accept: "image/*" });
  *     // → { path, name, mime, bytes } | null
  *
+ * ── IT ALSO GOES THE OTHER WAY (2026-07-27) ──────────────────────────────────────────────────
+ *
+ * The same element hands something BACK, which is how a persona keeps what a person made instead
+ * of pushing it into the operating system's downloads and forgetting it:
+ *
+ *     const saved = await document.getElementById("logoPicker").save({
+ *       name: "café wifi.qr", bytes, mime: "application/vnd.justai.qr+json",
+ *     });
+ *     // → { path, name } | null
+ *
+ * One element rather than two cuts, because it is one room: two frames would be two documents,
+ * two atrium routers and two copies of the same kernel open at once, to ask the same file system
+ * a question in each direction. The name stays `FilePicker` for now and that is a small debt —
+ * what it actually is, is the persona's door to its files.
+ *
  * 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.
  *
@@ -60,7 +75,13 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
   <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>
+    {/* NO `loading="lazy"`, and its removal is a fix rather than a tidy-up.
+        The laziness that matters is the SRC, which is empty until somebody asks — so the attribute
+        bought nothing, and it cost the one call that opens no sheet. A lazy frame inside a closed
+        <dialog> is display:none, which the browser reads as "not near the viewport", so it defers
+        the load forever: `read()` waited on a guest that was never going to arrive, and it waited
+        silently. Caught by this cut's own spec, which is the whole argument for law 2. */}
+    <iframe class="jfp-frame" title={title} data-frame allow=""></iframe>
   </div>
 </Sheet>
 
@@ -95,8 +116,21 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
   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;
@@ -106,6 +140,23 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
     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;
+    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!;
@@ -146,17 +197,33 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
       return svc;
     }
 
-    async function pick(req: PickRequest = {}): Promise<Picked | null> {
+    // 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();
-      if (!frame.getAttribute("src")) {
-        // 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);
-      }
+      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.
@@ -174,17 +241,21 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
       const dismissed = new Promise<null>((resolve) => {
         sheet.addEventListener("close", () => resolve(null), { once: true });
       });
-      const answered = arrived!.then(() => bus
-        .proxy({
+      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",
           args: { accept: req.accept },
           options: { timeout: req.timeout ?? 300000 },
-        }))
-        .catch(() => null);
-
-      const result = await Promise.race([answered, dismissed]);
-      if (sheet.open) sheet.close();
+        }));
       if (!result) return null;
 
       // THE CUT BRINGS ITS OWN GROUND, and bytes are not ground. Every consumer of this needs the
@@ -210,7 +281,102 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
       } 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.
+      const b: any = req.bytes;
+      const bytes: ArrayBuffer =
+        b instanceof ArrayBuffer ? b : b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+      const args = { name: req.name, ext: req.ext, id: req.id, bytes, 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());
+        }),
+      };
+    }
+
     (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;
   }
 </script>