@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

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

@@ -1 +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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"}
+{"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/brand-support-line.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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 type { ResolvedBrandingProfile } from './platform-brand';
+/**
+ * The "Need help?" footer of a built-in transactional email — **or nothing**
+ * (AGL-2428).
+ *
+ * A white-label organization that left its Support URL blank resolves
+ * `supportUrl` to null, and this returns the empty string rather than a line
+ * pointing at Aglyn. The recipient of that mail is the organization's own
+ * customer: our desk cannot help them, and the link would name their vendor
+ * to somebody who was never told one exists.
+ *
+ * It returns the SEPARATOR too, not just the sentence. A caller that
+ * concatenated `\n\n` itself would leave two blank lines at the end of the
+ * message for exactly the orgs this exists for — the "gap where something
+ * should be" that `emailLogoUrl` already avoids one field over.
+ *
+ * Every org WITHOUT the concealment entitlement resolves to the platform
+ * profile, whose support URL is real, so those emails are unchanged.
+ */
+export declare function brandSupportLine(branding: Pick<ResolvedBrandingProfile, 'supportUrl'>): string;

package/src/lib/app-utils/brand-support-line.js

@@ -0,0 +1,38 @@
+/**
+ * @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 "Need help?" footer of a built-in transactional email — **or nothing**
+ * (AGL-2428).
+ *
+ * A white-label organization that left its Support URL blank resolves
+ * `supportUrl` to null, and this returns the empty string rather than a line
+ * pointing at Aglyn. The recipient of that mail is the organization's own
+ * customer: our desk cannot help them, and the link would name their vendor
+ * to somebody who was never told one exists.
+ *
+ * It returns the SEPARATOR too, not just the sentence. A caller that
+ * concatenated `\n\n` itself would leave two blank lines at the end of the
+ * message for exactly the orgs this exists for — the "gap where something
+ * should be" that `emailLogoUrl` already avoids one field over.
+ *
+ * Every org WITHOUT the concealment entitlement resolves to the platform
+ * profile, whose support URL is real, so those emails are unchanged.
+ */ export function brandSupportLine(branding) {
+    const url = typeof branding.supportUrl === 'string' ? branding.supportUrl.trim() : '';
+    return url ? `\n\nNeed help? ${url}` : '';
+}
+
+//# sourceMappingURL=brand-support-line.js.map

package/src/lib/app-utils/brand-support-line.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/brand-support-line.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 type { ResolvedBrandingProfile } from './platform-brand'\n\n/**\n * The \"Need help?\" footer of a built-in transactional email — **or nothing**\n * (AGL-2428).\n *\n * A white-label organization that left its Support URL blank resolves\n * `supportUrl` to null, and this returns the empty string rather than a line\n * pointing at Aglyn. The recipient of that mail is the organization's own\n * customer: our desk cannot help them, and the link would name their vendor\n * to somebody who was never told one exists.\n *\n * It returns the SEPARATOR too, not just the sentence. A caller that\n * concatenated `\\n\\n` itself would leave two blank lines at the end of the\n * message for exactly the orgs this exists for — the \"gap where something\n * should be\" that `emailLogoUrl` already avoids one field over.\n *\n * Every org WITHOUT the concealment entitlement resolves to the platform\n * profile, whose support URL is real, so those emails are unchanged.\n */\nexport function brandSupportLine(\n  branding: Pick<ResolvedBrandingProfile, 'supportUrl'>,\n): string {\n  const url = typeof branding.supportUrl === 'string' ? branding.supportUrl.trim() : ''\n  return url ? `\\n\\nNeed help? ${url}` : ''\n}\n"],"names":["brandSupportLine","branding","url","supportUrl","trim"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASA,iBACdC,QAAqD;IAErD,MAAMC,MAAM,OAAOD,SAASE,UAAU,KAAK,WAAWF,SAASE,UAAU,CAACC,IAAI,KAAK;IACnF,OAAOF,MAAM,CAAC,eAAe,EAAEA,KAAK,GAAG;AACzC"}

package/src/lib/app-utils/campaign-touch.d.ts

@@ -42,7 +42,7 @@
  *
  * `localStorage`, expiring at {@link ATTRIBUTION_WINDOW_DAYS}.
  *
- * `campaign-forwarding.ts` holds its own campaign in `sessionStorage` and
+ * `utm-forwarding.ts` holds its own campaign in `sessionStorage` and
  * argues for it: a first touch that outlived the visit would start
  * attributing next week's organic return to this week's ad. That argument is
  * correct for the question it answers — which campaign produced THIS SIGNUP,
@@ -64,7 +64,7 @@
  * The revenue join credits the LAST click, and a product where a lead and an
  * order attribute by different rules is worse than one that is uniformly
  * approximate. So a new campaign arrival OVERWRITES the stored one. This is
- * the deliberate opposite of {@link rememberVisitCampaign}, which keeps the
+ * the deliberate opposite of {@link rememberVisitUtm}, which keeps the
  * first — that one describes a single visit's origin and this one describes
  * which campaign most recently brought a person back.
  *
@@ -104,7 +104,7 @@
  * ## What is never carried
  *
  * Only the three allowlisted `utm_` labels, scrubbed by
- * {@link parseCampaignAttribution} — which refuses an email-shaped value
+ * {@link parseUtmAttribution} — which refuses an email-shaped value
  * outright. No address, no person's identifier, no click id, nothing that
  * names the visitor. A campaign link is exactly where putting a recipient in
  * a query string would be tempting, and the parser is what makes it
@@ -120,7 +120,7 @@
  * are the WEB channel's touch, and a campaign that carries none is joined by
  * address instead.
  */
-import { type CampaignAttribution } from './campaign-attribution';
+import { type UtmAttribution } from './utm-attribution';
 /** Days between a campaign touch and a conversion it may be credited with. */
 export declare const ATTRIBUTION_WINDOW_DAYS = 7;
 /** The same window in milliseconds. */
@@ -137,7 +137,7 @@ export declare const CAMPAIGN_TOUCH_STORAGE_KEY = "aglyn:campaign-touch";
  */
 export declare const CAMPAIGN_TOUCH_TIME_KEY = "t";
 /** A campaign the visitor arrived from, and when they arrived from it. */
-export interface CampaignTouch extends CampaignAttribution {
+export interface CampaignTouch extends UtmAttribution {
     /** When the visitor followed the campaign link, epoch ms. */
     atMs: number;
 }

package/src/lib/app-utils/campaign-touch.js

@@ -42,7 +42,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  *
  * `localStorage`, expiring at {@link ATTRIBUTION_WINDOW_DAYS}.
  *
- * `campaign-forwarding.ts` holds its own campaign in `sessionStorage` and
+ * `utm-forwarding.ts` holds its own campaign in `sessionStorage` and
  * argues for it: a first touch that outlived the visit would start
  * attributing next week's organic return to this week's ad. That argument is
  * correct for the question it answers — which campaign produced THIS SIGNUP,
@@ -64,7 +64,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * The revenue join credits the LAST click, and a product where a lead and an
  * order attribute by different rules is worse than one that is uniformly
  * approximate. So a new campaign arrival OVERWRITES the stored one. This is
- * the deliberate opposite of {@link rememberVisitCampaign}, which keeps the
+ * the deliberate opposite of {@link rememberVisitUtm}, which keeps the
  * first — that one describes a single visit's origin and this one describes
  * which campaign most recently brought a person back.
  *
@@ -104,7 +104,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * ## What is never carried
  *
  * Only the three allowlisted `utm_` labels, scrubbed by
- * {@link parseCampaignAttribution} — which refuses an email-shaped value
+ * {@link parseUtmAttribution} — which refuses an email-shaped value
  * outright. No address, no person's identifier, no click id, nothing that
  * names the visitor. A campaign link is exactly where putting a recipient in
  * a query string would be tempting, and the parser is what makes it
@@ -119,7 +119,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * recorded server-side against the recipient's address hash. The labels below
  * are the WEB channel's touch, and a campaign that carries none is joined by
  * address instead.
- */ import { campaignAttributionQuery, parseCampaignAttribution } from "./campaign-attribution.js";
+ */ import { utmAttributionQuery, parseUtmAttribution } from "./utm-attribution.js";
 /*==========================================
  * THE WINDOW, AND WHY THIS IS THE SECOND COPY OF A NUMBER.
  *
@@ -183,7 +183,7 @@ function localStore() {
  * cannot drift from what {@link parseCampaignTouch} reads back.
  */ export function campaignTouchWire(touch) {
     if (!touch) return '';
-    const labels = campaignAttributionQuery(touch);
+    const labels = utmAttributionQuery(touch);
     if (!labels) return '';
     const atMs = Math.round(Number(touch.atMs));
     if (!Number.isFinite(atMs) || atMs <= 0) return '';
@@ -205,7 +205,7 @@ function localStore() {
     } catch (unused) {
         return null;
     }
-    const campaign = parseCampaignAttribution(params);
+    const campaign = parseUtmAttribution(params);
     if (!campaign) return null;
     const atMs = Number(params.get(CAMPAIGN_TOUCH_TIME_KEY));
     if (!touchIsInWindow(atMs, nowMs)) return null;
@@ -249,7 +249,7 @@ function localStore() {
     const store = localStore();
     if (!store) return null;
     const source = typeof search === 'string' ? search : typeof window === 'undefined' ? '' : window.location.search;
-    const campaign = parseCampaignAttribution(new URLSearchParams(source));
+    const campaign = parseUtmAttribution(new URLSearchParams(source));
     if (!campaign) return null;
     const touch = _extends({}, campaign, {
         atMs: nowMs
@@ -282,7 +282,7 @@ function localStore() {
  * device would be keeping a record of where somebody came from for no purpose
  * anything reads. The read that finds it removes it.
  */ export function readCampaignTouch(nowMs = Date.now()) {
-    const live = typeof window === 'undefined' ? null : parseCampaignAttribution(new URLSearchParams(window.location.search));
+    const live = typeof window === 'undefined' ? null : parseUtmAttribution(new URLSearchParams(window.location.search));
     if (live) return _extends({}, live, {
         atMs: nowMs
     });

package/src/lib/app-utils/campaign-touch.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-touch.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 VISITOR'S HALF OF CAMPAIGN ATTRIBUTION — the touch that has to survive\n * the gap between arriving from a campaign and becoming somebody.\n *\n * ## The gap this exists to cross\n *\n * A known recipient can be joined on their address: they clicked a campaign's\n * mail, the delivery webhook stamped the click on their person document, and\n * `email-revenue-attribution.ts` reads it back when their order settles. An\n * ANONYMOUS visitor has no such handle. They arrive from an ad, a partner\n * link or a social post, browse for a while, and only become identifiable at\n * the moment they submit a form, sign up, book or check out. Between the\n * arrival and that moment there is nothing on the server that connects them.\n *\n * The site's own collector already reads `utm_source`/`utm_medium`/\n * `utm_campaign` off the landing URL and increments a per-day label counter\n * with them. That answers \"how many views did this campaign send us\" and\n * stops there — the labels are never carried to the moment the visitor says\n * who they are, so every form, lead, contact and booking a campaign caused is\n * recorded as though nobody caused it.\n *\n * This carries them. The touch is held on the VISITOR, and every identify\n * moment attaches it.\n *\n * ## What holds it, and why it outlives the tab\n *\n * `localStorage`, expiring at {@link ATTRIBUTION_WINDOW_DAYS}.\n *\n * `campaign-forwarding.ts` holds its own campaign in `sessionStorage` and\n * argues for it: a first touch that outlived the visit would start\n * attributing next week's organic return to this week's ad. That argument is\n * correct for the question it answers — which campaign produced THIS SIGNUP,\n * asked of one uninterrupted visit to the marketing site — and it is the\n * wrong shape here, because this question already has a stated answer to\n * \"how long may a touch be credited\": the attribution window, seven days,\n * stamped onto every record so the rule is readable off the data.\n *\n * A store that dies with the tab cannot express a seven-day window. It would\n * credit only the visitors who convert without ever closing the tab and\n * silently record every other conversion as organic — a measured zero, which\n * is the failure mode this whole area exists to end. So the touch lives as\n * long as the window says it may and not one millisecond longer: an expired\n * entry is DELETED on the read that finds it, rather than ignored, so a\n * device never holds a campaign it can no longer be credited with.\n *\n * ## Last touch, not first\n *\n * The revenue join credits the LAST click, and a product where a lead and an\n * order attribute by different rules is worse than one that is uniformly\n * approximate. So a new campaign arrival OVERWRITES the stored one. This is\n * the deliberate opposite of {@link rememberVisitCampaign}, which keeps the\n * first — that one describes a single visit's origin and this one describes\n * which campaign most recently brought a person back.\n *\n * ## Consent\n *\n * Two tiers, exactly as the console hop splits them, and the split is the\n * same because the acts are the same:\n *\n *  - **The live URL at the moment of conversion** touches no storage. The\n *    parameters are already in the page the visitor asked for, nothing is\n *    written to their device, and there is accordingly nothing to consent to.\n *    A visitor who converts on the page the ad landed them on is attributed\n *    with no grant of any kind.\n *  - **The remembered touch** is written to the visitor's device for an\n *    analytics purpose, which is `analytics_storage`, and it waits for the\n *    same grant the analytics tag waits for. The gate is not re-derived here:\n *    the caller already computed it for the tag and hands the same boolean\n *    down, so there is one gate and it cannot drift from itself.\n *\n * `null` is UNRESOLVED and is not `false`. With `strictNullChecks` off\n * repo-wide that distinction evaporates unless it is carried explicitly, so\n * it is: until the visitor's state is actually settled, nothing is read and\n * nothing is written. Failing closed costs an attribution; failing open\n * writes to a device before the visitor answered.\n *\n * On a WITHDRAWAL the stored touch is removed rather than merely ignored.\n * Somebody who changes their mind should not leave the thing they withdrew\n * consent for sitting on their device.\n *\n * ⛔ **A host whose posture requires prior consent and whose visitor has not\n * given it produces no remembered touch at all.** Their conversion attributes\n * to nothing, exactly as direct traffic does. That is the degradation, stated\n * rather than worked around: there is no fallback identifier, no fingerprint\n * and no server-side cookie, because every one of those is the durable\n * identifier the analytics posture on this runtime deliberately does not set.\n *\n * ## What is never carried\n *\n * Only the three allowlisted `utm_` labels, scrubbed by\n * {@link parseCampaignAttribution} — which refuses an email-shaped value\n * outright. No address, no person's identifier, no click id, nothing that\n * names the visitor. A campaign link is exactly where putting a recipient in\n * a query string would be tempting, and the parser is what makes it\n * impossible rather than merely discouraged: the stored string is re-parsed\n * through the same allowlist that wrote it, so a hand-edited `localStorage`\n * entry can claim no more than a hand-edited URL could.\n *\n * ⛔ **Nothing here depends on a parameter surviving the mail provider's\n * click wrapper.** A campaign link is rewritten by the provider and redirects\n * to the authored URL, so whatever the marketer put on it arrives — but the\n * email channel does not rely on that, because an email click is already\n * recorded server-side against the recipient's address hash. The labels below\n * are the WEB channel's touch, and a campaign that carries none is joined by\n * address instead.\n */\n\nimport {\n  campaignAttributionQuery,\n  parseCampaignAttribution,\n  type CampaignAttribution,\n} from './campaign-attribution'\n\n/*==========================================\n * THE WINDOW, AND WHY THIS IS THE SECOND COPY OF A NUMBER.\n *\n * `email-revenue-window.ts` in `shared-util-email` declares the same seven\n * days, and its docblock is right that a window defined twice is a window\n * that drifts. Importing it here is not available: `shared-util-email` is\n * tagged `scope:shared` and reaches back into `@aglyn/aglyn`, so an edge in\n * this direction closes a project cycle and the module-boundary rule refuses\n * it. That is the same wall `email-media-src.ts` hit, and the answer is the\n * same one it took — a deliberate copy, pinned by a drift guard in an app\n * spec that can import both sides (`attribution-window-drift.spec.ts`).\n *\n * The copy is the WINDOW only. The model name is stamped onto records, which\n * happens server-side, so it stays in one place and never comes near this\n * file.\n *=========================================*/\n\n/** Days between a campaign touch and a conversion it may be credited with. */\nexport const ATTRIBUTION_WINDOW_DAYS = 7\n\n/** The same window in milliseconds. */\nexport const ATTRIBUTION_WINDOW_MS =\n  ATTRIBUTION_WINDOW_DAYS * 24 * 60 * 60 * 1000\n\n/**\n * Whether a touch may be credited with a conversion at `convertedAtMs`.\n *\n * Both bounds matter and they fail differently, exactly as the revenue join\n * describes them: a touch AFTER the conversion is the receipt rather than the\n * cause, and a touch older than the window is one nobody can argue caused\n * anything. Inclusive at both ends.\n */\nfunction touchIsInWindow(touchedAtMs: number, convertedAtMs: number): boolean {\n  if (!Number.isFinite(touchedAtMs) || !Number.isFinite(convertedAtMs)) {\n    return false\n  }\n  if (touchedAtMs <= 0 || convertedAtMs <= 0) return false\n  const age = convertedAtMs - touchedAtMs\n  return age >= 0 && age <= ATTRIBUTION_WINDOW_MS\n}\n\n/** Where the touch is held. Namespaced like every other key this app sets. */\nexport const CAMPAIGN_TOUCH_STORAGE_KEY = 'aglyn:campaign-touch'\n\n/**\n * The parameter the touch's instant rides under inside the wire form.\n *\n * Deliberately not a `utm_` name: the wire form is parsed by the same\n * allowlist that reads a URL, and a fourth `utm_` key would either be dropped\n * by it or have to widen it. `t` is outside the allowlist and read\n * separately.\n */\nexport const CAMPAIGN_TOUCH_TIME_KEY = 't'\n\n/** A campaign the visitor arrived from, and when they arrived from it. */\nexport interface CampaignTouch extends CampaignAttribution {\n  /** When the visitor followed the campaign link, epoch ms. */\n  atMs: number\n}\n\n/**\n * Whether the visitor has granted analytics storage.\n *\n * `null` means NOT YET RESOLVED and is not the same as `false` — see the\n * consent section above.\n */\nlet storageConsent: boolean | null = null\n\nfunction localStore(): Storage | null {\n  if (typeof window === 'undefined') return null\n  // Touching the property itself throws in some privacy modes, not just its\n  // methods.\n  try {\n    return window.localStorage ?? null\n  } catch {\n    return null\n  }\n}\n\n/**\n * The canonical stored form of a touch — the ONLY place it is written, so it\n * cannot drift from what {@link parseCampaignTouch} reads back.\n */\nexport function campaignTouchWire(touch: CampaignTouch | null | undefined): string {\n  if (!touch) return ''\n  const labels = campaignAttributionQuery(touch)\n  if (!labels) return ''\n  const atMs = Math.round(Number(touch.atMs))\n  if (!Number.isFinite(atMs) || atMs <= 0) return ''\n  return `${labels}&${CAMPAIGN_TOUCH_TIME_KEY}=${atMs}`\n}\n\n/**\n * Read a stored or transmitted touch back, or `null`.\n *\n * The window is enforced HERE rather than at the call sites, so every reader\n * — the browser deciding what to send, the server deciding what to credit —\n * agrees about what an expired touch is: nothing at all. A touch dated in the\n * future is refused for the reason the revenue join refuses one: a click\n * after the conversion is the receipt, not the cause.\n */\nexport function parseCampaignTouch(\n  wire: unknown,\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  if (typeof wire !== 'string' || !wire) return null\n  let params: URLSearchParams\n  try {\n    params = new URLSearchParams(wire)\n  } catch {\n    return null\n  }\n  const campaign = parseCampaignAttribution(params)\n  if (!campaign) return null\n  const atMs = Number(params.get(CAMPAIGN_TOUCH_TIME_KEY))\n  if (!touchIsInWindow(atMs, nowMs)) return null\n  return { ...campaign, atMs }\n}\n\n/**\n * Tell this module what the visitor's analytics consent state is.\n *\n * Called by whoever already computed it for the tag, on every render, so a\n * grant remembers the arrival the moment it is given and a withdrawal drops\n * the stored touch immediately.\n */\nexport function setCampaignTouchConsent(allowed: boolean | null): void {\n  storageConsent = allowed === true ? true : allowed === false ? false : null\n  if (storageConsent === true) {\n    rememberCampaignTouch()\n    return\n  }\n  if (storageConsent === false) {\n    const store = localStore()\n    if (!store) return\n    try {\n      store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n    } catch {\n      // Nothing else to try, and a failed cleanup must not break the page.\n    }\n  }\n}\n\n/**\n * Remember the campaign on the current URL as this visitor's latest touch.\n *\n * Overwrites, because the model is last touch. A URL naming no campaign\n * writes NOTHING and clears nothing: a visitor who arrives from an ad and\n * then browses ten organic pages has one touch, not one touch erased by the\n * second pageview.\n *\n * @returns what is now remembered, or `null`.\n */\nexport function rememberCampaignTouch(\n  search?: string,\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  if (storageConsent !== true) return null\n  const store = localStore()\n  if (!store) return null\n  const source =\n    typeof search === 'string'\n      ? search\n      : typeof window === 'undefined'\n        ? ''\n        : window.location.search\n  const campaign = parseCampaignAttribution(new URLSearchParams(source))\n  if (!campaign) return null\n  const touch: CampaignTouch = { ...campaign, atMs: nowMs }\n  const wire = campaignTouchWire(touch)\n  if (!wire) return null\n  try {\n    store.setItem(CAMPAIGN_TOUCH_STORAGE_KEY, wire)\n  } catch {\n    // A store that refuses the write costs the walk from the landing page to\n    // the conversion, never a conversion on the landing page itself — the\n    // live URL below still carries that visitor.\n    return null\n  }\n  return touch\n}\n\n/**\n * The touch to credit a conversion happening right now, or `null`.\n *\n * ## The order is the model\n *\n * The live URL is consulted FIRST and wins whenever it names a campaign,\n * because a campaign on the address bar at the moment of conversion is by\n * definition the most recent touch there is. Only when the current page names\n * none does this fall back to what was remembered.\n *\n * ## An expired entry is deleted, not skipped\n *\n * A touch past the window can never be credited again, so leaving it on the\n * device would be keeping a record of where somebody came from for no purpose\n * anything reads. The read that finds it removes it.\n */\nexport function readCampaignTouch(\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  const live =\n    typeof window === 'undefined'\n      ? null\n      : parseCampaignAttribution(new URLSearchParams(window.location.search))\n  if (live) return { ...live, atMs: nowMs }\n\n  if (storageConsent !== true) return null\n  const store = localStore()\n  if (!store) return null\n  let raw: string | null\n  try {\n    raw = store.getItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n  } catch {\n    return null\n  }\n  if (!raw) return null\n  const touch = parseCampaignTouch(raw, nowMs)\n  if (!touch) {\n    try {\n      store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n    } catch {\n      // The entry stays until the next read finds it again; it is already\n      // uncreditable, so nothing downstream is affected.\n    }\n    return null\n  }\n  return touch\n}\n\n/**\n * The fragment a conversion request spreads into its body, or `{}`.\n *\n * One helper rather than four hand-written spreads: a door that forgets it\n * reports its conversions as organic, which looks exactly like a campaign\n * that produced none. Empty when there is no touch — never a placeholder,\n * never `campaignTouch: undefined`, so that \"arrived from nowhere\" and \"this\n * door does not report\" stay distinguishable on the wire.\n */\nexport function campaignTouchField(\n  nowMs: number = Date.now(),\n): { campaignTouch?: string } {\n  const wire = campaignTouchWire(readCampaignTouch(nowMs))\n  return wire ? { campaignTouch: wire } : {}\n}\n"],"names":["campaignAttributionQuery","parseCampaignAttribution","ATTRIBUTION_WINDOW_DAYS","ATTRIBUTION_WINDOW_MS","touchIsInWindow","touchedAtMs","convertedAtMs","Number","isFinite","age","CAMPAIGN_TOUCH_STORAGE_KEY","CAMPAIGN_TOUCH_TIME_KEY","storageConsent","localStore","window","localStorage","campaignTouchWire","touch","labels","atMs","Math","round","parseCampaignTouch","wire","nowMs","Date","now","params","URLSearchParams","campaign","get","setCampaignTouchConsent","allowed","rememberCampaignTouch","store","removeItem","search","source","location","setItem","readCampaignTouch","live","raw","getItem","campaignTouchField","campaignTouch"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-touch.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 VISITOR'S HALF OF CAMPAIGN ATTRIBUTION — the touch that has to survive\n * the gap between arriving from a campaign and becoming somebody.\n *\n * ## The gap this exists to cross\n *\n * A known recipient can be joined on their address: they clicked a campaign's\n * mail, the delivery webhook stamped the click on their person document, and\n * `email-revenue-attribution.ts` reads it back when their order settles. An\n * ANONYMOUS visitor has no such handle. They arrive from an ad, a partner\n * link or a social post, browse for a while, and only become identifiable at\n * the moment they submit a form, sign up, book or check out. Between the\n * arrival and that moment there is nothing on the server that connects them.\n *\n * The site's own collector already reads `utm_source`/`utm_medium`/\n * `utm_campaign` off the landing URL and increments a per-day label counter\n * with them. That answers \"how many views did this campaign send us\" and\n * stops there — the labels are never carried to the moment the visitor says\n * who they are, so every form, lead, contact and booking a campaign caused is\n * recorded as though nobody caused it.\n *\n * This carries them. The touch is held on the VISITOR, and every identify\n * moment attaches it.\n *\n * ## What holds it, and why it outlives the tab\n *\n * `localStorage`, expiring at {@link ATTRIBUTION_WINDOW_DAYS}.\n *\n * `utm-forwarding.ts` holds its own campaign in `sessionStorage` and\n * argues for it: a first touch that outlived the visit would start\n * attributing next week's organic return to this week's ad. That argument is\n * correct for the question it answers — which campaign produced THIS SIGNUP,\n * asked of one uninterrupted visit to the marketing site — and it is the\n * wrong shape here, because this question already has a stated answer to\n * \"how long may a touch be credited\": the attribution window, seven days,\n * stamped onto every record so the rule is readable off the data.\n *\n * A store that dies with the tab cannot express a seven-day window. It would\n * credit only the visitors who convert without ever closing the tab and\n * silently record every other conversion as organic — a measured zero, which\n * is the failure mode this whole area exists to end. So the touch lives as\n * long as the window says it may and not one millisecond longer: an expired\n * entry is DELETED on the read that finds it, rather than ignored, so a\n * device never holds a campaign it can no longer be credited with.\n *\n * ## Last touch, not first\n *\n * The revenue join credits the LAST click, and a product where a lead and an\n * order attribute by different rules is worse than one that is uniformly\n * approximate. So a new campaign arrival OVERWRITES the stored one. This is\n * the deliberate opposite of {@link rememberVisitUtm}, which keeps the\n * first — that one describes a single visit's origin and this one describes\n * which campaign most recently brought a person back.\n *\n * ## Consent\n *\n * Two tiers, exactly as the console hop splits them, and the split is the\n * same because the acts are the same:\n *\n *  - **The live URL at the moment of conversion** touches no storage. The\n *    parameters are already in the page the visitor asked for, nothing is\n *    written to their device, and there is accordingly nothing to consent to.\n *    A visitor who converts on the page the ad landed them on is attributed\n *    with no grant of any kind.\n *  - **The remembered touch** is written to the visitor's device for an\n *    analytics purpose, which is `analytics_storage`, and it waits for the\n *    same grant the analytics tag waits for. The gate is not re-derived here:\n *    the caller already computed it for the tag and hands the same boolean\n *    down, so there is one gate and it cannot drift from itself.\n *\n * `null` is UNRESOLVED and is not `false`. With `strictNullChecks` off\n * repo-wide that distinction evaporates unless it is carried explicitly, so\n * it is: until the visitor's state is actually settled, nothing is read and\n * nothing is written. Failing closed costs an attribution; failing open\n * writes to a device before the visitor answered.\n *\n * On a WITHDRAWAL the stored touch is removed rather than merely ignored.\n * Somebody who changes their mind should not leave the thing they withdrew\n * consent for sitting on their device.\n *\n * ⛔ **A host whose posture requires prior consent and whose visitor has not\n * given it produces no remembered touch at all.** Their conversion attributes\n * to nothing, exactly as direct traffic does. That is the degradation, stated\n * rather than worked around: there is no fallback identifier, no fingerprint\n * and no server-side cookie, because every one of those is the durable\n * identifier the analytics posture on this runtime deliberately does not set.\n *\n * ## What is never carried\n *\n * Only the three allowlisted `utm_` labels, scrubbed by\n * {@link parseUtmAttribution} — which refuses an email-shaped value\n * outright. No address, no person's identifier, no click id, nothing that\n * names the visitor. A campaign link is exactly where putting a recipient in\n * a query string would be tempting, and the parser is what makes it\n * impossible rather than merely discouraged: the stored string is re-parsed\n * through the same allowlist that wrote it, so a hand-edited `localStorage`\n * entry can claim no more than a hand-edited URL could.\n *\n * ⛔ **Nothing here depends on a parameter surviving the mail provider's\n * click wrapper.** A campaign link is rewritten by the provider and redirects\n * to the authored URL, so whatever the marketer put on it arrives — but the\n * email channel does not rely on that, because an email click is already\n * recorded server-side against the recipient's address hash. The labels below\n * are the WEB channel's touch, and a campaign that carries none is joined by\n * address instead.\n */\n\nimport {\n  utmAttributionQuery,\n  parseUtmAttribution,\n  type UtmAttribution,\n} from './utm-attribution'\n\n/*==========================================\n * THE WINDOW, AND WHY THIS IS THE SECOND COPY OF A NUMBER.\n *\n * `email-revenue-window.ts` in `shared-util-email` declares the same seven\n * days, and its docblock is right that a window defined twice is a window\n * that drifts. Importing it here is not available: `shared-util-email` is\n * tagged `scope:shared` and reaches back into `@aglyn/aglyn`, so an edge in\n * this direction closes a project cycle and the module-boundary rule refuses\n * it. That is the same wall `email-media-src.ts` hit, and the answer is the\n * same one it took — a deliberate copy, pinned by a drift guard in an app\n * spec that can import both sides (`attribution-window-drift.spec.ts`).\n *\n * The copy is the WINDOW only. The model name is stamped onto records, which\n * happens server-side, so it stays in one place and never comes near this\n * file.\n *=========================================*/\n\n/** Days between a campaign touch and a conversion it may be credited with. */\nexport const ATTRIBUTION_WINDOW_DAYS = 7\n\n/** The same window in milliseconds. */\nexport const ATTRIBUTION_WINDOW_MS =\n  ATTRIBUTION_WINDOW_DAYS * 24 * 60 * 60 * 1000\n\n/**\n * Whether a touch may be credited with a conversion at `convertedAtMs`.\n *\n * Both bounds matter and they fail differently, exactly as the revenue join\n * describes them: a touch AFTER the conversion is the receipt rather than the\n * cause, and a touch older than the window is one nobody can argue caused\n * anything. Inclusive at both ends.\n */\nfunction touchIsInWindow(touchedAtMs: number, convertedAtMs: number): boolean {\n  if (!Number.isFinite(touchedAtMs) || !Number.isFinite(convertedAtMs)) {\n    return false\n  }\n  if (touchedAtMs <= 0 || convertedAtMs <= 0) return false\n  const age = convertedAtMs - touchedAtMs\n  return age >= 0 && age <= ATTRIBUTION_WINDOW_MS\n}\n\n/** Where the touch is held. Namespaced like every other key this app sets. */\nexport const CAMPAIGN_TOUCH_STORAGE_KEY = 'aglyn:campaign-touch'\n\n/**\n * The parameter the touch's instant rides under inside the wire form.\n *\n * Deliberately not a `utm_` name: the wire form is parsed by the same\n * allowlist that reads a URL, and a fourth `utm_` key would either be dropped\n * by it or have to widen it. `t` is outside the allowlist and read\n * separately.\n */\nexport const CAMPAIGN_TOUCH_TIME_KEY = 't'\n\n/** A campaign the visitor arrived from, and when they arrived from it. */\nexport interface CampaignTouch extends UtmAttribution {\n  /** When the visitor followed the campaign link, epoch ms. */\n  atMs: number\n}\n\n/**\n * Whether the visitor has granted analytics storage.\n *\n * `null` means NOT YET RESOLVED and is not the same as `false` — see the\n * consent section above.\n */\nlet storageConsent: boolean | null = null\n\nfunction localStore(): Storage | null {\n  if (typeof window === 'undefined') return null\n  // Touching the property itself throws in some privacy modes, not just its\n  // methods.\n  try {\n    return window.localStorage ?? null\n  } catch {\n    return null\n  }\n}\n\n/**\n * The canonical stored form of a touch — the ONLY place it is written, so it\n * cannot drift from what {@link parseCampaignTouch} reads back.\n */\nexport function campaignTouchWire(touch: CampaignTouch | null | undefined): string {\n  if (!touch) return ''\n  const labels = utmAttributionQuery(touch)\n  if (!labels) return ''\n  const atMs = Math.round(Number(touch.atMs))\n  if (!Number.isFinite(atMs) || atMs <= 0) return ''\n  return `${labels}&${CAMPAIGN_TOUCH_TIME_KEY}=${atMs}`\n}\n\n/**\n * Read a stored or transmitted touch back, or `null`.\n *\n * The window is enforced HERE rather than at the call sites, so every reader\n * — the browser deciding what to send, the server deciding what to credit —\n * agrees about what an expired touch is: nothing at all. A touch dated in the\n * future is refused for the reason the revenue join refuses one: a click\n * after the conversion is the receipt, not the cause.\n */\nexport function parseCampaignTouch(\n  wire: unknown,\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  if (typeof wire !== 'string' || !wire) return null\n  let params: URLSearchParams\n  try {\n    params = new URLSearchParams(wire)\n  } catch {\n    return null\n  }\n  const campaign = parseUtmAttribution(params)\n  if (!campaign) return null\n  const atMs = Number(params.get(CAMPAIGN_TOUCH_TIME_KEY))\n  if (!touchIsInWindow(atMs, nowMs)) return null\n  return { ...campaign, atMs }\n}\n\n/**\n * Tell this module what the visitor's analytics consent state is.\n *\n * Called by whoever already computed it for the tag, on every render, so a\n * grant remembers the arrival the moment it is given and a withdrawal drops\n * the stored touch immediately.\n */\nexport function setCampaignTouchConsent(allowed: boolean | null): void {\n  storageConsent = allowed === true ? true : allowed === false ? false : null\n  if (storageConsent === true) {\n    rememberCampaignTouch()\n    return\n  }\n  if (storageConsent === false) {\n    const store = localStore()\n    if (!store) return\n    try {\n      store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n    } catch {\n      // Nothing else to try, and a failed cleanup must not break the page.\n    }\n  }\n}\n\n/**\n * Remember the campaign on the current URL as this visitor's latest touch.\n *\n * Overwrites, because the model is last touch. A URL naming no campaign\n * writes NOTHING and clears nothing: a visitor who arrives from an ad and\n * then browses ten organic pages has one touch, not one touch erased by the\n * second pageview.\n *\n * @returns what is now remembered, or `null`.\n */\nexport function rememberCampaignTouch(\n  search?: string,\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  if (storageConsent !== true) return null\n  const store = localStore()\n  if (!store) return null\n  const source =\n    typeof search === 'string'\n      ? search\n      : typeof window === 'undefined'\n        ? ''\n        : window.location.search\n  const campaign = parseUtmAttribution(new URLSearchParams(source))\n  if (!campaign) return null\n  const touch: CampaignTouch = { ...campaign, atMs: nowMs }\n  const wire = campaignTouchWire(touch)\n  if (!wire) return null\n  try {\n    store.setItem(CAMPAIGN_TOUCH_STORAGE_KEY, wire)\n  } catch {\n    // A store that refuses the write costs the walk from the landing page to\n    // the conversion, never a conversion on the landing page itself — the\n    // live URL below still carries that visitor.\n    return null\n  }\n  return touch\n}\n\n/**\n * The touch to credit a conversion happening right now, or `null`.\n *\n * ## The order is the model\n *\n * The live URL is consulted FIRST and wins whenever it names a campaign,\n * because a campaign on the address bar at the moment of conversion is by\n * definition the most recent touch there is. Only when the current page names\n * none does this fall back to what was remembered.\n *\n * ## An expired entry is deleted, not skipped\n *\n * A touch past the window can never be credited again, so leaving it on the\n * device would be keeping a record of where somebody came from for no purpose\n * anything reads. The read that finds it removes it.\n */\nexport function readCampaignTouch(\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  const live =\n    typeof window === 'undefined'\n      ? null\n      : parseUtmAttribution(new URLSearchParams(window.location.search))\n  if (live) return { ...live, atMs: nowMs }\n\n  if (storageConsent !== true) return null\n  const store = localStore()\n  if (!store) return null\n  let raw: string | null\n  try {\n    raw = store.getItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n  } catch {\n    return null\n  }\n  if (!raw) return null\n  const touch = parseCampaignTouch(raw, nowMs)\n  if (!touch) {\n    try {\n      store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n    } catch {\n      // The entry stays until the next read finds it again; it is already\n      // uncreditable, so nothing downstream is affected.\n    }\n    return null\n  }\n  return touch\n}\n\n/**\n * The fragment a conversion request spreads into its body, or `{}`.\n *\n * One helper rather than four hand-written spreads: a door that forgets it\n * reports its conversions as organic, which looks exactly like a campaign\n * that produced none. Empty when there is no touch — never a placeholder,\n * never `campaignTouch: undefined`, so that \"arrived from nowhere\" and \"this\n * door does not report\" stay distinguishable on the wire.\n */\nexport function campaignTouchField(\n  nowMs: number = Date.now(),\n): { campaignTouch?: string } {\n  const wire = campaignTouchWire(readCampaignTouch(nowMs))\n  return wire ? { campaignTouch: wire } : {}\n}\n"],"names":["utmAttributionQuery","parseUtmAttribution","ATTRIBUTION_WINDOW_DAYS","ATTRIBUTION_WINDOW_MS","touchIsInWindow","touchedAtMs","convertedAtMs","Number","isFinite","age","CAMPAIGN_TOUCH_STORAGE_KEY","CAMPAIGN_TOUCH_TIME_KEY","storageConsent","localStore","window","localStorage","campaignTouchWire","touch","labels","atMs","Math","round","parseCampaignTouch","wire","nowMs","Date","now","params","URLSearchParams","campaign","get","setCampaignTouchConsent","allowed","rememberCampaignTouch","store","removeItem","search","source","location","setItem","readCampaignTouch","live","raw","getItem","campaignTouchField","campaignTouch"],"mappings":"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"}

package/src/lib/app-utils/collection-entries.d.ts

@@ -306,8 +306,8 @@ export interface CollectionEntryRecord {
     coverImage?: string;
     /**
      * The entry's featured video (AGL-2956), stored in the shape
-     * {@link coverImage} is: a `media:{scope}/{id}` reference or a URL, a Wistia
-     * media link included. Raw here for the reason every image field in this
+     * {@link coverImage} is: a `media:{scope}/{id}` reference or a URL, a hosted
+     * player's media link included (`video-embed-provider.ts`). Raw here for the reason every image field in this
      * file is raw — the resolver needs the rendering host, which this record
      * does not carry.
      *