@justai/cuts 0.79.0 → 0.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.79.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>