@justai/cuts 0.38.0 → 0.39.0

package/package.json

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

package/src/FilePicker.astro

@@ -116,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;
@@ -131,8 +144,19 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
    * 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 }
+  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!;
@@ -180,20 +204,26 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
     // 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.
@@ -275,13 +305,24 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
       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: { name: req.name, bytes, mime: req.mime },
-          options: { timeout: req.timeout ?? 300000 },
-        }));
+        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
@@ -302,16 +343,16 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
     // 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> {
+    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();
-      if (!frame.getAttribute("src")) {
-        const src = root.dataset.src!;
-        frame.setAttribute("src", src + (src.includes("?") ? "&" : "?") + PRESENTATION_PARAM + "=" + PRESENTATION_EMBEDDED);
-      }
+      ensureFrame();
       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 } }),
+          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