@justai/cuts 0.145.0 → 0.147.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.145.0",
+  "version": "0.147.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@justai/core": "^0.38.0",
+    "@justai/core": "^0.39.0",
     "@justai/ui": "^0.26.0",
     "@justai/atrium": "^0.1.9"
   },

package/src/Preroll.astro

@@ -43,9 +43,35 @@
 // "unstyled" — it means the player watches the game boot through the loading screen.
 import "./ground.css";
 
+type StoreKey = "ios" | "mac" | "android" | "steam" | "windows" | "switch" | "playstation" | "xbox";
+
 interface Props {
-  /** The game's own document, served from this persona's origin. */
-  src: string;
+  /** The game's own document, served from this persona's origin. Give this OR `stores`, never both. */
+  src?: string;
+
+  // ── THE DOOR THAT OPENS OUTWARD ───────────────────────────────────────────────────────────
+  //
+  // queries: native game persona · a game persona for an app store title · the play button goes
+  //          to the app store · store links on the preroll · door store · no frame · external store ·
+  //          persona published on the app store · cob · which store does the button open
+  //
+  // THE KERNEL OF A GAME PERSONA IS NOT THE GAME; IT IS THE DOOR TO IT — and a door can open
+  // outward. A game that lives in the App Store, Google Play or Steam is still one character with
+  // one home on pin.games: the same card, the same feed, the same three child personas. What differs
+  // is where the button leads. With `stores` instead of `src` the door keeps its composition and its
+  // gesture, and the button becomes a link to the store this visitor's device can install from — no
+  // frame is ever created, nothing is fetched, atrium is never asked for a room.
+  //
+  // Declared in the persona's manifest as `door: store` (dna · persona.example.yml), and this is the
+  // shell's side of that declaration. The first citizen: pg-cob, Clash of Boats — the ecosystem's
+  // first persona published on external stores (2026-09-15).
+  //
+  // The keys are the platforms a title can be installed on; the values are the store pages. Order
+  // is preference: the first one is the button's address before the device has been asked, and the
+  // address for a device nothing below matches.
+  stores?: Partial<Record<StoreKey, string>>;
+  /** The small word before the row of every store, e.g. "Also on". Only read with `stores`. */
+  also?: string;
 
   // ── THE FIVE FIELDS ARE THE PERSONA'S CARD ────────────────────────────────────────────────
   //
@@ -86,11 +112,28 @@ interface Props {
   /** atrium ids are a grammar — [a-z0-9._-] — so this is sanitised rather than trusted. */
   id?: string;
 }
-const { src, kicker, name, tag, sub, play, title, loading = "Loading", id = "game" } = Astro.props;
+const { src, stores, also = "Also on", kicker, name, tag, sub, play, title, loading = "Loading", id = "game" } = Astro.props;
 const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "x");
+
+// ONE DOOR, ONE DIRECTION. A preroll with both a frame and a store list would render two answers to
+// "what happens when I press play", and the one nobody meant is the one somebody finds in production
+// — the same refusal the template makes for two Cores in one kernel. Refused at build, with a sentence.
+const outward = Object.entries(stores ?? {}).filter(([, url]) => typeof url === "string" && url) as [StoreKey, string][];
+if (src && outward.length) throw new Error("<Preroll> takes `src` (a game document) or `stores` (a native title), not both");
+if (!src && !outward.length) throw new Error("<Preroll> needs a door: `src` for a game document, or `stores` with at least one store page");
+
+// Proper nouns, not copy — a store's name is the same in every language, which is why these live
+// here and not in a persona's dictionary. An unknown key is shown as itself rather than refused: the
+// next console to exist should not need this file to change first.
+const STORE_NAMES: Record<string, string> = {
+  ios: "App Store", mac: "Mac App Store", android: "Google Play", steam: "Steam",
+  windows: "Microsoft Store", switch: "Nintendo eShop", playstation: "PlayStation Store", xbox: "Xbox",
+};
+const storeRows = outward.map(([key, url]) => ({ key, url, label: STORE_NAMES[key] ?? key }));
+const primary = storeRows[0]?.url;
 ---
 
-<div class="pr" id="pr" data-src={src} data-atrium={safeId}>
+<div class="pr" id="pr" data-src={src} data-atrium={src ? safeId : undefined} data-door={outward.length ? "store" : "frame"}>
   {/* ── THE STAGE IS THE FLOW; THE DOOR IS A COVER 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
@@ -118,10 +161,29 @@ const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/
     {/* THE INVITATION BECOMES THE WAIT, IN PLACE. The first version replaced the whole door with a
         bar in an empty room: two screens, and the player was moved from one to the other for no
         reason they could see. The composition stays; this button fills. */}
-    <button class="pr-play" id="prPlay" type="button" data-label={play} data-loading={loading}>
-      <i class="pr-fill" id="prFill"></i>
-      <span id="prLabel">{play}</span>
-    </button>
+    {outward.length ? (
+      <>
+        {/* THE DOOR THAT OPENS OUTWARD. The same button in the same place, and it is a LINK: it works
+            with no script at all, it opens the store app on a phone, and it keeps this persona open
+            behind it. The behaviour module only improves the address — it asks the device which
+            store it can install from and points the button there; the row below shows every other
+            way in, so a desktop visitor is never told "iPhone only" by a page that knew better. */}
+        <a class="pr-play" id="prPlay" href={primary} target="_blank" rel="noopener" data-label={play}>
+          <span id="prLabel">{play}</span>
+        </a>
+        <p class="pr-stores" id="prStores">
+          <span class="pr-stores-also">{also}</span>
+          {storeRows.map((s) => (
+            <a href={s.url} target="_blank" rel="noopener" data-store={s.key}>{s.label}</a>
+          ))}
+        </p>
+      </>
+    ) : (
+      <button class="pr-play" id="prPlay" type="button" data-label={play} data-loading={loading}>
+        <i class="pr-fill" id="prFill"></i>
+        <span id="prLabel">{play}</span>
+      </button>
+    )}
 
     {/* queries: preroll imprint · sponsor · brand on the preroll · monetization out of the frame
         AN EMPTY SLOT ON PURPOSE, and it renders nothing until somebody fills it. The preroll is the
@@ -200,8 +262,8 @@ const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/
      * where the browser puts its own bar. He sent a screenshot from one: the URL bar sitting over the
      * play button, and a strip of the next section showing beneath it. A composition that ends at the
      * frame's bottom edge is a composition whose call to action a phone can cover. */
-    grid-template-rows: 50% auto auto minmax(0, 1fr);
-    grid-template-areas: "art" "copy" "play" "imprint";
+    grid-template-rows: 50% auto auto auto minmax(0, 1fr);
+    grid-template-areas: "art" "copy" "play" "stores" "imprint";
     padding: clamp(18px, 7cqw, 64px);
     /* And the strip the OS keeps for its home indicator, on top of the inset — never instead of it. */
     padding-block-end: calc(clamp(18px, 7cqw, 64px) + env(safe-area-inset-bottom, 0px));
@@ -273,7 +335,22 @@ const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/
     background: var(--accent); color: var(--accent-on); cursor: pointer;
     transition: transform 0.18s var(--ease-spring), opacity 0.2s;
   }
+  /* The outward door's button is an <a>, and a link has none of a button's box by default. Said
+     here once so both elements are the same shape to the eye and to the grid. */
+  .pr-play { display: inline-flex; align-items: center; justify-content: center; text-align: center; text-decoration: none; }
   .pr-play:active { transform: scale(0.97); }
+  /* ── EVERY OTHER WAY IN ──────────────────────────────────────────────────────────────────────
+     Rendered only by the outward door: the word, then one link per store. The one the device
+     matched is marked and quietened, because it is already the button. Wraps rather than scrolls —
+     a landscape phone is the shape this row is most likely to be read in. */
+  .pr-stores {
+    grid-area: stores; margin: clamp(8px, 1.6cqh, 14px) 0 0;
+    display: flex; flex-wrap: wrap; align-items: center; gap: 0.35em 0.9em;
+    font-size: clamp(0.75rem, 3cqw, 0.95rem); font-weight: 500; color: #8b949e;
+  }
+  .pr-stores a { color: #f5f7fa; text-decoration: none; border-bottom: 1px solid color-mix(in srgb, #f5f7fa 30%, transparent); }
+  .pr-stores a[data-current] { color: #8b949e; border-bottom-color: transparent; }
+  @container pr (max-height: 380px) { .pr-stores { display: none; } }
   .pr-play[data-busy] { cursor: default; }
   .pr-play[data-busy]:active { transform: none; }
   .pr-play span { position: relative; z-index: 1; }
@@ -301,8 +378,8 @@ const safeId = "game-" + (id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/
        centred in the box rather than pinned to its top. */
     .pr-door {
       grid-template-columns: 1fr auto;
-      grid-template-rows: auto auto auto;
-      grid-template-areas: "copy art" "play art" "imprint art";
+      grid-template-rows: auto auto auto auto;
+      grid-template-areas: "copy art" "play art" "stores art" "imprint art";
       align-content: center;
       column-gap: clamp(24px, 5cqw, 72px);
     }

package/src/behaviour/preroll.ts

@@ -15,8 +15,45 @@
 // name lets any frame on the page claim to be the game.
 import atrium from "@justai/atrium";
 
+// ── THE DOOR THAT OPENS OUTWARD ─────────────────────────────────────────────────────────────────
+//
+// queries: native game persona · store door · the play button opens the app store · which store ·
+//          door store · pg-cob · a game persona with no frame · iPad reports as a Mac
+//
+// A game that lives in a store is still a persona here; only the door's direction differs. The
+// component already rendered the button as a LINK to the first declared store, so this module's
+// whole job is to improve the address: ask the device which store it can install from, point the
+// button there, and mark that store in the row beneath. Nothing else in this file runs — no frame,
+// no router, no watchdog — because there is no frame to wait for.
+//
+// The device is asked, never the reader: no locale, no cookie, no guess about who they are.
+// iPadOS is the one trap — Safari there reports a Mac with touch points, and a Mac App Store link on
+// an iPad is a dead end — so a touch-capable "Mac" is read as iOS first.
+export function storeFor(keys: string[], ua: string, platform: string, touchPoints: number): string | null {
+  const has = (k: string) => (keys.includes(k) ? k : null);
+  const iPadOS = /Mac/.test(platform) && touchPoints > 1;
+  if (/iPhone|iPad|iPod/.test(ua) || iPadOS) return has("ios") ?? has("mac");
+  if (/Android/.test(ua)) return has("android");
+  if (/Mac/.test(platform)) return has("mac") ?? has("ios") ?? has("steam");
+  if (/Win/.test(platform)) return has("windows") ?? has("steam") ?? has("xbox");
+  if (/Linux|X11/.test(platform)) return has("steam");
+  return null;
+}
+
 const root = document.getElementById("pr");
-if (root) {
+if (root && root.dataset.door === "store") {
+  const playLink = document.getElementById("prPlay") as HTMLAnchorElement | null;
+  const rows = Array.from(document.querySelectorAll<HTMLAnchorElement>("#prStores a[data-store]"));
+  const keys = rows.map((a) => a.dataset.store as string);
+  const platform = (navigator as any).userAgentData?.platform || navigator.platform || "";
+  const chosen = storeFor(keys, navigator.userAgent, platform, navigator.maxTouchPoints || 0);
+  const row = rows.find((a) => a.dataset.store === chosen);
+  if (playLink && row) {
+    playLink.href = row.href;
+    playLink.dataset.store = chosen as string;
+    row.setAttribute("data-current", "");
+  }
+} else if (root) {
   const door = document.getElementById("prDoor") as HTMLElement;
   const stage = document.getElementById("prStage") as HTMLElement;
   const fill = document.getElementById("prFill") as HTMLElement;