@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/seo-title-variables.js

@@ -0,0 +1,190 @@
+/**
+ * @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. */ /**
+ * 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 const SEO_TITLE_VARIABLES = [
+    {
+        name: 'page.name',
+        label: 'Page name',
+        description: 'What this page is called — a screen’s display name.'
+    },
+    {
+        name: 'site.separator',
+        label: 'Separator',
+        description: 'The character from Host setup → SEO that joins the two.'
+    },
+    {
+        name: 'site.name',
+        label: 'Site name',
+        description: 'The site title from Host setup → SEO.'
+    }
+];
+/**
+ * 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 const DEFAULT_TITLE_PATTERN = '{{page.name}} {{site.separator}} {{site.name}}';
+/** Trimmed, or `''` for anything that is not a live string. */ function clean(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * 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 const DEFAULT_TITLE_SEPARATOR = '\u2013';
+/** The site's separator, defaulted the one way everything defaults it. */ export function seoSeparatorOrDefault(separator) {
+    return clean(separator) || DEFAULT_TITLE_SEPARATOR;
+}
+/**
+ * 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 function hasSeoTitleVariables(value) {
+    return typeof value === 'string' && value.includes('{{');
+}
+/** Whether a name is one this catalog defines. */ export function isSeoTitleVariable(name) {
+    return SEO_TITLE_VARIABLES.some((variable)=>variable.name === name);
+}
+/**
+ * `{{ name }}` — the whole token, and the name inside it with its padding
+ * trimmed, so a human who typed a space after the braces is not punished for
+ * it.
+ */ const TOKEN = /\{\{\s*([a-zA-Z][\w.]*)\s*\}\}/g;
+/** The written string as literal runs and variable slots, in order. */ function partsOf(source, values) {
+    const parts = [];
+    let at = 0;
+    TOKEN.lastIndex = 0;
+    for(let match = TOKEN.exec(source); match; match = TOKEN.exec(source)){
+        if (match.index > at) parts.push({
+            text: source.slice(at, match.index)
+        });
+        const name = match[1];
+        parts.push({
+            variable: name,
+            // An unknown variable renders AS ITSELF — see the resolver's docblock.
+            text: !isSeoTitleVariable(name) ? match[0] : name === 'site.separator' ? seoSeparatorOrDefault(values[name]) : clean(values[name])
+        });
+        at = match.index + match[0].length;
+    }
+    if (at < source.length) parts.push({
+        text: source.slice(at)
+    });
+    return parts;
+}
+/**
+ * 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 function resolveSeoTitleVariables(written, values) {
+    const source = typeof written === 'string' ? written : '';
+    if (!hasSeoTitleVariables(source)) return source;
+    const parts = partsOf(source, values);
+    const rendered = parts.map((part)=>part.text);
+    // A separator survives only where something renders on each side of it.
+    parts.forEach((part, index)=>{
+        if (part.variable !== 'site.separator') return;
+        const live = (from, to)=>rendered.slice(from, to).some((text)=>text.trim());
+        if (!live(0, index) || !live(index + 1, rendered.length)) rendered[index] = '';
+    });
+    return rendered.join('').replace(/\s{2,}/g, ' ').trim();
+}
+
+//# sourceMappingURL=seo-title-variables.js.map

package/src/lib/app-utils/seo-title-variables.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/seo-title-variables.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 * The variables a page title may be written in terms of, and how a written\n * title becomes a rendered one.\n *\n * ## Why this exists\n *\n * A title is verbatim (AGL-1341, and that rule is right — see `seo-title`), so\n * an author who wants the brand in a title TYPES it. Fifty screens on the\n * marketing site end in a literal ` | Aglyn`, which means the site name and\n * the character in front of it are stored fifty times, and changing either one\n * is fifty edits that nothing reminds you to make. `seo.separator` already\n * exists as a setting and every one of those titles ignores it.\n *\n * So a title may now be WRITTEN in terms of what it depends on:\n *\n * ```\n *   {{page.name}} {{site.separator}} {{site.name}}\n * ```\n *\n * and a site-name change is one edit in Host setup → SEO.\n *\n * ## ⛔ No rendered title changes because this shipped\n *\n * The whole feature is opt-in at the string level: a title with no `{{` in it\n * is returned unchanged, character for character, by the same code path that\n * returned it before. Nothing migrates the fifty existing titles — a migration\n * could not be output-preserving anyway, because ` | Aglyn` is not what\n * `{{site.separator}}{{site.name}}` resolves to on a host whose separator is\n * `-` and whose site title is the long form. They keep working as literals\n * until somebody decides otherwise, one at a time.\n *\n * `DEFAULT_TITLE_PATTERN` is held to the same standard: it is the composition\n * `resolveSeoTitle` already performed for a page with no authored title, said\n * in tokens instead of in code, and `seo-title.spec` pins that the two agree.\n *\n * ## The grammar is `{{…}}`, not `[…]`\n *\n * Because the platform already has one: the besigner's attribute fields, the\n * markdown blocks and the campaign editors all serialize `{{…}}` and the\n * people writing SEO titles are the same people who write those. A second\n * grammar for the same idea is a second thing to learn and a second parser to\n * keep in step.\n *\n * ## What is NOT a variable here\n *\n * Anything per-visitor or per-request. A `<title>` is rendered into a cached,\n * shared HTML document and read by crawlers, so a variable that resolved to\n * something about the reader would be wrong for everyone it was cached for.\n * These three are properties of the page and the site, both of which are the\n * same for everybody who asks for that URL.\n */\n\n/** A variable's name, as it is written between the braces. */\nexport type SeoTitleVariableName = 'page.name' | 'site.name' | 'site.separator'\n\nexport interface SeoTitleVariableDefinition {\n  name: SeoTitleVariableName\n  /** What the insert menu calls it. */\n  label: string\n  /** One line under the label, saying where the value comes from. */\n  description: string\n}\n\n/**\n * Every variable a title may use, in the order a picker should offer them —\n * which is the order they appear in the default pattern, so the menu reads as\n * the sentence it builds.\n */\nexport const SEO_TITLE_VARIABLES: readonly SeoTitleVariableDefinition[] = [\n  {\n    name: 'page.name',\n    label: 'Page name',\n    description: 'What this page is called — a screen’s display name.',\n  },\n  {\n    name: 'site.separator',\n    label: 'Separator',\n    description: 'The character from Host setup → SEO that joins the two.',\n  },\n  {\n    name: 'site.name',\n    label: 'Site name',\n    description: 'The site title from Host setup → SEO.',\n  },\n]\n\n/**\n * The composition every untitled page gets when the site sets no pattern of\n * its own.\n *\n * This is `resolveSeoTitle`'s previous hard-coded composition, written out:\n * name, separator padded by a space on each side, site title. It is a constant\n * rather than a string built at the call site so that the setting's default,\n * the placeholder the editor shows and the value the renderer falls back to\n * are one thing.\n */\nexport const DEFAULT_TITLE_PATTERN = '{{page.name}} {{site.separator}} {{site.name}}'\n\n/** The values the variables stand for, for one page of one site. */\nexport interface SeoTitleVariableValues {\n  'page.name'?: string | null\n  'site.name'?: string | null\n  'site.separator'?: string | null\n}\n\n/** Trimmed, or `''` for anything that is not a live string. */\nfunction clean(value?: string | null): string {\n  return typeof value === 'string' ? value.trim() : ''\n}\n\n/**\n * The separator a site uses when it has set none.\n *\n * An en dash, which is what `seo-title` has padded around since AGL-1341. It\n * lives here because `{{site.separator}}` has to resolve to the SAME character\n * the code composed with — a variable that stood for \"the separator, unless\n * it is unset, in which case nothing\" would silently change the title of every\n * untitled page on every site that never filled the field in.\n */\nexport const DEFAULT_TITLE_SEPARATOR = '\\u2013'\n\n/** The site's separator, defaulted the one way everything defaults it. */\nexport function seoSeparatorOrDefault(separator?: string | null): string {\n  return clean(separator) || DEFAULT_TITLE_SEPARATOR\n}\n\n/**\n * Whether a written value uses any variable at all.\n *\n * The cheap gate in front of every path here: a title with no `{{` is returned\n * by identity, which is what makes \"nothing renders differently\" a property of\n * the code rather than a claim about the data.\n */\nexport function hasSeoTitleVariables(value?: string | null): boolean {\n  return typeof value === 'string' && value.includes('{{')\n}\n\n/** Whether a name is one this catalog defines. */\nexport function isSeoTitleVariable(name: string): name is SeoTitleVariableName {\n  return SEO_TITLE_VARIABLES.some((variable) => variable.name === name)\n}\n\n/**\n * `{{ name }}` — the whole token, and the name inside it with its padding\n * trimmed, so a human who typed a space after the braces is not punished for\n * it.\n */\nconst TOKEN = /\\{\\{\\s*([a-zA-Z][\\w.]*)\\s*\\}\\}/g\n\ninterface Part {\n  /** What renders here, once the variable is resolved. */\n  text: string\n  /** The variable this came from, if it came from one. */\n  variable?: string\n}\n\n/** The written string as literal runs and variable slots, in order. */\nfunction partsOf(source: string, values: SeoTitleVariableValues): Part[] {\n  const parts: Part[] = []\n  let at = 0\n  TOKEN.lastIndex = 0\n  for (let match = TOKEN.exec(source); match; match = TOKEN.exec(source)) {\n    if (match.index > at) parts.push({ text: source.slice(at, match.index) })\n    const name = match[1]\n    parts.push({\n      variable: name,\n      // An unknown variable renders AS ITSELF — see the resolver's docblock.\n      text: !isSeoTitleVariable(name)\n        ? match[0]\n        : name === 'site.separator'\n          ? seoSeparatorOrDefault(values[name])\n          : clean(values[name]),\n    })\n    at = match.index + match[0].length\n  }\n  if (at < source.length) parts.push({ text: source.slice(at) })\n  return parts\n}\n\n/**\n * Resolve a written title into the one that is rendered.\n *\n * ## An unknown variable is left alone\n *\n * `{{page.subtitle}}` renders as itself, visibly, rather than as an empty gap.\n * A typo that vanished would produce a title that is silently missing a piece,\n * and the author's next look at the live page would show them a sentence that\n * merely reads a bit short. Leaving it visible is the version somebody\n * notices. The editor's picker and autocomplete are what keep it from\n * happening; this is what happens when they are bypassed.\n *\n * ## A separator needs something on BOTH sides\n *\n * This is `resolveSeoTitle`'s own rule (AGL-1341) and it survives the move into\n * a pattern, because it is the rule that stops `<title>` from beginning with a\n * dash on a page whose name is missing. A `{{site.separator}}` with nothing\n * rendered on one side of it is dropped, whatever order the pattern put the\n * pieces in — which is why the parts are walked rather than regex-substituted:\n * a substitution cannot see its neighbours.\n *\n * ## An empty variable takes its spacing with it\n *\n * Otherwise a site with no name set renders `Pricing  ` — the gap where the\n * missing piece was, and a trailing separator's worth of whitespace. Runs\n * collapse to one space and the result is trimmed.\n */\nexport function resolveSeoTitleVariables(\n  written: string | null | undefined,\n  values: SeoTitleVariableValues,\n): string {\n  const source = typeof written === 'string' ? written : ''\n  if (!hasSeoTitleVariables(source)) return source\n\n  const parts = partsOf(source, values)\n  const rendered = parts.map((part) => part.text)\n  // A separator survives only where something renders on each side of it.\n  parts.forEach((part, index) => {\n    if (part.variable !== 'site.separator') return\n    const live = (from: number, to: number) =>\n      rendered.slice(from, to).some((text) => text.trim())\n    if (!live(0, index) || !live(index + 1, rendered.length)) rendered[index] = ''\n  })\n\n  return rendered.join('').replace(/\\s{2,}/g, ' ').trim()\n}\n"],"names":["SEO_TITLE_VARIABLES","name","label","description","DEFAULT_TITLE_PATTERN","clean","value","trim","DEFAULT_TITLE_SEPARATOR","seoSeparatorOrDefault","separator","hasSeoTitleVariables","includes","isSeoTitleVariable","some","variable","TOKEN","partsOf","source","values","parts","at","lastIndex","match","exec","index","push","text","slice","length","resolveSeoTitleVariables","written","rendered","map","part","forEach","live","from","to","join","replace"],"mappings":"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"}

package/src/lib/app-utils/seo-title.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.
+ */
+export interface SeoTitleOptions {
+    /**
+     * The page's own AUTHORED title (screen `seo.title`, entry `seoTitle`).
+     * Rendered verbatim when set — nothing is appended to it.
+     */
+    title?: string | null;
+    /**
+     * What the page is CALLED when nobody authored a title for it: a screen's
+     * `displayName`, an entry's headline, a collection or category name. This is
+     * the side the site title joins.
+     */
+    name?: string | null;
+    /** The host's `seo.title` (or `displayName`) — the site-level fallback. */
+    siteTitle?: string | null;
+    /** The host's `seo.separator`; padded and defaulted, see below. */
+    separator?: string | null;
+    /**
+     * Last resort for a page with no name and a site that named itself nothing.
+     * Callers pass a brand-resolved string (never a hard-coded "Aglyn" — a
+     * white-label site must not leak the platform brand into its `<title>`).
+     */
+    fallback?: string | null;
+    /**
+     * The site's title PATTERN — `seo.titlePattern` — for the composed case
+     * (AGL-3197).
+     *
+     * Rule 2 below was one composition written in code, so the only thing a site
+     * could change about it was the separator. It is now a written pattern with
+     * a default that says the same thing, so a site can put its name first, drop
+     * it from the composition entirely, or keep what it has by setting nothing.
+     *
+     * It composes the FALLBACK only. A pattern that also wrapped authored titles
+     * would rewrite every title anyone has already written, which is the one
+     * outcome this feature is not allowed to have — an authored title that wants
+     * the site name in it says so with a variable of its own.
+     */
+    pattern?: string | null;
+}
+/**
+ * Resolves the `<title>` (and the matching `og:title`) for a page.
+ *
+ * See the module docblock for the rule; the short version is that `title` is
+ * an override and `siteTitle` is a fallback, never a suffix.
+ */
+export declare function resolveSeoTitle(options: SeoTitleOptions): string;
+/**
+ * The pattern a site composes untitled pages with, ready to render.
+ *
+ * Separate from the resolver so the console's editor can show the same default
+ * as a placeholder without duplicating the constant, and so a stored pattern
+ * of `''` — what a cleared field writes (AGL-1191) — means "the default"
+ * rather than "compose nothing".
+ */
+export declare function seoTitlePatternOrDefault(pattern?: string | null): string;

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

@@ -0,0 +1,117 @@
+/**
+ * @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 { DEFAULT_TITLE_PATTERN, hasSeoTitleVariables, resolveSeoTitleVariables } from "./seo-title-variables.js";
+/**
+ * The rendered page title (AGL-1341).
+ *
+ * ## The bug this ends
+ *
+ * Every head built its title the same way — `{page}{separator}{host title}` —
+ * so the host's SEO title was an unconditional SUFFIX rather than a fallback.
+ * On a site whose titles are written to be self-contained that reads the brand
+ * twice and blows the budget:
+ *
+ * ```
+ * Aglyn — the visual builder with a real platform underneath-Website Builder - Create Your Own Websites - Aglyn
+ * ```
+ *
+ * 111 characters, of which Google shows about 60 — so the distinctive half is
+ * exactly the half that gets cut. `Title*` and `Separator*` are both REQUIRED
+ * in Host Setup → SEO, so no setting could switch this off; it had to be the
+ * rule that changed.
+ *
+ * ## The rule
+ *
+ * 1. An **authored** SEO title wins **verbatim** — a screen's `seo.title`, an
+ *    entry's `seoTitle`. Someone typed those into a field labelled "Title"
+ *    with a 60-character counter beside it; appending to them overrides the
+ *    only person who knows what the page is called.
+ * 2. Otherwise the page's **name** (screen `displayName`, entry headline,
+ *    collection or category name) composes with the site title, separator in
+ *    between. This is what keeps the fallback path branded — and, more to the
+ *    point, DISTINCT: falling straight back to the host title would give every
+ *    untitled screen on a site the same `<title>`, which is a worse SEO defect
+ *    than the one being fixed.
+ * 3. The separator appears only with a live value on BOTH sides. A page with a
+ *    name and no site title, or a site title and no name, renders the one it
+ *    has; a page with neither renders the caller's `fallback`. No head ever
+ *    emits a leading separator or an empty `<title>`.
+ *
+ * Empty and whitespace-only are ABSENT, not set — the console writes `''` for
+ * a cleared field (AGL-1191), and a title of `'   '` is not a title.
+ *
+ * The brand does not disappear from the head: `og:site_name` still carries the
+ * site title on every page, which is where a consumer looks for it.
+ *
+ * ## Why a shared function
+ *
+ * Four surfaces composed this independently — the screen branch, the
+ * collection branch, the built-in gated pages and the search page — and they
+ * had already drifted (the search page hard-coded an en dash and ignored the
+ * host's separator entirely). One rule in one place is what makes the answer
+ * uniform for the fifth surface nobody has written yet.
+ */ /** Trimmed, or `''` for anything that is not a live string. */ function clean(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * The separator, padded.
+ *
+ * The field caps at 3 characters and hosts type a bare `-`, which joined
+ * without padding produced `…open web-Website Builder…` — two titles run
+ * together into one word. Padding is applied around whatever was typed (and a
+ * separator that is only whitespace is no separator), so an author who typed
+ * `|` gets ` | ` and one who typed `·` gets ` · `.
+ */ function padSeparator(separator) {
+    return ` ${clean(separator) || '–'} `;
+}
+/**
+ * Resolves the `<title>` (and the matching `og:title`) for a page.
+ *
+ * See the module docblock for the rule; the short version is that `title` is
+ * an override and `siteTitle` is a fallback, never a suffix.
+ */ export function resolveSeoTitle(options) {
+    const name = clean(options.name);
+    const siteTitle = clean(options.siteTitle);
+    const values = {
+        'page.name': name,
+        'site.name': siteTitle,
+        'site.separator': clean(options.separator)
+    };
+    const authored = clean(options.title);
+    if (authored) {
+        // Verbatim, still — rule 1 is untouched. A title with no variables in it
+        // does not reach the resolver at all, so it comes back identical by the
+        // shortest path there is (AGL-3197).
+        return hasSeoTitleVariables(authored) ? resolveSeoTitleVariables(authored, values) || clean(options.fallback) : authored;
+    }
+    const pattern = clean(options.pattern);
+    if (pattern) return resolveSeoTitleVariables(pattern, values) || clean(options.fallback);
+    // Both sides live: this is the only case that renders a separator.
+    if (name && siteTitle) return `${name}${padSeparator(options.separator)}${siteTitle}`;
+    return name || siteTitle || clean(options.fallback);
+}
+/**
+ * The pattern a site composes untitled pages with, ready to render.
+ *
+ * Separate from the resolver so the console's editor can show the same default
+ * as a placeholder without duplicating the constant, and so a stored pattern
+ * of `''` — what a cleared field writes (AGL-1191) — means "the default"
+ * rather than "compose nothing".
+ */ export function seoTitlePatternOrDefault(pattern) {
+    return clean(pattern) || DEFAULT_TITLE_PATTERN;
+}
+
+//# sourceMappingURL=seo-title.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/seo-title.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 {\n  DEFAULT_TITLE_PATTERN,\n  hasSeoTitleVariables,\n  resolveSeoTitleVariables,\n} from './seo-title-variables'\n\n/**\n * The rendered page title (AGL-1341).\n *\n * ## The bug this ends\n *\n * Every head built its title the same way — `{page}{separator}{host title}` —\n * so the host's SEO title was an unconditional SUFFIX rather than a fallback.\n * On a site whose titles are written to be self-contained that reads the brand\n * twice and blows the budget:\n *\n * ```\n * Aglyn — the visual builder with a real platform underneath-Website Builder - Create Your Own Websites - Aglyn\n * ```\n *\n * 111 characters, of which Google shows about 60 — so the distinctive half is\n * exactly the half that gets cut. `Title*` and `Separator*` are both REQUIRED\n * in Host Setup → SEO, so no setting could switch this off; it had to be the\n * rule that changed.\n *\n * ## The rule\n *\n * 1. An **authored** SEO title wins **verbatim** — a screen's `seo.title`, an\n *    entry's `seoTitle`. Someone typed those into a field labelled \"Title\"\n *    with a 60-character counter beside it; appending to them overrides the\n *    only person who knows what the page is called.\n * 2. Otherwise the page's **name** (screen `displayName`, entry headline,\n *    collection or category name) composes with the site title, separator in\n *    between. This is what keeps the fallback path branded — and, more to the\n *    point, DISTINCT: falling straight back to the host title would give every\n *    untitled screen on a site the same `<title>`, which is a worse SEO defect\n *    than the one being fixed.\n * 3. The separator appears only with a live value on BOTH sides. A page with a\n *    name and no site title, or a site title and no name, renders the one it\n *    has; a page with neither renders the caller's `fallback`. No head ever\n *    emits a leading separator or an empty `<title>`.\n *\n * Empty and whitespace-only are ABSENT, not set — the console writes `''` for\n * a cleared field (AGL-1191), and a title of `'   '` is not a title.\n *\n * The brand does not disappear from the head: `og:site_name` still carries the\n * site title on every page, which is where a consumer looks for it.\n *\n * ## Why a shared function\n *\n * Four surfaces composed this independently — the screen branch, the\n * collection branch, the built-in gated pages and the search page — and they\n * had already drifted (the search page hard-coded an en dash and ignored the\n * host's separator entirely). One rule in one place is what makes the answer\n * uniform for the fifth surface nobody has written yet.\n */\n\n/** Trimmed, or `''` for anything that is not a live string. */\nfunction clean(value?: string | null): string {\n  return typeof value === 'string' ? value.trim() : ''\n}\n\nexport interface SeoTitleOptions {\n  /**\n   * The page's own AUTHORED title (screen `seo.title`, entry `seoTitle`).\n   * Rendered verbatim when set — nothing is appended to it.\n   */\n  title?: string | null\n  /**\n   * What the page is CALLED when nobody authored a title for it: a screen's\n   * `displayName`, an entry's headline, a collection or category name. This is\n   * the side the site title joins.\n   */\n  name?: string | null\n  /** The host's `seo.title` (or `displayName`) — the site-level fallback. */\n  siteTitle?: string | null\n  /** The host's `seo.separator`; padded and defaulted, see below. */\n  separator?: string | null\n  /**\n   * Last resort for a page with no name and a site that named itself nothing.\n   * Callers pass a brand-resolved string (never a hard-coded \"Aglyn\" — a\n   * white-label site must not leak the platform brand into its `<title>`).\n   */\n  fallback?: string | null\n  /**\n   * The site's title PATTERN — `seo.titlePattern` — for the composed case\n   * (AGL-3197).\n   *\n   * Rule 2 below was one composition written in code, so the only thing a site\n   * could change about it was the separator. It is now a written pattern with\n   * a default that says the same thing, so a site can put its name first, drop\n   * it from the composition entirely, or keep what it has by setting nothing.\n   *\n   * It composes the FALLBACK only. A pattern that also wrapped authored titles\n   * would rewrite every title anyone has already written, which is the one\n   * outcome this feature is not allowed to have — an authored title that wants\n   * the site name in it says so with a variable of its own.\n   */\n  pattern?: string | null\n}\n\n/**\n * The separator, padded.\n *\n * The field caps at 3 characters and hosts type a bare `-`, which joined\n * without padding produced `…open web-Website Builder…` — two titles run\n * together into one word. Padding is applied around whatever was typed (and a\n * separator that is only whitespace is no separator), so an author who typed\n * `|` gets ` | ` and one who typed `·` gets ` · `.\n */\nfunction padSeparator(separator?: string | null): string {\n  return ` ${clean(separator) || '–'} `\n}\n\n/**\n * Resolves the `<title>` (and the matching `og:title`) for a page.\n *\n * See the module docblock for the rule; the short version is that `title` is\n * an override and `siteTitle` is a fallback, never a suffix.\n */\nexport function resolveSeoTitle(options: SeoTitleOptions): string {\n  const name = clean(options.name)\n  const siteTitle = clean(options.siteTitle)\n  const values = {\n    'page.name': name,\n    'site.name': siteTitle,\n    'site.separator': clean(options.separator),\n  }\n\n  const authored = clean(options.title)\n  if (authored) {\n    // Verbatim, still — rule 1 is untouched. A title with no variables in it\n    // does not reach the resolver at all, so it comes back identical by the\n    // shortest path there is (AGL-3197).\n    return hasSeoTitleVariables(authored)\n      ? resolveSeoTitleVariables(authored, values) || clean(options.fallback)\n      : authored\n  }\n\n  const pattern = clean(options.pattern)\n  if (pattern) return resolveSeoTitleVariables(pattern, values) || clean(options.fallback)\n\n  // Both sides live: this is the only case that renders a separator.\n  if (name && siteTitle) return `${name}${padSeparator(options.separator)}${siteTitle}`\n  return name || siteTitle || clean(options.fallback)\n}\n\n/**\n * The pattern a site composes untitled pages with, ready to render.\n *\n * Separate from the resolver so the console's editor can show the same default\n * as a placeholder without duplicating the constant, and so a stored pattern\n * of `''` — what a cleared field writes (AGL-1191) — means \"the default\"\n * rather than \"compose nothing\".\n */\nexport function seoTitlePatternOrDefault(pattern?: string | null): string {\n  return clean(pattern) || DEFAULT_TITLE_PATTERN\n}\n"],"names":["DEFAULT_TITLE_PATTERN","hasSeoTitleVariables","resolveSeoTitleVariables","clean","value","trim","padSeparator","separator","resolveSeoTitle","options","name","siteTitle","values","authored","title","fallback","pattern","seoTitlePatternOrDefault"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,qBAAqB,EACrBC,oBAAoB,EACpBC,wBAAwB,QACnB,2BAAuB;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDC,GAED,6DAA6D,GAC7D,SAASC,MAAMC,KAAqB;IAClC,OAAO,OAAOA,UAAU,WAAWA,MAAMC,IAAI,KAAK;AACpD;AAyCA;;;;;;;;CAQC,GACD,SAASC,aAAaC,SAAyB;IAC7C,OAAO,CAAC,CAAC,EAAEJ,MAAMI,cAAc,IAAI,CAAC,CAAC;AACvC;AAEA;;;;;CAKC,GACD,OAAO,SAASC,gBAAgBC,OAAwB;IACtD,MAAMC,OAAOP,MAAMM,QAAQC,IAAI;IAC/B,MAAMC,YAAYR,MAAMM,QAAQE,SAAS;IACzC,MAAMC,SAAS;QACb,aAAaF;QACb,aAAaC;QACb,kBAAkBR,MAAMM,QAAQF,SAAS;IAC3C;IAEA,MAAMM,WAAWV,MAAMM,QAAQK,KAAK;IACpC,IAAID,UAAU;QACZ,yEAAyE;QACzE,wEAAwE;QACxE,qCAAqC;QACrC,OAAOZ,qBAAqBY,YACxBX,yBAAyBW,UAAUD,WAAWT,MAAMM,QAAQM,QAAQ,IACpEF;IACN;IAEA,MAAMG,UAAUb,MAAMM,QAAQO,OAAO;IACrC,IAAIA,SAAS,OAAOd,yBAAyBc,SAASJ,WAAWT,MAAMM,QAAQM,QAAQ;IAEvF,mEAAmE;IACnE,IAAIL,QAAQC,WAAW,OAAO,GAAGD,OAAOJ,aAAaG,QAAQF,SAAS,IAAII,WAAW;IACrF,OAAOD,QAAQC,aAAaR,MAAMM,QAAQM,QAAQ;AACpD;AAEA;;;;;;;CAOC,GACD,OAAO,SAASE,yBAAyBD,OAAuB;IAC9D,OAAOb,MAAMa,YAAYhB;AAC3B"}

package/src/lib/app-utils/server.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2022 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.
+ */
+/**
+ * Server-safe app-utils: every app-util EXCEPT the client-only React
+ * contexts (see ./contexts). Nothing here calls `createContext` at module
+ * scope, so this barrel — re-exported by `@aglyn/aglyn/server` — is safe to
+ * import from tenant Server Components (AGL-405). The full `./index` barrel
+ * re-adds the contexts for client consumers.
+ */
+export * from './binding-token-catalog';
+export * from './binding-tokens';
+export * from './breadcrumb-json-ld';
+export * from './seo-listing-fields';
+export * from './video-object';
+export * from './collection-delete';
+export * from './collection-entries';
+export * from './collection-kind';
+export * from './collection-slug';
+export * from './content-authors';
+export * from './content-schema-type';
+export * from './content-author-profile';
+export * from './url-slug';
+export * from './child-contract';
+export * from './child-contract-compose';
+export * from './lineal-order';
+export * from './node-definition-sanitizer';
+export * from './console-routes';
+export * from './console-record-links';
+export * from './screen-link-value';
+export * from './link-references';
+export * from './analytics-path-key';
+export * from './contacts';
+export * from './crm';
+export * from './crm-email-templates';
+export * from './crm-booking';
+export * from './contact-merge';
+export * from './person-erasure';
+export * from './crm-reports';
+export * from './crm-csv';
+export * from './contact-holder';
+export * from './crm-digest';
+export * from './crm-task-reminders';
+export * from './crm-inbound';
+export * from './member-email-aliases';
+export * from './crm-next-activity';
+export { csvCell, csvDocument, customImportTarget, customImportTargetKey, } from './csv-import';
+export type { ImportChunkResult, ImportDroppedValue, ImportSkippedRow, } from './csv-import';
+export * from './contact-custom-fields';
+export * from './consent-groups';
+export * from './marketing-consent';
+export * from './list-assignment-policy';
+export * from './list-import';
+export * from './dynamic-list-rule';
+export * from './email-topics';
+export * from './compose-layout-nodes';
+export * from './compose-layout-props';
+export * from './document-landmark';
+export * from './functions';
+export * from './compose-reusable-components';
+export * from './compress';
+export * from './merge-node-sx';
+export * from './palette-sx';
+export * from './scheme-sx';
+export * from './create-resource-uid';
+export * from './decompress';
+export * from './stored-nodes';
+export * from './strip-undefined';
+export * from './organizations';
+export * from './org-permissions';
+export * from './host-permissions';
+export * from './password-policy';
+export * from './idp-profile';
+export * from './onboarding-deep-link';
+export * from './campaign-attribution';
+export * from './campaign-membership';
+export * from './deployment-shape';
+export * from './upload-cors';
+export * from './docs-help';
+export * from './platform-brand';
+export * from './plan-entitlements';
+export * from './bandwidth-cap';
+export * from './form-abuse-ceiling';
+export * from './forms';
+export * from './form-contract';
+export * from './visitor-record-ceiling';
+export * from './health-report';
+export * from './webhook-delivery';
+export * from './support-tiers';
+export * from './release-flags';
+export * from './operator-identity';
+export * from './lockdown';
+export * from './media-quarantine';
+export * from './media-takedown-reach';
+export * from './upload-inspection';
+export * from './abuse-report';
+export * from './dmca-counter-notice';
+export * from './repeat-infringer';
+export * from './org-override-reason';
+export * from './host-tokens';
+export * from './variables';
+export * from './workflows';
+export * from './datasets';
+export * from './expand-repeatables';
+export * from './org-roles';
+export * from './markdown-lite';
+export * from './notifications';
+export * from './definition-canvas-tree';
+export * from './ensure-canvas-root';
+export * from './repair-canvas-nodes';
+export * from './detect-template-placeholders';
+export * from './guarded-version-save';
+export * from './local-storage-budget';
+export * from './measure-node-map';
+export * from './resolve-named-tokens';
+export * from './screen-route';
+export * from './host-naming';
+export * from './marketplace-verification';
+export * from './name-search';
+export * from './name-match';
+export * from './api-plugins';
+export * from './plugin-api-rate-limit';
+export * from './plugin-api-cross-origin';
+export * from './actions';
+export * from './element-animation';
+export * from './attribution-guard';
+export * from './node-interactions';
+export * from './element-ui';
+export * from './image-upload-types';
+export * from './sanitize-svg';
+export * from './media-folders';
+export * from './media-metadata';
+export * from './media-ref';
+export * from './paid-media-source';
+export * from './author-css';
+export * from './author-html';
+export * from './dataset-models';
+export * from './dataset-csv';
+export * from './marketplace-provenance';
+export * from './marketplace-update-state';
+export * from './dataset-query';
+export * from './plugin-manifest';
+export * from './email-starter-policy';
+export * from './safe-json-ld';
+export * from './accept-negotiation';
+export * from './agent-api-catalog';
+export * from './agent-openapi';
+export * from './author-html-markdown';
+export * from './llms-txt';
+export * from './page-markdown';
+export * from './request-geo';
+export * from './request-ip';
+export * from './search-indexing';
+export * from './seo-title';
+export * from './sitemap';
+export * from './visitor-consent';
+export * from './social-image';
+export * from './scope-tokens';
+export * from './org-billing-doc';
+export * from './stripe-deployment-mode';
+export * from './deferred-image';