@justai/cuts 0.122.0 → 0.125.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.122.0",
+  "version": "0.125.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -41,8 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@justai/core": "^0.30.0",
-    "@justai/ui": "^0.20.0",
+    "@justai/core": "^0.32.0",
+    "@justai/ui": "^0.21.1",
     "@justai/atrium": "^0.1.9"
   }
 }

package/src/Toolbar.astro

@@ -82,6 +82,8 @@ interface Props {
   // half's default, which means copying core's `.pname` / `.handle` selectors into a second place
   // that nothing keeps in step. The strip is one line and its vocabulary should be one kind of
   // thing — names or sections, not one of each — so the API says so out loud.
+  kernelTitle?: string;
+  postsTitle?: string;
 
   // queries: toolbar shows a generic person icon · the profile icon is not my persona ·
   //          how do I put my own mark in the toolbar · avatar
@@ -153,7 +155,7 @@ interface Props {
 import BackToZone from "./BackToZone.astro";
 const {
   sectionsLabel, profileLabel, kernelLabel, postsLabel,
-  files = true, filesLabel = "Files", avatar = "/icon.svg", parent,
+  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.
@@ -164,7 +166,8 @@ import AuthMount from "./AuthMount.astro";
 <!-- The two titles reach the script as data attributes rather than through `define:vars`, which would
      make this script inline and it has an import. Astro drops an attribute whose value is undefined,
      so a persona that passes neither leaves no trace in the markup at all. -->
-<header class="toolbar">
+<div class="tb-slot">
+  <header class="toolbar" data-kernel-title={kernelTitle} data-posts-title={postsTitle}>
     <div class="tb-row">
       <div class="tb-left">
         {home && <BackToZone apex={apex} />}
@@ -265,14 +268,73 @@ import AuthMount from "./AuthMount.astro";
         <AuthMount />
       </div>
     </div>
+    <div class="tb-title" id="tbTitle"><span class="tb-title-text" id="tbTitleText"></span></div>
   </header>
+</div>
 
 <style>
   /* ---- app toolbar — sticky to the top of the active region (kernel + posts); it never
      enters the Profile (it lives inside .below). Flat / knife-cut: a left group and a
      right group, no rounded pills. ---- */
+  /* queries: tb-slot · why is the toolbar wrapped · the bar changes height · the kernel is 26px
+   *          short · a band of the feed at the bottom · the toolbar reserves a box · sticky flow
+   *
+   * ── THE SLOT IS WHAT FLOW SEES; THE BAR IS WHAT THE EYE SEES ──────────────────────────────
+   *
+   * `position: sticky` NEVER LEAVES FLOW. It reserves its full border box and paints inside it — so
+   * the bar's LIVE height positioned everything under it (52 with the title strip shut, 78 open)
+   * while `--shell-top` was deliberately frozen at the open height so that nothing would sample the
+   * 0.35s animation. The HEIGHT stopped sampling it. THE POSITION NEVER DID. Two numbers that must
+   * be equal, written a hundred lines apart in two packages, and their difference is a band of the
+   * next section above the fold: measured on the live persona with the scroll untouched, the kernel
+   * sat 52px below `#below` instead of 78 and 25.81px of the feed was on screen.
+   *
+   * The wrapper separates them. The SLOT is sticky and its box is `--shell-top`; the BAR is static
+   * inside it and may be any height it likes. Nothing above the kernel changes size any more, so
+   * there is nothing for an engine to compensate for — which is also why only a device ever showed
+   * it: Blink scroll-anchors the step away and WebKit has no scroll anchoring. */
+  .tb-slot { position: sticky; top: 0; z-index: 40; display: flow-root; }
+  /* queries: the title strip moves the fold · the page drifts after it lands · a band of posts under
+   *          the game · tb-slot min-height · the slot follows the bar · the strip pushes the page down
+   *
+   * ── THE BOX IS THE SLOT'S OWN, SO IT TRAVELS WITH THE SLOT ─────────────────────────────────────
+   *
+   * `position: sticky` never leaves flow: it reserves its full border box, so whatever the bar's LIVE
+   * height is at any instant, that is where everything under it sits. The strip opens and closes over
+   * 0.35s inside that box — so without a reserved height the shell breathes 26px and the whole
+   * document below it breathes with it. That is the drift the founder lost days to.
+   *
+   * IT LIVED IN `@justai/ui`'s base.css UNTIL 2026-08-06, and measured on pin.games that was the same
+   * as not existing: a persona that never imports base.css got the slot's structure from here and its
+   * BOX from a file it does not load, so the slot collapsed to the bar and posts moved 26px between
+   * the kernel and the profile. The first law again — a component brings its own ground — and the
+   * slot is this component's element, so its box is this component's business. The rule that keeps
+   * the whole strip safe cannot be the one rule that lives somewhere the strip does not.
+   *
+   * AND THE RESERVED BAND WEARS THE BAR'S OWN MATERIAL, not the room's. A slot taller than its bar is
+   * 26px of SOMETHING under the shelf whenever the strip is shut — the state at the profile, on
+   * screen, at rest. Painted in the persona's ground it was a hard black band between a light profile
+   * and a light kernel: the founder photographed it within a minute. It is the BAR'S box, so it takes
+   * the bar's fill, bleeding by the same `--edge` expression so the two cannot leave slivers. */
+  .tb-slot { min-height: var(--shell-top, 78px); }
+  .tb-slot::before {
+    content: "";
+    position: absolute;
+    z-index: -1;
+    inset-block: 0;
+    inset-inline:
+      calc(-1 * max(var(--edge, 16px), env(safe-area-inset-left)))
+      calc(-1 * max(var(--edge, 16px), env(safe-area-inset-right)));
+    background: var(--toolbar-bg, #1e202a);
+  }
+  /* The shelf's fill has two branches and so must its box: `--toolbar-bg` is one token but its
+     FALLBACK differs by scheme, and a band carrying only the dark default is a black strip on a light
+     page — which is exactly what the founder photographed a minute after the first attempt. */
+  @media (prefers-color-scheme: light) {
+    .tb-slot::before { background: var(--toolbar-bg, #fbfcfe); }
+  }
   .toolbar {
-    position: sticky; top: 0; z-index: 40;
+    /* position, top and z-index live on .tb-slot above — this element is static inside it now. */
     display: flex; flex-direction: column;
     /* full-bleed: the bar (frosted bg + hairline) touches the contained-view edges; the icons stay
        aligned with the body via matching inline padding. --edge is the persona's page inline padding
@@ -325,23 +387,54 @@ import AuthMount from "./AuthMount.astro";
   @media (min-width: 640px) { .toolbar { margin-inline: -28px; padding-inline: 28px; } }
   /* icons row + the scroll-reactive title strip below it */
   .tb-row { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
-  /* queries: where is the title strip · tb-title · the persona's name under the icons · tbTitle
+  /* queries: --tb-strip · the title strip's height · the toolbar changes height · 26px ·
+   *          the kernel is 26px short · the game frame does not reach the fold
+   *
+   * ── THE ONE NUMBER THAT MAKES THIS ROW'S HEIGHT A MOVING TARGET, DECLARED SO IT CAN BE READ ──
+   *
+   * The strip opens and closes over 0.35s, so `.toolbar`'s height is anywhere in a 26px range at any
+   * given moment — and anything that measures the row and feeds a LAYOUT with it is sampling an
+   * animation. `--shell-top` did exactly that and the kernel's height came out 26px short whenever
+   * the page happened to be measured with the strip open, which is to say whenever somebody opened
+   * the persona at #kernel. It reads as a strip of the next section showing above the fold.
+   *
+   * So the number is a custom property rather than a literal: this rule uses it, and @justai/core's
+   * `personaScroll` reads it to compute the row's EXPANDED height without waiting for or racing the
+   * transition — `toolbar - strip` is the row, and the row plus this is what the bar will be. One
+   * declaration, two readers, and nothing samples a moving value. */
+  .toolbar { --tb-strip: 26px; }
+  /* queries: the bar grows after load · why does the strip animate on arrival · data-motion ·
+   *          first paint animation · can this transition wait for the first interaction
+   *
+   * ── THE TRANSITION IS ALSO A DAMPER, WHICH IS WHY IT CANNOT SIMPLY WAIT ─────────────────────
+   *
+   * The founder asked the obvious and right question: *"şu geçiş süresi güzel — ama neden bu özellik
+   * kullanıcının ilk interaction'ından sonra aktif edilmiyor?"* A persona lands on its kernel, so the
+   * strip's correct state on the first frame is open; animating into it grows the bar 26px just after
+   * the page appears, which is a glitch nobody asked for.
    *
-   * ── THERE IS NO SECONDARY STRIP, AND THAT IS A DECISION ──────────────────────────────────
+   * IT WAS TRIED, AND IT BREAKS SOMETHING ELSE. Gated behind a `data-motion` flag set on the first
+   * pointer/key/wheel, the strip snaps open during the landing — and that 26px arrives in a SINGLE
+   * frame, inside `#below`, while the scroll spy is deciding which cut is active. That is the
+   * bistable oscillator `personaScroll` documents at length: the spy measures a page its own output
+   * moved. Measured: with the gate in place, `#navProfile` no longer navigates — the page re-asserts
+   * the kernel and stays. The 0.35s is not only easing; it is what keeps that step out of one frame.
    *
-   * A second row under the icons carried the current cut's name and opened over 0.35s. It cost more
-   * than it said. `position: sticky` never leaves flow, so the row's LIVE height positioned every
-   * section beneath it — 52 shut, 78 open — while anything that measured the shell had to freeze one
-   * of those two numbers and was therefore wrong in the other state. That gap is a band of the next
-   * section above the fold; on a game persona, whose kernel is an EXACT height, it is on the glass.
-   * It also coupled the scroll spy to the layout: the spy decided which cut was current, that opened
-   * the strip, the strip moved the page, and the spy read the page it had just moved.
+   * SO THE HEIGHT IS NEVER READ INSTEAD. `--shell-top` is computed as `row + --tb-strip` — the row
+   * being the bar minus whatever the strip currently is, which is the same number at every frame of
+   * the transition. Nothing samples the animation, so nothing depends on when it was sampled.
    *
-   * The founder's ruling, 2026-08-06: *"secondary şeridi tamamen kaldır. net karar."* So the bar is
-   * one row and one height, always. Nothing above the kernel changes size, and every derivation that
-   * existed to survive that change is gone with it — `--tb-strip`, the slot that reserved a constant
-   * box, the painted band that filled the reserve, and the probe that measured the strip before it
-   * opened. The name is on the profile, which is where a name belongs. */
+   * The real fix for the founder's question is a toolbar whose height does not change at all: reserve
+   * the strip's space always and fade only its content. That removes the feedback at the source and
+   * makes the gate free — and it is a fleet-wide design decision about how the bar looks at the
+   * profile, so it is his to take rather than one to slip in. */
+  .tb-title { display: flex; align-items: center; height: 0; overflow: hidden; opacity: 0; transition: height 0.35s var(--ease-out), opacity 0.25s var(--ease-out); }
+  /* The fallback is not decoration: the token is declared on `.toolbar` and consumed here, which is
+     a different selector — so the framework's own token spec reads it as ungrounded and is right to.
+     A rule that silently collapses to `height: 0` would close the strip and say nothing. */
+  .tb-title.show { height: 26px; height: var(--tb-strip, 26px); opacity: 1; }
+  .tb-title-text { font-size: var(--fs-sm); font-weight: 600; letter-spacing: -0.01em; color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; transition: opacity 0.16s var(--ease-out); }
+  .tb-title-text.fade { opacity: 0; }
   /* nav lives on the left, beside the back affordance — the middle is intentionally empty */
   .tb-left { display: flex; align-items: center; gap: 2px; min-width: 0; }
   .tb-nav-group { display: flex; align-items: center; gap: 2px; }
@@ -508,6 +601,15 @@ import AuthMount from "./AuthMount.astro";
   const ownMark = document.querySelector("#navProfile img");
   if (ownMark) adoptMark({ id: "navProfile" });
 
-  // No titleFor: the bar has one row and no strip to name anything in. See the note in the styles.
-  personaScroll();
+  // Both or neither — see the props above. When both are set the strip names the SECTIONS; core's
+  // default, which names the persona and its handle, is left entirely alone otherwise. Nothing here
+  // reproduces that default, which is the point: `.pname` and `.handle` stay core's business.
+  const bar = document.querySelector(".toolbar") as HTMLElement | null;
+  const kt = bar?.dataset.kernelTitle;
+  const pt = bar?.dataset.postsTitle;
+  personaScroll(
+    kt && pt
+      ? { titleFor: (id: string) => (id === "kernel" ? kt : id === "posts" ? pt : "") }
+      : undefined,
+  );
 </script>

package/src/ground.css

@@ -114,7 +114,7 @@
 /* What the shell takes above the kernel — see @justai/ui base.css, which measures it. Ground only:
    `:where()` is specificity zero, so a consumer that ships the shell always wins, and a surface that
    ships no shell still lands its cuts clear of a sticky bar instead of under one. */
-:where(:root) { --shell-top: 52px; }
+:where(:root) { --shell-top: 78px; }
 
 :where(html) {
   background: var(--bg);