@justai/cuts 0.127.0 → 0.129.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justai/cuts",
-  "version": "0.127.0",
-  "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
+  "version": "0.129.0",
+  "description": "A persona's named parts \u2014 the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -45,4 +45,4 @@
     "@justai/ui": "^0.21.1",
     "@justai/atrium": "^0.1.9"
   }
-}
+}

package/src/FilePicker.astro

@@ -420,11 +420,72 @@ const { id, title = "Choose a file", src = "/files" } = Astro.props;
       };
     }
 
+    // queries: write a file without asking · FilePicker write · a persona's own cached asset ·
+    //          keep a dependency a project points at · write vs save · save asks and I do not want
+    //          to ask · store a file the person did not make · project dependency from outside files
+    //
+    // THE SECOND VERB THAT ASKS NOBODY, AND THE ONE THAT WAS MISSING.
+    //
+    // `save` is deliberately not a friendlier `write`. The kernel's own corpus states the split and
+    // it is not about permission — both write the same origin under the same policy:
+    //
+    //   `write` is arithmetic and keeps the PERSONA's things — a cached asset, a draft it will
+    //   reopen itself. `save` is an interaction and hands a person THEIRS, because the two questions
+    //   that make a saved document a document — what is it called, where does it go — are the
+    //   person's to answer.
+    //
+    // The service has had `write` since the beginning. This door did not expose it, and for fifteen
+    // personas that was invisible, because the only project dependency anybody had was `qr`'s logo —
+    // which arrives through `pick`, so it is already in files and already has an id.
+    //
+    // `3dviewer` is the first persona whose dependency comes from OUTSIDE: a model dragged off a
+    // desktop. Its project file must point at that model, so the model needs a home — and it is not
+    // a document the person made here, it is the asset this persona will reopen itself. Exactly the
+    // case the paragraph above describes, with no verb to express it. The persona was left choosing
+    // between a doctrine it could not follow and a second Save sheet asking somebody to name a file
+    // they did not create.
+    //
+    // ADDITIVE, and that matters: nothing that exists behaves differently. The policy still answers
+    // "who is asking" — same-origin only, exactly as `read` does — so this widens no door.
+    //
+    // It returns the NODE, because a caller writing a project dependency needs the `id`: a path is
+    // what a person renames and an id is what a thing IS.
+    async function write(
+      path: string,
+      bytes: ArrayBuffer | Uint8Array,
+      opts: { mime?: string; keepVersions?: number } = {},
+    ): Promise<{ id: string; name: string; path: string } | null> {
+      const bus = await router();
+      ensureFrame();
+      const body = bytes instanceof Uint8Array
+        ? (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+            ? bytes.buffer
+            : bytes.slice().buffer)
+        : bytes;
+      const node = await arrived!
+        .then(() => bus.proxy({
+          service: "files",
+          method: "write",
+          args: { path, bytes: body, mime: opts.mime, keepVersions: opts.keepVersions },
+          // The same 30s ceiling `read` uses. A model is tens of megabytes and a phone's storage is
+          // not fast; the default would time out on exactly the files this verb exists for.
+          options: { timeout: 30000 },
+        }))
+        .catch(() => null);
+      // A quota that is full, or a path the kernel refused. `null` rather than a throw, for the same
+      // reason `read` returns null: a caller must be able to carry on and say so.
+      if (!node) return null;
+      const n = node as { id: string; name: string };
+      return { id: n.id, name: n.name, path };
+    }
+
     (host as any).pick = pick;
     (sheet as any).pick = pick;
     (host as any).save = save;
     (sheet as any).save = save;
     (host as any).read = read;
     (sheet as any).read = read;
+    (host as any).write = write;
+    (sheet as any).write = write;
   }
 </script>

package/src/Preroll.astro

@@ -344,6 +344,35 @@ const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/
   }
 </style>
 
+<style is:global>
+  /* ── THE STAGE, v2 of the game–shell protocol: what the page does while a game is PLAYING ──────
+   * queries: theater mode · the room dims · cuts inert while playing · the page scrolls under the
+   *          game · oyun basladiginda kararma · stage protocol css
+   *
+   * Global on purpose: everything here styles elements OUTSIDE this component — the page, the other
+   * cuts, the dim the script hangs on <body>. The attribute lives on <html> so one selector reaches
+   * all of it, and so a persona (or a spec) can read the whole state in one place.
+   *
+   * THE DIM IS A LAYER, NOT A THEME. The visitor chose their theme; a cinema does not repaint its
+   * walls, it lowers the lights. The layer covers the room and the room is everything EXCEPT the
+   * stage: the kernel rises above it, the toolbar's slot (z 40) stays above everything, and the
+   * profile and posts cuts stay put underneath it. A dim that covered the frame would dim the GAME —
+   * the exact opposite of what it is for, and invisible in review because it reads as a washed-out
+   * renderer rather than as a z-order mistake.
+   *
+   * Why the dim hangs on <body> rather than living in this component's markup: #pr is a size
+   * container, and layout containment makes it the containing block for FIXED descendants too — a
+   * fixed overlay written inside it would be clipped to the frame it is meant to surround. */
+  html[data-stage="playing"] { overflow: hidden; }
+  html[data-stage="playing"] .cut.kernel { position: relative; z-index: 35; }
+  .pr-room {
+    position: fixed; inset: 0; z-index: 30;
+    background: #05070d; opacity: 0; pointer-events: none;
+    transition: opacity 0.5s var(--ease-out, ease-out);
+  }
+  html[data-stage="playing"] .pr-room { opacity: 0.55; }
+</style>
+
 <script>
   // queries: preroll script · the game never connects · atrium router game · boot · curtain
   //
@@ -429,6 +458,105 @@ const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/
         // A game that cannot speak still runs; it simply gets no progress and no early curtain.
       }
 
+      // ── THE STAGE — v2 of the protocol: who owns attention, and who owns the chrome ─────────
+      //
+      // queries: stage playing · pause the game from the shell · mood accent · theater mode ·
+      //          the cuts stay reachable while playing · focus protocol · oyun basladi
+      //
+      // The game declares STATE and the shell decides what it means — a game never asks for a
+      // toolbar to be hidden, it says what the player is doing. Three messages: `stage` and `mood`
+      // travel up (the same direction every progress report already travels), `pause` comes back.
+      //
+      // THE RETURN DIRECTION IS THE SAFETY OF THE WHOLE DESIGN. Whoever grants exclusive attention
+      // must be able to take it back — the player reached for the way out, the tab went to the
+      // background. A focus handover with no way back does not trap the shell, it traps the PLAYER,
+      // and on a phone the only escape from that is closing the tab. So: a game that has not
+      // declared protocol 2 in its boot answer is never given the stage. The declaration IS the
+      // promise that `pause` is registered, and the shell holds it to that.
+      let protocol = 1;
+      if (bus) {
+        // The room's lights, hung on <body> — see the global style block for why not in here.
+        const room = document.createElement("div");
+        room.className = "pr-room";
+        room.setAttribute("aria-hidden", "true");
+        document.body.appendChild(room);
+
+        const setStage = (mode: string) => {
+          const playing = mode === "playing";
+          if (playing) document.documentElement.dataset.stage = "playing";
+          else delete document.documentElement.dataset.stage;
+          // The other cuts go INERT rather than display:none — the page must not reflow, and the
+          // player's scroll position has to survive a pause. inert takes them out of tab order and
+          // the accessibility tree both; a screen reader must not keep walking a page the player
+          // has left.
+          for (const id of ["profile", "posts"]) {
+            const el = document.getElementById(id);
+            if (el) el.toggleAttribute("inert", playing);
+          }
+          // The page is locked, so make sure what it is locked ON is the stage.
+          if (playing) stage.scrollIntoView({ block: "nearest" });
+          // The toolbar swaps its icons for the handle on this event — it owns its own row.
+          document.dispatchEvent(new CustomEvent("justai:stage", { detail: { mode } }));
+        };
+
+        // ── the mood: meaning, not pixels ─────────────────────────────────────────────────────
+        // A few calls a second at most, eased here over ~600ms — never sampled from a framebuffer.
+        // It leans on the ONE variable the whole ground is already built from, so the persona's
+        // page re-tints without anything being painted: the door's washes, the buttons, the links
+        // all read --accent already.
+        const moodHost = (document.getElementById("infinite") ?? document.documentElement) as HTMLElement;
+        const hex = (c: string) => {
+          const m = /^#([0-9a-f]{6})$/i.exec(c.trim());
+          return m ? [parseInt(m[1].slice(0, 2), 16), parseInt(m[1].slice(2, 4), 16), parseInt(m[1].slice(4, 6), 16)] : null;
+        };
+        let moodRaf = 0;
+        const moodTo = (args: any) => {
+          if (typeof args?.energy === "number")
+            moodHost.style.setProperty("--stage-energy", String(Math.max(0, Math.min(1, args.energy))));
+          const to = typeof args?.accent === "string" ? hex(args.accent) : null;
+          if (!to) return;
+          const from = hex(getComputedStyle(moodHost).getPropertyValue("--accent")) ?? to;
+          cancelAnimationFrame(moodRaf);
+          const t0 = performance.now();
+          const step = (now: number) => {
+            const k = Math.min(1, (now - t0) / 600);
+            const e = k * k * (3 - 2 * k);
+            const c = from.map((f, i) => Math.round(f + (to[i] - f) * e));
+            moodHost.style.setProperty("--accent", `rgb(${c[0]}, ${c[1]}, ${c[2]})`);
+            if (k < 1) moodRaf = requestAnimationFrame(step);
+          };
+          moodRaf = requestAnimationFrame(step);
+        };
+
+        bus.register({
+          method: "stage",
+          handler: (a: any) => {
+            // No protocol 2, no stage — the rule, not a courtesy. See the boot answer below.
+            if (protocol < 2) return { granted: false };
+            setStage(a?.mode === "playing" ? "playing" : "paused");
+            return { granted: true };
+          },
+        });
+        bus.register({ method: "mood", handler: (a: any) => { moodTo(a); return {}; } });
+
+        // The shell's asks, all funnelled through one line so every reason travels the same path.
+        const askPause = (reason: string) =>
+          bus.proxy({ method: "pause", service: "game", args: { reason }, options: { timeout: 3000 } })
+            .catch(() => {});
+        // The pause handle and the fullscreen control live in the toolbar's own row; it dispatches,
+        // this listens. The shell restores its chrome only when the GAME announces `paused` — one
+        // source of truth for state, which is the game, always.
+        document.addEventListener("justai:pause-request", () => askPause("chrome"));
+        document.addEventListener("justai:fullscreen-request", () =>
+          (stage as any).requestFullscreen?.().catch(() => {}));
+        document.addEventListener("visibilitychange", () => {
+          if (document.hidden && document.documentElement.dataset.stage === "playing") askPause("hidden");
+        });
+        document.addEventListener("keydown", (e) => {
+          if (e.key === "Escape" && document.documentElement.dataset.stage === "playing") askPause("chrome");
+        });
+      }
+
       const arrived = bus
         ? new Promise<void>((resolve) => bus.on("connected", (e: any) => { if (e?.name === "game") resolve(); }))
         : Promise.resolve();
@@ -496,6 +624,11 @@ const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/
       ]);
       if (watchdog) clearTimeout(watchdog);
 
+      // The boot answer carries the game's protocol version, and version 2 is the declaration
+      // that `pause` is registered and will be honoured. Read before open(), so a game announcing
+      // `playing` in its very first frame is already trusted.
+      protocol = typeof answer?.protocol === "number" ? answer.protocol : 1;
+
       open();
       // `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

package/src/Toolbar.astro

@@ -156,6 +156,8 @@ import BackToZone from "./BackToZone.astro";
 const {
   sectionsLabel, profileLabel, kernelLabel, postsLabel,
   files = true, filesLabel = "Files", kernelTitle, postsTitle, avatar = "/icon.svg", parent,
+  pauseLabel = "Pause",
+  fullscreenLabel = "Fullscreen",
 } = 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.
@@ -261,6 +263,29 @@ import AuthMount from "./AuthMount.astro";
              page (justai.pro carries app.zone's mark here). Keeping it out of <nav aria-label=sections>
              is the a11y half of the reason it is its own slot. -->
         <slot name="leftExtra" />
+        <!-- ── THE HANDLE — the stage protocol's one promise about this row ─────────────────────
+             queries: pause button in the toolbar · the way back while playing · stage controls ·
+                      fullscreen button · oyun icinde geri donus
+
+             THE SHELL DOES NOT DISAPPEAR. IT WITHDRAWS TO A SINGLE HANDLE, AND THAT HANDLE IS THE
+             WAY BACK. While a game is playing the section nav fades and goes inert, and these two
+             controls appear in the same row, in the same place — so the way back is where the way
+             around used to be. Hiding everything is a trap; hiding everything except the way out is
+             a stage.
+
+             The buttons only DISPATCH. The Preroll owns the bus, so it listens and asks the game;
+             the chrome is restored when the GAME announces paused, never optimistically — state has
+             one source and it is the game. Fullscreen is feature-detected in the script below:
+             absent rather than dead where the platform does not implement it, which is every
+             iPhone. -->
+        <span class="tb-stage" id="tbStage">
+          <button class="tb-nav tb-pausebtn" id="tbPause" type="button" aria-label={pauseLabel} title={pauseLabel}>
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M9 5v14M15 5v14"/></svg>
+          </button>
+          <button class="tb-nav tb-fsbtn" id="tbFullscreen" type="button" aria-label={fullscreenLabel} title={fullscreenLabel} hidden>
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3H5a2 2 0 0 0-2 2v3M16 3h3a2 2 0 0 1 2 2v3M8 21H5a2 2 0 0 1-2-2v-3M16 21h3a2 2 0 0 0 2-2v-3"/></svg>
+          </button>
+        </span>
       </div>
       <div class="tb-right">
         <slot name="toolbarRight" />
@@ -439,6 +464,19 @@ import AuthMount from "./AuthMount.astro";
   .tb-left { display: flex; align-items: center; gap: 2px; min-width: 0; }
   .tb-nav-group { display: flex; align-items: center; gap: 2px; }
   .tb-right { display: flex; align-items: center; min-width: 0; }
+
+  /* ── the withdraw: what this row does while a game is playing ───────────────────────────────
+   * Opacity and pointer-events here; the INERT that takes them out of the tab order is set in the
+   * script, because CSS cannot. The transition matters more than it looks: chrome that snaps away
+   * reads as breaking, chrome that withdraws reads as dimming the house lights. */
+  .tb-stage { display: none; align-items: center; gap: 2px; }
+  :global(html[data-stage="playing"]) .tb-stage { display: flex; }
+  :global(html[data-stage="playing"]) .tb-nav-group,
+  :global(html[data-stage="playing"]) .tb-right,
+  :global(html[data-stage="playing"]) .tb-title {
+    opacity: 0.16; pointer-events: none;
+    transition: opacity 0.4s var(--ease-out);
+  }
   /* icon-only section nav — current cut highlighted */
   .tb-nav {
     display: grid; place-items: center; width: 38px; height: 36px;
@@ -604,6 +642,27 @@ import AuthMount from "./AuthMount.astro";
   // 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.
+  // ── the stage handle — see the markup's comment for the design ────────────────────────────
+  // queries: pause button does nothing · fullscreen hidden on iphone · toolbar during a game
+  const tbStage = document.getElementById("tbStage");
+  if (tbStage) {
+    const fsBtn = document.getElementById("tbFullscreen") as HTMLButtonElement | null;
+    // Feature-detected, absent rather than dead: Element.requestFullscreen does not exist in
+    // Safari on iPhone (iPad has it), and a button that throws is worse than no button.
+    if (fsBtn && "requestFullscreen" in document.documentElement) fsBtn.hidden = false;
+    document.getElementById("tbPause")?.addEventListener("click", () =>
+      document.dispatchEvent(new CustomEvent("justai:pause-request")));
+    fsBtn?.addEventListener("click", () =>
+      document.dispatchEvent(new CustomEvent("justai:fullscreen-request")));
+    // The nav fades by CSS; inert is what CSS cannot do — out of the tab order and the
+    // accessibility tree, so a keyboard or a screen reader is not walking chrome the player left.
+    document.addEventListener("justai:stage", (e: any) => {
+      const playing = e?.detail?.mode === "playing";
+      document.querySelector(".tb-nav-group")?.toggleAttribute("inert", playing);
+      document.querySelector(".tb-right")?.toggleAttribute("inert", playing);
+    });
+  }
+
   const bar = document.querySelector(".toolbar") as HTMLElement | null;
   const kt = bar?.dataset.kernelTitle;
   const pt = bar?.dataset.postsTitle;