@justai/cuts 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -22,7 +22,9 @@
     "./ConfirmSheet.astro": "./src/ConfirmSheet.astro",
     "./Sheet.astro": "./src/Sheet.astro",
     "./ground.css": "./src/ground.css",
-    "./FilePicker.astro": "./src/FilePicker.astro"
+    "./FilePicker.astro": "./src/FilePicker.astro",
+    "./ActionList.astro": "./src/ActionList.astro",
+    "./ActionRow.astro": "./src/ActionRow.astro"
   },
   "peerDependencies": {
     "astro": ">=5"

package/src/ActionList.astro

@@ -0,0 +1,68 @@
+---
+// THE GROUND rides with the list, same as every cut — law 1 is a file it imports, not a promise.
+import "./ground.css";
+/**
+ * <ActionList> — a group of verbs, in the shape a phone has taught everyone to read.
+ *
+ * The inset grouped list: one rounded card, hairline-separated rows, full width. It is what iOS
+ * uses for actions in Files, Photos, Mail and Settings, and it is here because a row of side-by-side
+ * buttons stops working at exactly the width this ecosystem designs for.
+ *
+ * ── USE ──────────────────────────────────────────────────────────────────────────────────────
+ *
+ *     <ActionList>
+ *       <ActionRow id="open" tone="accent" label="Open in qr"><svg slot="icon" …/></ActionRow>
+ *       <ActionRow id="rename" label="Rename"><svg slot="icon" …/></ActionRow>
+ *     </ActionList>
+ *     <ActionList>
+ *       <ActionRow id="delete" tone="danger" label="Delete"><svg slot="icon" …/></ActionRow>
+ *     </ActionList>
+ *
+ * TWO LISTS RATHER THAN ONE IS THE GRAMMAR, not a styling choice. A group break is what separates
+ * "things you might do" from "the door with no way back", and on a phone that gap is the only
+ * protection standing between a thumb and a delete.
+ *
+ * ── WHY IT IS A COMPONENT AND NOT A CLASS TO COPY ────────────────────────────────────────────
+ *
+ * The founder's framing, 2026-07-27: the ecosystem is being built as a mobile app that happens to
+ * live on the web, and reusable Apple-grade parts are how that survives contact with a hundred
+ * personas. A class name copied into each persona is the O(N) shape this fleet keeps ruling out —
+ * one bump here has to be able to reach every sheet that shows a verb.
+ */
+interface Props {
+  /** An optional group heading, as a phone's settings list has. Sentence case, no shouting. */
+  title?: string;
+  /** A line under the group, for the thing a person needs to know BEFORE choosing. */
+  note?: string;
+}
+const { title, note } = Astro.props;
+---
+
+<div class="jal-group">
+  {title && <h3 class="jal-title">{title}</h3>}
+  <div class="jal"><slot /></div>
+  {note && <p class="jal-note">{note}</p>}
+</div>
+
+<style>
+  .jal-group { display: flex; flex-direction: column; gap: 7px; }
+  /* Inset and grouped: the card is the group, and `overflow: hidden` is what lets a row's own
+     background reach the rounded corner instead of squaring it off on press. */
+  .jal {
+    display: flex;
+    flex-direction: column;
+    background: var(--surface-2);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-md);
+    overflow: hidden;
+  }
+  .jal-title {
+    font-size: var(--fs-xs);
+    font-weight: 600;
+    color: var(--text-dim);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    padding-inline: 4px;
+  }
+  .jal-note { font-size: var(--fs-xs); color: var(--text-dim); padding-inline: 4px; line-height: 1.45; }
+</style>

package/src/ActionRow.astro

@@ -0,0 +1,123 @@
+---
+// THE GROUND rides with the row, same as every cut — law 1 is a file it imports, not a promise.
+import "./ground.css";
+/**
+ * <ActionRow> — one verb in an <ActionList>. A full-width row: icon, label, and room to be read.
+ *
+ * WHY IT IS A ROW AND NOT A BUTTON IN A LINE (founder, 2026-07-27). files' detail sheet put four
+ * buttons shoulder to shoulder and two of the four labels came out clipped — "Open i…", "Downl…".
+ * The founder named the feeling before the cause:
+ *
+ *     "kullanici mobile cozunurlukte calistigi icin ux deneyimini insanin icini daraltacak sekilde
+ *      tasarmamamiz gerekiyor … 4 adet butonu yan yana yaparak bu hissi bana verdin"
+ *
+ * The CSS was the confession: `text-overflow: ellipsis` on a control's own label means the layout
+ * had already lost the argument with the space it had. A phone column is ~480px; four equal
+ * controls with icons and words do not fit, and no amount of tightening makes them fit.
+ *
+ * iOS answers this the same way everywhere it matters — Files, Photos, Mail, Settings: verbs live
+ * in an INSET GROUPED LIST. Full width each, never truncated, and the list grows without a
+ * redesign, which is the property that actually decides it here: this sheet is about to gain
+ * Share, versions and restore.
+ *
+ * ── TONE, AND WHY DESTRUCTIVE IS NOT JUST A COLOUR ───────────────────────────────────────────
+ *
+ * `accent` is the reason the sheet is open. `danger` is a door you cannot walk back through, and it
+ * belongs in a group of its OWN — a row's-width of separation is the cheapest protection there is,
+ * and it is why Delete never sits shoulder to shoulder with Rename in a well-made sheet.
+ */
+interface Props {
+  /** DOM id, so a consumer wires it exactly as it wired a button. */
+  id?: string;
+  /** The verb. Written in full — this row has the width for it. */
+  label: string;
+  /** `plain` (default) · `accent` for the reason you came · `danger` for the door with no way back. */
+  tone?: "plain" | "accent" | "danger";
+  /** A value or hint shown at the trailing edge — a size, a count, a chosen option. */
+  detail?: string;
+  /** Start hidden; a consumer reveals it when it applies (files does this for "Open in …"). */
+  hidden?: boolean;
+  // queries: translate an action row · data-i on ActionRow · setting textContent wiped the icon
+  //
+  // THE LABEL IS ADDRESSABLE, and that is not a convenience.
+  //
+  // A route-less surface translates in the browser, which means something writes `textContent` onto
+  // the element that holds a word. Point that at the ROW and it erases the icon along with the
+  // label, because the icon is a child of the same button — a whole class of bug that ships looking
+  // like "the icons disappeared in Turkish".
+  //
+  // So the row exposes its label two ways: `i18n` puts the key on the label span for a dictionary
+  // sweep, and the span carries `<id>-label` so a consumer with one string to set can address it
+  // without knowing this component's internals.
+  /** Key for a runtime translator — lands on the LABEL, never on the row. */
+  i18n?: string;
+}
+const { id, label, tone = "plain", detail, hidden, i18n } = Astro.props;
+---
+
+<button class:list={["jal-row", tone !== "plain" && `is-${tone}`]} type="button" id={id} hidden={hidden}>
+  <span class="jal-ico" aria-hidden="true"><slot name="icon" /></span>
+  <span class="jal-label" id={id ? `${id}-label` : undefined} data-i={i18n}>{label}</span>
+  {detail && <span class="jal-detail">{detail}</span>}
+</button>
+
+<style>
+  /* A ROW, not a button in a line: it takes the full width it is given, so the label is never the
+     thing that has to shrink. The 44px floor is the one number iOS never moves — it is a fingertip,
+     and `min-height` rather than a fixed height so a reader who raised their text size gets a
+     taller row instead of a clipped one. */
+  .jal-row {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    width: 100%;
+    min-height: 44px;
+    padding: 11px 14px;
+    border: 0;
+    background: none;
+    color: var(--text);
+    font: inherit;
+    font-size: var(--fs-sm);
+    font-weight: 500;
+    text-align: start;
+    cursor: pointer;
+    /* The separator lives on the row and is removed from the last one by the list — so a row can be
+       hidden or revealed without leaving a hairline hanging under nothing. */
+    border-block-end: 1px solid var(--border);
+    transition: background 0.15s;
+  }
+  .jal-row:last-child,
+  .jal-row[hidden] + .jal-row:last-child { border-block-end: 0; }
+  .jal-row:active { background: color-mix(in srgb, var(--text) 8%, transparent); }
+  @media (hover: hover) {
+    .jal-row:hover { background: color-mix(in srgb, var(--text) 5%, transparent); }
+  }
+  .jal-row:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
+
+  .jal-ico {
+    display: inline-flex;
+    flex: none;
+    color: var(--text-dim);
+  }
+  /* The glyph is cut to a fixed box, so it is sized in px on purpose — it is a mark, not reading
+     text, and the box it sits in is a hand size rather than a type size. */
+  .jal-ico :global(svg) { width: 20px; height: 20px; display: block; }
+
+  /* The label takes the room. This is the whole point of the component: nothing here clips. */
+  .jal-label { flex: 1; min-width: 0; }
+  .jal-detail { color: var(--text-dim); font-size: var(--fs-xs); flex: none; }
+
+  .jal-row.is-accent { color: var(--accent); font-weight: 600; }
+  .jal-row.is-accent .jal-ico { color: var(--accent); }
+  .jal-row.is-danger { color: var(--danger); }
+  .jal-row.is-danger .jal-ico { color: var(--danger); }
+  .jal-row.is-danger:active { background: color-mix(in srgb, var(--danger) 12%, transparent); }
+  @media (hover: hover) {
+    .jal-row.is-danger:hover { background: color-mix(in srgb, var(--danger) 10%, transparent); }
+  }
+
+  .jal-row[disabled] { opacity: 0.4; cursor: default; }
+  /* A class-set display beats the user agent's `[hidden] { display: none }` — that has bitten this
+     ecosystem twice already, in this very sheet. Said again where the display is set. */
+  .jal-row[hidden] { display: none !important; }
+</style>

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

package/src/Toolbar.astro

@@ -32,13 +32,19 @@ interface Props {
   profileLabel: string;  // aria/title for the Profile nav icon
   kernelLabel: string;   // aria/title for the Kernel (app) nav icon
   postsLabel: string;    // aria/title for the Posts nav icon
+  // The persona's own files. ON by default — the edge mounts `/files` on every persona host, so a
+  // persona that had to opt in would be a persona whose files exist and cannot be found. The label
+  // has an ecosystem default because a component brings its own ground: a consumer that has not
+  // translated it yet gets a working, named control rather than an unlabelled icon.
+  files?: boolean;
+  filesLabel?: string;
   // The home affordance points at app.zone, so the two apexes suppress it: app.zone IS that
   // destination, and justai.pro is above it (sending the parent "home" to a child platform is
   // the wrong direction). Every other persona keeps it.
   home?: boolean;
 }
 import BackToZone from "./BackToZone.astro";
-const { sectionsLabel, profileLabel, kernelLabel, postsLabel, home = true } = Astro.props;
+const { sectionsLabel, profileLabel, kernelLabel, postsLabel, home = true, files = true, filesLabel = "Files" } = Astro.props;
 ---
 
 <header class="toolbar">
@@ -57,6 +63,29 @@ const { sectionsLabel, profileLabel, kernelLabel, postsLabel, home = true } = As
         </a>
         <slot name="navExtra" />
       </nav>
+      {files && (
+        // queries: files icon in the toolbar · how do I reach my files from a persona · the folder
+        //          in the toolbar · why is files not in the section nav
+        //
+        // THE PERSONA'S FILES, ONE TAP FROM ANYWHERE IN IT.
+        //
+        // Until this, the only way into `<persona>/files` was to be asked for a file — the room
+        // where your things live could be entered only by a persona's invitation, which is exactly
+        // backwards for a room that is yours.
+        //
+        // OUTSIDE the sections nav, and deliberately: profile, kernel and posts are parts of THIS
+        // page and their links are fragments. `/files` is a different document — a place, not a
+        // section — and putting a navigation to elsewhere inside `<nav aria-label="sections">`
+        // would tell a screen reader it is one of them. Same reasoning the `leftExtra` slot below
+        // already carries, which is why this sits beside it rather than in the group above.
+        //
+        // ON BY DEFAULT, because the edge mounts `/files` on EVERY persona host: a persona that had
+        // to opt in would be a persona whose files exist and cannot be found. One bump here reaches
+        // the whole fleet, which is the only shape that survives a thousand of them.
+        <a class="tb-nav tb-files" id="navFiles" href="/files" aria-label={filesLabel} title={filesLabel}>
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 7.5A1.5 1.5 0 0 1 4.5 6h4L11 8.5h8.5A1.5 1.5 0 0 1 21 10v7a1.5 1.5 0 0 1-1.5 1.5h-15A1.5 1.5 0 0 1 3 17z"/></svg>
+        </a>
+      )}
       <!-- beside the section nav, but deliberately OUTSIDE it: a link that is not a section of this
            page (justai.pro carries app.zone's mark here). Keeping it out of <nav aria-label=sections>
            is the a11y half of the reason it is its own slot. -->