@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/binding-tokens.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @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.
+ */
+/** `{{var:variableId}}` — capture group 1 is the variable's doc id. */
+export declare const VARIABLE_ID_TOKEN_PATTERN: RegExp;
+/**
+ * `{{fn:ref(args)}}` — capture 1 is a function doc id OR legacy name,
+ * capture 2 the raw argument list. One pattern serves both generations;
+ * lookup order (id first, then name) decides what the ref means.
+ */
+export declare const FUNCTION_TOKEN_PATTERN: RegExp;
+/** Legacy `{{name}}` — names never contain `:`, so `var:`/`fn:` can't match. */
+export declare const NAME_TOKEN_PATTERN: RegExp;
+/** Renders the id-form variable token the picker inserts (AGL-186). */
+export declare function formatVariableIdToken(variableId: string): string;
+/** Renders the id-form function token with its parameter placeholders. */
+export declare function formatFunctionIdToken(functionId: string, parameterNames?: string[]): string;
+/**
+ * Keys resource docs by doc id — the only key resolution uses since the
+ * legacy name fallback retired (AGL-194). Editor-side lookups that need
+ * name access (typed-name normalization, friendly display) read the
+ * `name` field off the values instead of relying on map keys.
+ */
+export declare function keyById<T extends {
+    name?: string;
+}>(docs: Array<T & {
+    id: string;
+}>): Record<string, T>;
+/**
+ * Doc shape the editor-side helpers need: consoles pass Firestore docs
+ * that carry their id as `$id` (reactfire idField) beside the name.
+ */
+export interface BindingDocRef {
+    name?: string;
+    $id?: string;
+    parameters?: Array<{
+        name: string;
+    }>;
+}
+/**
+ * Rewrites legacy name tokens to their id forms when the name matches a
+ * known doc (AGL-186 typing normalization): hand-typed `{{Message}}`
+ * becomes `{{var:abc123}}` at save so it survives renames. Unknown names
+ * are left alone — the variable may be created later, and legacy
+ * resolution still covers them meanwhile.
+ */
+export declare function normalizeBindingTokens(text: string, variables?: Record<string, BindingDocRef>, functions?: Record<string, BindingDocRef>): string;
+/**
+ * Rewrites id-form variable tokens to the `{{name}}` an author types — the
+ * inverse of {@link normalizeBindingTokens}, for an editor that shows stored
+ * copy in a plain text field and normalizes it again when it saves.
+ *
+ * Unlike {@link displayBindingTokens}, whose result must never be persisted,
+ * this one survives the round trip: normalizing its output restores the
+ * input. So a token is rewritten only when that holds — its variable exists,
+ * its name is one a typed token can carry, and looking that name up leads back
+ * to this id and no other. Every other token keeps its id form. That includes
+ * a deleted variable's token, which renders as nothing on a published page,
+ * where `{{missing binding}}` would render as typed.
+ *
+ * @param variables - the lookup `normalizeBindingTokens` takes: the site's
+ *   variables keyed by name, each carrying its document id as `$id`.
+ */
+export declare function editableBindingTokens(text: string, variables?: Record<string, BindingDocRef>): string;
+/** A variable/function referent to search for in stored content. */
+export interface BindingRef {
+    kind: 'variable' | 'function';
+    /** Firestore doc id — matches id-form tokens. */
+    id?: string;
+    /** Current name — matches legacy name-form tokens. */
+    name?: string;
+}
+/** How a dependent references the binding: rename-safe id or legacy name. */
+export type BindingRefVia = 'id' | 'name';
+/**
+ * Which token generation(s) in `text` reference the given binding
+ * (AGL-187 where-used). Returns matches so callers can distinguish
+ * rename-safe id references from legacy name references — a rename only
+ * endangers the latter.
+ */
+export declare function textReferencesBinding(text: string, ref: BindingRef): BindingRefVia[];
+/**
+ * Scans a normalized nodes map's string props for references to the
+ * binding; returns the union of match kinds across all nodes.
+ */
+export declare function nodesReferenceBinding(nodes: Record<string, {
+    props?: Record<string, unknown>;
+} | undefined>, ref: BindingRef): BindingRefVia[];
+/**
+ * Deep-walks a JSON-ish value, applying `normalizeBindingTokens` to every
+ * string containing a token opener (AGL-188 migration / host import).
+ * Arrays and plain objects recurse; other values pass through untouched.
+ * Returns the (possibly new) value and whether anything changed.
+ */
+export declare function rewriteBindingTokensDeep<T>(value: T, variables?: Record<string, BindingDocRef>, functions?: Record<string, BindingDocRef>): {
+    value: T;
+    changed: boolean;
+};
+/**
+ * Which binding lookups a value's tokens would actually need (AGL-703).
+ *
+ * A read-only twin of {@link rewriteBindingTokensDeep}, and it exists for
+ * cost. Publish-time normalization used to fetch EVERY variable and EVERY
+ * function on the site — two `limit(1000)` gets — before looking at whether
+ * the version being published contained a single token to rewrite. Almost
+ * none do: AGL-188 migrated the corpus years ago and the picker has written
+ * id-form tokens ever since, so the overwhelming majority of publishes paid
+ * for two collection reads to discover there was nothing to do.
+ *
+ * The two flags are separate because the two rewrites are:
+ *
+ * - a legacy `{{name}}` token is resolved against VARIABLES and nothing else
+ *   — {@link normalizeBindingTokens} only consults `variables` for it;
+ * - a `{{fn:ref(...)}}` token is resolved against FUNCTIONS.
+ *
+ * So a page holding only function tokens never reads the variables.
+ *
+ * `{{var:id}}` deliberately sets NEITHER. It is already the rename-safe form,
+ * nothing rewrites it, and it cannot match `NAME_TOKEN_PATTERN` because a
+ * name may not contain `:`. A page whose tokens are all id-form — which is
+ * what a page authored through the picker looks like — costs nothing.
+ *
+ * A `{{fn:}}` token sets `functions` even when its ref is ALREADY an id,
+ * because telling an id from a legacy name is exactly what the lookup is for.
+ * Erring that way costs one read on a page that has function tokens; erring
+ * the other way would skip a rewrite that was due.
+ */
+export interface BindingTokenNeeds {
+    /** A legacy `{{name}}` token is present — needs the variables lookup. */
+    variables: boolean;
+    /** A `{{fn:…}}` token is present — needs the functions lookup. */
+    functions: boolean;
+}
+export declare function bindingTokenNeedsDeep(value: unknown): BindingTokenNeeds;
+/** Editor display text for a token whose referent no longer exists. */
+export declare const MISSING_BINDING_LABEL = "missing binding";
+/**
+ * Rewrites id tokens to friendly name forms for editor display (AGL-186):
+ * `{{var:abc123}}` shows as `{{Message}}` (the CURRENT name — renames
+ * reflect immediately), and tokens whose doc was deleted show as
+ * `{{missing binding}}` instead of leaking raw ids. Display only — never
+ * persist the result.
+ */
+export declare function displayBindingTokens(text: string, variables?: Record<string, BindingDocRef>, functions?: Record<string, BindingDocRef>): string;

package/src/lib/app-utils/binding-tokens.js

@@ -0,0 +1,251 @@
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @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.
+ */ /**
+ * Binding token grammar (AGL-185) — the single source of truth for what a
+ * binding token looks like, shared by the besigner editor, the console
+ * binding picker, and the tenant renderer.
+ *
+ * Two generations coexist:
+ * - id tokens: `{{var:variableId}}` and `{{fn:functionId(args)}}` — the
+ *   reference survives renames because only the display name changes.
+ * - legacy name tokens: `{{name}}` and `{{fn:name(args)}}` — resolved as a
+ *   fallback until AGL-188 migrates stored content.
+ *
+ * Resolution maps are id-keyed (AGL-194); the editor keeps name-capable
+ * lookups only for typed-name normalization and friendly display.
+ */ /** Firestore doc ids and legacy binding names both fit this shape. */ const REF = '[a-zA-Z0-9_-]{1,64}';
+/** `{{var:variableId}}` — capture group 1 is the variable's doc id. */ export const VARIABLE_ID_TOKEN_PATTERN = new RegExp(`\\{\\{\\s*var:(${REF})\\s*\\}\\}`, 'g');
+/**
+ * `{{fn:ref(args)}}` — capture 1 is a function doc id OR legacy name,
+ * capture 2 the raw argument list. One pattern serves both generations;
+ * lookup order (id first, then name) decides what the ref means.
+ */ export const FUNCTION_TOKEN_PATTERN = new RegExp(`\\{\\{\\s*fn:(${REF}(?: ${REF})*)\\s*\\(([^)]*)\\)\\s*\\}\\}`, 'g');
+/** Legacy `{{name}}` — names never contain `:`, so `var:`/`fn:` can't match. */ export const NAME_TOKEN_PATTERN = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]{0,39})\s*\}\}/g;
+/** Renders the id-form variable token the picker inserts (AGL-186). */ export function formatVariableIdToken(variableId) {
+    return `{{var:${variableId}}}`;
+}
+/** Renders the id-form function token with its parameter placeholders. */ export function formatFunctionIdToken(functionId, parameterNames = []) {
+    return `{{fn:${functionId}(${parameterNames.join(', ')})}}`;
+}
+/**
+ * Keys resource docs by doc id — the only key resolution uses since the
+ * legacy name fallback retired (AGL-194). Editor-side lookups that need
+ * name access (typed-name normalization, friendly display) read the
+ * `name` field off the values instead of relying on map keys.
+ */ export function keyById(docs) {
+    const map = {};
+    for (const _ref of docs){
+        let { id } = _ref, doc = _object_without_properties_loose(_ref, [
+            "id"
+        ]);
+        map[id] = doc;
+    }
+    return map;
+}
+/**
+ * Rewrites legacy name tokens to their id forms when the name matches a
+ * known doc (AGL-186 typing normalization): hand-typed `{{Message}}`
+ * becomes `{{var:abc123}}` at save so it survives renames. Unknown names
+ * are left alone — the variable may be created later, and legacy
+ * resolution still covers them meanwhile.
+ */ export function normalizeBindingTokens(text, variables = {}, functions = {}) {
+    const withFunctions = text.replace(FUNCTION_TOKEN_PATTERN, (token, ref, rawArgs)=>{
+        const definition = functions[String(ref).trim()];
+        // Already an id (the ref maps to a doc whose $id is the ref itself)
+        // or unknown: leave as-is.
+        if (!(definition == null ? void 0 : definition.$id) || definition.$id === String(ref).trim()) {
+            return token;
+        }
+        return `{{fn:${definition.$id}(${String(rawArgs)})}}`;
+    });
+    return withFunctions.replace(NAME_TOKEN_PATTERN, (token, name)=>{
+        const variable = variables[name];
+        return (variable == null ? void 0 : variable.$id) ? formatVariableIdToken(variable.$id) : token;
+    });
+}
+/** A whole `{{name}}` token, for asking whether a name can be typed as one. */ const TYPED_NAME_TOKEN = new RegExp(`^${NAME_TOKEN_PATTERN.source}$`);
+/**
+ * Rewrites id-form variable tokens to the `{{name}}` an author types — the
+ * inverse of {@link normalizeBindingTokens}, for an editor that shows stored
+ * copy in a plain text field and normalizes it again when it saves.
+ *
+ * Unlike {@link displayBindingTokens}, whose result must never be persisted,
+ * this one survives the round trip: normalizing its output restores the
+ * input. So a token is rewritten only when that holds — its variable exists,
+ * its name is one a typed token can carry, and looking that name up leads back
+ * to this id and no other. Every other token keeps its id form. That includes
+ * a deleted variable's token, which renders as nothing on a published page,
+ * where `{{missing binding}}` would render as typed.
+ *
+ * @param variables - the lookup `normalizeBindingTokens` takes: the site's
+ *   variables keyed by name, each carrying its document id as `$id`.
+ */ export function editableBindingTokens(text, variables = {}) {
+    if (!text.includes('{{')) return text;
+    return text.replace(VARIABLE_ID_TOKEN_PATTERN, (token, rawId)=>{
+        var _Object_values_find, _variables_name;
+        const id = String(rawId);
+        const name = (_Object_values_find = Object.values(variables).find((variable)=>(variable == null ? void 0 : variable.$id) === id)) == null ? void 0 : _Object_values_find.name;
+        if (!name || ((_variables_name = variables[name]) == null ? void 0 : _variables_name.$id) !== id) return token;
+        const typed = `{{${name}}}`;
+        return TYPED_NAME_TOKEN.test(typed) ? typed : token;
+    });
+}
+const escapeRegExp = (value)=>value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Which token generation(s) in `text` reference the given binding
+ * (AGL-187 where-used). Returns matches so callers can distinguish
+ * rename-safe id references from legacy name references — a rename only
+ * endangers the latter.
+ */ export function textReferencesBinding(text, ref) {
+    const via = [];
+    if (ref.kind === 'variable') {
+        if (ref.id && new RegExp(`\\{\\{\\s*var:${escapeRegExp(ref.id)}\\s*\\}\\}`).test(text)) {
+            via.push('id');
+        }
+        if (ref.name && new RegExp(`\\{\\{\\s*${escapeRegExp(ref.name)}\\s*\\}\\}`).test(text)) {
+            via.push('name');
+        }
+    } else {
+        if (ref.id && new RegExp(`\\{\\{\\s*fn:${escapeRegExp(ref.id)}\\s*\\(`).test(text)) {
+            via.push('id');
+        }
+        if (ref.name && new RegExp(`\\{\\{\\s*fn:${escapeRegExp(ref.name)}\\s*\\(`).test(text)) {
+            via.push('name');
+        }
+    }
+    return via;
+}
+/**
+ * Scans a normalized nodes map's string props for references to the
+ * binding; returns the union of match kinds across all nodes.
+ */ export function nodesReferenceBinding(nodes, ref) {
+    const via = new Set();
+    for (const node of Object.values(nodes != null ? nodes : {})){
+        var _ref;
+        for (const value of Object.values((_ref = node == null ? void 0 : node.props) != null ? _ref : {})){
+            if (typeof value !== 'string' || !value.includes('{{')) continue;
+            for (const match of textReferencesBinding(value, ref))via.add(match);
+        }
+        if (via.size === 2) break;
+    }
+    return [
+        ...via
+    ];
+}
+/**
+ * Deep-walks a JSON-ish value, applying `normalizeBindingTokens` to every
+ * string containing a token opener (AGL-188 migration / host import).
+ * Arrays and plain objects recurse; other values pass through untouched.
+ * Returns the (possibly new) value and whether anything changed.
+ */ export function rewriteBindingTokensDeep(value, variables = {}, functions = {}) {
+    if (typeof value === 'string') {
+        if (!value.includes('{{')) return {
+            value,
+            changed: false
+        };
+        const next = normalizeBindingTokens(value, variables, functions);
+        return {
+            value: next,
+            changed: next !== value
+        };
+    }
+    if (Array.isArray(value)) {
+        let changed = false;
+        const next = value.map((item)=>{
+            const result = rewriteBindingTokensDeep(item, variables, functions);
+            changed = changed || result.changed;
+            return result.value;
+        });
+        return {
+            value: changed ? next : value,
+            changed
+        };
+    }
+    if (value && typeof value === 'object') {
+        let changed = false;
+        const next = {};
+        for (const [key, item] of Object.entries(value)){
+            const result = rewriteBindingTokensDeep(item, variables, functions);
+            changed = changed || result.changed;
+            next[key] = result.value;
+        }
+        return {
+            value: changed ? next : value,
+            changed
+        };
+    }
+    return {
+        value,
+        changed: false
+    };
+}
+export function bindingTokenNeedsDeep(value) {
+    const needs = {
+        variables: false,
+        functions: false
+    };
+    /*
+    Fresh, NON-GLOBAL copies. The exported patterns carry the `g` flag, and a
+    global regex's `.test()` advances its own `lastIndex` — so testing the
+    same shared object twice in a walk skips matches, and does it in a way
+    that depends on the order the tree happened to be visited in.
+  */ const nameToken = new RegExp(NAME_TOKEN_PATTERN.source);
+    const functionToken = new RegExp(FUNCTION_TOKEN_PATTERN.source);
+    const walk = (current)=>{
+        if (needs.variables && needs.functions) return;
+        if (typeof current === 'string') {
+            if (!current.includes('{{')) return;
+            if (!needs.variables && nameToken.test(current)) needs.variables = true;
+            if (!needs.functions && functionToken.test(current)) {
+                needs.functions = true;
+            }
+            return;
+        }
+        if (Array.isArray(current)) {
+            for (const item of current)walk(item);
+            return;
+        }
+        if (current && typeof current === 'object') {
+            for (const item of Object.values(current))walk(item);
+        }
+    };
+    walk(value);
+    return needs;
+}
+/** Editor display text for a token whose referent no longer exists. */ export const MISSING_BINDING_LABEL = 'missing binding';
+/**
+ * Rewrites id tokens to friendly name forms for editor display (AGL-186):
+ * `{{var:abc123}}` shows as `{{Message}}` (the CURRENT name — renames
+ * reflect immediately), and tokens whose doc was deleted show as
+ * `{{missing binding}}` instead of leaking raw ids. Display only — never
+ * persist the result.
+ */ export function displayBindingTokens(text, variables = {}, functions = {}) {
+    const withVariables = text.replace(VARIABLE_ID_TOKEN_PATTERN, (_token, id)=>{
+        var _ref;
+        const variable = variables[String(id)];
+        return `{{${(_ref = variable == null ? void 0 : variable.name) != null ? _ref : MISSING_BINDING_LABEL}}}`;
+    });
+    return withVariables.replace(FUNCTION_TOKEN_PATTERN, (token, ref, rawArgs)=>{
+        var _definition_name;
+        const definition = functions[String(ref).trim()];
+        // Name-form refs already read fine; only id-form refs get mapped.
+        if (!definition || definition.name === String(ref).trim()) return token;
+        return `{{fn:${(_definition_name = definition.name) != null ? _definition_name : MISSING_BINDING_LABEL}(${String(rawArgs)})}}`;
+    });
+}
+
+//# sourceMappingURL=binding-tokens.js.map

package/src/lib/app-utils/binding-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/binding-tokens.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 * Binding token grammar (AGL-185) — the single source of truth for what a\n * binding token looks like, shared by the besigner editor, the console\n * binding picker, and the tenant renderer.\n *\n * Two generations coexist:\n * - id tokens: `{{var:variableId}}` and `{{fn:functionId(args)}}` — the\n *   reference survives renames because only the display name changes.\n * - legacy name tokens: `{{name}}` and `{{fn:name(args)}}` — resolved as a\n *   fallback until AGL-188 migrates stored content.\n *\n * Resolution maps are id-keyed (AGL-194); the editor keeps name-capable\n * lookups only for typed-name normalization and friendly display.\n */\n\n/** Firestore doc ids and legacy binding names both fit this shape. */\nconst REF = '[a-zA-Z0-9_-]{1,64}'\n\n/** `{{var:variableId}}` — capture group 1 is the variable's doc id. */\nexport const VARIABLE_ID_TOKEN_PATTERN = new RegExp(\n  `\\\\{\\\\{\\\\s*var:(${REF})\\\\s*\\\\}\\\\}`,\n  'g',\n)\n\n/**\n * `{{fn:ref(args)}}` — capture 1 is a function doc id OR legacy name,\n * capture 2 the raw argument list. One pattern serves both generations;\n * lookup order (id first, then name) decides what the ref means.\n */\nexport const FUNCTION_TOKEN_PATTERN = new RegExp(\n  `\\\\{\\\\{\\\\s*fn:(${REF}(?: ${REF})*)\\\\s*\\\\(([^)]*)\\\\)\\\\s*\\\\}\\\\}`,\n  'g',\n)\n\n/** Legacy `{{name}}` — names never contain `:`, so `var:`/`fn:` can't match. */\nexport const NAME_TOKEN_PATTERN = /\\{\\{\\s*([a-zA-Z_][a-zA-Z0-9_]{0,39})\\s*\\}\\}/g\n\n/** Renders the id-form variable token the picker inserts (AGL-186). */\nexport function formatVariableIdToken(variableId: string): string {\n  return `{{var:${variableId}}}`\n}\n\n/** Renders the id-form function token with its parameter placeholders. */\nexport function formatFunctionIdToken(\n  functionId: string,\n  parameterNames: string[] = [],\n): string {\n  return `{{fn:${functionId}(${parameterNames.join(', ')})}}`\n}\n\n/**\n * Keys resource docs by doc id — the only key resolution uses since the\n * legacy name fallback retired (AGL-194). Editor-side lookups that need\n * name access (typed-name normalization, friendly display) read the\n * `name` field off the values instead of relying on map keys.\n */\nexport function keyById<T extends { name?: string }>(\n  docs: Array<T & { id: string }>,\n): Record<string, T> {\n  const map: Record<string, T> = {}\n  for (const { id, ...doc } of docs) {\n    map[id] = doc as unknown as T\n  }\n  return map\n}\n\n/**\n * Doc shape the editor-side helpers need: consoles pass Firestore docs\n * that carry their id as `$id` (reactfire idField) beside the name.\n */\nexport interface BindingDocRef {\n  name?: string\n  $id?: string\n  parameters?: Array<{ name: string }>\n}\n\n/**\n * Rewrites legacy name tokens to their id forms when the name matches a\n * known doc (AGL-186 typing normalization): hand-typed `{{Message}}`\n * becomes `{{var:abc123}}` at save so it survives renames. Unknown names\n * are left alone — the variable may be created later, and legacy\n * resolution still covers them meanwhile.\n */\nexport function normalizeBindingTokens(\n  text: string,\n  variables: Record<string, BindingDocRef> = {},\n  functions: Record<string, BindingDocRef> = {},\n): string {\n  const withFunctions = text.replace(\n    FUNCTION_TOKEN_PATTERN,\n    (token, ref, rawArgs) => {\n      const definition = functions[String(ref).trim()]\n      // Already an id (the ref maps to a doc whose $id is the ref itself)\n      // or unknown: leave as-is.\n      if (!definition?.$id || definition.$id === String(ref).trim()) {\n        return token\n      }\n      return `{{fn:${definition.$id}(${String(rawArgs)})}}`\n    },\n  )\n  return withFunctions.replace(NAME_TOKEN_PATTERN, (token, name) => {\n    const variable = variables[name]\n    return variable?.$id ? formatVariableIdToken(variable.$id) : token\n  })\n}\n\n/** A whole `{{name}}` token, for asking whether a name can be typed as one. */\nconst TYPED_NAME_TOKEN = new RegExp(`^${NAME_TOKEN_PATTERN.source}$`)\n\n/**\n * Rewrites id-form variable tokens to the `{{name}}` an author types — the\n * inverse of {@link normalizeBindingTokens}, for an editor that shows stored\n * copy in a plain text field and normalizes it again when it saves.\n *\n * Unlike {@link displayBindingTokens}, whose result must never be persisted,\n * this one survives the round trip: normalizing its output restores the\n * input. So a token is rewritten only when that holds — its variable exists,\n * its name is one a typed token can carry, and looking that name up leads back\n * to this id and no other. Every other token keeps its id form. That includes\n * a deleted variable's token, which renders as nothing on a published page,\n * where `{{missing binding}}` would render as typed.\n *\n * @param variables - the lookup `normalizeBindingTokens` takes: the site's\n *   variables keyed by name, each carrying its document id as `$id`.\n */\nexport function editableBindingTokens(\n  text: string,\n  variables: Record<string, BindingDocRef> = {},\n): string {\n  if (!text.includes('{{')) return text\n  return text.replace(VARIABLE_ID_TOKEN_PATTERN, (token, rawId) => {\n    const id = String(rawId)\n    const name = Object.values(variables).find(\n      (variable) => variable?.$id === id,\n    )?.name\n    if (!name || variables[name]?.$id !== id) return token\n    const typed = `{{${name}}}`\n    return TYPED_NAME_TOKEN.test(typed) ? typed : token\n  })\n}\n\n/** A variable/function referent to search for in stored content. */\nexport interface BindingRef {\n  kind: 'variable' | 'function'\n  /** Firestore doc id — matches id-form tokens. */\n  id?: string\n  /** Current name — matches legacy name-form tokens. */\n  name?: string\n}\n\n/** How a dependent references the binding: rename-safe id or legacy name. */\nexport type BindingRefVia = 'id' | 'name'\n\nconst escapeRegExp = (value: string) =>\n  value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n\n/**\n * Which token generation(s) in `text` reference the given binding\n * (AGL-187 where-used). Returns matches so callers can distinguish\n * rename-safe id references from legacy name references — a rename only\n * endangers the latter.\n */\nexport function textReferencesBinding(\n  text: string,\n  ref: BindingRef,\n): BindingRefVia[] {\n  const via: BindingRefVia[] = []\n  if (ref.kind === 'variable') {\n    if (\n      ref.id &&\n      new RegExp(`\\\\{\\\\{\\\\s*var:${escapeRegExp(ref.id)}\\\\s*\\\\}\\\\}`).test(text)\n    ) {\n      via.push('id')\n    }\n    if (\n      ref.name &&\n      new RegExp(`\\\\{\\\\{\\\\s*${escapeRegExp(ref.name)}\\\\s*\\\\}\\\\}`).test(text)\n    ) {\n      via.push('name')\n    }\n  } else {\n    if (\n      ref.id &&\n      new RegExp(`\\\\{\\\\{\\\\s*fn:${escapeRegExp(ref.id)}\\\\s*\\\\(`).test(text)\n    ) {\n      via.push('id')\n    }\n    if (\n      ref.name &&\n      new RegExp(`\\\\{\\\\{\\\\s*fn:${escapeRegExp(ref.name)}\\\\s*\\\\(`).test(text)\n    ) {\n      via.push('name')\n    }\n  }\n  return via\n}\n\n/**\n * Scans a normalized nodes map's string props for references to the\n * binding; returns the union of match kinds across all nodes.\n */\nexport function nodesReferenceBinding(\n  nodes: Record<string, { props?: Record<string, unknown> } | undefined>,\n  ref: BindingRef,\n): BindingRefVia[] {\n  const via = new Set<BindingRefVia>()\n  for (const node of Object.values(nodes ?? {})) {\n    for (const value of Object.values(node?.props ?? {})) {\n      if (typeof value !== 'string' || !value.includes('{{')) continue\n      for (const match of textReferencesBinding(value, ref)) via.add(match)\n    }\n    if (via.size === 2) break\n  }\n  return [...via]\n}\n\n/**\n * Deep-walks a JSON-ish value, applying `normalizeBindingTokens` to every\n * string containing a token opener (AGL-188 migration / host import).\n * Arrays and plain objects recurse; other values pass through untouched.\n * Returns the (possibly new) value and whether anything changed.\n */\nexport function rewriteBindingTokensDeep<T>(\n  value: T,\n  variables: Record<string, BindingDocRef> = {},\n  functions: Record<string, BindingDocRef> = {},\n): { value: T; changed: boolean } {\n  if (typeof value === 'string') {\n    if (!value.includes('{{')) return { value, changed: false }\n    const next = normalizeBindingTokens(value, variables, functions)\n    return { value: next as T, changed: next !== value }\n  }\n  if (Array.isArray(value)) {\n    let changed = false\n    const next = value.map((item) => {\n      const result = rewriteBindingTokensDeep(item, variables, functions)\n      changed = changed || result.changed\n      return result.value\n    })\n    return { value: (changed ? next : value) as T, changed }\n  }\n  if (value && typeof value === 'object') {\n    let changed = false\n    const next: Record<string, unknown> = {}\n    for (const [key, item] of Object.entries(value)) {\n      const result = rewriteBindingTokensDeep(item, variables, functions)\n      changed = changed || result.changed\n      next[key] = result.value\n    }\n    return { value: (changed ? next : value) as T, changed }\n  }\n  return { value, changed: false }\n}\n\n/**\n * Which binding lookups a value's tokens would actually need (AGL-703).\n *\n * A read-only twin of {@link rewriteBindingTokensDeep}, and it exists for\n * cost. Publish-time normalization used to fetch EVERY variable and EVERY\n * function on the site — two `limit(1000)` gets — before looking at whether\n * the version being published contained a single token to rewrite. Almost\n * none do: AGL-188 migrated the corpus years ago and the picker has written\n * id-form tokens ever since, so the overwhelming majority of publishes paid\n * for two collection reads to discover there was nothing to do.\n *\n * The two flags are separate because the two rewrites are:\n *\n * - a legacy `{{name}}` token is resolved against VARIABLES and nothing else\n *   — {@link normalizeBindingTokens} only consults `variables` for it;\n * - a `{{fn:ref(...)}}` token is resolved against FUNCTIONS.\n *\n * So a page holding only function tokens never reads the variables.\n *\n * `{{var:id}}` deliberately sets NEITHER. It is already the rename-safe form,\n * nothing rewrites it, and it cannot match `NAME_TOKEN_PATTERN` because a\n * name may not contain `:`. A page whose tokens are all id-form — which is\n * what a page authored through the picker looks like — costs nothing.\n *\n * A `{{fn:}}` token sets `functions` even when its ref is ALREADY an id,\n * because telling an id from a legacy name is exactly what the lookup is for.\n * Erring that way costs one read on a page that has function tokens; erring\n * the other way would skip a rewrite that was due.\n */\nexport interface BindingTokenNeeds {\n  /** A legacy `{{name}}` token is present — needs the variables lookup. */\n  variables: boolean\n  /** A `{{fn:…}}` token is present — needs the functions lookup. */\n  functions: boolean\n}\n\nexport function bindingTokenNeedsDeep(value: unknown): BindingTokenNeeds {\n  const needs: BindingTokenNeeds = { variables: false, functions: false }\n  /*\n    Fresh, NON-GLOBAL copies. The exported patterns carry the `g` flag, and a\n    global regex's `.test()` advances its own `lastIndex` — so testing the\n    same shared object twice in a walk skips matches, and does it in a way\n    that depends on the order the tree happened to be visited in.\n  */\n  const nameToken = new RegExp(NAME_TOKEN_PATTERN.source)\n  const functionToken = new RegExp(FUNCTION_TOKEN_PATTERN.source)\n\n  const walk = (current: unknown): void => {\n    if (needs.variables && needs.functions) return\n    if (typeof current === 'string') {\n      if (!current.includes('{{')) return\n      if (!needs.variables && nameToken.test(current)) needs.variables = true\n      if (!needs.functions && functionToken.test(current)) {\n        needs.functions = true\n      }\n      return\n    }\n    if (Array.isArray(current)) {\n      for (const item of current) walk(item)\n      return\n    }\n    if (current && typeof current === 'object') {\n      for (const item of Object.values(current)) walk(item)\n    }\n  }\n  walk(value)\n  return needs\n}\n\n/** Editor display text for a token whose referent no longer exists. */\nexport const MISSING_BINDING_LABEL = 'missing binding'\n\n/**\n * Rewrites id tokens to friendly name forms for editor display (AGL-186):\n * `{{var:abc123}}` shows as `{{Message}}` (the CURRENT name — renames\n * reflect immediately), and tokens whose doc was deleted show as\n * `{{missing binding}}` instead of leaking raw ids. Display only — never\n * persist the result.\n */\nexport function displayBindingTokens(\n  text: string,\n  variables: Record<string, BindingDocRef> = {},\n  functions: Record<string, BindingDocRef> = {},\n): string {\n  const withVariables = text.replace(\n    VARIABLE_ID_TOKEN_PATTERN,\n    (_token, id) => {\n      const variable = variables[String(id)]\n      return `{{${variable?.name ?? MISSING_BINDING_LABEL}}}`\n    },\n  )\n  return withVariables.replace(\n    FUNCTION_TOKEN_PATTERN,\n    (token, ref, rawArgs) => {\n      const definition = functions[String(ref).trim()]\n      // Name-form refs already read fine; only id-form refs get mapped.\n      if (!definition || definition.name === String(ref).trim()) return token\n      return `{{fn:${definition.name ?? MISSING_BINDING_LABEL}(${String(rawArgs)})}}`\n    },\n  )\n}\n"],"names":["REF","VARIABLE_ID_TOKEN_PATTERN","RegExp","FUNCTION_TOKEN_PATTERN","NAME_TOKEN_PATTERN","formatVariableIdToken","variableId","formatFunctionIdToken","functionId","parameterNames","join","keyById","docs","map","id","doc","normalizeBindingTokens","text","variables","functions","withFunctions","replace","token","ref","rawArgs","definition","String","trim","$id","name","variable","TYPED_NAME_TOKEN","source","editableBindingTokens","includes","rawId","Object","values","find","typed","test","escapeRegExp","value","textReferencesBinding","via","kind","push","nodesReferenceBinding","nodes","Set","node","props","match","add","size","rewriteBindingTokensDeep","changed","next","Array","isArray","item","result","key","entries","bindingTokenNeedsDeep","needs","nameToken","functionToken","walk","current","MISSING_BINDING_LABEL","displayBindingTokens","withVariables","_token"],"mappings":"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"}

package/src/lib/app-utils/breadcrumb-json-ld.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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.
+ */
+/** One step on the trail: what it is called, and where it goes. */
+export interface BreadcrumbCrumb {
+    /** The DISPLAY name — a collection's title, an entry's headline. */
+    name: string;
+    /** Site-relative path, e.g. `/blog` or `/blog/hello`. */
+    path: string;
+}
+/**
+ * `schema.org/BreadcrumbList` for a trail of crumbs (AGL-2535).
+ *
+ * ## Why content routes needed their own
+ *
+ * The tenant already emitted a breadcrumb, for nested SCREEN paths only, built
+ * by splitting the routing-map path — so its crumb names are URL segments
+ * (`/company/about` publishes "company" and "about"). That is passable for a
+ * screen, whose slug is usually its title in lower case, and it is the wrong
+ * mechanism entirely for content: `/blog/from-a-form-to-a-dataset-in-five-minutes`
+ * would publish that slug as a crumb name when the entry's actual headline is
+ * sitting right there in the loader's result.
+ *
+ * So this takes NAMES rather than a path, and the caller supplies them from
+ * whatever it knows — a collection's `displayName`, an entry's `title`, a
+ * category's resolved label.
+ *
+ * ## Fewer than two crumbs emits nothing
+ *
+ * A one-item breadcrumb is not a trail, it is the page restating its own
+ * title, and Google's own guidance treats a single-element list as ineligible.
+ * Returning `undefined` lets a caller spread the result unconditionally
+ * instead of counting first — the same shape every other serializer in this
+ * codebase uses.
+ *
+ * ## Absolute urls, because a crawler reads this without a page
+ *
+ * `item` must resolve on its own. With no origin to resolve against, this
+ * emits nothing rather than a list of relative paths a consumer would silently
+ * ignore — the rule `contentAuthorJsonLd` states about images, applied to
+ * links.
+ */
+export declare function breadcrumbListJsonLd(crumbs: readonly BreadcrumbCrumb[] | null | undefined, origin: string | null | undefined): Record<string, unknown> | undefined;
+export default breadcrumbListJsonLd;

package/src/lib/app-utils/breadcrumb-json-ld.js

@@ -0,0 +1,67 @@
+/**
+ * @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.
+ */ /** One step on the trail: what it is called, and where it goes. */ /**
+ * `schema.org/BreadcrumbList` for a trail of crumbs (AGL-2535).
+ *
+ * ## Why content routes needed their own
+ *
+ * The tenant already emitted a breadcrumb, for nested SCREEN paths only, built
+ * by splitting the routing-map path — so its crumb names are URL segments
+ * (`/company/about` publishes "company" and "about"). That is passable for a
+ * screen, whose slug is usually its title in lower case, and it is the wrong
+ * mechanism entirely for content: `/blog/from-a-form-to-a-dataset-in-five-minutes`
+ * would publish that slug as a crumb name when the entry's actual headline is
+ * sitting right there in the loader's result.
+ *
+ * So this takes NAMES rather than a path, and the caller supplies them from
+ * whatever it knows — a collection's `displayName`, an entry's `title`, a
+ * category's resolved label.
+ *
+ * ## Fewer than two crumbs emits nothing
+ *
+ * A one-item breadcrumb is not a trail, it is the page restating its own
+ * title, and Google's own guidance treats a single-element list as ineligible.
+ * Returning `undefined` lets a caller spread the result unconditionally
+ * instead of counting first — the same shape every other serializer in this
+ * codebase uses.
+ *
+ * ## Absolute urls, because a crawler reads this without a page
+ *
+ * `item` must resolve on its own. With no origin to resolve against, this
+ * emits nothing rather than a list of relative paths a consumer would silently
+ * ignore — the rule `contentAuthorJsonLd` states about images, applied to
+ * links.
+ */ export function breadcrumbListJsonLd(crumbs, origin) {
+    const base = String(origin != null ? origin : '').trim().replace(/\/+$/, '');
+    if (!base) return undefined;
+    const usable = (crumbs != null ? crumbs : []).filter((crumb)=>{
+        var _ref, _ref1;
+        return String((_ref = crumb == null ? void 0 : crumb.name) != null ? _ref : '').trim() && String((_ref1 = crumb == null ? void 0 : crumb.path) != null ? _ref1 : '').trim();
+    });
+    if (usable.length < 2) return undefined;
+    return {
+        '@type': 'BreadcrumbList',
+        itemListElement: usable.map((crumb, index)=>({
+                '@type': 'ListItem',
+                position: index + 1,
+                name: String(crumb.name).trim(),
+                item: `${base}/${String(crumb.path).trim().replace(/^\/+/, '')}`
+            }))
+    };
+}
+export default breadcrumbListJsonLd;
+
+//# sourceMappingURL=breadcrumb-json-ld.js.map

package/src/lib/app-utils/breadcrumb-json-ld.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/breadcrumb-json-ld.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/** One step on the trail: what it is called, and where it goes. */\nexport interface BreadcrumbCrumb {\n  /** The DISPLAY name — a collection's title, an entry's headline. */\n  name: string\n  /** Site-relative path, e.g. `/blog` or `/blog/hello`. */\n  path: string\n}\n\n/**\n * `schema.org/BreadcrumbList` for a trail of crumbs (AGL-2535).\n *\n * ## Why content routes needed their own\n *\n * The tenant already emitted a breadcrumb, for nested SCREEN paths only, built\n * by splitting the routing-map path — so its crumb names are URL segments\n * (`/company/about` publishes \"company\" and \"about\"). That is passable for a\n * screen, whose slug is usually its title in lower case, and it is the wrong\n * mechanism entirely for content: `/blog/from-a-form-to-a-dataset-in-five-minutes`\n * would publish that slug as a crumb name when the entry's actual headline is\n * sitting right there in the loader's result.\n *\n * So this takes NAMES rather than a path, and the caller supplies them from\n * whatever it knows — a collection's `displayName`, an entry's `title`, a\n * category's resolved label.\n *\n * ## Fewer than two crumbs emits nothing\n *\n * A one-item breadcrumb is not a trail, it is the page restating its own\n * title, and Google's own guidance treats a single-element list as ineligible.\n * Returning `undefined` lets a caller spread the result unconditionally\n * instead of counting first — the same shape every other serializer in this\n * codebase uses.\n *\n * ## Absolute urls, because a crawler reads this without a page\n *\n * `item` must resolve on its own. With no origin to resolve against, this\n * emits nothing rather than a list of relative paths a consumer would silently\n * ignore — the rule `contentAuthorJsonLd` states about images, applied to\n * links.\n */\nexport function breadcrumbListJsonLd(\n  crumbs: readonly BreadcrumbCrumb[] | null | undefined,\n  origin: string | null | undefined,\n): Record<string, unknown> | undefined {\n  const base = String(origin ?? '').trim().replace(/\\/+$/, '')\n  if (!base) return undefined\n  const usable = (crumbs ?? []).filter(\n    (crumb) => String(crumb?.name ?? '').trim() && String(crumb?.path ?? '').trim(),\n  )\n  if (usable.length < 2) return undefined\n  return {\n    '@type': 'BreadcrumbList',\n    itemListElement: usable.map((crumb, index) => ({\n      '@type': 'ListItem',\n      position: index + 1,\n      name: String(crumb.name).trim(),\n      item: `${base}/${String(crumb.path).trim().replace(/^\\/+/, '')}`,\n    })),\n  }\n}\n\nexport default breadcrumbListJsonLd\n"],"names":["breadcrumbListJsonLd","crumbs","origin","base","String","trim","replace","undefined","usable","filter","crumb","name","path","length","itemListElement","map","index","position","item"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,iEAAiE,GAQjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BC,GACD,OAAO,SAASA,qBACdC,MAAqD,EACrDC,MAAiC;IAEjC,MAAMC,OAAOC,OAAOF,iBAAAA,SAAU,IAAIG,IAAI,GAAGC,OAAO,CAAC,QAAQ;IACzD,IAAI,CAACH,MAAM,OAAOI;IAClB,MAAMC,SAAS,CAACP,iBAAAA,SAAU,EAAE,EAAEQ,MAAM,CAClC,CAACC;;eAAUN,eAAOM,yBAAAA,MAAOC,IAAI,mBAAI,IAAIN,IAAI,MAAMD,gBAAOM,yBAAAA,MAAOE,IAAI,oBAAI,IAAIP,IAAI;;IAE/E,IAAIG,OAAOK,MAAM,GAAG,GAAG,OAAON;IAC9B,OAAO;QACL,SAAS;QACTO,iBAAiBN,OAAOO,GAAG,CAAC,CAACL,OAAOM,QAAW,CAAA;gBAC7C,SAAS;gBACTC,UAAUD,QAAQ;gBAClBL,MAAMP,OAAOM,MAAMC,IAAI,EAAEN,IAAI;gBAC7Ba,MAAM,GAAGf,KAAK,CAAC,EAAEC,OAAOM,MAAME,IAAI,EAAEP,IAAI,GAAGC,OAAO,CAAC,QAAQ,KAAK;YAClE,CAAA;IACF;AACF;AAEA,eAAeN,qBAAoB"}