@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/seo-listing-fields.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The fields of a search listing: what a search result and a share card say
+ * about one page or one product, and how long each may be.
+ *
+ * One catalog, because more than one surface edits these and more than one
+ * reader holds them to a length. The screen detail page's SEO card draws its
+ * inputs from it, the besigner's SEO panel shares the counts, the commerce
+ * product editor labels its search engine listing with it, and anything that
+ * proposes a value — a template, an import, a generator — reads the same
+ * limits the editor enforces instead of restating them. A limit written in
+ * two places is a limit the two places disagree about the first time one of
+ * them changes.
+ *
+ * The lengths are what a search result shows before it truncates: about 60
+ * characters of a title and 155 of a description. A breadcrumb label is the
+ * page's short name in a trail, so it is held shorter than the title it
+ * usually abbreviates. The image description is an `alt`, and takes the
+ * platform's one `alt` ceiling.
+ */
+/** Every field a search listing editor may hold. */
+export type SeoListingFieldKey = 'title' | 'description' | 'breadcrumb' | 'imageAlt';
+export interface SeoListingFieldDefinition {
+    key: SeoListingFieldKey;
+    /** The input's label, as the editors draw it. */
+    label: string;
+    /** The longest value the editor accepts; a longer one is flagged, not trimmed. */
+    maxLength: number;
+    /** Drawn as a multi-line input. */
+    multiline?: boolean;
+    /** What the value is FOR, in a sentence an author or a generator can act on. */
+    purpose: string;
+}
+/** A breadcrumb label: the page's short name in a trail. */
+export declare const SEO_BREADCRUMB_MAX_LENGTH = 40;
+export declare const SEO_LISTING_FIELDS: Readonly<Record<SeoListingFieldKey, SeoListingFieldDefinition>>;
+/**
+ * The fields the screen detail page's SEO card edits, in the order it draws
+ * them. `imageAlt` is the social image's own description and is only editable
+ * beside an image, which the card enforces.
+ */
+export declare const SCREEN_SEO_LISTING_FIELDS: readonly SeoListingFieldKey[];
+/**
+ * The screen card's plain text inputs: every field but the image's
+ * description. The listing's own title and description are the besigner's
+ * `SCREEN_SEO_TEXT_FIELDS`; the card adds the breadcrumb label beside them.
+ */
+export declare const SCREEN_SEO_CARD_TEXT_FIELDS: readonly ["title", "description", "breadcrumb"];
+export type ScreenSeoCardTextField = (typeof SCREEN_SEO_CARD_TEXT_FIELDS)[number];
+/** Whether a string names a field of the catalog. */
+export declare function isSeoListingFieldKey(value: unknown): value is SeoListingFieldKey;
+/** A field's counter text, `12/60`, as every editor prints it. */
+export declare function seoListingFieldCount(key: SeoListingFieldKey, value: string | null | undefined): string;
+/** Whether a value is over its field's length. */
+export declare function seoListingFieldTooLong(key: SeoListingFieldKey, value: string | null | undefined): boolean;

package/src/lib/app-utils/seo-listing-fields.js

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { MEDIA_ALT_MAX_LENGTH } from "./media-alt.js";
+import { SCREEN_SEO_TEXT_FIELDS, SCREEN_SEO_TEXT_GUIDANCE } from "./screen-seo-fields.js";
+/** A breadcrumb label: the page's short name in a trail. */ export const SEO_BREADCRUMB_MAX_LENGTH = 40;
+export const SEO_LISTING_FIELDS = {
+    title: {
+        key: 'title',
+        label: 'Title',
+        maxLength: SCREEN_SEO_TEXT_GUIDANCE.title,
+        purpose: 'The headline of the search result, published exactly as written; the site title is not appended to it.'
+    },
+    description: {
+        key: 'description',
+        label: 'Description',
+        maxLength: SCREEN_SEO_TEXT_GUIDANCE.description,
+        multiline: true,
+        purpose: 'The summary a search result shows under the headline.'
+    },
+    breadcrumb: {
+        key: 'breadcrumb',
+        label: 'Breadcrumb label',
+        maxLength: SEO_BREADCRUMB_MAX_LENGTH,
+        purpose: 'The short name of the page where a breadcrumb trail names it.'
+    },
+    imageAlt: {
+        key: 'imageAlt',
+        label: 'Image description',
+        maxLength: MEDIA_ALT_MAX_LENGTH,
+        multiline: true,
+        purpose: 'What the social image shows, read aloud in a share preview. It describes the picture, not the page.'
+    }
+};
+/**
+ * The fields the screen detail page's SEO card edits, in the order it draws
+ * them. `imageAlt` is the social image's own description and is only editable
+ * beside an image, which the card enforces.
+ */ export const SCREEN_SEO_LISTING_FIELDS = [
+    'title',
+    'description',
+    'breadcrumb',
+    'imageAlt'
+];
+/**
+ * The screen card's plain text inputs: every field but the image's
+ * description. The listing's own title and description are the besigner's
+ * `SCREEN_SEO_TEXT_FIELDS`; the card adds the breadcrumb label beside them.
+ */ export const SCREEN_SEO_CARD_TEXT_FIELDS = [
+    ...SCREEN_SEO_TEXT_FIELDS,
+    'breadcrumb'
+];
+/** Whether a string names a field of the catalog. */ export function isSeoListingFieldKey(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(SEO_LISTING_FIELDS, value);
+}
+/** A field's counter text, `12/60`, as every editor prints it. */ export function seoListingFieldCount(key, value) {
+    return `${String(value != null ? value : '').length}/${SEO_LISTING_FIELDS[key].maxLength}`;
+}
+/** Whether a value is over its field's length. */ export function seoListingFieldTooLong(key, value) {
+    return String(value != null ? value : '').length > SEO_LISTING_FIELDS[key].maxLength;
+}
+
+//# sourceMappingURL=seo-listing-fields.js.map

package/src/lib/app-utils/seo-listing-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/seo-listing-fields.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { MEDIA_ALT_MAX_LENGTH } from './media-alt'\nimport { SCREEN_SEO_TEXT_FIELDS, SCREEN_SEO_TEXT_GUIDANCE } from './screen-seo-fields'\n\n/**\n * The fields of a search listing: what a search result and a share card say\n * about one page or one product, and how long each may be.\n *\n * One catalog, because more than one surface edits these and more than one\n * reader holds them to a length. The screen detail page's SEO card draws its\n * inputs from it, the besigner's SEO panel shares the counts, the commerce\n * product editor labels its search engine listing with it, and anything that\n * proposes a value — a template, an import, a generator — reads the same\n * limits the editor enforces instead of restating them. A limit written in\n * two places is a limit the two places disagree about the first time one of\n * them changes.\n *\n * The lengths are what a search result shows before it truncates: about 60\n * characters of a title and 155 of a description. A breadcrumb label is the\n * page's short name in a trail, so it is held shorter than the title it\n * usually abbreviates. The image description is an `alt`, and takes the\n * platform's one `alt` ceiling.\n */\n\n/** Every field a search listing editor may hold. */\nexport type SeoListingFieldKey = 'title' | 'description' | 'breadcrumb' | 'imageAlt'\n\nexport interface SeoListingFieldDefinition {\n  key: SeoListingFieldKey\n  /** The input's label, as the editors draw it. */\n  label: string\n  /** The longest value the editor accepts; a longer one is flagged, not trimmed. */\n  maxLength: number\n  /** Drawn as a multi-line input. */\n  multiline?: boolean\n  /** What the value is FOR, in a sentence an author or a generator can act on. */\n  purpose: string\n}\n\n/** A breadcrumb label: the page's short name in a trail. */\nexport const SEO_BREADCRUMB_MAX_LENGTH = 40\n\nexport const SEO_LISTING_FIELDS: Readonly<Record<SeoListingFieldKey, SeoListingFieldDefinition>> = {\n  title: {\n    key: 'title',\n    label: 'Title',\n    maxLength: SCREEN_SEO_TEXT_GUIDANCE.title,\n    purpose:\n      'The headline of the search result, published exactly as written; the site title is not appended to it.',\n  },\n  description: {\n    key: 'description',\n    label: 'Description',\n    maxLength: SCREEN_SEO_TEXT_GUIDANCE.description,\n    multiline: true,\n    purpose: 'The summary a search result shows under the headline.',\n  },\n  breadcrumb: {\n    key: 'breadcrumb',\n    label: 'Breadcrumb label',\n    maxLength: SEO_BREADCRUMB_MAX_LENGTH,\n    purpose: 'The short name of the page where a breadcrumb trail names it.',\n  },\n  imageAlt: {\n    key: 'imageAlt',\n    label: 'Image description',\n    maxLength: MEDIA_ALT_MAX_LENGTH,\n    multiline: true,\n    purpose:\n      'What the social image shows, read aloud in a share preview. It describes the picture, not the page.',\n  },\n}\n\n/**\n * The fields the screen detail page's SEO card edits, in the order it draws\n * them. `imageAlt` is the social image's own description and is only editable\n * beside an image, which the card enforces.\n */\nexport const SCREEN_SEO_LISTING_FIELDS: readonly SeoListingFieldKey[] = [\n  'title',\n  'description',\n  'breadcrumb',\n  'imageAlt',\n]\n\n/**\n * The screen card's plain text inputs: every field but the image's\n * description. The listing's own title and description are the besigner's\n * `SCREEN_SEO_TEXT_FIELDS`; the card adds the breadcrumb label beside them.\n */\nexport const SCREEN_SEO_CARD_TEXT_FIELDS = [...SCREEN_SEO_TEXT_FIELDS, 'breadcrumb'] as const\n\nexport type ScreenSeoCardTextField = (typeof SCREEN_SEO_CARD_TEXT_FIELDS)[number]\n\n/** Whether a string names a field of the catalog. */\nexport function isSeoListingFieldKey(value: unknown): value is SeoListingFieldKey {\n  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(SEO_LISTING_FIELDS, value)\n}\n\n/** A field's counter text, `12/60`, as every editor prints it. */\nexport function seoListingFieldCount(key: SeoListingFieldKey, value: string | null | undefined): string {\n  return `${String(value ?? '').length}/${SEO_LISTING_FIELDS[key].maxLength}`\n}\n\n/** Whether a value is over its field's length. */\nexport function seoListingFieldTooLong(key: SeoListingFieldKey, value: string | null | undefined): boolean {\n  return String(value ?? '').length > SEO_LISTING_FIELDS[key].maxLength\n}\n"],"names":["MEDIA_ALT_MAX_LENGTH","SCREEN_SEO_TEXT_FIELDS","SCREEN_SEO_TEXT_GUIDANCE","SEO_BREADCRUMB_MAX_LENGTH","SEO_LISTING_FIELDS","title","key","label","maxLength","purpose","description","multiline","breadcrumb","imageAlt","SCREEN_SEO_LISTING_FIELDS","SCREEN_SEO_CARD_TEXT_FIELDS","isSeoListingFieldKey","value","Object","prototype","hasOwnProperty","call","seoListingFieldCount","String","length","seoListingFieldTooLong"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,oBAAoB,QAAQ,iBAAa;AAClD,SAASC,sBAAsB,EAAEC,wBAAwB,QAAQ,yBAAqB;AAqCtF,0DAA0D,GAC1D,OAAO,MAAMC,4BAA4B,GAAE;AAE3C,OAAO,MAAMC,qBAAsF;IACjGC,OAAO;QACLC,KAAK;QACLC,OAAO;QACPC,WAAWN,yBAAyBG,KAAK;QACzCI,SACE;IACJ;IACAC,aAAa;QACXJ,KAAK;QACLC,OAAO;QACPC,WAAWN,yBAAyBQ,WAAW;QAC/CC,WAAW;QACXF,SAAS;IACX;IACAG,YAAY;QACVN,KAAK;QACLC,OAAO;QACPC,WAAWL;QACXM,SAAS;IACX;IACAI,UAAU;QACRP,KAAK;QACLC,OAAO;QACPC,WAAWR;QACXW,WAAW;QACXF,SACE;IACJ;AACF,EAAC;AAED;;;;CAIC,GACD,OAAO,MAAMK,4BAA2D;IACtE;IACA;IACA;IACA;CACD,CAAA;AAED;;;;CAIC,GACD,OAAO,MAAMC,8BAA8B;OAAId;IAAwB;CAAa,CAAS;AAI7F,mDAAmD,GACnD,OAAO,SAASe,qBAAqBC,KAAc;IACjD,OAAO,OAAOA,UAAU,YAAYC,OAAOC,SAAS,CAACC,cAAc,CAACC,IAAI,CAACjB,oBAAoBa;AAC/F;AAEA,gEAAgE,GAChE,OAAO,SAASK,qBAAqBhB,GAAuB,EAAEW,KAAgC;IAC5F,OAAO,GAAGM,OAAON,gBAAAA,QAAS,IAAIO,MAAM,CAAC,CAAC,EAAEpB,kBAAkB,CAACE,IAAI,CAACE,SAAS,EAAE;AAC7E;AAEA,gDAAgD,GAChD,OAAO,SAASiB,uBAAuBnB,GAAuB,EAAEW,KAAgC;IAC9F,OAAOM,OAAON,gBAAAA,QAAS,IAAIO,MAAM,GAAGpB,kBAAkB,CAACE,IAAI,CAACE,SAAS;AACvE"}

package/src/lib/app-utils/seo-locale.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * WHAT LANGUAGE A PAGE IS IN, answered once (AGL-3148).
+ *
+ * Three surfaces need this answer and none of them had it: `og:locale` and
+ * `og:locale:alternate` were absent from every page type on the platform,
+ * and `inLanguage` was absent from every JSON-LD node. The fourth surface,
+ * `<link rel="alternate" hreflang>`, has had its own copy of the fallback
+ * since AGL-164.
+ *
+ * They must agree. A page that declares `en` in its markup, `fr` in its Open
+ * Graph and nothing in its structured data has told three readers three
+ * things, and the one that matters — which language a searcher should be
+ * served — is the one they disagree about. So the chain lives here and every
+ * surface reads it.
+ */
+/**
+ * The language a page is in when nothing on the site says otherwise.
+ *
+ * NOT a guess: it is the language the document actually declares. The
+ * `lang` attribute is no longer the literal `"en"` it was when this constant
+ * was written — `apps/tenant/app/[host]/layout.tsx` resolves it through
+ * `resolvePageLocale` and the two host-agnostic boundaries beside the root
+ * layout emit THIS value (AGL-3153) — so the coupling now runs the honest
+ * way round: the markup takes its answer from here rather than this constant
+ * restating a literal somewhere else.
+ *
+ * That is what keeps `og:locale` safe to emit unconditionally. A page derived
+ * from this chain can only ever repeat what the same chain put in the
+ * document's own `lang`.
+ *
+ * ⚠️ Still PINNED to that attribute, in the direction that is now true: this
+ * resolver is its SOURCE. A surface that needs a fallback language reads this
+ * constant; it never writes a second default of its own, and changing this
+ * value changes what every untranslated site declares.
+ *
+ * ⚠️ `<html lang>` is the SITE's language, not the screen's. A layout is the
+ * deepest thing that can render `<html>`, and no layout has the slug the
+ * screen is resolved from, so a locale variant's own language reaches the
+ * metadata surfaces below — which call this resolver WITH a screen — and not
+ * the document element. `apps/tenant/app/[host]/layout.tsx` records why
+ * closing that gap would cost the catch-all's ISR window.
+ */
+export declare const PLATFORM_DEFAULT_LOCALE = "en";
+/** The hreflang key for "no locale of its own", as `alternates.languages` spells it. */
+export declare const LOCALE_X_DEFAULT = "x-default";
+/**
+ * A language tag, or nothing.
+ *
+ * Validated rather than trusted: these values reach a `<meta>` and a JSON-LD
+ * document, and a locale field is free text in Firestore. An unparseable one
+ * is dropped so the chain falls through to the next candidate — a page with a
+ * corrupt locale emits the site's language, never the corruption.
+ *
+ * Accepts `language[-Script][-REGION]` — `en`, `en-GB`, `zh-Hant`,
+ * `zh-Hant-TW`, `es-419` — in any casing, and returns it in the canonical
+ * BCP-47 casing so two spellings of one locale cannot read as two locales.
+ */
+export declare function normalizeLocaleTag(value: string | null | undefined): string | undefined;
+/** The screen and host fields the language of a page is decided from. */
+export interface PageLocaleSources {
+    /** The screen being rendered — its `locale` is the most specific answer. */
+    screen?: {
+        locale?: string;
+    } | null;
+    /** The host document — `defaultLocale`, then the first of `locales`. */
+    host?: {
+        defaultLocale?: string;
+        locales?: string[];
+    } | null;
+}
+/**
+ * The language THIS page is written in.
+ *
+ * Most specific first: the screen says what it was written in, the site says
+ * what it defaults to, and the platform default answers for the sites — today
+ * every one of them — that have configured neither.
+ *
+ * Never returns `undefined`. A page is always in some language, and a reader
+ * that finds no answer assumes one anyway; saying which one out loud is
+ * strictly more information than leaving it to be guessed.
+ */
+export declare function resolvePageLocale(sources: PageLocaleSources): string;
+/**
+ * A language tag in the form Open Graph spells it — `en_GB`, not `en-GB`.
+ *
+ * The one transformation, kept beside the normalizer so the two forms cannot
+ * drift: `alternates.languages` keys stay BCP-47 because that is what
+ * `hreflang` takes, and `og:locale` takes the underscore form.
+ */
+export declare function toOpenGraphLocale(value: string | null | undefined): string | undefined;
+/**
+ * The OTHER languages this page exists in, as `og:locale:alternate` values.
+ *
+ * Derived from the very keys that drive `alternates.languages`, deliberately,
+ * rather than from the site's configured `locales`: a language reaches that
+ * map only once its translated screen resolves to a real routed path, so
+ * every value returned here has a page behind it. A site that lists `fr`
+ * among its locales but has translated nothing advertises no French card.
+ *
+ * `x-default` is dropped — it is a routing instruction, not a language — and
+ * so is the page's own locale, which `og:locale` already carries.
+ */
+export declare function openGraphAlternateLocales(languageKeys: readonly string[] | null | undefined, pageLocale?: string): string[];

package/src/lib/app-utils/seo-locale.js

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WHAT LANGUAGE A PAGE IS IN, answered once (AGL-3148).
+ *
+ * Three surfaces need this answer and none of them had it: `og:locale` and
+ * `og:locale:alternate` were absent from every page type on the platform,
+ * and `inLanguage` was absent from every JSON-LD node. The fourth surface,
+ * `<link rel="alternate" hreflang>`, has had its own copy of the fallback
+ * since AGL-164.
+ *
+ * They must agree. A page that declares `en` in its markup, `fr` in its Open
+ * Graph and nothing in its structured data has told three readers three
+ * things, and the one that matters — which language a searcher should be
+ * served — is the one they disagree about. So the chain lives here and every
+ * surface reads it.
+ */ /**
+ * The language a page is in when nothing on the site says otherwise.
+ *
+ * NOT a guess: it is the language the document actually declares. The
+ * `lang` attribute is no longer the literal `"en"` it was when this constant
+ * was written — `apps/tenant/app/[host]/layout.tsx` resolves it through
+ * `resolvePageLocale` and the two host-agnostic boundaries beside the root
+ * layout emit THIS value (AGL-3153) — so the coupling now runs the honest
+ * way round: the markup takes its answer from here rather than this constant
+ * restating a literal somewhere else.
+ *
+ * That is what keeps `og:locale` safe to emit unconditionally. A page derived
+ * from this chain can only ever repeat what the same chain put in the
+ * document's own `lang`.
+ *
+ * ⚠️ Still PINNED to that attribute, in the direction that is now true: this
+ * resolver is its SOURCE. A surface that needs a fallback language reads this
+ * constant; it never writes a second default of its own, and changing this
+ * value changes what every untranslated site declares.
+ *
+ * ⚠️ `<html lang>` is the SITE's language, not the screen's. A layout is the
+ * deepest thing that can render `<html>`, and no layout has the slug the
+ * screen is resolved from, so a locale variant's own language reaches the
+ * metadata surfaces below — which call this resolver WITH a screen — and not
+ * the document element. `apps/tenant/app/[host]/layout.tsx` records why
+ * closing that gap would cost the catch-all's ISR window.
+ */ export const PLATFORM_DEFAULT_LOCALE = 'en';
+/** The hreflang key for "no locale of its own", as `alternates.languages` spells it. */ export const LOCALE_X_DEFAULT = 'x-default';
+/**
+ * A language tag, or nothing.
+ *
+ * Validated rather than trusted: these values reach a `<meta>` and a JSON-LD
+ * document, and a locale field is free text in Firestore. An unparseable one
+ * is dropped so the chain falls through to the next candidate — a page with a
+ * corrupt locale emits the site's language, never the corruption.
+ *
+ * Accepts `language[-Script][-REGION]` — `en`, `en-GB`, `zh-Hant`,
+ * `zh-Hant-TW`, `es-419` — in any casing, and returns it in the canonical
+ * BCP-47 casing so two spellings of one locale cannot read as two locales.
+ */ export function normalizeLocaleTag(value) {
+    if (typeof value !== 'string') return undefined;
+    // `_` is the Open Graph separator and `-` the BCP-47 one; a stored value may
+    // legitimately arrive in either, and both name the same locale.
+    const raw = value.trim().replace(/_/g, '-');
+    if (!raw) return undefined;
+    const match = /^([A-Za-z]{2,3})(?:-([A-Za-z]{4}))?(?:-([A-Za-z]{2}|[0-9]{3}))?$/.exec(raw);
+    if (!match) return undefined;
+    const [, language, script, region] = match;
+    return [
+        language.toLowerCase(),
+        script ? script[0].toUpperCase() + script.slice(1).toLowerCase() : undefined,
+        region ? region.toUpperCase() : undefined
+    ].filter(Boolean).join('-');
+}
+/**
+ * The language THIS page is written in.
+ *
+ * Most specific first: the screen says what it was written in, the site says
+ * what it defaults to, and the platform default answers for the sites — today
+ * every one of them — that have configured neither.
+ *
+ * Never returns `undefined`. A page is always in some language, and a reader
+ * that finds no answer assumes one anyway; saying which one out loud is
+ * strictly more information than leaving it to be guessed.
+ */ export function resolvePageLocale(sources) {
+    var _ref, _ref1, _normalizeLocaleTag;
+    var _sources_screen, _sources_host, _sources_host_locales, _sources_host1;
+    return (_ref = (_ref1 = (_normalizeLocaleTag = normalizeLocaleTag((_sources_screen = sources.screen) == null ? void 0 : _sources_screen.locale)) != null ? _normalizeLocaleTag : normalizeLocaleTag((_sources_host = sources.host) == null ? void 0 : _sources_host.defaultLocale)) != null ? _ref1 : normalizeLocaleTag((_sources_host1 = sources.host) == null ? void 0 : (_sources_host_locales = _sources_host1.locales) == null ? void 0 : _sources_host_locales[0])) != null ? _ref : PLATFORM_DEFAULT_LOCALE;
+}
+/**
+ * A language tag in the form Open Graph spells it — `en_GB`, not `en-GB`.
+ *
+ * The one transformation, kept beside the normalizer so the two forms cannot
+ * drift: `alternates.languages` keys stay BCP-47 because that is what
+ * `hreflang` takes, and `og:locale` takes the underscore form.
+ */ export function toOpenGraphLocale(value) {
+    const tag = normalizeLocaleTag(value);
+    return tag ? tag.replace(/-/g, '_') : undefined;
+}
+/**
+ * The OTHER languages this page exists in, as `og:locale:alternate` values.
+ *
+ * Derived from the very keys that drive `alternates.languages`, deliberately,
+ * rather than from the site's configured `locales`: a language reaches that
+ * map only once its translated screen resolves to a real routed path, so
+ * every value returned here has a page behind it. A site that lists `fr`
+ * among its locales but has translated nothing advertises no French card.
+ *
+ * `x-default` is dropped — it is a routing instruction, not a language — and
+ * so is the page's own locale, which `og:locale` already carries.
+ */ export function openGraphAlternateLocales(languageKeys, pageLocale) {
+    const own = toOpenGraphLocale(pageLocale);
+    const alternates = new Set();
+    for (const key of languageKeys != null ? languageKeys : []){
+        if (key === LOCALE_X_DEFAULT) continue;
+        const tag = toOpenGraphLocale(key);
+        if (tag && tag !== own) alternates.add(tag);
+    }
+    return [
+        ...alternates
+    ];
+}
+
+//# sourceMappingURL=seo-locale.js.map

package/src/lib/app-utils/seo-locale.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/seo-locale.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * WHAT LANGUAGE A PAGE IS IN, answered once (AGL-3148).\n *\n * Three surfaces need this answer and none of them had it: `og:locale` and\n * `og:locale:alternate` were absent from every page type on the platform,\n * and `inLanguage` was absent from every JSON-LD node. The fourth surface,\n * `<link rel=\"alternate\" hreflang>`, has had its own copy of the fallback\n * since AGL-164.\n *\n * They must agree. A page that declares `en` in its markup, `fr` in its Open\n * Graph and nothing in its structured data has told three readers three\n * things, and the one that matters — which language a searcher should be\n * served — is the one they disagree about. So the chain lives here and every\n * surface reads it.\n */\n\n/**\n * The language a page is in when nothing on the site says otherwise.\n *\n * NOT a guess: it is the language the document actually declares. The\n * `lang` attribute is no longer the literal `\"en\"` it was when this constant\n * was written — `apps/tenant/app/[host]/layout.tsx` resolves it through\n * `resolvePageLocale` and the two host-agnostic boundaries beside the root\n * layout emit THIS value (AGL-3153) — so the coupling now runs the honest\n * way round: the markup takes its answer from here rather than this constant\n * restating a literal somewhere else.\n *\n * That is what keeps `og:locale` safe to emit unconditionally. A page derived\n * from this chain can only ever repeat what the same chain put in the\n * document's own `lang`.\n *\n * ⚠️ Still PINNED to that attribute, in the direction that is now true: this\n * resolver is its SOURCE. A surface that needs a fallback language reads this\n * constant; it never writes a second default of its own, and changing this\n * value changes what every untranslated site declares.\n *\n * ⚠️ `<html lang>` is the SITE's language, not the screen's. A layout is the\n * deepest thing that can render `<html>`, and no layout has the slug the\n * screen is resolved from, so a locale variant's own language reaches the\n * metadata surfaces below — which call this resolver WITH a screen — and not\n * the document element. `apps/tenant/app/[host]/layout.tsx` records why\n * closing that gap would cost the catch-all's ISR window.\n */\nexport const PLATFORM_DEFAULT_LOCALE = 'en'\n\n/** The hreflang key for \"no locale of its own\", as `alternates.languages` spells it. */\nexport const LOCALE_X_DEFAULT = 'x-default'\n\n/**\n * A language tag, or nothing.\n *\n * Validated rather than trusted: these values reach a `<meta>` and a JSON-LD\n * document, and a locale field is free text in Firestore. An unparseable one\n * is dropped so the chain falls through to the next candidate — a page with a\n * corrupt locale emits the site's language, never the corruption.\n *\n * Accepts `language[-Script][-REGION]` — `en`, `en-GB`, `zh-Hant`,\n * `zh-Hant-TW`, `es-419` — in any casing, and returns it in the canonical\n * BCP-47 casing so two spellings of one locale cannot read as two locales.\n */\nexport function normalizeLocaleTag(\n  value: string | null | undefined,\n): string | undefined {\n  if (typeof value !== 'string') return undefined\n  // `_` is the Open Graph separator and `-` the BCP-47 one; a stored value may\n  // legitimately arrive in either, and both name the same locale.\n  const raw = value.trim().replace(/_/g, '-')\n  if (!raw) return undefined\n  const match =\n    /^([A-Za-z]{2,3})(?:-([A-Za-z]{4}))?(?:-([A-Za-z]{2}|[0-9]{3}))?$/.exec(raw)\n  if (!match) return undefined\n  const [, language, script, region] = match\n  return [\n    language.toLowerCase(),\n    script ? script[0].toUpperCase() + script.slice(1).toLowerCase() : undefined,\n    region ? region.toUpperCase() : undefined,\n  ]\n    .filter(Boolean)\n    .join('-')\n}\n\n/** The screen and host fields the language of a page is decided from. */\nexport interface PageLocaleSources {\n  /** The screen being rendered — its `locale` is the most specific answer. */\n  screen?: { locale?: string } | null\n  /** The host document — `defaultLocale`, then the first of `locales`. */\n  host?: { defaultLocale?: string; locales?: string[] } | null\n}\n\n/**\n * The language THIS page is written in.\n *\n * Most specific first: the screen says what it was written in, the site says\n * what it defaults to, and the platform default answers for the sites — today\n * every one of them — that have configured neither.\n *\n * Never returns `undefined`. A page is always in some language, and a reader\n * that finds no answer assumes one anyway; saying which one out loud is\n * strictly more information than leaving it to be guessed.\n */\nexport function resolvePageLocale(sources: PageLocaleSources): string {\n  return (\n    normalizeLocaleTag(sources.screen?.locale) ??\n    normalizeLocaleTag(sources.host?.defaultLocale) ??\n    normalizeLocaleTag(sources.host?.locales?.[0]) ??\n    PLATFORM_DEFAULT_LOCALE\n  )\n}\n\n/**\n * A language tag in the form Open Graph spells it — `en_GB`, not `en-GB`.\n *\n * The one transformation, kept beside the normalizer so the two forms cannot\n * drift: `alternates.languages` keys stay BCP-47 because that is what\n * `hreflang` takes, and `og:locale` takes the underscore form.\n */\nexport function toOpenGraphLocale(\n  value: string | null | undefined,\n): string | undefined {\n  const tag = normalizeLocaleTag(value)\n  return tag ? tag.replace(/-/g, '_') : undefined\n}\n\n/**\n * The OTHER languages this page exists in, as `og:locale:alternate` values.\n *\n * Derived from the very keys that drive `alternates.languages`, deliberately,\n * rather than from the site's configured `locales`: a language reaches that\n * map only once its translated screen resolves to a real routed path, so\n * every value returned here has a page behind it. A site that lists `fr`\n * among its locales but has translated nothing advertises no French card.\n *\n * `x-default` is dropped — it is a routing instruction, not a language — and\n * so is the page's own locale, which `og:locale` already carries.\n */\nexport function openGraphAlternateLocales(\n  languageKeys: readonly string[] | null | undefined,\n  pageLocale?: string,\n): string[] {\n  const own = toOpenGraphLocale(pageLocale)\n  const alternates = new Set<string>()\n  for (const key of languageKeys ?? []) {\n    if (key === LOCALE_X_DEFAULT) continue\n    const tag = toOpenGraphLocale(key)\n    if (tag && tag !== own) alternates.add(tag)\n  }\n  return [...alternates]\n}\n"],"names":["PLATFORM_DEFAULT_LOCALE","LOCALE_X_DEFAULT","normalizeLocaleTag","value","undefined","raw","trim","replace","match","exec","language","script","region","toLowerCase","toUpperCase","slice","filter","Boolean","join","resolvePageLocale","sources","screen","locale","host","defaultLocale","locales","toOpenGraphLocale","tag","openGraphAlternateLocales","languageKeys","pageLocale","own","alternates","Set","key","add"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;CAcC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GACD,OAAO,MAAMA,0BAA0B,KAAI;AAE3C,sFAAsF,GACtF,OAAO,MAAMC,mBAAmB,YAAW;AAE3C;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,mBACdC,KAAgC;IAEhC,IAAI,OAAOA,UAAU,UAAU,OAAOC;IACtC,6EAA6E;IAC7E,gEAAgE;IAChE,MAAMC,MAAMF,MAAMG,IAAI,GAAGC,OAAO,CAAC,MAAM;IACvC,IAAI,CAACF,KAAK,OAAOD;IACjB,MAAMI,QACJ,mEAAmEC,IAAI,CAACJ;IAC1E,IAAI,CAACG,OAAO,OAAOJ;IACnB,MAAM,GAAGM,UAAUC,QAAQC,OAAO,GAAGJ;IACrC,OAAO;QACLE,SAASG,WAAW;QACpBF,SAASA,MAAM,CAAC,EAAE,CAACG,WAAW,KAAKH,OAAOI,KAAK,CAAC,GAAGF,WAAW,KAAKT;QACnEQ,SAASA,OAAOE,WAAW,KAAKV;KACjC,CACEY,MAAM,CAACC,SACPC,IAAI,CAAC;AACV;AAUA;;;;;;;;;;CAUC,GACD,OAAO,SAASC,kBAAkBC,OAA0B;QAExDlB,MAAAA,OAAAA;QAAmBkB,iBACAA,eACAA,uBAAAA;IAHrB,QACElB,QAAAA,SAAAA,sBAAAA,oBAAmBkB,kBAAAA,QAAQC,MAAM,qBAAdD,gBAAgBE,MAAM,aAAzCpB,sBACAA,oBAAmBkB,gBAAAA,QAAQG,IAAI,qBAAZH,cAAcI,aAAa,aAD9CtB,QAEAA,oBAAmBkB,iBAAAA,QAAQG,IAAI,sBAAZH,wBAAAA,eAAcK,OAAO,qBAArBL,qBAAuB,CAAC,EAAE,aAF7ClB,OAGAF;AAEJ;AAEA;;;;;;CAMC,GACD,OAAO,SAAS0B,kBACdvB,KAAgC;IAEhC,MAAMwB,MAAMzB,mBAAmBC;IAC/B,OAAOwB,MAAMA,IAAIpB,OAAO,CAAC,MAAM,OAAOH;AACxC;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASwB,0BACdC,YAAkD,EAClDC,UAAmB;IAEnB,MAAMC,MAAML,kBAAkBI;IAC9B,MAAME,aAAa,IAAIC;IACvB,KAAK,MAAMC,OAAOL,uBAAAA,eAAgB,EAAE,CAAE;QACpC,IAAIK,QAAQjC,kBAAkB;QAC9B,MAAM0B,MAAMD,kBAAkBQ;QAC9B,IAAIP,OAAOA,QAAQI,KAAKC,WAAWG,GAAG,CAACR;IACzC;IACA,OAAO;WAAIK;KAAW;AACxB"}

package/src/lib/app-utils/seo-title-variables.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The variables a page title may be written in terms of, and how a written
+ * title becomes a rendered one.
+ *
+ * ## Why this exists
+ *
+ * A title is verbatim (AGL-1341, and that rule is right — see `seo-title`), so
+ * an author who wants the brand in a title TYPES it. Fifty screens on the
+ * marketing site end in a literal ` | Aglyn`, which means the site name and
+ * the character in front of it are stored fifty times, and changing either one
+ * is fifty edits that nothing reminds you to make. `seo.separator` already
+ * exists as a setting and every one of those titles ignores it.
+ *
+ * So a title may now be WRITTEN in terms of what it depends on:
+ *
+ * ```
+ *   {{page.name}} {{site.separator}} {{site.name}}
+ * ```
+ *
+ * and a site-name change is one edit in Host setup → SEO.
+ *
+ * ## ⛔ No rendered title changes because this shipped
+ *
+ * The whole feature is opt-in at the string level: a title with no `{{` in it
+ * is returned unchanged, character for character, by the same code path that
+ * returned it before. Nothing migrates the fifty existing titles — a migration
+ * could not be output-preserving anyway, because ` | Aglyn` is not what
+ * `{{site.separator}}{{site.name}}` resolves to on a host whose separator is
+ * `-` and whose site title is the long form. They keep working as literals
+ * until somebody decides otherwise, one at a time.
+ *
+ * `DEFAULT_TITLE_PATTERN` is held to the same standard: it is the composition
+ * `resolveSeoTitle` already performed for a page with no authored title, said
+ * in tokens instead of in code, and `seo-title.spec` pins that the two agree.
+ *
+ * ## The grammar is `{{…}}`, not `[…]`
+ *
+ * Because the platform already has one: the besigner's attribute fields, the
+ * markdown blocks and the campaign editors all serialize `{{…}}` and the
+ * people writing SEO titles are the same people who write those. A second
+ * grammar for the same idea is a second thing to learn and a second parser to
+ * keep in step.
+ *
+ * ## What is NOT a variable here
+ *
+ * Anything per-visitor or per-request. A `<title>` is rendered into a cached,
+ * shared HTML document and read by crawlers, so a variable that resolved to
+ * something about the reader would be wrong for everyone it was cached for.
+ * These three are properties of the page and the site, both of which are the
+ * same for everybody who asks for that URL.
+ */
+/** A variable's name, as it is written between the braces. */
+export type SeoTitleVariableName = 'page.name' | 'site.name' | 'site.separator';
+export interface SeoTitleVariableDefinition {
+    name: SeoTitleVariableName;
+    /** What the insert menu calls it. */
+    label: string;
+    /** One line under the label, saying where the value comes from. */
+    description: string;
+}
+/**
+ * Every variable a title may use, in the order a picker should offer them —
+ * which is the order they appear in the default pattern, so the menu reads as
+ * the sentence it builds.
+ */
+export declare const SEO_TITLE_VARIABLES: readonly SeoTitleVariableDefinition[];
+/**
+ * The composition every untitled page gets when the site sets no pattern of
+ * its own.
+ *
+ * This is `resolveSeoTitle`'s previous hard-coded composition, written out:
+ * name, separator padded by a space on each side, site title. It is a constant
+ * rather than a string built at the call site so that the setting's default,
+ * the placeholder the editor shows and the value the renderer falls back to
+ * are one thing.
+ */
+export declare const DEFAULT_TITLE_PATTERN = "{{page.name}} {{site.separator}} {{site.name}}";
+/** The values the variables stand for, for one page of one site. */
+export interface SeoTitleVariableValues {
+    'page.name'?: string | null;
+    'site.name'?: string | null;
+    'site.separator'?: string | null;
+}
+/**
+ * The separator a site uses when it has set none.
+ *
+ * An en dash, which is what `seo-title` has padded around since AGL-1341. It
+ * lives here because `{{site.separator}}` has to resolve to the SAME character
+ * the code composed with — a variable that stood for "the separator, unless
+ * it is unset, in which case nothing" would silently change the title of every
+ * untitled page on every site that never filled the field in.
+ */
+export declare const DEFAULT_TITLE_SEPARATOR = "\u2013";
+/** The site's separator, defaulted the one way everything defaults it. */
+export declare function seoSeparatorOrDefault(separator?: string | null): string;
+/**
+ * Whether a written value uses any variable at all.
+ *
+ * The cheap gate in front of every path here: a title with no `{{` is returned
+ * by identity, which is what makes "nothing renders differently" a property of
+ * the code rather than a claim about the data.
+ */
+export declare function hasSeoTitleVariables(value?: string | null): boolean;
+/** Whether a name is one this catalog defines. */
+export declare function isSeoTitleVariable(name: string): name is SeoTitleVariableName;
+/**
+ * Resolve a written title into the one that is rendered.
+ *
+ * ## An unknown variable is left alone
+ *
+ * `{{page.subtitle}}` renders as itself, visibly, rather than as an empty gap.
+ * A typo that vanished would produce a title that is silently missing a piece,
+ * and the author's next look at the live page would show them a sentence that
+ * merely reads a bit short. Leaving it visible is the version somebody
+ * notices. The editor's picker and autocomplete are what keep it from
+ * happening; this is what happens when they are bypassed.
+ *
+ * ## A separator needs something on BOTH sides
+ *
+ * This is `resolveSeoTitle`'s own rule (AGL-1341) and it survives the move into
+ * a pattern, because it is the rule that stops `<title>` from beginning with a
+ * dash on a page whose name is missing. A `{{site.separator}}` with nothing
+ * rendered on one side of it is dropped, whatever order the pattern put the
+ * pieces in — which is why the parts are walked rather than regex-substituted:
+ * a substitution cannot see its neighbours.
+ *
+ * ## An empty variable takes its spacing with it
+ *
+ * Otherwise a site with no name set renders `Pricing  ` — the gap where the
+ * missing piece was, and a trailing separator's worth of whitespace. Runs
+ * collapse to one space and the result is trimmed.
+ */
+export declare function resolveSeoTitleVariables(written: string | null | undefined, values: SeoTitleVariableValues): string;