@justai/cuts 0.78.0 → 0.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.78.0",
+  "version": "0.80.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -27,7 +27,8 @@
     "./ActionList.astro": "./src/ActionList.astro",
     "./ActionRow.astro": "./src/ActionRow.astro",
     "./Files.astro": "./src/FilePicker.astro",
-    "./AuthMount.astro": "./src/AuthMount.astro"
+    "./AuthMount.astro": "./src/AuthMount.astro",
+    "./ChildPersona.astro": "./src/ChildPersona.astro"
   },
   "peerDependencies": {
     "astro": ">=5"
@@ -36,7 +37,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@justai/core": "^0.10.0",
+    "@justai/core": "^0.11.0",
     "@justai/ui": "^0",
     "@justai/atrium": "^0.1.9"
   }

package/src/ChildPersona.astro

@@ -0,0 +1,219 @@
+---
+import "./ground.css";
+import Profile from "./Profile.astro";
+import Toolbar from "./Toolbar.astro";
+
+/**
+ * <ChildPersona> — the shell every child persona wears, so a builder writes only its kernel.
+ *
+ * queries: child persona shell · files me feed shared codebase · how do I write a new child persona ·
+ *          why does every child persona repeat the same CSS · .pp · persona page inside a sheet ·
+ *          standalone and embedded · child persona template
+ *
+ * ── WHAT A CHILD PERSONA IS ──────────────────────────────────────────────────────────────────────
+ *
+ * A persona that can only exist UNDER another (foundations 01): `/me`, `/files`, `/feed`. Say "qr's
+ * files" and it means something; say "files" and it does not. The edge mounts ONE implementation onto
+ * every persona's host, in that host's origin, so it sees only that persona's storage.
+ *
+ * ── A CHILD PERSONA HAS FACES ────────────────────────────────────────────────────────────────────
+ *
+ * THE PATTERN IS APPLE'S WIDGET MODEL AND THE WORD IS NOT, and that split is the decision rather
+ * than a compromise. A widget declares which FAMILIES it supports — systemSmall, systemMedium,
+ * accessoryInline — and the host asks for one: one identity, several surfaces, each a different
+ * amount of room and a different amount of attention. That model is right, thought through for
+ * years, and we take it whole.
+ *
+ * The word `widget` is the part that does not travel, and this codebase already knows why. Look at
+ * the cuts: `Sheet`, `ActionRow`, `Segmented` are Apple's words because they are Apple's THINGS —
+ * components. `Profile`, `Posts`, `Toolbar`, `BackToZone` are the ecosystem's, because they are
+ * about the persona. A child persona's surface is not a component; it is the persona SHOWING UP.
+ *
+ * And the ownership runs the other way. An iOS widget belongs to the HOST's world — a thing the Home
+ * Screen contains. This belongs to the PERSONA's world: how it appears when somebody asks for it.
+ * Borrowing the word would import the wrong ownership, and it would walk back the rename foundations
+ * 01 already paid for — "sub-persona" became "child persona" precisely because *nobody argues that a
+ * sub-thing deserves a face*.
+ *
+ * `face` is also already ours: `profile.avatar` is "the canonical face", `PersonaFace` is a type,
+ * `/api/face` answers who owns a host. That is not a collision — the endpoint returns the MATERIALS
+ * of a face (mark, colour, name) and this prop says WHICH face is being worn. One concept, two uses.
+ *
+ * (Pattern borrowed, vocabulary kept — which is the ecosystem's own thesis stated in miniature: the
+ * mechanism is a commodity, the soul is ours.)
+ *
+ * A child persona has two faces today, and the axis is open on purpose:
+ *
+ *   `page`  — a person types `qr.app.zone/files`. A full persona page: profile, toolbar, kernel.
+ *   `sheet` — qr's kernel calls it, and it arrives inside qr's sheet as a guest. Chrome is the
+ *             host's; this draws content only.
+ *
+ * and the ones that will come are already visible from here — an INLINE face (a strip a kernel
+ * embeds in its own column rather than presenting over it), a COMPACT face (a summary that answers
+ * without being opened), a PICKER face (the value-returning one, which today is `sheet` doing double
+ * duty). Each is a widget family in Apple's sense and a face in ours.
+ *
+ * IT IS A NAMED FACE, NOT A BOOLEAN, and that is the whole reason this prop exists in this shape.
+ * `presented: true/false` describes today and cannot describe a third surface without becoming two
+ * booleans that can both be true. A face is a name; adding one is adding a name.
+ *
+ * A face is a PRESENTATION CLASS and never a permission. Anything that must not be forged — who may
+ * read a file, whose persona owns a write — is decided by the verified origin on the atrium channel.
+ * A face decides only how much room there is and which words a person reads.
+ *
+ * ── THE APPLE ANALOGY, AND WHERE IT STOPS ────────────────────────────────────────────────────────
+ *
+ * The founder's reading, and it is the right one: this is the widget model. The HOST supplies the
+ * frame — the sheet, its bar, its dismiss, its detent — and the guest supplies only the content. The
+ * two run in separate processes with no shared build and no version coupling, and the guest does not
+ * know where it was placed (atrium identity is hop-local: a callee sees who HANDED it the message).
+ *
+ * Where it stops is the part that shapes this file: an Apple widget is read-mostly and
+ * timeline-driven, and a child persona is interactive and RETURNS A VALUE. The closer relative is
+ * `UIDocumentPickerViewController` — the system's picker, presented inside your app, drawing its own
+ * content, wearing your sheet, handing you back what the person chose.
+ *
+ * So: **chrome belongs to the host, content belongs to the guest.** A presented child draws no way
+ * out of its own, because the sheet it is in already has one, and two exits put "leave" at the rank
+ * of the thing the person came to do.
+ *
+ * ── WHY `.pp` ───────────────────────────────────────────────────────────────────────────────────
+ *
+ * Everything is scoped under one wrapper because that is what lets one document be both situations.
+ * It also has a consequence worth knowing before fighting it: `.pp .app` is (0,2,0) and the
+ * package's global `.app` is (0,1,0), so a child's own rules always win. That is not an accident to
+ * work around — it is what makes the two-mode wrapper possible — but it does mean a child cannot
+ * inherit `@justai/ui`'s geometry the way an ordinary persona does. This cut carries it instead.
+ *
+ * ── MEASURED, NOT ASSUMED ───────────────────────────────────────────────────────────────────────
+ *
+ * files (174 rules), me (87) and feed (79) were compared rule by rule on 2026-08-02: 26 are
+ * character-identical in all three, and they are exactly this shell — the column both halves,
+ * `.below`, the landing offset, the toolbar row, the mark, the reduced-motion rule. `files ∩ me` is
+ * 50, because both are rooms you browse. Everything they do NOT share is their kernel.
+ *
+ * That is the whole argument: a child persona is its kernel plus this file.
+ */
+interface Props {
+  /** The child's own handle — `files`, `me`, `feed`. Its name in the row and in its own title. */
+  child: string;
+  /** What the child is called, in the reader's language. */
+  name: string;
+  /** One line, the child's own voice, for the profile. */
+  bio?: string;
+  /** The small print under the bio — what it costs, what it keeps. */
+  meta?: string;
+  /** The host persona's face, if the page already resolved it server-side. Otherwise `childFace()`
+   *  fills it in at runtime from /api/face — see @justai/core. */
+  host?: { name?: string; avatar?: string; accent?: string };
+  /** Where the parent's kernel is. Defaults to the host root, which is where a visitor came from. */
+  parentHref?: string;
+  parentLabel?: string;
+  /** Section labels for the row. */
+  sectionsLabel?: string;
+  profileLabel?: string;
+  kernelLabel?: string;
+  /** Which face to render. `page` standalone, `sheet` as a guest inside a host's chrome. Open by
+   *  design — see the header: a child persona has faces, the way an iOS widget has families. */
+  face?: "page" | "sheet";
+}
+const {
+  child, name, bio, meta, host,
+  parentHref = "/#kernel", parentLabel = "Home",
+  sectionsLabel = "Sections", profileLabel, kernelLabel, face = "page",
+} = Astro.props;
+// `page` is the default because it is the face a child shows when nobody asked for one — somebody
+// typed the address. A guest is always ASKED for, which is why the caller names it.
+const chrome = face === "page";
+---
+
+{/* `.pp` IS the child persona. One wrapper, two situations — and `data-presented` is how the kernel
+    inside asks which one it is in without re-deriving it from the URL. */}
+<div class="pp" id="pp" data-child={child} data-face={face}>
+  {/* A PRESENTED CHILD SHOWS NO PROFILE AND NO ROW. It is content inside somebody's sheet, and a
+      biography there is the guest introducing itself while the host is mid-sentence. Standalone it
+      is a full persona page, because then it IS the page. */}
+  {chrome && (
+    <>
+      <Profile
+        name={name}
+        handle={`@${child}`}
+        bio={bio}
+        meta={meta}
+        kernelLabel={name}
+        avatarBg="#fff"
+        avatarPad="14px"
+        cover="linear-gradient(135deg, color-mix(in srgb, var(--accent) 88%, #fff), var(--accent) 55%, color-mix(in srgb, var(--accent) 70%, #000))"
+      >
+        <Fragment slot="avatar"><slot name="mark" /></Fragment>
+      </Profile>
+
+      <div class="below" id="below">
+        <Toolbar
+          sectionsLabel={sectionsLabel}
+          profileLabel={profileLabel ?? name}
+          kernelLabel={kernelLabel ?? name}
+          postsLabel="Posts"
+          parent={{ href: parentHref, label: parentLabel, icon: host?.avatar }}
+          files={false}
+        >
+          <Fragment slot="profileIcon"><slot name="mark" /></Fragment>
+          <slot name="langPicker" slot="langPicker" />
+        </Toolbar>
+        <section class="cut kernel" id="kernel"><slot /></section>
+      </div>
+    </>
+  )}
+
+  {!chrome && <section class="cut kernel" id="kernel" data-guest><slot /></section>}
+</div>
+
+<style>
+  /* THE SHELL, scoped under `.pp` — the 26 rules files, me and feed each carried verbatim.
+   *
+   * They are written here at the SAME depth the children wrote them, and that is deliberate: a
+   * child's own `.pp .x` rule ties with this one and wins on order, so a child that needs to differ
+   * still can, without !important and without knowing anything about this file. */
+
+  .pp { min-height: 100dvh; }
+  .pp a { color: inherit; text-decoration: none; }
+
+  /* the column — the fleet's one presentation at every width */
+  .pp .app {
+    /* Set here AND read with a fallback, which is not belt-and-braces: a consumer that overrides
+       `.pp .app` — same selector, later stylesheet — drops the declaration and keeps the reads, and
+       an unresolved var() invalidates the whole `padding-inline`. The cut brings its own ground
+       (law 1) means the ground has to survive being partly overwritten. */
+    --gutter: 16px;
+    display: flex; flex-direction: column;
+    padding-inline: max(var(--gutter, 16px), env(safe-area-inset-left)) max(var(--gutter, 16px), env(safe-area-inset-right));
+  }
+  @media (min-width: 768px) {
+    .pp .app {
+      --gutter: 28px;
+      max-width: 480px; margin-inline: auto; padding-inline: var(--gutter, 28px);
+      border-inline: 1px solid var(--border); background: var(--surface);
+      backdrop-filter: blur(40px) saturate(1.4); -webkit-backdrop-filter: blur(40px) saturate(1.4);
+    }
+  }
+
+  .pp .below { position: relative; }
+  /* the sticky row means a section reached by its id arrives UNDER it unless it says otherwise */
+  .pp #profile, .pp #kernel { scroll-margin-top: 82px; }
+
+  /* THE `sheet` FACE: no column, no ground, no chrome. The sheet around it IS the frame, and a
+     second frame inside one is a box in a box. Keyed on the face name rather than on a boolean, so a
+     third face styles itself by adding a selector instead of by renaming this one. */
+  .pp[data-face="sheet"] { min-height: 0; }
+  .pp[data-face="sheet"] .app { max-width: none; margin-inline: 0; border: 0; background: none;
+                                backdrop-filter: none; -webkit-backdrop-filter: none; }
+
+  /* a mark fills its box; the picture inside it covers */
+  .pp .mk { display: block; width: 100%; height: 100%; object-fit: cover; }
+
+  /* Motion is never forced on somebody who asked it not to be — and the biggest effects, the ones a
+     surface is proudest of, are exactly what that setting exists to suppress. */
+  @media (prefers-reduced-motion: reduce) {
+    .pp *, .pp *::before, .pp *::after { animation: none !important; transition: none !important; }
+  }
+</style>

package/src/Toolbar.astro

@@ -61,6 +61,10 @@ interface Props {
   // 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;
+
+  // Posts is required only where there IS a stream (doctrine 02 — an empty cut shipped to look
+  // complete is the buffet). A child persona has none, so `parent` turns this off by default.
+  posts?: boolean;
   // What the title strip says when the Kernel or the Posts cut is the one at the toolbar line.
   //
   // OMIT THEM AND NOTHING MOVES: the strip keeps naming the persona and its handle, which is right
@@ -93,9 +97,47 @@ interface Props {
   // The `profileIcon` slot still wins when a persona passes one — an inline SVG can take
   // `currentColor` where an <img> cannot, which is why qr passes its mark rather than pointing at it.
   avatar?: string;
+
+  // queries: child persona toolbar · files me feed toolbar · the toolbar inside /files ·
+  //          how does a child persona get back to its parent · parent icon in the toolbar
+  //
+  // ── THE CHILD PERSONA TOOLBAR ────────────────────────────────────────────────────────────────
+  //
+  // `me`, `files` and `feed` are sub-personas mounted BY THE EDGE on every persona's host — you meet
+  // them at `qr.app.zone/files`, wearing qr's face, in qr's origin. They are somebody else's
+  // codebase living at your address, and their row has to say so.
+  //
+  // Pass `parent` and the row becomes the child's:
+  //
+  //     the PARENT's face  →  this child's own mark  →  the bolt
+  //
+  // which is the ordinary row's grammar, unchanged. Position one is still "where you came from" —
+  // for a persona that is app.zone, and for a child it is the persona above it. Position two is
+  // still WHO. Position three is still the way IN. Nothing new was invented; the same four kinds of
+  // thing are being said by a shorter row, and there is no app.zone or justai icon in it because
+  // neither is where a visitor to `qr.app.zone/files` came from.
+  //
+  // THE PARENT'S FACE COSTS NOTHING TO FIND. A child runs in the parent's origin, so `/icon.svg` —
+  // the same path this cut already uses for a persona's own face — resolves to the PARENT's mark
+  // when the page is a child's. One path, two meanings, both correct, and neither needs a registry
+  // lookup or a build-time value the edge would have to inject.
+  //
+  // A child has no Posts and no BackToZone: `parent` turns both off unless asked otherwise.
+  //
+  // `icon` is optional and almost always should be: `/icon.svg` is already the parent's face when the
+  // child runs in the parent's origin. It exists for the one child that does not have to guess —
+  // `feed` already reads the host persona's avatar from the registry, and an absolute URL it was
+  // given beats a relative one it inferred.
+  parent?: { href?: string; label?: string; icon?: string };
 }
 import BackToZone from "./BackToZone.astro";
-const { sectionsLabel, profileLabel, kernelLabel, postsLabel, home = true, files = true, filesLabel = "Files", kernelTitle, postsTitle, avatar = "/icon.svg" } = Astro.props;
+const {
+  sectionsLabel, profileLabel, kernelLabel, postsLabel,
+  files = true, filesLabel = "Files", kernelTitle, postsTitle, avatar = "/icon.svg", parent,
+} = Astro.props;
+// A child's row answers UP to its parent, not out to the zone, and has no stream of its own — so
+// both default off the moment `parent` is given, rather than each consumer remembering to say so.
+const { home = !parent, posts = !parent } = Astro.props;
 import AuthMount from "./AuthMount.astro";
 ---
 
@@ -107,6 +149,15 @@ import AuthMount from "./AuthMount.astro";
     <div class="tb-left">
       {home && <BackToZone />}
       <nav class="tb-nav-group" aria-label={sectionsLabel}>
+        {/* POSITION ONE OF A CHILD'S ROW: the persona this one is mounted inside. `/icon.svg` is the
+            parent's face here, because a child runs in the parent's origin — the same path, read from
+            a different address. `#kernel` rather than `/` so the way back lands on the parent's work
+            and not on its biography, which is where a person who came from there was standing. */}
+        {parent && (
+          <a class="tb-nav tb-mark" id="navParent" href={parent.href ?? "/#kernel"} aria-label={parent.label ?? "Home"} title={parent.label ?? "Home"}>
+            <img src={parent.icon ?? "/icon.svg"} alt="" width="19" height="19" loading="lazy" decoding="async" />
+          </a>
+        )}
         {/* THE PROFILE ICON IS THE PERSONA'S OWN FACE. Always — the founder's rule, and app.zone and
             qr had already settled it while thirteen siblings still showed a generic bust.
 
@@ -119,8 +170,24 @@ import AuthMount from "./AuthMount.astro";
             `tb-mark` is set whichever way the face arrives, because it is what the sizing rule looks
             for: a mark runs to the edge of its viewBox and a glyph does not, so they need different
             boxes to put the same ink on screen. */}
-        <a class="tb-nav tb-mark" id="navProfile" href="#profile" aria-label={profileLabel} title={profileLabel}>
-          {Astro.slots.has("profileIcon") ? <slot name="profileIcon" /> : <img src={avatar} alt="" width="19" height="19" loading="lazy" decoding="async" />}
+        {/* `tb-mark` says "a solid MARK is in this box" — it is what the sizing rule looks for, and a
+            mark runs to the edge of its viewBox where a stroke glyph sits inside 75% of one. A
+            persona's face is always a mark, so a persona always carries the class.
+
+            A CHILD IS THE OTHER CASE, and it was measured rather than assumed: files passes a stroke
+            folder, and with `tb-mark` on it, it rendered at 19px beside a 25.33px bolt — one size
+            smaller, which is exactly the defect the 25.33 rule exists to remove. So in child mode the
+            slotted icon takes the GLYPH box and the row reads level. A child that draws a solid mark
+            instead should say so in its own CSS; every child in the fleet draws a glyph today. */}
+        <a class:list={["tb-nav", { "tb-mark": !parent }]} id="navProfile" href="#profile" aria-label={profileLabel} title={profileLabel}>
+          {/* A CHILD MUST PASS ITS OWN MARK. The default `/icon.svg` is the face of whoever owns this
+              origin — right for a persona, and its PARENT for a child, which would put the same
+              picture in two places and say nothing in either. So when `parent` is given there is no
+              fallback: a child that passes nothing renders an empty box, which is a defect somebody
+              sees, rather than a duplicate face, which is a defect nobody reports. */}
+          {Astro.slots.has("profileIcon")
+            ? <slot name="profileIcon" />
+            : (!parent && <img src={avatar} alt="" width="19" height="19" loading="lazy" decoding="async" />)}
         </a>
         {/* THE KERNEL IS ALWAYS THE BOLT. The founder's rule, and it is the shell's to draw rather
             than the persona's to remember.
@@ -137,9 +204,11 @@ import AuthMount from "./AuthMount.astro";
         <a class="tb-nav" id="navKernel" href="#kernel" aria-label={kernelLabel} title={kernelLabel}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12.9 3L5.7 13.35h5.4L10.2 21l8.1-10.8h-5.4l.9-7.2z"/></svg>
         </a>
-        <a class="tb-nav" id="navPosts" href="#posts" aria-label={postsLabel} title={postsLabel}>
-          <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>
-        </a>
+        {posts && (
+          <a class="tb-nav" id="navPosts" href="#posts" aria-label={postsLabel} title={postsLabel}>
+            <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>
+          </a>
+        )}
         <slot name="navExtra" />
       </nav>
       {files && (