@justai/cuts 0.37.0 → 0.38.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.38.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>
 
@@ -106,6 +127,12 @@ 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 { name: string; bytes: ArrayBuffer | Uint8Array; mime?: string; title?: string; timeout?: number }
+  interface Saved { path: string; name: string }
 
   for (const root of document.querySelectorAll<HTMLElement>("[data-picker]")) {
     const id = root.dataset.picker!;
@@ -146,7 +173,17 @@ 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.
+    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
@@ -174,17 +211,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 +251,91 @@ 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);
+      return ask(req, (bus) =>
+        bus.proxy({
+          service: "files",
+          method: "save",
+          args: { name: req.name, bytes, mime: req.mime },
+          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(path: string): Promise<{ bytes: ArrayBuffer; blob(): Blob; dataUrl(): Promise<string> } | null> {
+      const bus = await router();
+      if (!frame.getAttribute("src")) {
+        const src = root.dataset.src!;
+        frame.setAttribute("src", src + (src.includes("?") ? "&" : "?") + PRESENTATION_PARAM + "=" + PRESENTATION_EMBEDDED);
+      }
+      const [bytes, stat] = await arrived!
+        .then(() => Promise.all([
+          bus.proxy({ service: "files", method: "read", args: { path }, options: { timeout: 30000 } }),
+          bus.proxy({ service: "files", method: "stat", args: { path }, 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>