@justai/cuts 0.157.0 → 0.158.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.157.0",
+  "version": "0.158.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -32,6 +32,10 @@
     "./Sheet.astro": "./src/Sheet.astro",
     "./Toolbar.astro": "./src/Toolbar.astro",
     "./ground.css": "./src/ground.css",
+    "./personaHref": {
+      "types": "./src/personaHref.d.ts",
+      "default": "./src/personaHref.js"
+    },
     "./tagline.js": "./src/tagline.js"
   },
   "peerDependencies": {

package/src/Catalogue.astro

@@ -38,6 +38,7 @@
 // statement about what the ecosystem IS, living in one page's markup, twice. It is now a question
 // asked of the registry, which has carried `personaKind` since long before anything read it.
 import CatalogueCard, { type CatalogueEntry } from "./CatalogueCard.astro";
+import { personaHref } from "./personaHref.js";
 
 interface Props {
   /** BCP-47 code of the page — the language the registry is asked for. */
@@ -63,6 +64,19 @@ interface Props {
   kind?: string;
   /** The apex's own host, used for the referral parameter on every card. */
   apexHost: string;
+  /**
+   * queries: localeLinks · clean locale links · ref=app.zone · lang parameter · data-locale-links
+   *
+   * LINK STRAIGHT TO THE PERSONA'S PAGE IN THIS PAGE'S LANGUAGE — `https://<home>/<lang>/`, no query
+   * string — instead of `https://<home>/?ref=<apex>&lang=<lang>`.
+   *
+   * An apex turns this on when its citizens all serve the apex's languages at `/<lang>/` (app.zone:
+   * measured, 37 of 37 personas × 13 languages). It is a statement only the apex can make, which is
+   * why it is a prop and not the default: a persona that lacks the language answers 404 at that
+   * address, where the old hint was quietly ignored. See ./personaHref.js for the measurements that
+   * made the parameters worth removing.
+   */
+  localeLinks?: boolean;
   /** Layer one. Empty is valid and correct for an apex with nothing seeded yet. */
   seed?: CatalogueEntry[];
   /** The curated sequence, keyed by host — read by the runtime sort. */
@@ -102,7 +116,7 @@ interface Props {
   };
 }
 const {
-  lang, apexHost,
+  lang, apexHost, localeLinks = false,
   seed = [], order = [], taglines = {}, catLabels = {}, entries = {},
   locales, strings,
 } = Astro.props;
@@ -228,8 +242,8 @@ const isNew = (added: string): boolean => { const t0 = Date.parse(added || "");
       {/* taglines ride the same channel as newLabel and catMap: a data attribute on the grid. The
           runtime append builds its cards in plain strings and cannot reach this component's scope, so
           anything it needs has to arrive this way. Keyed by host, which is what the API calls `home`. */}
-      <section class="grid" id="grid" data-apex={apexHost} data-new-label={strings.new} data-cat-map={JSON.stringify(catLabels)} data-order={JSON.stringify(order)} data-taglines={JSON.stringify(taglines)}>
-        {seed.map((app) => <CatalogueCard app={app} name={appName(app)} desc={appDesc(app)} isNew={isNew(app.added)} newLabel={strings.new} />)}
+      <section class="grid" id="grid" data-apex={apexHost} data-locale-links={localeLinks ? "" : undefined} data-new-label={strings.new} data-cat-map={JSON.stringify(catLabels)} data-order={JSON.stringify(order)} data-taglines={JSON.stringify(taglines)}>
+        {seed.map((app) => <CatalogueCard app={app} href={localeLinks ? personaHref(hostOf(app.url), lang) : undefined} name={appName(app)} desc={appDesc(app)} isNew={isNew(app.added)} newLabel={strings.new} />)}
       </section>
       {/* queries: runtime cards are unstyled · the card has no CSS · an apex with no seed · scope cid ·
                    data-astro-cid · pin.games cards render as blue links
@@ -264,8 +278,21 @@ const isNew = (added: string): boolean => { const t0 = Date.parse(added || "");
   // locale list has ONE home and is never typed here. A literal array once lived on this line and
   // drifted: it was edited by hand when Italian shipped, and any locale missing from it fell through
   // to "en", which the receiving persona then WROTE as the visitor's saved language choice.
-  // Pass the visitor's language + a referral to each app link, so apps open in the same
-  // language and show their "home → app.zone" affordance.
+  // queries: ?ref=app.zone&lang= indexed · parameterised persona url in search console · crawler sees
+  //          ref and lang · Google indexed the hint, not the page · when does a card get ?ref
+  //
+  // THE VISITOR'S LANGUAGE AND A REFERRAL, HANDED OVER AT THE MOMENT OF THE TAP — never written into
+  // the page. This used to rewrite every card's href on load. A crawler renders the script too, so the
+  // links it followed were `https://<home>/?ref=<apex>&lang=<xx>`. That address is a page whose HTML is
+  // the default language, whose canonical is the root, and whose script goes elsewhere. Search Console
+  // then filed those addresses as pages of their own: 232 "Page with redirect" and 67 indexed on
+  // app.zone (2026-10-11, see ./personaHref.js).
+  //
+  // Now the href in the DOM stays whatever the card was rendered with: the persona's own page in this
+  // language when the apex opted in (`localeLinks`), its bare root otherwise. The hint is added only
+  // when a person actually opens a card: pointerdown, keyboard Enter or a context menu, delegated so
+  // runtime-appended cards are covered. A crawler does none of those. An apex on `localeLinks` needs no
+  // hint at all, because the address is already the language.
   (function () {
     function detectLang() {
       const saved = localStorage.getItem("lang");
@@ -277,15 +304,21 @@ const isNew = (added: string): boolean => { const t0 = Date.parse(added || "");
       }
       return "en";
     }
-    const lang = detectLang();
-    for (const a of document.querySelectorAll(".card")) {
+    const grid = document.getElementById("grid");
+    if (!grid || grid.dataset.localeLinks !== undefined) return;
+    function hint(e) {
+      const a = e.target && e.target.closest ? e.target.closest("a.card") : null;
+      if (!a || !grid.contains(a)) return;
       try {
         const u = new URL(a.href);
         u.searchParams.set("ref", apexHost);
-        u.searchParams.set("lang", lang);
+        u.searchParams.set("lang", detectLang());
         a.href = u.toString();
-      } catch (e) {}
+      } catch (err) {}
     }
+    // pointerdown precedes click, middle-click and cmd-click alike; keydown covers Enter on a focused
+    // card; contextmenu covers "open in new tab". Capture phase, so nothing below can skip it.
+    for (const type of ["pointerdown", "keydown", "contextmenu"]) document.addEventListener(type, hint, true);
   })();
 
   // queries: can a campaign link to just one app or one category · what is the ?apps= URL parameter ·

package/src/CatalogueCard.astro

@@ -17,8 +17,10 @@ export interface CatalogueEntry {
 // words repeated down the page — "Fitness" four times — carrying almost no information per card, while
 // costing every card a block-level line. As a filter it earns its space instead, and it surfaces the
 // ?category= slice the catalog already supported but never showed. data-category stays: the filter reads it.
-const { app, name, desc, isNew, newLabel } = Astro.props as {
-  app: App; name: string; desc: string; isNew: boolean; newLabel: string;
+// `href` — where the card goes, when the apex has a better answer than the persona's bare root (its page in
+// this page's language; see Catalogue's `localeLinks`). The icon still comes from `app.url`, the root.
+const { app, name, desc, isNew, newLabel, href } = Astro.props as {
+  app: App; name: string; desc: string; isNew: boolean; newLabel: string; href?: string;
 };
 // The persona's canonical icon — every persona serves /icon.svg on its own host. One face everywhere.
 const icon = `${app.url}/icon.svg`;
@@ -26,7 +28,7 @@ const icon = `${app.url}/icon.svg`;
 
 <a
   class="card"
-  href={app.url}
+  href={href ?? app.url}
   data-name={`${name} ${app.name}`.toLowerCase()}
   data-category={app.category}
   data-id={app.id.toLowerCase()}

package/src/behaviour/catalogue.ts

@@ -21,6 +21,8 @@
 // nothing errors, the card just renders completely unstyled. (2) The whole grid is re-sorted after
 // the append, seeds and newcomers together, so ordering is a property of the merged list, not of
 // either source. Then a `zone:cards` event lets the URL filter re-run over the newcomers.
+import { personaHref } from "../personaHref.js";
+
 (function () {
   const grid = document.getElementById("grid");
   if (!grid) return;
@@ -40,6 +42,8 @@
   // household where they part — its citizens are sometimes games and sometimes apps — and asking it
   // for one kind returns half a family and calls that the storefront.
   const apexHost = grid.dataset.apex || "app.zone";
+  // Present (even empty) when the apex opted in to clean locale links — see Catalogue's `localeLinks`.
+  const localeLinks = grid.dataset.localeLinks !== undefined;
   // The category label must be localized like the SSR path (catLabel), but the API returns the
   // category in English regardless of ?locale=. So carry this page's cat dictionary through a data
   // attribute (same channel as newLabel) and map through it — the English key stays the stable
@@ -73,7 +77,7 @@
   const esc = (s: unknown): string =>
     String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] as string);
 
-  type Entry = { handle: string; home: string; bio: string | null; name: string | null; avatar: string | null; glyph: string | null; category: string | null; accent: string | null; qrIcon: boolean; badge: string | null; createdAt: string | null };
+  type Entry = { handle: string; home: string; locales?: string[] | null; bio: string | null; name: string | null; avatar: string | null; glyph: string | null; category: string | null; accent: string | null; qrIcon: boolean; badge: string | null; createdAt: string | null };
   const cardHTML = (a: Entry): string => {
     const url = `https://${a.home}`;
     // the persona's canonical icon, served on its own host — one face everywhere (avatar wins; glyph is gone).
@@ -133,7 +137,16 @@
           el.setAttribute(scopeAttr, "");
           el.querySelectorAll("*").forEach((n) => n.setAttribute(scopeAttr, ""));
         }
-        try { const u = new URL(el.href); u.searchParams.set("ref", apexHost); u.searchParams.set("lang", locale); el.href = u.toString(); } catch {}
+        // queries: ref=app.zone · lang parameter on a card · clean locale link · data-locale-links
+        //
+        // WHERE THE CARD GOES. An apex that has opted in (`localeLinks` on Catalogue) sends the visitor
+        // straight to the persona's page in this page's language — the canonical address, no query
+        // string; see ../personaHref.js for what the parameters cost in Search Console. An apex that
+        // has not keeps the bare root it was built with, because only the apex can vouch that its
+        // citizens speak its languages, and a persona without `/<xx>/` answers 404 there. Its
+        // visitor's language still travels: Catalogue.astro adds the hint at the moment of the tap,
+        // never into the page a crawler renders.
+        if (localeLinks) el.href = personaHref(a.home, locale, { locales: a.locales });
       }
 
       // The filter panel is rendered from the build-time seed, so a persona that registered afterwards

package/src/personaHref.d.ts

@@ -0,0 +1,6 @@
+/** The address an apex links a persona by: the persona's own page in the reader's language, no query string. */
+export function personaHref(
+  home: string,
+  lang: string,
+  opts?: { defaultLocale?: string; locales?: readonly string[] | null },
+): string;

package/src/personaHref.js

@@ -0,0 +1,46 @@
+// THE ADDRESS AN APEX HANDS A VISITOR WHEN IT SENDS THEM TO A PERSONA — one rule, one copy.
+//
+// queries: persona link · app.zone card href · ref=app.zone · lang parameter · locale link ·
+//          clean locale url · page with redirect in search console · parameterised url indexed ·
+//          how does a storefront link to a persona in the reader's language
+//
+// ── WHAT IT REPLACES, AND WHY ───────────────────────────────────────────────────────────────────
+//
+// A storefront used to link to `https://<home>/?ref=<apex>&lang=<xx>`. The persona's root then read
+// `lang` as a hint and replaced the location with `/<xx>/?ref=…&lang=…` in the browser. For a person
+// that is one extra hop. For a search engine it is a page whose HTML is the default language, whose
+// canonical is the root, and whose script goes somewhere else — three statements that disagree.
+//
+// Measured in Search Console for app.zone on 2026-10-11: 232 of those addresses filed as "Page with
+// redirect", 67 indexed as pages of their own, and for 49 of the 67 the real `/<xx>/` page was still
+// waiting to be crawled. The parameterised address had taken the localized page's place.
+//
+// So the link is the page itself: `https://<home>/` for the default language, `https://<home>/<xx>/`
+// for any other. No query string. `ref` had no reader — the arrival's own `document.referrer` already
+// says which storefront it came from.
+//
+// ── THE ONE THING THIS CANNOT KNOW BY ITSELF ────────────────────────────────────────────────────
+//
+// Whether the persona HAS that language. A persona without `/<xx>/` answers 404 there, where the old
+// hint was simply ignored. So:
+//   · `locales` given (the persona's own list)  → the localized page only if it is in the list.
+//   · `locales` not given                       → the caller has vouched for it (see `localeLinks`
+//                                                  on Catalogue: an apex opts in when its citizens
+//                                                  all speak the apex's languages).
+// A language code that is not a plain BCP-47 tag never reaches a path at all.
+import { localePath } from "@justai/ui/locale";
+
+/**
+ * @param {string} home  the persona's host, e.g. "merge-pdf.app.zone" (a scheme or path is ignored)
+ * @param {string} lang  the page's language
+ * @param {{ defaultLocale?: string, locales?: readonly string[] | null }} [opts]
+ * @returns {string} an absolute https URL with no query string and no fragment
+ */
+export function personaHref(home, lang, opts) {
+  const def = (opts && opts.defaultLocale) || "en";
+  const host = String(home || "").trim().replace(/^[a-z]+:\/\//i, "").replace(/[/?#].*$/, "").toLowerCase();
+  const code = String(lang || "").trim().toLowerCase();
+  const known = opts && Array.isArray(opts.locales) ? opts.locales : null;
+  const speaks = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/.test(code) && (!known || known.indexOf(code) !== -1);
+  return `https://${host}${localePath(speaks ? code : def, def)}`;
+}