@justai/cuts 0.150.0 → 0.151.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.150.0",
+  "version": "0.151.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {

package/src/Base.astro

@@ -100,6 +100,34 @@ interface Props {
    * where it wanted none — rather than an app persona bleeding to the edges.
    */
   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 {
@@ -108,6 +136,7 @@ const {
   themeLight,
   gaId = "G-13L3BP6XCW",
   kind = "app",
+  page,
 } = Astro.props;
 
 // ── ONE HOME FOR THE ORIGIN ───────────────────────────────────────────────────────────────────
@@ -157,6 +186,16 @@ 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>
@@ -248,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"