@justai/cuts 0.149.0 → 0.151.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.149.0",
+  "version": "0.151.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.39.0",
-    "@justai/ui": "^0.26.0",
+    "@justai/core": "^0.40.0",
+    "@justai/ui": "^0.27.0",
     "@justai/atrium": "^0.1.9"
   },
   "scripts": {

package/src/Base.astro

@@ -92,11 +92,42 @@ interface Props {
    * sides and is *at least* the active view's height; a GAME kernel keeps no inset at all and is
    * *exactly* that height.
    *
+   * `art` (2026-10-09) — a musical or visual work that embeds its piece — takes the game's geometry and
+   * its dark ground: it is entered, not scrolled.
+   *
    * IT DEFAULTS TO `app` BECAUSE FIFTEEN OF THE SIXTEEN PERSONAS ARE ONE. The failure of getting it
    * wrong is quiet in the right direction: a game persona that forgets it renders as an app — margins
    * where it wanted none — rather than an app persona bleeding to the edges.
    */
-  kind?: "app" | "game" | "now" | "expert" | "knower" | "platform";
+  kind?: "app" | "game" | "art" | "now" | "expert" | "knower" | "platform";
+  /**
+   * queries: a persona with pages of its own · canonical points at the home · every page has the
+   *          persona's og image · per-page title · per-page share card · hreflang for a sub-page ·
+   *          a QR opens a page that previews as the home
+   *
+   * A PAGE OF ITS OWN — for a persona whose kernel is many named things, each at its own address
+   * (`card.cityinmotion.nl/where-waters-meet`). Leave it out and this layout writes the persona's
+   * HOME, which is right for every persona that has one page: the persona's title, its `/og.jpg`, and
+   * a canonical at the locale's root.
+   *
+   * Written for a page that is NOT the home, those three are false in the worst way: nothing is red,
+   * the page renders, and every one of its tags says "I am the home". A search engine then folds all
+   * of them into one result (a canonical is an instruction, not a hint it ignores), and a link to one
+   * of them pasted into a chat previews as the persona's generic card instead of the thing linked —
+   * which, for a printed QR code, is the one impression there is. Birth 10 found it before the first
+   * page shipped.
+   *
+   * `path(locale)` is the page's address in each locale, so the alternates name THIS page in every
+   * language rather than the other languages' homes. `image` is absolute or site-relative; its size is
+   * required because a preview that has to fetch the image to learn its shape renders late or not at
+   * all.
+   */
+  page?: {
+    path: (locale: string) => string;
+    title: string;
+    description: string;
+    image?: { url: string; width: number; height: number; type?: string; alt?: string };
+  };
 }
 
 const {
@@ -105,6 +136,7 @@ const {
   themeLight,
   gaId = "G-13L3BP6XCW",
   kind = "app",
+  page,
 } = Astro.props;
 
 // ── ONE HOME FOR THE ORIGIN ───────────────────────────────────────────────────────────────────
@@ -147,12 +179,23 @@ if (siteProp && Astro.site && new URL(siteProp).origin !== Astro.site.origin) {
 // bottom of the screen because there is nothing there that is not the room. A persona that wants
 // otherwise passes its own — this is a default, not a law.
 const GAME_GROUND = "#080b12";
-const dark = themeDark ?? (kind === "game" ? GAME_GROUND : "#000000");
-const light = themeLight ?? (kind === "game" ? GAME_GROUND : "#f2f2f7");
+const placeKind = kind === "game" || kind === "art";   // a place you go into: the dark ground in both schemes
+const dark = themeDark ?? (placeKind ? GAME_GROUND : "#000000");
+const light = themeLight ?? (placeKind ? GAME_GROUND : "#f2f2f7");
 
 const d = dirOf(lang);
 const consent = consentCopy(lang);
 const localePath = (l: string) => (l === defaultLocale ? "/" : `/${l}/`);
+
+// The head speaks for the page when the page has its own address, and for the persona otherwise —
+// see `page` above. One set of values, so the canonical, og:url and the alternates cannot disagree.
+const hrefOf = (l: string) => `${site}${page ? page.path(l) : localePath(l)}`;
+const canonical = hrefOf(lang);
+const headTitle = page?.title ?? t.metaTitle;
+const headDescription = page?.description ?? t.metaDescription;
+const ogImage = page?.image
+  ? { ...page.image, url: new URL(page.image.url, Astro.site).href }
+  : { url: new URL("/og.jpg", Astro.site).href, width: 1200, height: 630, type: "image/jpeg", alt: undefined };
 ---
 
 <!doctype html>
@@ -244,26 +287,27 @@ const localePath = (l: string) => (l === defaultLocale ? "/" : `/${l}/`);
         } catch (e) {}
       })();
     </script>
-    <title>{t.metaTitle}</title>
-    <meta name="description" content={t.metaDescription} />
-    <meta property="og:title" content={t.metaTitle} />
-    <meta property="og:description" content={t.metaDescription} />
+    <title>{headTitle}</title>
+    <meta name="description" content={headDescription} />
+    <meta property="og:title" content={headTitle} />
+    <meta property="og:description" content={headDescription} />
     <meta property="og:type" content="website" />
-    <meta property="og:image" content={new URL("/og.jpg", Astro.site)} />
-    <meta property="og:image:type" content="image/jpeg" />
-    <meta property="og:image:width" content="1200" />
-    <meta property="og:image:height" content="630" />
-    <meta property="og:url" content={new URL(Astro.url.pathname, Astro.site)} />
+    <meta property="og:image" content={ogImage.url} />
+    {ogImage.type && <meta property="og:image:type" content={ogImage.type} />}
+    <meta property="og:image:width" content={String(ogImage.width)} />
+    <meta property="og:image:height" content={String(ogImage.height)} />
+    {ogImage.alt && <meta property="og:image:alt" content={ogImage.alt} />}
+    <meta property="og:url" content={page ? canonical : new URL(Astro.url.pathname, Astro.site).href} />
     <meta property="og:site_name" content={new URL(site).host} />
     <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:image" content={new URL("/og.jpg", Astro.site)} />
+    <meta name="twitter:image" content={ogImage.url} />
     <meta name="theme-color" content={dark} media="(prefers-color-scheme: dark)" />
     <meta name="theme-color" content={light} media="(prefers-color-scheme: light)" />
-    <link rel="canonical" href={`${site}${localePath(lang)}`} />
+    <link rel="canonical" href={canonical} />
     {locales.map((l) => (
-      <link rel="alternate" hreflang={l} href={`${site}${localePath(l)}`} />
+      <link rel="alternate" hreflang={l} href={hrefOf(l)} />
     ))}
-    <link rel="alternate" hreflang="x-default" href={`${site}/`} />
+    <link rel="alternate" hreflang="x-default" href={page ? hrefOf(defaultLocale) : `${site}/`} />
     <link rel="icon" href="/favicon.ico" sizes="32x32" />
     <link
       rel="icon"

package/src/Preroll.astro

@@ -46,9 +46,24 @@ 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. Give this OR `stores`, never both. */
+  /** The game's own document, served from this persona's origin — or a WORK at its own address
+   *  (`https://…`), embedded as it is. Give this OR `stores`, never both. */
   src?: string;
 
+  // ── A WORK THAT LIVES AT ITS OWN ADDRESS ──────────────────────────────────────────────────
+  //
+  // queries: art persona · embed a work by iframe · the kernel embeds another site · city rises ·
+  //          the work updates without the shell · handover on load · a frame that does not speak atrium
+  //
+  // An `art` persona's kernel does not carry the work, it EMBEDS it: City Rises lives at
+  // city-rises.justrd.pro and keeps changing there, and city-rises.cityinmotion.nl shows it without a
+  // release of its own. Such a work does not speak the game–shell protocol — it has its own gate and
+  // asks for its own gesture — so waiting for a `boot` answer would hold the door for the whole
+  // patience window. `handover` says what ends the wait: `boot` (the protocol's answer, the default
+  // for a document on this origin) or `load` (the frame's own load event, the default for a `src`
+  // that names another origin). Same door, same gesture, same bar; only the signal differs.
+  handover?: "boot" | "load";
+
   // ── THE DOOR THAT OPENS OUTWARD ───────────────────────────────────────────────────────────
   //
   // queries: native game persona · a game persona for an app store title · the play button goes
@@ -113,6 +128,7 @@ interface Props {
   id?: string;
 }
 const { src, stores, also = "Also on", kicker, name, tag, sub, play, title, loading = "Loading", id = "game" } = Astro.props;
+const handover = Astro.props.handover ?? (/^https?:\/\//i.test(src ?? "") ? "load" : "boot");
 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
@@ -133,7 +149,7 @@ const storeRows = outward.map(([key, url]) => ({ key, url, label: STORE_NAMES[ke
 const primary = storeRows[0]?.url;
 ---
 
-<div class="pr" id="pr" data-src={src} data-atrium={src ? safeId : undefined} data-door={outward.length ? "store" : "frame"}>
+<div class="pr" id="pr" data-src={src} data-handover={src ? handover : undefined} 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

package/src/behaviour/preroll.ts

@@ -62,6 +62,8 @@ if (root && root.dataset.door === "store") {
 
   const src = root.dataset.src as string;
   const atriumId = root.dataset.atrium as string;
+  // `load` for a work at its own address (see Preroll.astro, "A WORK THAT LIVES AT ITS OWN ADDRESS").
+  const onLoad = root.dataset.handover === "load";
 
   let started = false;
 
@@ -268,7 +270,10 @@ if (root && root.dataset.door === "store") {
     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;
+    // A document on this origin is named by its path, as it always was; a work at another address
+    // keeps its whole address — the path alone would load a page of this persona into the frame.
+    frame.src = url.origin === location.origin ? url.pathname + url.search : url.href;
+    const loaded = new Promise<any>((resolve) => frame.addEventListener("load", () => resolve({}), { once: true }));
 
     // ── THE HANDOVER ─────────────────────────────────────────────────────────────────────────
     //
@@ -309,12 +314,16 @@ if (root && root.dataset.door === "store") {
     // 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.
+    // A work that does not speak the protocol is ready when its document has loaded — it draws its
+    // own gate from there. Its frame's load event joins the race only for `handover: load`: a game on
+    // this origin loads its document long before it can draw, and that is what the boot answer is for.
     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,
+      ...(onLoad ? [loaded] : []),
     ]);
     if (watchdog) clearTimeout(watchdog);