@justai/cuts 0.111.0 → 0.112.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.111.0",
+  "version": "0.112.1",
   "description": "A persona's named parts \u2014 the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -13,25 +13,26 @@
     "src"
   ],
   "exports": {
+    "./ActionList.astro": "./src/ActionList.astro",
+    "./ActionRow.astro": "./src/ActionRow.astro",
+    "./AuthMount.astro": "./src/AuthMount.astro",
+    "./BackToZone.astro": "./src/BackToZone.astro",
     "./Base.astro": "./src/Base.astro",
+    "./Catalogue.astro": "./src/Catalogue.astro",
+    "./CatalogueCard.astro": "./src/CatalogueCard.astro",
+    "./ChildPersona.astro": "./src/ChildPersona.astro",
+    "./ConfirmSheet.astro": "./src/ConfirmSheet.astro",
+    "./FilePicker.astro": "./src/FilePicker.astro",
+    "./Files.astro": "./src/FilePicker.astro",
     "./LangPicker.astro": "./src/LangPicker.astro",
-    "./BackToZone.astro": "./src/BackToZone.astro",
     "./Posts.astro": "./src/Posts.astro",
-    "./Toolbar.astro": "./src/Toolbar.astro",
+    "./Preroll.astro": "./src/Preroll.astro",
     "./Profile.astro": "./src/Profile.astro",
-    "./ConfirmSheet.astro": "./src/ConfirmSheet.astro",
-    "./Sheet.astro": "./src/Sheet.astro",
     "./Segmented.astro": "./src/Segmented.astro",
+    "./Sheet.astro": "./src/Sheet.astro",
+    "./Toolbar.astro": "./src/Toolbar.astro",
     "./ground.css": "./src/ground.css",
-    "./FilePicker.astro": "./src/FilePicker.astro",
-    "./ActionList.astro": "./src/ActionList.astro",
-    "./ActionRow.astro": "./src/ActionRow.astro",
-    "./Files.astro": "./src/FilePicker.astro",
-    "./AuthMount.astro": "./src/AuthMount.astro",
-    "./ChildPersona.astro": "./src/ChildPersona.astro",
-    "./tagline.js": "./src/tagline.js",
-    "./Catalogue.astro": "./src/Catalogue.astro",
-    "./CatalogueCard.astro": "./src/CatalogueCard.astro"
+    "./tagline.js": "./src/tagline.js"
   },
   "peerDependencies": {
     "astro": ">=5"

package/src/Preroll.astro

@@ -0,0 +1,316 @@
+---
+// ── PREROLL — the shell holds the door until somebody knocks ────────────────────────────────────
+//
+// queries: preroll · the game loads on page open · why does the game not start immediately ·
+//          game persona kernel · tap to play · loading progress · game ready · atrium game ·
+//          first interaction · autoplay gesture · the frame is empty until you tap
+//
+// A game persona is two things at one address: the SHELL — profile, toolbar, feed, child personas —
+// and the GAME, which runs in a frame of its own. This cut is the line between them, and it is the
+// shell's side of the game–shell protocol (pin.games' `.justai/expert/the-game-shell-protocol.md`).
+//
+// ── WHY THE GAME IS NOT LOADED ON PAGE LOAD ───────────────────────────────────────────────────
+//
+// Three arguments, and they land on the same design, which is usually the sign it is the right one.
+//
+//   IT COSTS THE PERSONA ITS BENCHMARKS. sudoku's game is 3.9 MB over 92 requests and reaches a
+//   playable state in about 4.7s over the network. Spent at first paint, that is LCP and blocking
+//   time on a page a search engine judges — and the persona is more than its game.
+//
+//   THE VISITOR MAY NOT HAVE COME FOR THE GAME. They may want the feed, or to meet the character, or
+//   to see what it keeps about them. And a player who DOES tap play may want to read the feed while
+//   it loads and come back, which is only possible when the load is not the page.
+//
+//   AND THE BROWSER ALREADY REQUIRES A GESTURE. Audio will not autoplay without one. A game with
+//   sound needs a tap before it can be itself, so the tap is not a cost this cut invents — it is one
+//   the platform imposes, turned into the moment the game introduces itself.
+//
+// ── THE HANDOVER, AND THE DISTINCTION IT RESTS ON ─────────────────────────────────────────────
+//
+// A LOADING SCREEN AND A CURTAIN ARE NOT THE SAME THING. A loading screen exists because waiting
+// exists, and it belongs here — this cut has the gesture and it has the progress. A curtain is a
+// title card, a logo animation, the game's own identity, and it is played even on an instant load;
+// it belongs to the game.
+//
+// So a game that answers `{ curtain: true }` is handed the frame EARLY and covers the rest of its
+// own loading. One that says nothing is held until it reports ready. What must never happen is both:
+// a bar that fills here and a "Loading…" that starts there is a player waiting twice, with the
+// second wait being theatre pretending to be work.
+
+// THE GROUND rides with the cut. Law 1: a component that renders broken unless its consumer defined
+// --accent, --surface-2 and --text-dim is a template with homework. The wait is an OPAQUE cover over
+// a game that is drawing itself underneath, so a ground that resolves to nothing here does not mean
+// "unstyled" — it means the player watches the game boot through the loading screen.
+import "./ground.css";
+
+interface Props {
+  /** The game's own document, served from this persona's origin. */
+  src: string;
+  /** The button. Keep it a verb. */
+  play: string;
+  /** One line under it — what this is, in the persona's voice. Optional. */
+  note?: string;
+  /** What the frame is called for somebody who cannot see it. */
+  title: string;
+  /** Said while the bytes are moving. */
+  loading?: string;
+  /** atrium ids are a grammar — [a-z0-9._-] — so this is sanitised rather than trusted. */
+  id?: string;
+}
+const { src, play, note, title, loading = "Loading", id = "game" } = Astro.props;
+const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "x");
+---
+
+<div class="pr" id="pr" data-src={src} data-atrium={safeId}>
+  {/* ── THE STAGE IS THE FLOW; THE DOOR AND THE WAIT ARE COVERS OVER IT ─────────────────────────
+      queries: the game boots at zero size · getBoundingClientRect returns 0 in the frame ·
+               the game jumps when the preroll hands over · display none iframe · hidden iframe
+      A GAME MUST BOOT AT ITS REAL SIZE. The first version of this cut put the stage, the door and
+      the wait side by side and switched between them with `display: none` — and a game loading
+      inside a `display: none` frame has no layout at all: every rect it measures is zero, images do
+      not decode, and rAF is suspended. It would have booted blind and then been handed a viewport it
+      had already measured as nothing.
+      So the stage is always laid out and the covers sit ON TOP of it. The frame reaches its final
+      size the moment it is created, and the handover is one element leaving rather than a reflow. */}
+  <div class="pr-stage" id="prStage" data-title={title}></div>
+
+  {/* THE DOOR. No iframe exists yet — that is the entire point, and it is why this markup is a
+      button and a slot rather than a frame with a cover over it. A hidden iframe still fetches. */}
+  <div class="pr-door" id="prDoor">
+    <slot name="art" />
+    <button class="pr-play" id="prPlay" type="button">{play}</button>
+    {note && <p class="pr-note">{note}</p>}
+  </div>
+
+  {/* The wait. Indeterminate until the game says otherwise: a bar that moves without measuring
+      anything teaches a player that the number means nothing. */}
+  <div class="pr-wait" id="prWait" hidden>
+    <div class="pr-bar" id="prBar" data-indeterminate><i id="prFill"></i></div>
+    <p class="pr-note">{loading}</p>
+  </div>
+</div>
+
+<style>
+  /* queries: the game frame has square corners · the game's colours do not match the page ·
+   *          a seam around the game · full-bleed game · preroll radius
+   *
+   * ── THE SHELL OWNS THE FRAME'S SHAPE; THE GAME OWNS WHAT IS INSIDE IT ──────────────────────
+   *
+   * A game paints its own ground and it will not match the persona's — sudoku's art direction is
+   * nothing like app.zone's grey. Rendered edge to edge with square corners, that mismatch reads as
+   * a page that failed rather than as a game that has a look; rounded and clipped, it reads as an
+   * object ON the page, which is what it is. So the seam is made deliberate instead of denied.
+   *
+   * `--preroll-radius` is the escape hatch, and it is one line: a game persona that wants the frame
+   * to BE the screen — the shape sudoku takes — sets it to 0 and cancels the gutter itself. */
+  /* queries: the play button cannot be clicked · something else intercepts pointer events ·
+   *          the preroll has no height · blank page preroll · law 1 geometry
+   *
+   * ── A COMPONENT BRINGS ITS OWN HEIGHT, NOT ONLY ITS OWN COLOURS ────────────────────────────
+   *
+   * `flex: 1` gives this cut the kernel's whole height — in a kernel. On a page that is not a flex
+   * column it means nothing, the only in-flow child is an empty stage, and the box collapses to
+   * zero: the door is then an absolutely positioned overlay inside a zero-height parent, clipped by
+   * the `overflow` below and sitting under whatever the page put above it. The blank-page fixture
+   * caught it as `<p>bare page — no consumer css</p> intercepts pointer events`, which is the same
+   * law 1 the ground.css import two screens up answers for colour.
+   *
+   * The floor is small enough that the flex case always wins it and large enough that a door is a
+   * door. Nothing real is shorter: the narrowest phone leaves ~486px under the toolbar. */
+  .pr {
+    position: relative; flex: 1; min-height: 240px; display: flex; flex-direction: column;
+    border-radius: var(--preroll-radius, var(--radius-lg)); overflow: hidden;
+  }
+
+  /* OPAQUE, and `--bg` rather than `--surface`: the fleet's `--surface` is a translucent overlay
+     tint, so a cover painted with it shows the booting game through itself. */
+  .pr-door, .pr-wait {
+    position: absolute; inset: 0; z-index: 1; background: var(--bg);
+    display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 14px;
+  }
+  .pr-door[hidden], .pr-wait[hidden] { display: none; }
+
+  .pr-play {
+    font: inherit; font-weight: 600; font-size: var(--fs-md);
+    padding: 14px 40px; border: 0; border-radius: var(--radius-pill);
+    background: var(--accent); color: var(--accent-on); cursor: pointer;
+    transition: transform 0.18s var(--ease-spring);
+  }
+  .pr-play:active { transform: scale(0.94); }
+  .pr-note { margin: 0; color: var(--text-dim); font-size: var(--fs-sm); text-align: center; }
+
+  .pr-bar {
+    width: min(240px, 70%); height: 4px; border-radius: 999px;
+    background: var(--surface-2); overflow: hidden;
+  }
+  .pr-bar i { display: block; height: 100%; width: 0; border-radius: 999px; background: var(--accent); }
+  /* A game that reports nothing gets a sweep rather than a number — honest about not knowing. */
+  .pr-bar[data-indeterminate] i {
+    width: 40%; animation: pr-sweep 1.1s var(--ease-out) infinite;
+  }
+  @keyframes pr-sweep { from { transform: translateX(-100%); } to { transform: translateX(250%); } }
+  @media (prefers-reduced-motion: reduce) {
+    .pr-bar[data-indeterminate] i { animation: none; width: 100%; opacity: 0.5; }
+  }
+
+  .pr-stage { flex: 1; min-height: 0; }
+  .pr-stage :global(iframe) { display: block; width: 100%; height: 100%; border: 0; }
+</style>
+
+<script>
+  // queries: preroll script · the game never connects · atrium router game · boot · curtain
+  //
+  // THE SHELL IS THE ROUTER, AND IT IS ONE BEFORE THE FRAME EXISTS. atrium's rule is that a guest
+  // discovers UPWARD, so the room has to be standing before anybody can walk into it. `mount` names
+  // the guest by its WINDOW — never by what it calls itself, because a guest that announces its own
+  // name lets any frame on the page claim to be the game.
+  import atrium from "@justai/atrium";
+
+  const root = document.getElementById("pr");
+  if (root) {
+    const door = document.getElementById("prDoor") as HTMLElement;
+    const wait = document.getElementById("prWait") as HTMLElement;
+    const stage = document.getElementById("prStage") as HTMLElement;
+    const bar = document.getElementById("prBar") as HTMLElement;
+    const fill = document.getElementById("prFill") as HTMLElement;
+    const playBtn = document.getElementById("prPlay") as HTMLButtonElement;
+
+    const src = root.dataset.src as string;
+    const atriumId = root.dataset.atrium as string;
+
+    let started = false;
+
+    // The stage is never switched — it is underneath the whole time. `show(null)` is the handover:
+    // both covers leave and what was already drawing there is simply visible.
+    const show = (el: HTMLElement | null) => {
+      for (const n of [door, wait]) n.hidden = n !== el;
+    };
+
+    // ── PATIENCE IS MEASURED IN SILENCE, NOT IN SECONDS ──────────────────────────────────────
+    //
+    // queries: the game was cut off while it was still loading · the preroll gave up too early ·
+    //          how long does the shell wait · slow connection · the bar vanished mid-load
+    //
+    // A total time limit is the wrong instrument and it fails in both directions: 20s abandons a
+    // real game on a real 3G connection, and 120s leaves a player staring at a dead frame. What
+    // separates the two cases is not how long it has taken — it is whether the game is still
+    // TALKING. So the clock is reset by every progress report, and only silence runs it down.
+    //
+    // A game that never speaks at all gets one window's worth from the moment the frame is created,
+    // which is the same promise made to a player whose game is simply broken.
+    const PATIENCE = 20000;
+    let watchdog: ReturnType<typeof setTimeout> | null = null;
+    // Assigned where the promise it resolves is created — a no-op until then, because a progress
+    // report cannot arrive before the frame exists and a `bump` that throws would take the bar
+    // down with it.
+    let bump = () => {};
+
+    const setProgress = (v: unknown) => {
+      bump();
+      const n = typeof v === "number" ? v : (v as any)?.value;
+      if (typeof n !== "number" || !isFinite(n)) return;
+      bar.removeAttribute("data-indeterminate");
+      fill.style.width = Math.max(0, Math.min(1, n)) * 100 + "%";
+    };
+
+    const start = async () => {
+      if (started) return;
+      started = true;
+      show(wait);
+
+      const frame = document.createElement("iframe");
+      frame.title = stage.dataset.title || "";
+      // `allow` carries the gesture forward: the tap that opened this frame is what lets the game
+      // play sound at all, and a frame without it starts muted for reasons nobody can see.
+      frame.setAttribute("allow", "autoplay; fullscreen");
+      frame.setAttribute("referrerpolicy", "same-origin");
+
+      let bus: any = null;
+      try {
+        bus = await atrium({
+          id: atriumId,
+          router: true,
+          mount: ({ source }: any) => (source === frame.contentWindow ? "game" : null),
+        });
+      } catch {
+        // atrium failing must not cost the player the game: mount the frame and hand over blind.
+        // A game that cannot speak still runs; it simply gets no progress and no early curtain.
+      }
+
+      const arrived = bus
+        ? new Promise<void>((resolve) => bus.on("connected", (e: any) => { if (e?.name === "game") resolve(); }))
+        : Promise.resolve();
+
+      stage.appendChild(frame);
+      // ── WHAT CROSSES INTO THE FRAME: AN ALLOWLIST, AND A SHORT ONE ──────────────────────────
+      //
+      // Forwarding the persona's whole query string would be the obvious convenience and it is a
+      // privacy hole: a `?data=` envelope, a campaign's utm tags and anything else a person arrived
+      // carrying would be handed to a frame that will one day be a third party's deployment. So the
+      // shell passes exactly two flags, both of them DEBUG instruments that belong to whoever is
+      // looking at the page rather than to whoever built the game: `xray`, the framework's design
+      // grid, and `slow`, which asks a game to spread its own loading out far enough to watch.
+      // A game that does not understand either simply ignores them.
+      const here = new URLSearchParams(location.search);
+      const url = new URL(src, location.href);
+      for (const flag of ["xray", "slow"]) if (here.has(flag)) url.searchParams.set(flag, here.get(flag) ?? "");
+      frame.src = url.pathname + url.search;
+
+      // ── THE HANDOVER ─────────────────────────────────────────────────────────────────────────
+      //
+      // ONE CALL CARRIES BOTH. atrium's `proxy` takes a progress callback and resolves when the
+      // method returns, so `boot` is the whole protocol: the game reports as it loads and answers
+      // when it can draw. No second channel, no polling, and nothing to keep in sync.
+      //
+      // ** THE EXPLICIT `timeout` IS LOAD-BEARING. ** atrium's default transaction timeout is ONE
+      // SECOND — right for a `pick` or an `echo`, and catastrophic here: every game on earth takes
+      // longer than a second to load, so `boot` rejected at 1.000s, the catch below swallowed it,
+      // and the shell handed over an empty frame while the game was still fetching. It failed the
+      // same way every time and said nothing, which is the whole silent-failure genre in one line.
+      // Caught by the spec in harness/tests/behavior.spec.mjs, which asked the bar what it read.
+      //
+      // The number is deliberately far beyond any real load: the POLICY is the watchdog above, and
+      // two clocks racing to enforce one promise means the promise is whichever one you forgot.
+      const boot = (async () => {
+        if (!bus) return {};
+        await arrived;
+        return await bus.proxy({
+          method: "boot",
+          service: "game",
+          options: { timeout: 600000, callback: (e: any) => setProgress(e?.progress ?? e?.value ?? e) },
+        });
+      })();
+
+      // The watchdog is the other half of the promise made to the player: whatever is wrong in
+      // there, they are better off seeing it than seeing us wait for it.
+      const giveUp = new Promise<any>((resolve) => {
+        bump = () => {
+          if (watchdog) clearTimeout(watchdog);
+          watchdog = setTimeout(() => resolve({ lateBy: "silence" }), PATIENCE);
+        };
+        bump();
+      });
+
+      // A SWALLOWED REASON IS THE FAILURE ITSELF. The frame is handed over either way — a player must
+      // not lose the game to a broken handshake — but the catch SAYS what went wrong, because the
+      // symptom on the other side of it is "the wait ended early" and nothing else. This cut's own
+      // one-second bug lived inside an empty catch and was invisible until a spec read the bar.
+      const answer: any = await Promise.race([
+        boot.catch((e: any) => {
+          console.warn("[preroll] the game's boot did not complete:", e?.message || e);
+          return {};
+        }),
+        giveUp,
+      ]);
+      if (watchdog) clearTimeout(watchdog);
+
+      show(null);
+      // `curtain: true` is the game saying "hand over early, I will cover the rest myself" — which
+      // is what a console does, where the logo animation IS the loading screen. Nothing else here
+      // changes; the difference is only how long this cut keeps the door shut.
+      if (answer?.curtain) root.dataset.curtain = "";
+    };
+
+    playBtn.addEventListener("click", start, { once: true });
+  }
+</script>

package/src/ground.css

@@ -54,6 +54,15 @@
   --surface: rgba(255, 255, 255, 0.04);
   --surface-2: rgba(255, 255, 255, 0.07);
   --accent: #0a84ff;
+  /* THE INK ON A FILLED ACCENT. Every persona already declares this — the template writes it from
+     the accent's own `color.on` — but no cut had rendered a filled accent button until <Preroll>'s
+     play surface, so it had never needed a ground and did not have one. It arrives with the same
+     lesson the card tokens above carry: a token is not grounded because the fleet defines it, it is
+     grounded because THIS package does. The value pairs with the `--accent` on the line above and
+     is not scheme-aware, because that accent is not either.
+     A persona whose accent is pale — a yellow, an orange — must override it, and every one of them
+     already does; white ink on a #f5a623 button is the failure this token exists to prevent. */
+  --accent-on: #ffffff;
   /* THE ecosystem's destructive red — Apple's system red, and one of it. Written here rather than
      in each component because a confirmation sheet and a Sign Out row saying "this ends something"
      in two different reds is exactly the drift the ConfirmSheet's own header warns about. It is