@justai/cuts 0.46.1 → 0.48.0

package/package.json

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

package/src/Posts.astro

@@ -29,8 +29,27 @@ interface Props {
   displayHandle?: string; // the rendered @handle when it differs from the key (app.zone → @appzone)
   avatarBg?: string; // post-avatar tile background (default #fff)
   avatarBgLight?: string; // light-scheme override for that tile (a dark gradient must invert, not stay dark)
+  // Which file is THIS persona's face in the feed. Defaults to /icon.svg, which every persona serves at its
+  // root, and which is a tile-with-a-mark-inside — right for an app, and what the tile knobs above are for.
+  avatarSrc?: string;
+  // A mark with no tile of its own, shown on the feed's ground rather than on a tile. app.zone is the case
+  // this exists for: the platform mark is a different kind of object from an app icon (the house rule is in
+  // app-zone/.justai/expert/how-an-app-zone-icon-is-lit.md — the platform mark is inset, app marks are
+  // raised), so wrapping it in a tile states a sibling relationship that is not true.
+  //
+  // Measured, because it decides the size too: /icon.svg puts its coloured ink across 72% of a 42px box,
+  // since the mark sits inset within its own tile. A bare mark spans 98% of the same box. So dropping the
+  // tile does not shrink the mark — it renders it about a third larger, which is why nothing here scales it.
+  avatarBare?: boolean;
+  // The dark-scheme twin of avatarSrc, for a bare mark whose centre has to invert.
+  //
+  // Two files rather than one file with `@media (prefers-color-scheme)` inside it, and that is a measurement
+  // rather than a preference: an SVG referenced by <img> renders in its own document, and the embedding page's
+  // scheme did NOT reach it — the centre stayed #2B2724 on a dark feed, where it is all but invisible against
+  // the ground. The page's own media query is reliable, so the page picks the file and the file stays dumb.
+  avatarSrcDark?: string;
 }
-const { handle, name, footer, displayHandle, avatarBg, avatarBgLight } = Astro.props;
+const { handle, name, footer, displayHandle, avatarBg, avatarBgLight, avatarSrc, avatarBare, avatarSrcDark } = Astro.props;
 const vars = [
   avatarBg && `--feed-av-bg:${avatarBg}`,
   avatarBgLight && `--feed-av-bg-light:${avatarBgLight}`,
@@ -43,6 +62,9 @@ const vars = [
   data-persona={handle}
   data-handle={displayHandle ?? handle}
   data-name={name}
+  data-av={avatarSrc ?? "/icon.svg"}
+  data-av-dark={avatarSrcDark}
+  data-av-bare={avatarBare ? "" : undefined}
   style={vars || undefined}
 >
   <!-- filled at runtime by the loader below (lazy, on Posts-cut intersection) — single source: the console -->
@@ -81,6 +103,22 @@ const vars = [
      pass avatarBgLight; the rest fall back to their single background. */
   @media (prefers-color-scheme: light) { .pa, .rav { background: var(--feed-av-bg-light, var(--feed-av-bg, #fff)); } }
 
+  /* A bare mark stands on the feed's own ground, so the tile and its hairline have to go — and they have to
+     go from the CONTAINER, which is why this reads upward from the image with :has(). Scoping it to the image
+     is what keeps a sibling persona's tiled icon tiled: .rav wraps their reply as well as a self-reply.
+     `contain` rather than `cover`, because a mark with transparent margins must not be cropped to fill. */
+  .pa:has(.mk.bare), .rav:has(.mk.bare) { background: none; border-color: transparent; }
+  .pa .mk.bare, .rav .mk.bare { object-fit: contain; }
+  /* The scheme pair: the page decides, because the SVG's own media query does not survive <img>.
+     Written as `.pa .mk.av-*` rather than `.av-*` deliberately — `.pa .mk { display: block }` above is two
+     classes deep, so a single-class `.av-light { display: none }` loses on specificity and the toggle silently
+     does nothing. Measured: it showed the pale-ground file in both schemes until these selectors matched. */
+  .pa .mk.av-dark, .rav .mk.av-dark { display: none; }
+  @media (prefers-color-scheme: dark) {
+    .pa .mk.av-light, .rav .mk.av-light { display: none; }
+    .pa .mk.av-dark, .rav .mk.av-dark { display: block; }
+  }
+
   .ph { display: flex; align-items: center; gap: 5px; font-size: var(--fs-xs); flex-wrap: wrap; }
   .ph b { font-weight: 600; }
   .phandle, .dot, .pt { color: var(--text-dim); font-weight: 400; }
@@ -142,8 +180,19 @@ const vars = [
 
     const esc = (s: unknown): string =>
       String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] as string);
-    // every persona signs its posts with its own /icon.svg (each app serves one at its root)
-    const AV = `<img class="mk" src="/icon.svg" alt="">`;
+    // Every persona signs its posts with its own face, /icon.svg by default (each app serves one at its
+    // root). The path is a data attribute rather than a literal because a persona may sign with a mark that
+    // has no tile — see avatarSrc / avatarBare above. `bare` rides on the IMAGE, not on the container:
+    // .rav wraps both a self-reply and ANOTHER persona's reply, so a container rule would strip the tile
+    // from siblings who legitimately have one.
+    const bare = section.hasAttribute("data-av-bare") ? " bare" : "";
+    const avLight = esc(section.dataset.av || "/icon.svg");
+    // When a dark twin is declared, BOTH are in the markup and CSS shows one. The alternative — one <img>
+    // whose src is chosen in JS off matchMedia — would be a second source of truth for the same decision and
+    // would not follow a scheme change without a listener.
+    const AV = section.dataset.avDark
+      ? `<img class="mk${bare} av-light" src="${avLight}" alt=""><img class="mk${bare} av-dark" src="${esc(section.dataset.avDark)}" alt="">`
+      : `<img class="mk${bare}" src="${avLight}" alt="">`;
     const ck = `<svg class="ck" viewBox="0 0 24 24" fill="currentColor"><path d="M12 2l2.4 1.8 3 .2.9 2.8 2.3 1.9-1 2.8 1 2.8-2.3 1.9-.9 2.8-3 .2L12 22l-2.4-1.8-3-.2-.9-2.8L3.4 14l1-2.8-1-2.8 2.3-1.9.9-2.8 3-.2z" fill="var(--accent)"/><path d="M9 12.5l2 2 4-4.5" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
     const pact = `<div class="pact"><span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 8.5a5.5 5.5 0 0 0-9-4.2A5.5 5.5 0 0 0 3 8.5c0 5 9 11 9 11s9-6 9-11z"/></svg></span><span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 11.5a8.4 8.4 0 0 1-9 8.3 9.6 9.6 0 0 1-4-.9L3 21l1.1-5A8.4 8.4 0 1 1 21 11.5z"/></svg></span></div>`;
 

package/src/Sheet.astro

@@ -118,6 +118,28 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
         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>
+    {/* queries: back button in a sheet · sheet navigation · go deeper without opening another sheet
+        · in-sheet push · a second sheet loses the context · sheet breadcrumb
+
+        DEPTH WITHOUT A SECOND SHEET.
+
+        Stacking works — an opened sheet takes the one below as a height floor, so it never reads as
+        a retreat. What stacking cannot do is keep you ORIENTED: a full-height sheet over a
+        full-height sheet covers the thing you came from, and the only way back is a dismissal that
+        looks exactly like leaving altogether.
+
+        So a sheet may hold PAGES, and push between them. `<button data-sheet-push="versions">`
+        moves to the element carrying `data-sheet-page="versions"`; this chevron appears with the
+        previous page's title beside it and pops one level. Escape and the backdrop pop too, and
+        only close the sheet at the root — the platform behaviour a person already expects from a
+        navigation stack anywhere else.
+
+        NO HOMEWORK: a consumer writes markup and two attributes. No script, and the sheet still
+        works exactly as before for the consumers that never declare a page. */}
+    <button class="sheet-back" id={`${id}-back`} type="button" data-sheet-back hidden>
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 18l-6-6 6-6"/></svg>
+      <span data-sheet-back-label></span>
+    </button>
     {title && <h2 class="sheet-title" id={`${id}-title`}>{title}</h2>}
     {/* `id`-suffixed for the same reason the title is: a surface that translates at RUNTIME needs a
         stable hook to re-label it from its own dictionary. */}
@@ -143,6 +165,36 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
 
   /* Trailing and level with the title, where a navigation bar's right-hand action lives — the one
      place a thumb looks for "I am finished here". */
+  /* The back control mirrors Done across the header: same band, same weight, same restraint. It is
+     the accent colour because it is a NAVIGATION affordance rather than a destructive one, and the
+     chevron sits tight against the label the way iOS sets a back item. */
+  .sheet-back {
+    position: absolute; inset-inline-start: 12px; inset-block-start: 10px;
+    display: inline-flex; align-items: center; gap: 2px;
+    border: 0; background: none; padding: 6px 8px 6px 4px; cursor: pointer;
+    color: var(--accent); font: inherit; font-size: var(--fs-sm); font-weight: 500;
+    max-width: 42%;
+  }
+  .sheet-back[hidden] { display: none; }
+  .sheet-back svg { width: 20px; height: 20px; flex: none; }
+  .sheet-back span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sheet-back:active { opacity: 0.6; }
+  .sheet-back:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; border-radius: 8px; }
+
+  /* queries: sheet page transition · in-sheet push animation · the pages slide
+
+     Only one page is in the layout at a time, so the body's height is the CURRENT page's — which is
+     what makes the sheet grow and shrink around the content the way a navigation stack does. The
+     slide is 220ms and is skipped for reduced motion, where the pages simply swap. */
+  :global([data-sheet-page]) { display: none; }
+  :global([data-sheet-page].is-current) { display: block; animation: sheet-push 0.22s var(--ease-out) both; }
+  :global([data-sheet-page].is-popping) { display: block; animation: sheet-pop 0.22s var(--ease-out) both; }
+  @keyframes sheet-push { from { transform: translateX(18%); opacity: 0; } }
+  @keyframes sheet-pop { from { transform: translateX(-14%); opacity: 0; } }
+  @media (prefers-reduced-motion: reduce) {
+    :global([data-sheet-page].is-current), :global([data-sheet-page].is-popping) { animation: none; }
+  }
+
   .sheet-done {
     position: absolute; inset-block-start: 0; inset-inline-end: 0;
     background: none; border: 0; cursor: pointer; padding: 12px 16px;
@@ -339,6 +391,91 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
       else panel.style.removeProperty("min-height");
     }
 
+    // ── in-sheet navigation ────────────────────────────────────────────────────────────────────
+    // queries: sheet push pop · back button in a sheet · data-sheet-push · escape pops instead of
+    //          closing · in-sheet navigation stack
+    //
+    // A STACK PER SHEET, held on the element rather than in a module variable, because two sheets
+    // can be open at once and each has its own history. Empty means "at the root", which is also the
+    // state every sheet that never declares a page is permanently in — that is what makes this
+    // addition free for the consumers who do not use it.
+    const stacks = new WeakMap<HTMLDialogElement, string[]>();
+
+    const pageOf = (sheet: HTMLDialogElement, key: string) =>
+      sheet.querySelector<HTMLElement>(`[data-sheet-page="${CSS.escape(key)}"]`);
+
+    // The name a person reads on the way back. The page's own `data-sheet-page-title` if it has one,
+    // otherwise the sheet's heading — which is the honest answer at the root, since that IS where
+    // back goes.
+    const titleAt = (sheet: HTMLDialogElement, key: string | undefined) =>
+      (key ? pageOf(sheet, key)?.dataset.sheetPageTitle : null)
+        ?? sheet.querySelector<HTMLElement>(".sheet-title")?.textContent?.trim()
+        ?? "";
+
+    function show(sheet: HTMLDialogElement, popping: boolean) {
+      const stack = stacks.get(sheet) ?? [];
+      const pages = sheet.querySelectorAll<HTMLElement>("[data-sheet-page]");
+      if (!pages.length) return;
+      const current = stack[stack.length - 1];
+      for (const el of pages) {
+        const on = current ? el.dataset.sheetPage === current : el.hasAttribute("data-sheet-root");
+        el.classList.toggle("is-current", on && !popping);
+        el.classList.toggle("is-popping", on && popping);
+      }
+      const back = sheet.querySelector<HTMLElement>("[data-sheet-back]");
+      const label = sheet.querySelector<HTMLElement>("[data-sheet-back-label]");
+      if (back) back.hidden = stack.length === 0;
+      // The label names WHERE BACK GOES — the level beneath the current one — which is the whole
+      // convention iOS set. Naming the current page instead is the mistake that makes a back button
+      // read as a title.
+      if (label) label.textContent = stack.length ? titleAt(sheet, stack[stack.length - 2]) : "";
+    }
+
+    function push(sheet: HTMLDialogElement, key: string) {
+      if (!pageOf(sheet, key)) return;
+      const stack = stacks.get(sheet) ?? [];
+      stacks.set(sheet, [...stack, key]);
+      show(sheet, false);
+    }
+
+    function pop(sheet: HTMLDialogElement) {
+      const stack = stacks.get(sheet) ?? [];
+      if (!stack.length) return false;
+      stacks.set(sheet, stack.slice(0, -1));
+      show(sheet, true);
+      return true;
+    }
+
+    document.addEventListener("click", (e) => {
+      const t = (e.target as HTMLElement)?.closest?.("[data-sheet-push]");
+      if (t) {
+        const sheet = t.closest("dialog.sheet") as HTMLDialogElement | null;
+        if (sheet) { e.preventDefault(); push(sheet, t.getAttribute("data-sheet-push") || ""); }
+        return;
+      }
+      const b = (e.target as HTMLElement)?.closest?.("[data-sheet-back]");
+      if (b) { e.preventDefault(); pop(b.closest("dialog.sheet") as HTMLDialogElement); }
+    });
+
+    // ESCAPE POPS BEFORE IT CLOSES, and the backdrop does the same. Anywhere else in a browser, Back
+    // at depth means "up one level"; a sheet that jumps straight out from three levels down throws
+    // away everything the person navigated through, and they cannot tell the two gestures apart
+    // beforehand. `preventDefault` on `cancel` is what keeps <dialog> from closing underneath us.
+    document.addEventListener("cancel", (e) => {
+      const sheet = e.target as HTMLDialogElement;
+      if (sheet?.classList?.contains("sheet") && pop(sheet)) e.preventDefault();
+    }, true);
+
+    // A sheet always REOPENS AT ITS ROOT. Coming back to a surface and finding it three levels deep
+    // where you left it is the behaviour of a window, not of a sheet — and nobody expects a sheet to
+    // remember.
+    document.addEventListener("click", (e) => {
+      const t = (e.target as HTMLElement)?.closest?.("[data-sheet-open]");
+      if (!t) return;
+      const sheet = document.getElementById(t.getAttribute("data-sheet-open") || "") as HTMLDialogElement | null;
+      if (sheet) { stacks.set(sheet, []); show(sheet, false); }
+    }, true);
+
     function wire(sheet: HTMLDialogElement) {
       if (wired.has(sheet) || !sheet.showModal) return;
       wired.add(sheet);
@@ -356,11 +493,17 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
       if (!panel) return;
 
       // A tap on the stage (outside the panel) dismisses — the one behaviour <dialog> lacks.
-      sheet.addEventListener("click", (e) => { if (e.target === sheet) sheet.close(); });
+      // A tap on the stage pops one level first, for the same reason Escape does.
+      sheet.addEventListener("click", (e) => { if (e.target === sheet && !pop(sheet)) sheet.close(); });
       sheet.addEventListener("close", () => {
         sheet.removeAttribute("data-expanded");
         panel.style.transform = "";
+        // Back to the root on the way out, whichever way it was dismissed — see the reopen note.
+        if (stacks.get(sheet)?.length) { stacks.set(sheet, []); show(sheet, false); }
       });
+      // A sheet that ships pages must show one from the very first frame, or its body is empty until
+      // somebody navigates. The root is whichever page carries `data-sheet-root`.
+      show(sheet, false);
 
       // ── drag: the grabber follows the pointer, and the release decides ──
       let id: number | null = null, y0 = 0, t0 = 0, dy = 0;