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

package/src/lib/app-utils/email-starter-policy.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-starter-policy.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * What a marketplace email starter may contain, and whether one may still be\n * mailed.\n *\n * In core rather than beside the rest of the marketplace model for the reason\n * `marketplace-provenance` gives: three different projects have to ask these\n * questions and a `scope:app` project may not depend on an `aglyn:addons` lib.\n * `marketplace-verification` used to be cited here too and no longer can be —\n * its console reader became the plugin's own surface, so the policy went with\n * it (AGL-3080). A shared reason is only shared while both halves still hold. The marketplace plugin enforces the\n * policy when content is published and installed; the marketing plugin asks\n * the kill question on the send path; the console renders the assurance.\n * Three readings of \"is this template safe to mail\" is the failure mode this\n * module exists to prevent.\n *\n * ## Why an email design needs a policy the page allowlist does not supply\n *\n * A published page component is rendered by us, inside a document we serve,\n * behind our CSP. A published EMAIL design is rendered by the recipient's mail\n * client, out of our reach entirely, and it leaves on a sending domain whose\n * reputation every tenant shares. The two facts that follow are the whole\n * reason this file is stricter than `sanitizeMarketplaceDefinition`:\n *\n * - **A remote asset in an email is a read receipt.** The recipient's client\n *   fetches every `src` on open, so whatever host the string names learns that\n *   this person opened this message, at this time, from this IP. Naming a\n *   host the PUBLISHER controls hands a third party a recipient-level\n *   engagement feed on the tenant's audience — processing with no recorded\n *   basis and no `assertedBy` provenance, which is exactly what the consent\n *   architecture exists to make impossible. A 1×1 pixel is the deliberate form;\n *   an ordinary hero image is the same disclosure with a picture attached.\n * - **A link is sent under the tenant's name.** A recipient reads the From\n *   header, not the publisher's listing page.\n *\n * So `src` is held to first-party or inline, and `href` to a transport a\n * recipient's client will not silently downgrade. Violations are REFUSED\n * rather than stripped: `sanitizePublishedNodeProps` drops an unsafe URL and\n * publishes the rest, which is right for a page — a missing image is a\n * cosmetic defect — and wrong here, because the publisher whose tracker was\n * quietly removed learns nothing and tries again.\n */\n\nimport { isMediaCdnPath, isMediaRef, parseMediaRef } from './media-ref'\nimport { isListingWideRevocation, isPluginRevoked } from './plugin-manifest'\nimport type { PluginRevocation } from './plugin-manifest'\nimport { decodeStoredNodes } from './stored-nodes'\n\n/** Props that carry a URL into a recipient's mail client. */\nconst URL_PROPS = ['src', 'href'] as const\n\n/**\n * Props whose value is markup rather than text.\n *\n * `emailHtml` is already off `MARKETPLACE_EMAIL_COMPONENT_ID_ALLOWLIST`, so a\n * publish cannot mint one. This catches the same content arriving as a PROP on\n * a block that is on the list — a hand-written document, or a block that grows\n * an `html` prop later — which the component-id allowlist alone would pass.\n */\nconst MARKUP_PROPS = ['html', 'dangerouslySetInnerHTML'] as const\n\n/** Merge-tag opener. Recipient data must never reach a URL (see below). */\nconst MERGE_TAG_OPEN = '{{'\n\n/** Inline image data, which is inert and discloses nothing on open. */\nconst INLINE_IMAGE = /^data:image\\//i\n\n/** Link transports a recipient's client will not silently downgrade. */\nconst MAIL_SAFE_HREF = /^(https:\\/\\/|mailto:|\\/|#)/i\n\nexport type EmailStarterViolationCode =\n  /** A `src` naming a host that is not ours — the read-receipt vector. */\n  | 'remote-asset'\n  /** An `href` on a transport we will not send under a tenant's name. */\n  | 'unsafe-link'\n  /** Recipient data heading for a URL. */\n  | 'merge-tag-in-url'\n  /** Markup we would have to trust rather than render. */\n  | 'raw-markup'\n  /** The node map could not be read, so nothing about it is known. */\n  | 'unreadable'\n\nexport interface EmailStarterViolation {\n  code: EmailStarterViolationCode\n  /** The offending node's id, or `'nodes'` when the map itself is the fault. */\n  nodeId: string\n  componentId: string\n  /** The prop that carried it, for a message that can be acted on. */\n  prop: string\n  /** Truncated: a violation is reported to a publisher, and often logged. */\n  value: string\n}\n\nexport interface EmailStarterInspection {\n  ok: boolean\n  violations: EmailStarterViolation[]\n  /**\n   * Every host this design would send a recipient to, sorted and deduplicated.\n   *\n   * The inspectable half of the link policy. A tenant about to mail their\n   * customers under their own From header is entitled to see the list of\n   * domains a stranger's template points them at, and no allowlist can decide\n   * that for them — a link to a legitimate retailer and a link to the\n   * publisher's affiliate funnel are the same shape.\n   */\n  linkHosts: string[]\n  /**\n   * Media scopes belonging to somebody other than the installing site.\n   *\n   * Not a violation: the asset is served by our own CDN, so the publisher\n   * learns nothing about the recipient, and refusing would make almost every\n   * real template uninstallable. It is REPORTED because the reference stays\n   * live after a copy-on-install — the publisher can still replace the bytes\n   * behind it — which is the one way an installed design can change without\n   * an update being taken.\n   */\n  foreignMediaScopes: string[]\n  /** The decoded map, so a caller need not decode twice. Null when unreadable. */\n  nodes: Record<string, unknown> | null\n}\n\nfunction truncate(value: unknown): string {\n  const text = typeof value === 'string' ? value : String(value ?? '')\n  return text.length > 120 ? `${text.slice(0, 117)}...` : text\n}\n\n/**\n * The host a link points at, or null for a same-origin or non-URL target.\n *\n * `URL` rather than a regex because the question is \"which host will the mail\n * client resolve this to\", and that is the parser's answer, not ours. A value\n * that will not parse is not reported as a host — it is already refused by the\n * transport check, and inventing a host for it would put a fiction on a screen\n * a tenant is using to make a decision.\n */\nfunction linkHost(value: string): string | null {\n  if (!/^https?:\\/\\//i.test(value)) return null\n  try {\n    return new URL(value).host.toLowerCase() || null\n  } catch {\n    return null\n  }\n}\n\n/**\n * Whether a decoded value is a node MAP rather than something that merely\n * survived decoding.\n *\n * The case this exists for is the AGL-1394 shape: `nodes` read raw off a\n * screen version is a msgpack `Buffer`, and `Object.entries` of a Buffer\n * yields byte INDICES paired with NUMBERS. Every check below asks a node for a\n * `props` object, finds none, and the walk completes reporting a clean design.\n * A scanner that cannot read its input must say so, not pass it.\n *\n * `decodeStoredNodes` handles the three storage forms, so anything still\n * failing here was never a node map to begin with.\n */\nfunction isNodeMap(value: unknown): value is Record<string, unknown> {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return false\n  const entries = Object.values(value as Record<string, unknown>)\n  if (!entries.length) return false\n  return entries.every(\n    (entry) => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry),\n  )\n}\n\n/**\n * Reads a marketplace email design against the mail-client policy above.\n *\n * Takes `nodes` in whatever form the document stored it — a plain Firestore\n * map, compressed msgpack bytes, or the `{type:'Buffer'}` envelope an export\n * bundle carries — and decodes before walking, because a naive walk over the\n * compressed form finds nothing and reports the design clean.\n *\n * @param raw - the version document's `nodes` field, undecoded.\n * @param options - carries `hostId`, the site the design is being installed\n *   onto, used only to classify media scopes as local or foreign. Omitted at\n *   publish time, where there is no installing site yet.\n */\nexport function inspectEmailStarter(\n  raw: unknown,\n  options?: { hostId?: string | null },\n): EmailStarterInspection {\n  const decoded = decodeStoredNodes<Record<string, unknown>>(raw)\n  if (!isNodeMap(decoded)) {\n    return {\n      ok: false,\n      violations: [\n        {\n          code: 'unreadable',\n          nodeId: 'nodes',\n          componentId: '',\n          prop: 'nodes',\n          value: decoded === null ? 'undecodable' : 'not a node map',\n        },\n      ],\n      linkHosts: [],\n      foreignMediaScopes: [],\n      nodes: null,\n    }\n  }\n\n  const violations: EmailStarterViolation[] = []\n  const hosts = new Set<string>()\n  const foreignScopes = new Set<string>()\n\n  for (const [nodeId, value] of Object.entries(decoded)) {\n    const node = value as { componentId?: unknown; props?: unknown }\n    const componentId = String(node.componentId ?? '')\n    const props =\n      node.props && typeof node.props === 'object' && !Array.isArray(node.props)\n        ? (node.props as Record<string, unknown>)\n        : {}\n\n    for (const prop of MARKUP_PROPS) {\n      if (props[prop] === undefined) continue\n      violations.push({\n        code: 'raw-markup',\n        nodeId,\n        componentId,\n        prop,\n        value: truncate(props[prop]),\n      })\n    }\n\n    for (const prop of URL_PROPS) {\n      const value = props[prop]\n      if (typeof value !== 'string' || !value) continue\n\n      // Checked before the transport rules, and reported as its own code,\n      // because the two failures need different sentences: an `http:` link is\n      // a mistake to correct, and a merge tag in a URL is recipient data on\n      // its way into a query string — a standing prohibition, and the reason\n      // it is prohibited is that a URL is logged by every hop that serves it.\n      if (value.includes(MERGE_TAG_OPEN)) {\n        violations.push({\n          code: 'merge-tag-in-url',\n          nodeId,\n          componentId,\n          prop,\n          value: truncate(value),\n        })\n        continue\n      }\n\n      if (prop === 'src') {\n        if (isMediaRef(value)) {\n          const ref = parseMediaRef(value)\n          if (!ref) {\n            violations.push({\n              code: 'remote-asset',\n              nodeId,\n              componentId,\n              prop,\n              value: truncate(value),\n            })\n            continue\n          }\n          if (options?.hostId && !ref.scope.split(':').includes(options.hostId)) {\n            foreignScopes.add(ref.scope)\n          }\n          continue\n        }\n        if (isMediaCdnPath(value) || INLINE_IMAGE.test(value)) continue\n        violations.push({\n          code: 'remote-asset',\n          nodeId,\n          componentId,\n          prop,\n          value: truncate(value),\n        })\n        continue\n      }\n\n      const host = linkHost(value)\n      if (host) hosts.add(host)\n      if (!MAIL_SAFE_HREF.test(value)) {\n        violations.push({\n          code: 'unsafe-link',\n          nodeId,\n          componentId,\n          prop,\n          value: truncate(value),\n        })\n      }\n    }\n  }\n\n  return {\n    ok: violations.length === 0,\n    violations,\n    linkHosts: [...hosts].sort(),\n    foreignMediaScopes: [...foreignScopes].sort(),\n    nodes: decoded,\n  }\n}\n\n/** One sentence per violation code, in the second person. */\nconst VIOLATION_COPY: Record<EmailStarterViolationCode, string> = {\n  'remote-asset':\n    'images must come from your own media library or be inline — an image ' +\n    'loaded from another site tells that site who opened the email',\n  'unsafe-link':\n    'links must be https, mailto, or a path on the sending site',\n  'merge-tag-in-url':\n    'a merge tag may not appear in a link or image address — that puts ' +\n    'recipient data into a URL',\n  'raw-markup':\n    'raw HTML cannot be published as an email design; build it from email ' +\n    'blocks',\n  unreadable: 'the design could not be read',\n}\n\n/**\n * A refusal message for a failed inspection, or `undefined` when it passed.\n *\n * One message naming ONE violation and its count, rather than a list: the\n * caller is an API route whose body is rendered in a dialog, and a publisher\n * fixing eleven images fixes them the same way they fix the first.\n */\nexport function emailStarterRefusal(\n  inspection: EmailStarterInspection,\n): string | undefined {\n  const [first] = inspection.violations\n  if (!first) return undefined\n  const more = inspection.violations.length - 1\n  const at = first.componentId ? ` (on a ${first.componentId} block)` : ''\n  return (\n    `This email design cannot be published or installed: ` +\n    `${VIOLATION_COPY[first.code]}${at}. Found \"${first.value}\"` +\n    (more > 0 ? ` and ${more} more like it.` : '.')\n  )\n}\n\n/**\n * How much is actually known about the version of an email starter that was\n * installed.\n *\n * `unreviewed` is a real state, not a missing one, and it is the DEFAULT.\n */\nexport type EmailStarterAssurance = 'approved' | 'unreviewed' | 'rejected'\n\n/**\n * The assurance of ONE version, read from that version's own document.\n *\n * Deliberately takes the version and nothing else. A listing carries\n * `reviewStatus: 'verified'` and a `latestVersionReviewState` mirror, and both\n * describe the listing or its newest build — neither is a statement about the\n * version somebody is installing right now. Passing the listing in here would\n * let version 7 inherit version 3's approval, which is the precise failure the\n * per-version model exists to prevent, and it would do it silently.\n *\n * An absent `reviewState` is `unreviewed`, never `approved`: an email starter\n * is auto-listed like every other copied artifact, so most versions have no\n * verdict at all and the honest answer is that nobody has looked.\n */\nexport function resolveEmailStarterAssurance(\n  version: { reviewState?: unknown } | null | undefined,\n): EmailStarterAssurance {\n  const state = String(version?.reviewState ?? '')\n  if (state === 'approved') return 'approved'\n  if (state === 'rejected') return 'rejected'\n  return 'unreviewed'\n}\n\n/** What the console says about an assurance, so no surface invents its own. */\nexport function emailStarterAssuranceLabel(\n  assurance: EmailStarterAssurance,\n): string {\n  switch (assurance) {\n    case 'approved':\n      return 'Reviewed by Aglyn'\n    case 'rejected':\n      return 'Turned down in review'\n    default:\n      return 'Not reviewed'\n  }\n}\n\n/** Why an installed email design may not be mailed. */\nexport interface EmailStarterSendBlock {\n  code: 'killed'\n  /** Rendered to the tenant; staff's reason when they recorded one. */\n  reason: string\n}\n\n/**\n * Whether the kill switch stops this installed design from being SENT.\n *\n * ## What a kill has to reach, and why the other levers do not reach it\n *\n * An email starter is copied on install: the tree becomes a screen document in\n * the tenant's own site and nothing reads the listing again. That is the right\n * versioning model — a publisher's push must not rewrite an email a tenant is\n * mailing from — but it means every lever the marketplace already had stops at\n * the storefront. `deletedAt` unpublishes, `hiddenAt` blocks browse and blocks\n * the next install, and a rejected version was never installable. None of them\n * is felt by a tenant who installed last week and is sending today.\n *\n * So the kill switch is the one that has to reach through, and it is checked\n * HERE — at the send — rather than by deleting or rewriting the tenant's\n * document. Refusing the send and leaving the content alone is the same rule\n * capacity enforcement follows: a control that reaches a customer's own data\n * to enforce a decision about somebody else's artifact takes the wrong thing\n * away. The tenant keeps the design, keeps editing it, keeps previewing it;\n * what they cannot do is put it on the shared sending domain.\n *\n * Rejection is deliberately NOT a kill and must not become one here: a version\n * turned down in review was never installable, so nothing is running it, and\n * conflating the two would let a review verdict silently stop live mail.\n *\n * A listing-wide kill catches an install whose provenance never recorded a\n * version (everything installed before the provenance stamp). A per-version\n * kill cannot, and does not pretend to — `isPluginRevoked` answers false for\n * an empty version against a version list, which is the honest reading.\n */\nexport function emailStarterSendBlock(input: {\n  /** The install stamp on the document being sent. */\n  installedFrom: { listingId?: string | null; version?: string | null } | null | undefined\n  /** `revocations/{listingId}`, or null when there is none. */\n  revocation: PluginRevocation | null | undefined\n}): EmailStarterSendBlock | null {\n  const listingId = input.installedFrom?.listingId\n  if (!listingId || !input.revocation) return null\n  const version = String(input.installedFrom?.version ?? '')\n  const killed = version\n    ? isPluginRevoked(input.revocation, version)\n    : isListingWideRevocation(input.revocation)\n  if (!killed) return null\n  const reason = String(input.revocation.reason ?? '').trim()\n  return {\n    code: 'killed',\n    reason:\n      'This email was installed from a marketplace template that Aglyn has ' +\n      'since stopped' +\n      (reason ? `: ${reason}. ` : '. ') +\n      'Sending from it is blocked. The design is still here and still ' +\n      'editable, and a campaign built from your own design sends normally.',\n  }\n}\n"],"names":["isMediaCdnPath","isMediaRef","parseMediaRef","isListingWideRevocation","isPluginRevoked","decodeStoredNodes","URL_PROPS","MARKUP_PROPS","MERGE_TAG_OPEN","INLINE_IMAGE","MAIL_SAFE_HREF","truncate","value","text","String","length","slice","linkHost","test","URL","host","toLowerCase","isNodeMap","Array","isArray","entries","Object","values","every","entry","Boolean","inspectEmailStarter","raw","options","decoded","ok","violations","code","nodeId","componentId","prop","linkHosts","foreignMediaScopes","nodes","hosts","Set","foreignScopes","node","props","undefined","push","includes","ref","hostId","scope","split","add","sort","VIOLATION_COPY","unreadable","emailStarterRefusal","inspection","first","more","at","resolveEmailStarterAssurance","version","state","reviewState","emailStarterAssuranceLabel","assurance","emailStarterSendBlock","input","listingId","installedFrom","revocation","killed","reason","trim"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-starter-policy.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * What a marketplace email starter may contain, and whether one may still be\n * mailed.\n *\n * In core rather than beside the rest of the marketplace model for the reason\n * `artifact-provenance` gives: three different projects have to ask these\n * questions and a `scope:app` project may not depend on an `aglyn:addons` lib.\n * `marketplace-verification` used to be cited here too and no longer can be —\n * its console reader became the plugin's own surface, so the policy went with\n * it (AGL-3080). A shared reason is only shared while both halves still hold. The marketplace plugin enforces the\n * policy when content is published and installed; the marketing plugin asks\n * the kill question on the send path; the console renders the assurance.\n * Three readings of \"is this template safe to mail\" is the failure mode this\n * module exists to prevent.\n *\n * ## Why an email design needs a policy the page allowlist does not supply\n *\n * A published page component is rendered by us, inside a document we serve,\n * behind our CSP. A published EMAIL design is rendered by the recipient's mail\n * client, out of our reach entirely, and it leaves on a sending domain whose\n * reputation every tenant shares. The two facts that follow are the whole\n * reason this file is stricter than `sanitizePortableDefinition`:\n *\n * - **A remote asset in an email is a read receipt.** The recipient's client\n *   fetches every `src` on open, so whatever host the string names learns that\n *   this person opened this message, at this time, from this IP. Naming a\n *   host the PUBLISHER controls hands a third party a recipient-level\n *   engagement feed on the tenant's audience — processing with no recorded\n *   basis and no `assertedBy` provenance, which is exactly what the consent\n *   architecture exists to make impossible. A 1×1 pixel is the deliberate form;\n *   an ordinary hero image is the same disclosure with a picture attached.\n * - **A link is sent under the tenant's name.** A recipient reads the From\n *   header, not the publisher's listing page.\n *\n * So `src` is held to first-party or inline, and `href` to a transport a\n * recipient's client will not silently downgrade. Violations are REFUSED\n * rather than stripped: `sanitizePublishedNodeProps` drops an unsafe URL and\n * publishes the rest, which is right for a page — a missing image is a\n * cosmetic defect — and wrong here, because the publisher whose tracker was\n * quietly removed learns nothing and tries again.\n */\n\nimport { isMediaCdnPath, isMediaRef, parseMediaRef } from './media-ref'\nimport { isListingWideRevocation, isPluginRevoked } from './plugin-manifest'\nimport type { PluginRevocation } from './plugin-manifest'\nimport { decodeStoredNodes } from './stored-nodes'\n\n/** Props that carry a URL into a recipient's mail client. */\nconst URL_PROPS = ['src', 'href'] as const\n\n/**\n * Props whose value is markup rather than text.\n *\n * `emailHtml` is already off `PORTABLE_EMAIL_COMPONENT_ID_ALLOWLIST`, so a\n * publish cannot mint one. This catches the same content arriving as a PROP on\n * a block that is on the list — a hand-written document, or a block that grows\n * an `html` prop later — which the component-id allowlist alone would pass.\n */\nconst MARKUP_PROPS = ['html', 'dangerouslySetInnerHTML'] as const\n\n/** Merge-tag opener. Recipient data must never reach a URL (see below). */\nconst MERGE_TAG_OPEN = '{{'\n\n/** Inline image data, which is inert and discloses nothing on open. */\nconst INLINE_IMAGE = /^data:image\\//i\n\n/** Link transports a recipient's client will not silently downgrade. */\nconst MAIL_SAFE_HREF = /^(https:\\/\\/|mailto:|\\/|#)/i\n\nexport type EmailStarterViolationCode =\n  /** A `src` naming a host that is not ours — the read-receipt vector. */\n  | 'remote-asset'\n  /** An `href` on a transport we will not send under a tenant's name. */\n  | 'unsafe-link'\n  /** Recipient data heading for a URL. */\n  | 'merge-tag-in-url'\n  /** Markup we would have to trust rather than render. */\n  | 'raw-markup'\n  /** The node map could not be read, so nothing about it is known. */\n  | 'unreadable'\n\nexport interface EmailStarterViolation {\n  code: EmailStarterViolationCode\n  /** The offending node's id, or `'nodes'` when the map itself is the fault. */\n  nodeId: string\n  componentId: string\n  /** The prop that carried it, for a message that can be acted on. */\n  prop: string\n  /** Truncated: a violation is reported to a publisher, and often logged. */\n  value: string\n}\n\nexport interface EmailStarterInspection {\n  ok: boolean\n  violations: EmailStarterViolation[]\n  /**\n   * Every host this design would send a recipient to, sorted and deduplicated.\n   *\n   * The inspectable half of the link policy. A tenant about to mail their\n   * customers under their own From header is entitled to see the list of\n   * domains a stranger's template points them at, and no allowlist can decide\n   * that for them — a link to a legitimate retailer and a link to the\n   * publisher's affiliate funnel are the same shape.\n   */\n  linkHosts: string[]\n  /**\n   * Media scopes belonging to somebody other than the installing site.\n   *\n   * Not a violation: the asset is served by our own CDN, so the publisher\n   * learns nothing about the recipient, and refusing would make almost every\n   * real template uninstallable. It is REPORTED because the reference stays\n   * live after a copy-on-install — the publisher can still replace the bytes\n   * behind it — which is the one way an installed design can change without\n   * an update being taken.\n   */\n  foreignMediaScopes: string[]\n  /** The decoded map, so a caller need not decode twice. Null when unreadable. */\n  nodes: Record<string, unknown> | null\n}\n\nfunction truncate(value: unknown): string {\n  const text = typeof value === 'string' ? value : String(value ?? '')\n  return text.length > 120 ? `${text.slice(0, 117)}...` : text\n}\n\n/**\n * The host a link points at, or null for a same-origin or non-URL target.\n *\n * `URL` rather than a regex because the question is \"which host will the mail\n * client resolve this to\", and that is the parser's answer, not ours. A value\n * that will not parse is not reported as a host — it is already refused by the\n * transport check, and inventing a host for it would put a fiction on a screen\n * a tenant is using to make a decision.\n */\nfunction linkHost(value: string): string | null {\n  if (!/^https?:\\/\\//i.test(value)) return null\n  try {\n    return new URL(value).host.toLowerCase() || null\n  } catch {\n    return null\n  }\n}\n\n/**\n * Whether a decoded value is a node MAP rather than something that merely\n * survived decoding.\n *\n * The case this exists for is the AGL-1394 shape: `nodes` read raw off a\n * screen version is a msgpack `Buffer`, and `Object.entries` of a Buffer\n * yields byte INDICES paired with NUMBERS. Every check below asks a node for a\n * `props` object, finds none, and the walk completes reporting a clean design.\n * A scanner that cannot read its input must say so, not pass it.\n *\n * `decodeStoredNodes` handles the three storage forms, so anything still\n * failing here was never a node map to begin with.\n */\nfunction isNodeMap(value: unknown): value is Record<string, unknown> {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return false\n  const entries = Object.values(value as Record<string, unknown>)\n  if (!entries.length) return false\n  return entries.every(\n    (entry) => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry),\n  )\n}\n\n/**\n * Reads a marketplace email design against the mail-client policy above.\n *\n * Takes `nodes` in whatever form the document stored it — a plain Firestore\n * map, compressed msgpack bytes, or the `{type:'Buffer'}` envelope an export\n * bundle carries — and decodes before walking, because a naive walk over the\n * compressed form finds nothing and reports the design clean.\n *\n * @param raw - the version document's `nodes` field, undecoded.\n * @param options - carries `hostId`, the site the design is being installed\n *   onto, used only to classify media scopes as local or foreign. Omitted at\n *   publish time, where there is no installing site yet.\n */\nexport function inspectEmailStarter(\n  raw: unknown,\n  options?: { hostId?: string | null },\n): EmailStarterInspection {\n  const decoded = decodeStoredNodes<Record<string, unknown>>(raw)\n  if (!isNodeMap(decoded)) {\n    return {\n      ok: false,\n      violations: [\n        {\n          code: 'unreadable',\n          nodeId: 'nodes',\n          componentId: '',\n          prop: 'nodes',\n          value: decoded === null ? 'undecodable' : 'not a node map',\n        },\n      ],\n      linkHosts: [],\n      foreignMediaScopes: [],\n      nodes: null,\n    }\n  }\n\n  const violations: EmailStarterViolation[] = []\n  const hosts = new Set<string>()\n  const foreignScopes = new Set<string>()\n\n  for (const [nodeId, value] of Object.entries(decoded)) {\n    const node = value as { componentId?: unknown; props?: unknown }\n    const componentId = String(node.componentId ?? '')\n    const props =\n      node.props && typeof node.props === 'object' && !Array.isArray(node.props)\n        ? (node.props as Record<string, unknown>)\n        : {}\n\n    for (const prop of MARKUP_PROPS) {\n      if (props[prop] === undefined) continue\n      violations.push({\n        code: 'raw-markup',\n        nodeId,\n        componentId,\n        prop,\n        value: truncate(props[prop]),\n      })\n    }\n\n    for (const prop of URL_PROPS) {\n      const value = props[prop]\n      if (typeof value !== 'string' || !value) continue\n\n      // Checked before the transport rules, and reported as its own code,\n      // because the two failures need different sentences: an `http:` link is\n      // a mistake to correct, and a merge tag in a URL is recipient data on\n      // its way into a query string — a standing prohibition, and the reason\n      // it is prohibited is that a URL is logged by every hop that serves it.\n      if (value.includes(MERGE_TAG_OPEN)) {\n        violations.push({\n          code: 'merge-tag-in-url',\n          nodeId,\n          componentId,\n          prop,\n          value: truncate(value),\n        })\n        continue\n      }\n\n      if (prop === 'src') {\n        if (isMediaRef(value)) {\n          const ref = parseMediaRef(value)\n          if (!ref) {\n            violations.push({\n              code: 'remote-asset',\n              nodeId,\n              componentId,\n              prop,\n              value: truncate(value),\n            })\n            continue\n          }\n          if (options?.hostId && !ref.scope.split(':').includes(options.hostId)) {\n            foreignScopes.add(ref.scope)\n          }\n          continue\n        }\n        if (isMediaCdnPath(value) || INLINE_IMAGE.test(value)) continue\n        violations.push({\n          code: 'remote-asset',\n          nodeId,\n          componentId,\n          prop,\n          value: truncate(value),\n        })\n        continue\n      }\n\n      const host = linkHost(value)\n      if (host) hosts.add(host)\n      if (!MAIL_SAFE_HREF.test(value)) {\n        violations.push({\n          code: 'unsafe-link',\n          nodeId,\n          componentId,\n          prop,\n          value: truncate(value),\n        })\n      }\n    }\n  }\n\n  return {\n    ok: violations.length === 0,\n    violations,\n    linkHosts: [...hosts].sort(),\n    foreignMediaScopes: [...foreignScopes].sort(),\n    nodes: decoded,\n  }\n}\n\n/** One sentence per violation code, in the second person. */\nconst VIOLATION_COPY: Record<EmailStarterViolationCode, string> = {\n  'remote-asset':\n    'images must come from your own media library or be inline — an image ' +\n    'loaded from another site tells that site who opened the email',\n  'unsafe-link':\n    'links must be https, mailto, or a path on the sending site',\n  'merge-tag-in-url':\n    'a merge tag may not appear in a link or image address — that puts ' +\n    'recipient data into a URL',\n  'raw-markup':\n    'raw HTML cannot be published as an email design; build it from email ' +\n    'blocks',\n  unreadable: 'the design could not be read',\n}\n\n/**\n * A refusal message for a failed inspection, or `undefined` when it passed.\n *\n * One message naming ONE violation and its count, rather than a list: the\n * caller is an API route whose body is rendered in a dialog, and a publisher\n * fixing eleven images fixes them the same way they fix the first.\n */\nexport function emailStarterRefusal(\n  inspection: EmailStarterInspection,\n): string | undefined {\n  const [first] = inspection.violations\n  if (!first) return undefined\n  const more = inspection.violations.length - 1\n  const at = first.componentId ? ` (on a ${first.componentId} block)` : ''\n  return (\n    `This email design cannot be published or installed: ` +\n    `${VIOLATION_COPY[first.code]}${at}. Found \"${first.value}\"` +\n    (more > 0 ? ` and ${more} more like it.` : '.')\n  )\n}\n\n/**\n * How much is actually known about the version of an email starter that was\n * installed.\n *\n * `unreviewed` is a real state, not a missing one, and it is the DEFAULT.\n */\nexport type EmailStarterAssurance = 'approved' | 'unreviewed' | 'rejected'\n\n/**\n * The assurance of ONE version, read from that version's own document.\n *\n * Deliberately takes the version and nothing else. A listing carries\n * `reviewStatus: 'verified'` and a `latestVersionReviewState` mirror, and both\n * describe the listing or its newest build — neither is a statement about the\n * version somebody is installing right now. Passing the listing in here would\n * let version 7 inherit version 3's approval, which is the precise failure the\n * per-version model exists to prevent, and it would do it silently.\n *\n * An absent `reviewState` is `unreviewed`, never `approved`: an email starter\n * is auto-listed like every other copied artifact, so most versions have no\n * verdict at all and the honest answer is that nobody has looked.\n */\nexport function resolveEmailStarterAssurance(\n  version: { reviewState?: unknown } | null | undefined,\n): EmailStarterAssurance {\n  const state = String(version?.reviewState ?? '')\n  if (state === 'approved') return 'approved'\n  if (state === 'rejected') return 'rejected'\n  return 'unreviewed'\n}\n\n/** What the console says about an assurance, so no surface invents its own. */\nexport function emailStarterAssuranceLabel(\n  assurance: EmailStarterAssurance,\n): string {\n  switch (assurance) {\n    case 'approved':\n      return 'Reviewed by Aglyn'\n    case 'rejected':\n      return 'Turned down in review'\n    default:\n      return 'Not reviewed'\n  }\n}\n\n/** Why an installed email design may not be mailed. */\nexport interface EmailStarterSendBlock {\n  code: 'killed'\n  /** Rendered to the tenant; staff's reason when they recorded one. */\n  reason: string\n}\n\n/**\n * Whether the kill switch stops this installed design from being SENT.\n *\n * ## What a kill has to reach, and why the other levers do not reach it\n *\n * An email starter is copied on install: the tree becomes a screen document in\n * the tenant's own site and nothing reads the listing again. That is the right\n * versioning model — a publisher's push must not rewrite an email a tenant is\n * mailing from — but it means every lever the marketplace already had stops at\n * the storefront. `deletedAt` unpublishes, `hiddenAt` blocks browse and blocks\n * the next install, and a rejected version was never installable. None of them\n * is felt by a tenant who installed last week and is sending today.\n *\n * So the kill switch is the one that has to reach through, and it is checked\n * HERE — at the send — rather than by deleting or rewriting the tenant's\n * document. Refusing the send and leaving the content alone is the same rule\n * capacity enforcement follows: a control that reaches a customer's own data\n * to enforce a decision about somebody else's artifact takes the wrong thing\n * away. The tenant keeps the design, keeps editing it, keeps previewing it;\n * what they cannot do is put it on the shared sending domain.\n *\n * Rejection is deliberately NOT a kill and must not become one here: a version\n * turned down in review was never installable, so nothing is running it, and\n * conflating the two would let a review verdict silently stop live mail.\n *\n * A listing-wide kill catches an install whose provenance never recorded a\n * version (everything installed before the provenance stamp). A per-version\n * kill cannot, and does not pretend to — `isPluginRevoked` answers false for\n * an empty version against a version list, which is the honest reading.\n */\nexport function emailStarterSendBlock(input: {\n  /** The install stamp on the document being sent. */\n  installedFrom: { listingId?: string | null; version?: string | null } | null | undefined\n  /** `revocations/{listingId}`, or null when there is none. */\n  revocation: PluginRevocation | null | undefined\n}): EmailStarterSendBlock | null {\n  const listingId = input.installedFrom?.listingId\n  if (!listingId || !input.revocation) return null\n  const version = String(input.installedFrom?.version ?? '')\n  const killed = version\n    ? isPluginRevoked(input.revocation, version)\n    : isListingWideRevocation(input.revocation)\n  if (!killed) return null\n  const reason = String(input.revocation.reason ?? '').trim()\n  return {\n    code: 'killed',\n    reason:\n      'This email was installed from a marketplace template that Aglyn has ' +\n      'since stopped' +\n      (reason ? `: ${reason}. ` : '. ') +\n      'Sending from it is blocked. The design is still here and still ' +\n      'editable, and a campaign built from your own design sends normally.',\n  }\n}\n"],"names":["isMediaCdnPath","isMediaRef","parseMediaRef","isListingWideRevocation","isPluginRevoked","decodeStoredNodes","URL_PROPS","MARKUP_PROPS","MERGE_TAG_OPEN","INLINE_IMAGE","MAIL_SAFE_HREF","truncate","value","text","String","length","slice","linkHost","test","URL","host","toLowerCase","isNodeMap","Array","isArray","entries","Object","values","every","entry","Boolean","inspectEmailStarter","raw","options","decoded","ok","violations","code","nodeId","componentId","prop","linkHosts","foreignMediaScopes","nodes","hosts","Set","foreignScopes","node","props","undefined","push","includes","ref","hostId","scope","split","add","sort","VIOLATION_COPY","unreadable","emailStarterRefusal","inspection","first","more","at","resolveEmailStarterAssurance","version","state","reviewState","emailStarterAssuranceLabel","assurance","emailStarterSendBlock","input","listingId","installedFrom","revocation","killed","reason","trim"],"mappings":"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"}

package/src/lib/app-utils/entity-picker-context.d.ts

@@ -72,12 +72,17 @@ export interface EntityPickerContextValue {
     /** The host's form entities, id-first, feeding FORM_SELECT attributes. */
     forms?: EntityOption[];
     /**
-     * Per-dataset model fields (AGL-556), keyed by dataset id, in model
-     * order: id = stable model fieldId, label = current display name. Feeds
-     * DATASET_FIELD_SELECT attributes (e.g. a form field's "Maps to schema
-     * field" picker).
+     * The fields an entity's documents declare, keyed by kind and then by
+     * entity id, in the order the entity declares them: id = the stable field
+     * id a node persists, label = its current display name (AGL-556).
+     *
+     * Only kinds whose documents carry a field model appear. Two surfaces read
+     * it: a field picker that maps a value onto one of an entity's fields (a
+     * form field's "Maps to schema field"), and the insert-token menu inside a
+     * repeat, which offers `{{item.<field>}}` for each field of the entity the
+     * repeat names (see `RepeatSource.entityKind`).
      */
-    datasetFields?: Record<string, EntityOption[]>;
+    entityFields?: Partial<Record<EntityPickerKind, Readonly<Record<string, EntityOption[]>>>>;
     /**
      * Declare that a picker of this kind is on screen (AGL-703).
      *

package/src/lib/app-utils/entity-picker-context.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/entity-picker-context.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// Same placement rationale as screen-link-context.ts: lives in\n// @aglyn/aglyn without a 'use client' banner so canvas-rendering surfaces\n// share one module graph.\nimport { createContext } from 'react'\n\nexport interface EntityOption {\n  /** Stable document id — the persisted reference (AGL-343/344). */\n  id: string\n  /** Current display name, resolved at edit time. */\n  label: string\n}\n\n/**\n * Edit-time option lists for id-based entity pickers in component\n * attributes (products, collections, categories, datasets, forms). Names are\n * display-only; nodes persist the id, so renames never break references —\n * the same contract as {@link ScreenLinkContext}. Provided by the\n * console's besigner/preview surfaces; absent on the tenant (the tenant\n * only resolves ids, never lists them).\n */\n/** The lists a picker can ask for. */\nexport type EntityPickerKind =\n  | 'products'\n  | 'collections'\n  | 'categories'\n  | 'datasets'\n  | 'forms'\n\n/**\n * How much an empty list is worth believing.\n *\n * Every one of these renders as a dropdown with no entries, and an author\n * looking at four identical empty dropdowns cannot tell \"this site has no\n * forms yet\" from \"the read failed\" from \"this editor never lists forms at\n * all\". Only the first of those is a fact about their site; the other two\n * are the picker being broken, and a picker that cannot say which it is\n * sends the author looking for a form they already made.\n *\n * - `unavailable` — no provider is mounted, so nothing on this surface can\n *   list entities. The tenant, and any editor outside a host.\n * - `loading` — a read is open or about to be, and no answer has arrived.\n *   Also the state of a list nothing has asked for yet: demand is declared\n *   on the same commit that would display it, so \"not asked\" and \"asked,\n *   unanswered\" are the same beat.\n * - `ready` — the read settled. An empty list here IS the site's answer.\n * - `error` — the read failed. Empty means nothing.\n */\nexport type EntityListState = 'unavailable' | 'loading' | 'ready' | 'error'\n\n/**\n * How many documents a picker BROWSES.\n *\n * A picker is not a catalog viewer. It is a dropdown on a besigner surface\n * where the author is placing one element, and no table in the console offers\n * a page past `TABLE_PAGE_SIZE_OPTIONS` — a dropdown is the smaller surface of\n * the two, not the larger.\n *\n * The middle of that range rather than its floor: a table has a pager under it\n * and a dropdown does not, so the page a reader cannot advance is worth more\n * rows than the one they can.\n *\n * What makes this size SAFE is that browsing is the only job it does. A stored\n * value is named by {@link EntityPickerContextValue.resolve} — one keyed read\n * for the one document, exact at any catalog size — so nothing here has to be\n * wide enough to contain whatever an author picked last month. A window that\n * carried both jobs would have to be, and would still render a bound element\n * as unbound past its own width; widening this cannot fix that, only make it\n * rarer and more expensive.\n */\nexport const ENTITY_PICKER_BROWSE_LIMIT = 25\n\n/**\n * How many documents a server-side name search may return.\n *\n * The same size as the browse window, for the same reason: a reader who has\n * typed a query and still faces 25 rows narrows it further rather than\n * scrolling. Only the kinds in {@link EntityPickerContextValue.searchable}\n * spend this at all.\n */\nexport const ENTITY_PICKER_SEARCH_LIMIT = 25\n\nexport interface EntityPickerContextValue {\n  products?: EntityOption[]\n  collections?: EntityOption[]\n  categories?: EntityOption[]\n  datasets?: EntityOption[]\n  /** The host's form entities, id-first, feeding FORM_SELECT attributes. */\n  forms?: EntityOption[]\n  /**\n   * Per-dataset model fields (AGL-556), keyed by dataset id, in model\n   * order: id = stable model fieldId, label = current display name. Feeds\n   * DATASET_FIELD_SELECT attributes (e.g. a form field's \"Maps to schema\n   * field\" picker).\n   */\n  datasetFields?: Record<string, EntityOption[]>\n  /**\n   * Declare that a picker of this kind is on screen (AGL-703).\n   *\n   * The provider reads these lists from Firestore, and it used to read ALL of\n   * them the moment the besigner opened — up to 300 products, 200 catalog\n   * collections, 200 categories and 200 datasets, on a site with a real\n   * catalog, for pickers most editing sessions never open. Nothing about\n   * moving a heading needs the product list.\n   *\n   * So the lists are demand-driven now, and the demand signal is the thing\n   * that would DISPLAY one: a selected node whose schema declares a\n   * `PRODUCT_SELECT`, a repeat bound to a dataset. Call this when that is\n   * true and read the list on the render after; until then the list is\n   * absent, exactly as it is for the beat before any listener syncs.\n   *\n   * Optional, and absent on the tenant — which resolves ids and never lists\n   * them, so nothing there has a picker to ask for.\n   */\n  request?: (kind: EntityPickerKind) => void\n  /**\n   * Per-kind read state, so a picker can say WHY it has nothing to offer.\n   * A kind the provider omits reads as `loading`; see {@link entityListState}.\n   */\n  status?: Partial<Record<EntityPickerKind, EntityListState>>\n  /**\n   * The browse window came back FULL for this kind, so the list above is a\n   * page of the site's catalog and not the whole of it.\n   *\n   * Measured with a probe — the read asks for one document past\n   * {@link ENTITY_PICKER_BROWSE_LIMIT} and the extra one is never offered —\n   * so this is a fact about the collection rather than a guess from the\n   * window being exactly full.\n   *\n   * A picker owes the reader this sentence for the same reason the inbox's\n   * form filter does: \"not in the picker\" and \"does not exist\" are the same\n   * empty dropdown, and only one of them is a fact about their site.\n   */\n  truncated?: Partial<Record<EntityPickerKind, boolean>>\n  /**\n   * This kind's documents carry the name-search keys, so a typed query\n   * reaches the WHOLE collection rather than only the browse window.\n   *\n   * True for products alone today: `nameTokens`/`nameLower` are stamped by\n   * the catalog's own write path, and `hosts/{host}/resources` deliberately\n   * does not stamp them on the other four kinds. A picker for a kind that is\n   * absent here must say its search covers the window only — claiming\n   * otherwise would let an unfound entity read as a nonexistent one.\n   */\n  searchable?: Partial<Record<EntityPickerKind, boolean>>\n  /**\n   * Narrow this kind's offered list to what somebody typed.\n   *\n   * Matching is the provider's, not the dropdown's: it is the only side that\n   * can merge the window's own matches with the ones a server query found\n   * past it, and it uses `scoreMatch` so a query matches a word ANYWHERE in a\n   * name — the same rule the switchers and global search follow.\n   *\n   * Passing an empty string restores the browse window.\n   */\n  search?: (kind: EntityPickerKind, text: string) => void\n  /**\n   * Resolve ONE stored id to its current name, whatever the browse window\n   * holds.\n   *\n   * Deliberately NOT a job for the browse list, though a bulk read could do\n   * both. Sharing one read makes the list's width the limit on which stored\n   * values can be named, and past that width a picker renders a bound element\n   * as UNBOUND rather than as its label — an empty control on an element that\n   * is set, which an author repairs by picking again. That is how a correct\n   * reference gets replaced with a different one.\n   *\n   * One keyed `getDoc` for one document instead: exact at any catalog size,\n   * and asked for only when a node actually carries a value. Results land in\n   * {@link resolved} and are never re-read.\n   */\n  resolve?: (kind: EntityPickerKind, id: string) => void\n  /**\n   * What {@link resolve} found, keyed by kind and then by id.\n   *\n   * Three states, and the picker renders a different label for each: an\n   * `EntityOption` is the resolved name, `null` is a settled read that found\n   * NO such document, and an absent key is a resolution still in flight.\n   * Absent must never render as missing — a picker that flashed \"unavailable\"\n   * over every live reference for the beat before its read landed would teach\n   * authors to ignore the one warning that matters.\n   */\n  resolved?: Partial<\n    Record<EntityPickerKind, Readonly<Record<string, EntityOption | null>>>\n  >\n}\n\n/**\n * What the picker for `kind` should believe about its own emptiness.\n *\n * `request` is the \"a provider is mounted\" signal — it is the one member the\n * contract already says is absent wherever nothing lists entities — so a\n * surface with no provider resolves to `unavailable` rather than passing an\n * empty list off as the site's answer.\n */\nexport function entityListState(\n  context: EntityPickerContextValue | undefined,\n  kind: EntityPickerKind,\n): EntityListState {\n  if (!context?.request) return 'unavailable'\n  return context.status?.[kind] ?? 'loading'\n}\n\n/**\n * The id whose label a picker still needs a keyed read to learn, if any.\n *\n * Part of the contract rather than of one screen, because two surfaces ask\n * it — the attributes panel about a node's picker value, and the insert-token\n * menu about the dataset a repeat is bound to — and an answer that differed\n * between them would be a second keyed read for a document one of them\n * already had.\n *\n * Four cases resolve to \"ask nobody\", and each is a read not spent: there is\n * no value; the browse window already carries it, which is the common case on\n * a small site; a resolution has already answered, including the answer that\n * the document is gone; or the browse read has not settled, so the window may\n * be about to supply it for free.\n *\n * The last is the one worth stating. Asking while the listener is still\n * loading would spend a keyed read on nearly every picker on every site,\n * which is the cost splitting these two jobs exists to remove rather than to\n * move.\n */\nexport function entityValueNeedsResolution(\n  context: EntityPickerContextValue | undefined,\n  kind: EntityPickerKind,\n  value: unknown,\n): string | undefined {\n  const id = typeof value === 'string' ? value.trim() : ''\n  if (!id || !context?.resolve) return undefined\n  if ((context[kind] ?? []).some((entity) => entity.id === id)) return undefined\n  if (id in (context.resolved?.[kind] ?? {})) return undefined\n  if (entityListState(context, kind) !== 'ready') return undefined\n  return id\n}\n\nexport const EntityPickerContext = createContext<EntityPickerContextValue>({})\nEntityPickerContext.displayName = 'EntityPickerContext'\n"],"names":["createContext","ENTITY_PICKER_BROWSE_LIMIT","ENTITY_PICKER_SEARCH_LIMIT","entityListState","context","kind","request","status","entityValueNeedsResolution","value","id","trim","resolve","undefined","some","entity","resolved","EntityPickerContext","displayName"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD,+DAA+D;AAC/D,0EAA0E;AAC1E,0BAA0B;AAC1B,SAASA,aAAa,QAAQ,QAAO;AA8CrC;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,MAAMC,6BAA6B,GAAE;AAE5C;;;;;;;CAOC,GACD,OAAO,MAAMC,6BAA6B,GAAE;AA2G5C;;;;;;;CAOC,GACD,OAAO,SAASC,gBACdC,OAA6C,EAC7CC,IAAsB;;QAGfD;IADP,IAAI,EAACA,2BAAAA,QAASE,OAAO,GAAE,OAAO;IAC9B,gBAAOF,kBAAAA,QAAQG,MAAM,qBAAdH,eAAgB,CAACC,KAAK,mBAAI;AACnC;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASG,2BACdJ,OAA6C,EAC7CC,IAAsB,EACtBI,KAAc;QAITL;QACMA;IAHX,MAAMM,KAAK,OAAOD,UAAU,WAAWA,MAAME,IAAI,KAAK;IACtD,IAAI,CAACD,MAAM,EAACN,2BAAAA,QAASQ,OAAO,GAAE,OAAOC;IACrC,IAAI,EAACT,gBAAAA,OAAO,CAACC,KAAK,YAAbD,gBAAiB,EAAE,EAAEU,IAAI,CAAC,CAACC,SAAWA,OAAOL,EAAE,KAAKA,KAAK,OAAOG;IACrE,IAAIH,gBAAON,oBAAAA,QAAQY,QAAQ,qBAAhBZ,iBAAkB,CAACC,KAAK,mBAAI,CAAC,IAAI,OAAOQ;IACnD,IAAIV,gBAAgBC,SAASC,UAAU,SAAS,OAAOQ;IACvD,OAAOH;AACT;AAEA,OAAO,MAAMO,sBAAsBjB,cAAwC,CAAC,GAAE;AAC9EiB,oBAAoBC,WAAW,GAAG"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/entity-picker-context.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// Same placement rationale as screen-link-context.ts: lives in\n// @aglyn/aglyn without a 'use client' banner so canvas-rendering surfaces\n// share one module graph.\nimport { createContext } from 'react'\n\nexport interface EntityOption {\n  /** Stable document id — the persisted reference (AGL-343/344). */\n  id: string\n  /** Current display name, resolved at edit time. */\n  label: string\n}\n\n/**\n * Edit-time option lists for id-based entity pickers in component\n * attributes (products, collections, categories, datasets, forms). Names are\n * display-only; nodes persist the id, so renames never break references —\n * the same contract as {@link ScreenLinkContext}. Provided by the\n * console's besigner/preview surfaces; absent on the tenant (the tenant\n * only resolves ids, never lists them).\n */\n/** The lists a picker can ask for. */\nexport type EntityPickerKind =\n  | 'products'\n  | 'collections'\n  | 'categories'\n  | 'datasets'\n  | 'forms'\n\n/**\n * How much an empty list is worth believing.\n *\n * Every one of these renders as a dropdown with no entries, and an author\n * looking at four identical empty dropdowns cannot tell \"this site has no\n * forms yet\" from \"the read failed\" from \"this editor never lists forms at\n * all\". Only the first of those is a fact about their site; the other two\n * are the picker being broken, and a picker that cannot say which it is\n * sends the author looking for a form they already made.\n *\n * - `unavailable` — no provider is mounted, so nothing on this surface can\n *   list entities. The tenant, and any editor outside a host.\n * - `loading` — a read is open or about to be, and no answer has arrived.\n *   Also the state of a list nothing has asked for yet: demand is declared\n *   on the same commit that would display it, so \"not asked\" and \"asked,\n *   unanswered\" are the same beat.\n * - `ready` — the read settled. An empty list here IS the site's answer.\n * - `error` — the read failed. Empty means nothing.\n */\nexport type EntityListState = 'unavailable' | 'loading' | 'ready' | 'error'\n\n/**\n * How many documents a picker BROWSES.\n *\n * A picker is not a catalog viewer. It is a dropdown on a besigner surface\n * where the author is placing one element, and no table in the console offers\n * a page past `TABLE_PAGE_SIZE_OPTIONS` — a dropdown is the smaller surface of\n * the two, not the larger.\n *\n * The middle of that range rather than its floor: a table has a pager under it\n * and a dropdown does not, so the page a reader cannot advance is worth more\n * rows than the one they can.\n *\n * What makes this size SAFE is that browsing is the only job it does. A stored\n * value is named by {@link EntityPickerContextValue.resolve} — one keyed read\n * for the one document, exact at any catalog size — so nothing here has to be\n * wide enough to contain whatever an author picked last month. A window that\n * carried both jobs would have to be, and would still render a bound element\n * as unbound past its own width; widening this cannot fix that, only make it\n * rarer and more expensive.\n */\nexport const ENTITY_PICKER_BROWSE_LIMIT = 25\n\n/**\n * How many documents a server-side name search may return.\n *\n * The same size as the browse window, for the same reason: a reader who has\n * typed a query and still faces 25 rows narrows it further rather than\n * scrolling. Only the kinds in {@link EntityPickerContextValue.searchable}\n * spend this at all.\n */\nexport const ENTITY_PICKER_SEARCH_LIMIT = 25\n\nexport interface EntityPickerContextValue {\n  products?: EntityOption[]\n  collections?: EntityOption[]\n  categories?: EntityOption[]\n  datasets?: EntityOption[]\n  /** The host's form entities, id-first, feeding FORM_SELECT attributes. */\n  forms?: EntityOption[]\n  /**\n   * The fields an entity's documents declare, keyed by kind and then by\n   * entity id, in the order the entity declares them: id = the stable field\n   * id a node persists, label = its current display name (AGL-556).\n   *\n   * Only kinds whose documents carry a field model appear. Two surfaces read\n   * it: a field picker that maps a value onto one of an entity's fields (a\n   * form field's \"Maps to schema field\"), and the insert-token menu inside a\n   * repeat, which offers `{{item.<field>}}` for each field of the entity the\n   * repeat names (see `RepeatSource.entityKind`).\n   */\n  entityFields?: Partial<\n    Record<EntityPickerKind, Readonly<Record<string, EntityOption[]>>>\n  >\n  /**\n   * Declare that a picker of this kind is on screen (AGL-703).\n   *\n   * The provider reads these lists from Firestore, and it used to read ALL of\n   * them the moment the besigner opened — up to 300 products, 200 catalog\n   * collections, 200 categories and 200 datasets, on a site with a real\n   * catalog, for pickers most editing sessions never open. Nothing about\n   * moving a heading needs the product list.\n   *\n   * So the lists are demand-driven now, and the demand signal is the thing\n   * that would DISPLAY one: a selected node whose schema declares a\n   * `PRODUCT_SELECT`, a repeat bound to a dataset. Call this when that is\n   * true and read the list on the render after; until then the list is\n   * absent, exactly as it is for the beat before any listener syncs.\n   *\n   * Optional, and absent on the tenant — which resolves ids and never lists\n   * them, so nothing there has a picker to ask for.\n   */\n  request?: (kind: EntityPickerKind) => void\n  /**\n   * Per-kind read state, so a picker can say WHY it has nothing to offer.\n   * A kind the provider omits reads as `loading`; see {@link entityListState}.\n   */\n  status?: Partial<Record<EntityPickerKind, EntityListState>>\n  /**\n   * The browse window came back FULL for this kind, so the list above is a\n   * page of the site's catalog and not the whole of it.\n   *\n   * Measured with a probe — the read asks for one document past\n   * {@link ENTITY_PICKER_BROWSE_LIMIT} and the extra one is never offered —\n   * so this is a fact about the collection rather than a guess from the\n   * window being exactly full.\n   *\n   * A picker owes the reader this sentence for the same reason the inbox's\n   * form filter does: \"not in the picker\" and \"does not exist\" are the same\n   * empty dropdown, and only one of them is a fact about their site.\n   */\n  truncated?: Partial<Record<EntityPickerKind, boolean>>\n  /**\n   * This kind's documents carry the name-search keys, so a typed query\n   * reaches the WHOLE collection rather than only the browse window.\n   *\n   * True for products alone today: `nameTokens`/`nameLower` are stamped by\n   * the catalog's own write path, and `hosts/{host}/resources` deliberately\n   * does not stamp them on the other four kinds. A picker for a kind that is\n   * absent here must say its search covers the window only — claiming\n   * otherwise would let an unfound entity read as a nonexistent one.\n   */\n  searchable?: Partial<Record<EntityPickerKind, boolean>>\n  /**\n   * Narrow this kind's offered list to what somebody typed.\n   *\n   * Matching is the provider's, not the dropdown's: it is the only side that\n   * can merge the window's own matches with the ones a server query found\n   * past it, and it uses `scoreMatch` so a query matches a word ANYWHERE in a\n   * name — the same rule the switchers and global search follow.\n   *\n   * Passing an empty string restores the browse window.\n   */\n  search?: (kind: EntityPickerKind, text: string) => void\n  /**\n   * Resolve ONE stored id to its current name, whatever the browse window\n   * holds.\n   *\n   * Deliberately NOT a job for the browse list, though a bulk read could do\n   * both. Sharing one read makes the list's width the limit on which stored\n   * values can be named, and past that width a picker renders a bound element\n   * as UNBOUND rather than as its label — an empty control on an element that\n   * is set, which an author repairs by picking again. That is how a correct\n   * reference gets replaced with a different one.\n   *\n   * One keyed `getDoc` for one document instead: exact at any catalog size,\n   * and asked for only when a node actually carries a value. Results land in\n   * {@link resolved} and are never re-read.\n   */\n  resolve?: (kind: EntityPickerKind, id: string) => void\n  /**\n   * What {@link resolve} found, keyed by kind and then by id.\n   *\n   * Three states, and the picker renders a different label for each: an\n   * `EntityOption` is the resolved name, `null` is a settled read that found\n   * NO such document, and an absent key is a resolution still in flight.\n   * Absent must never render as missing — a picker that flashed \"unavailable\"\n   * over every live reference for the beat before its read landed would teach\n   * authors to ignore the one warning that matters.\n   */\n  resolved?: Partial<\n    Record<EntityPickerKind, Readonly<Record<string, EntityOption | null>>>\n  >\n}\n\n/**\n * What the picker for `kind` should believe about its own emptiness.\n *\n * `request` is the \"a provider is mounted\" signal — it is the one member the\n * contract already says is absent wherever nothing lists entities — so a\n * surface with no provider resolves to `unavailable` rather than passing an\n * empty list off as the site's answer.\n */\nexport function entityListState(\n  context: EntityPickerContextValue | undefined,\n  kind: EntityPickerKind,\n): EntityListState {\n  if (!context?.request) return 'unavailable'\n  return context.status?.[kind] ?? 'loading'\n}\n\n/**\n * The id whose label a picker still needs a keyed read to learn, if any.\n *\n * Part of the contract rather than of one screen, because two surfaces ask\n * it — the attributes panel about a node's picker value, and the insert-token\n * menu about the dataset a repeat is bound to — and an answer that differed\n * between them would be a second keyed read for a document one of them\n * already had.\n *\n * Four cases resolve to \"ask nobody\", and each is a read not spent: there is\n * no value; the browse window already carries it, which is the common case on\n * a small site; a resolution has already answered, including the answer that\n * the document is gone; or the browse read has not settled, so the window may\n * be about to supply it for free.\n *\n * The last is the one worth stating. Asking while the listener is still\n * loading would spend a keyed read on nearly every picker on every site,\n * which is the cost splitting these two jobs exists to remove rather than to\n * move.\n */\nexport function entityValueNeedsResolution(\n  context: EntityPickerContextValue | undefined,\n  kind: EntityPickerKind,\n  value: unknown,\n): string | undefined {\n  const id = typeof value === 'string' ? value.trim() : ''\n  if (!id || !context?.resolve) return undefined\n  if ((context[kind] ?? []).some((entity) => entity.id === id)) return undefined\n  if (id in (context.resolved?.[kind] ?? {})) return undefined\n  if (entityListState(context, kind) !== 'ready') return undefined\n  return id\n}\n\nexport const EntityPickerContext = createContext<EntityPickerContextValue>({})\nEntityPickerContext.displayName = 'EntityPickerContext'\n"],"names":["createContext","ENTITY_PICKER_BROWSE_LIMIT","ENTITY_PICKER_SEARCH_LIMIT","entityListState","context","kind","request","status","entityValueNeedsResolution","value","id","trim","resolve","undefined","some","entity","resolved","EntityPickerContext","displayName"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD,+DAA+D;AAC/D,0EAA0E;AAC1E,0BAA0B;AAC1B,SAASA,aAAa,QAAQ,QAAO;AA8CrC;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,MAAMC,6BAA6B,GAAE;AAE5C;;;;;;;CAOC,GACD,OAAO,MAAMC,6BAA6B,GAAE;AAkH5C;;;;;;;CAOC,GACD,OAAO,SAASC,gBACdC,OAA6C,EAC7CC,IAAsB;;QAGfD;IADP,IAAI,EAACA,2BAAAA,QAASE,OAAO,GAAE,OAAO;IAC9B,gBAAOF,kBAAAA,QAAQG,MAAM,qBAAdH,eAAgB,CAACC,KAAK,mBAAI;AACnC;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASG,2BACdJ,OAA6C,EAC7CC,IAAsB,EACtBI,KAAc;QAITL;QACMA;IAHX,MAAMM,KAAK,OAAOD,UAAU,WAAWA,MAAME,IAAI,KAAK;IACtD,IAAI,CAACD,MAAM,EAACN,2BAAAA,QAASQ,OAAO,GAAE,OAAOC;IACrC,IAAI,EAACT,gBAAAA,OAAO,CAACC,KAAK,YAAbD,gBAAiB,EAAE,EAAEU,IAAI,CAAC,CAACC,SAAWA,OAAOL,EAAE,KAAKA,KAAK,OAAOG;IACrE,IAAIH,gBAAON,oBAAAA,QAAQY,QAAQ,qBAAhBZ,iBAAkB,CAACC,KAAK,mBAAI,CAAC,IAAI,OAAOQ;IACnD,IAAIV,gBAAgBC,SAASC,UAAU,SAAS,OAAOQ;IACvD,OAAOH;AACT;AAEA,OAAO,MAAMO,sBAAsBjB,cAAwC,CAAC,GAAE;AAC9EiB,oBAAoBC,WAAW,GAAG"}

package/src/lib/app-utils/error-beacon.d.ts

@@ -15,7 +15,12 @@
  * limitations under the License.
  */
 export interface ErrorBeaconEvent {
-    /** 'error' | 'unhandledrejection' — which handler caught it. */
+    /**
+     * Which handler caught it — 'error' | 'unhandledrejection' — or the
+     * family it was labeled with: 'hydration', {@link AUTH_DESYNC_KIND},
+     * {@link CHUNK_LOAD_KIND}, or a caller's own kind for a handled error.
+     * Lands at `jsonPayload.kind`, where the alert policies filter on it.
+     */
     kind: string;
     /** Error message, clamped. */
     message: string;
@@ -39,8 +44,8 @@ export interface ErrorBeaconOptions {
 /**
  * Was this thrown by a script somebody ELSE evaluated into our page?
  *
- * Two tells, both read off the frames' URLs and neither off a function name —
- * a name would be a denylist needing a new entry per vendor.
+ * Three tells, all read off the frames' positions and none off a function
+ * name — a name would be a denylist needing a new entry per vendor.
  *
  * **Every frame is the DOCUMENT.** Measured 2026-09-02 (AGL-2523) on
  * aglyn.com/pricing, reported as an error of ours:
@@ -59,9 +64,22 @@ export interface ErrorBeaconOptions {
  *     at sendDataToNative (iabjs://navigation_performance_logger_android:1:10632)
  *
  * That webview names its scripts under its own `iabjs://` scheme, and
- * extensions do the same under theirs — see `FOREIGN_SCRIPT_SCHEMES`. A frame
- * may carry either tell. Nothing we ship can be fixed in response to any of
- * them, which is the same test the opaque `Script error.` cut already applies.
+ * extensions do the same under theirs — see `FOREIGN_SCRIPT_SCHEMES`.
+ *
+ * **Every frame is a script with NO URL** (AGL-3423). Measured on the
+ * sign-up page and on aglyn.com/solutions/agencies:
+ *
+ *     at eval (<anonymous>)
+ *     at predicate (eval at evaluate (:234:30), <anonymous>:11:37)
+ *
+ *     at <anonymous>:1:54
+ *     at <anonymous>:1:64
+ *
+ * An automation driver's `evaluate` and a snippet pasted into devtools. Every
+ * script we serve has a URL — a chunk, a CDN asset, or the document for an
+ * inline one — so a frame whose position is `<anonymous>:line:col`, or code
+ * `eval`'d by such a frame, was not served by us. See
+ * {@link anonymousScriptFrameCount} for exactly which frames count.
  *
  * ⚑ Deliberately `every`, and deliberately compared against the document
  * rather than against our asset path. A rule like "no frame under
@@ -70,11 +88,42 @@ export interface ErrorBeaconOptions {
  * Comparing to the document cannot fail that way: a CDN frame is not the
  * document either, so it keeps the report.
  *
+ * A stack may mix the tells frame by frame. Nothing we ship can be fixed in
+ * response to any of them, which is the same test the opaque `Script error.`
+ * cut already applies.
+ *
  * The cost is honest and small: a throw from one of our own inline
  * bootstrap scripts looks the same and is dropped with it. That trade buys a
  * rule that needs no maintenance as new webviews and extensions appear.
  */
 export declare function isInjectedThirdPartyFrame(stack: string, documentUrl: string): boolean;
+/** How many frames of this stack are in a script with no URL at all. */
+export declare function anonymousScriptFrameCount(stack: string): number;
+export declare function isBenignBrowserNotice(message: string): boolean;
+/**
+ * `kind` for Firebase's `auth/tenant-id-mismatch` — a sibling tab signed in to
+ * another account pool (AGL-3280). The console recovers the tab by reloading
+ * it once it is hidden and deliberately leaves the rejection unhandled so it
+ * is still seen; this label is what lets it be seen by RATE instead of paging
+ * on each of the several rejections one storage event raises.
+ */
+export declare const AUTH_DESYNC_KIND = "auth-desync";
+/**
+ * `kind` for a chunk the document names and the origin no longer serves
+ * (AGL-3279). Every boundary reloads once for it; what still arrives is the
+ * failure the reload did not cure. One of those is a visitor on a bad
+ * connection; a burst of them is a broken deploy, which only a rate can tell.
+ */
+export declare const CHUNK_LOAD_KIND = "chunk-load";
+/**
+ * The label for a fault we RECOVER from and still want to see, or undefined.
+ *
+ * These could be ours, so unlike an injected stack they are never dropped:
+ * they are written at full severity under their own `kind`, the per-entry
+ * policy excludes that kind, and a rate policy watches it — the same split
+ * `hydration` already has.
+ */
+export declare function recoveredErrorKind(error: unknown): string | undefined;
 export declare function isHydrationMismatch(message: string): boolean;
 /**
  * WHAT A REJECTED PROMISE ACTUALLY CARRIED (AGL-3279).
@@ -100,6 +149,26 @@ export declare function isHydrationMismatch(message: string): boolean;
  * was called to improve.
  */
 export declare function describeRejectionReason(reason: unknown): string;
+/**
+ * How many frames a thrown error keeps, on a pageview that reports (AGL-3423).
+ *
+ * V8 keeps ten by default, and ten is not enough to find where a render loop
+ * STARTED. The Besigner's one React #185 report (2026-09-24) was a
+ * react-final-form field's `setState` inside final-form's `notify` loop, and
+ * every one of its ten frames was inside those two libraries: the component
+ * whose update fed the loop was cut off below them. Fifty reaches past a
+ * form library's own frames to ours, and still fits the {@link MAX_STACK}
+ * clamp at the length a minified frame line has.
+ */
+export declare const BEACON_STACK_TRACE_LIMIT = 50;
+/**
+ * Raises the engine's frame limit to `limit`, never lowers it. V8 and
+ * JavaScriptCore read `Error.stackTraceLimit`; an engine that does not has no
+ * such number, and is left without one rather than handed a property it
+ * ignores. It applies to errors created after the call, which is why the
+ * beacon sets it at install, at module scope of the app's first client chunk.
+ */
+export declare function raiseStackTraceLimit(limit: number): void;
 /**
  * Re-export so `error-beacon` stays the one name a caller has to know for
  * browser error reporting. The definition lives in its own module because a

package/src/lib/app-utils/error-beacon.js

@@ -41,7 +41,9 @@
  * tenant runtime from its own, and neither needs React here. Deliberately NO
  * 'use client' directive — inside this shared lib the directive forks the
  * module graph (AGL-52); every importer is already a client module.
- */ import { isForeignScriptUrl, stackFrameUrls } from "./foreign-script.js";
+ */ import { isCrossPoolDesync } from "./cross-pool-desync.js";
+import { isForeignScriptUrl, stackFrameUrls } from "./foreign-script.js";
+import { isStaleBuildError, recoverStaleBuildRejection } from "./stale-build-error.js";
 const MAX_MESSAGE = 1024;
 const MAX_STACK = 8192;
 const FLUSH_DELAY_MS = 2000;
@@ -60,8 +62,8 @@ function clamp(value, max) {
 /**
  * Was this thrown by a script somebody ELSE evaluated into our page?
  *
- * Two tells, both read off the frames' URLs and neither off a function name —
- * a name would be a denylist needing a new entry per vendor.
+ * Three tells, all read off the frames' positions and none off a function
+ * name — a name would be a denylist needing a new entry per vendor.
  *
  * **Every frame is the DOCUMENT.** Measured 2026-09-02 (AGL-2523) on
  * aglyn.com/pricing, reported as an error of ours:
@@ -80,9 +82,22 @@ function clamp(value, max) {
  *     at sendDataToNative (iabjs://navigation_performance_logger_android:1:10632)
  *
  * That webview names its scripts under its own `iabjs://` scheme, and
- * extensions do the same under theirs — see `FOREIGN_SCRIPT_SCHEMES`. A frame
- * may carry either tell. Nothing we ship can be fixed in response to any of
- * them, which is the same test the opaque `Script error.` cut already applies.
+ * extensions do the same under theirs — see `FOREIGN_SCRIPT_SCHEMES`.
+ *
+ * **Every frame is a script with NO URL** (AGL-3423). Measured on the
+ * sign-up page and on aglyn.com/solutions/agencies:
+ *
+ *     at eval (<anonymous>)
+ *     at predicate (eval at evaluate (:234:30), <anonymous>:11:37)
+ *
+ *     at <anonymous>:1:54
+ *     at <anonymous>:1:64
+ *
+ * An automation driver's `evaluate` and a snippet pasted into devtools. Every
+ * script we serve has a URL — a chunk, a CDN asset, or the document for an
+ * inline one — so a frame whose position is `<anonymous>:line:col`, or code
+ * `eval`'d by such a frame, was not served by us. See
+ * {@link anonymousScriptFrameCount} for exactly which frames count.
  *
  * ⚑ Deliberately `every`, and deliberately compared against the document
  * rather than against our asset path. A rule like "no frame under
@@ -91,15 +106,92 @@ function clamp(value, max) {
  * Comparing to the document cannot fail that way: a CDN frame is not the
  * document either, so it keeps the report.
  *
+ * A stack may mix the tells frame by frame. Nothing we ship can be fixed in
+ * response to any of them, which is the same test the opaque `Script error.`
+ * cut already applies.
+ *
  * The cost is honest and small: a throw from one of our own inline
  * bootstrap scripts looks the same and is dropped with it. That trade buys a
  * rule that needs no maintenance as new webviews and extensions appear.
  */ export function isInjectedThirdPartyFrame(stack, documentUrl) {
     const urls = stackFrameUrls(stack);
-    // No frames parsed is not evidence of anything — keep the report.
-    if (!urls.length) return false;
+    // No frames parsed is not evidence of anything — keep the report. A stack
+    // with neither a URL nor an anonymous-script frame is exactly that: an
+    // empty frame list must never read as "every frame is injected".
+    if (!urls.length && !anonymousScriptFrameCount(stack)) return false;
+    // Anonymous frames need no test of their own — they are injected by
+    // definition — so `every` over the URLs is `every` over the whole stack.
+    // One URL of ours, even as the origin of an `eval`, keeps the report.
     return urls.every((url)=>isForeignScriptUrl(url) || scrubUrl(url) === documentUrl);
 }
+/** A frame line, in V8's `at …` format or WebKit/Firefox's `fn@location`. */ const STACK_FRAME_LINE = /^\s*at\s|@/;
+/**
+ * A position in a script that has no URL.
+ *
+ * - `<anonymous>:line:col` — V8's name for such a script, both for a top-level
+ *   snippet and as the position of code run through `eval`/`new Function`.
+ * - `eval at …` — V8's origin of `eval`'d code. When OUR script ran the eval
+ *   its URL is inside this origin, `stackFrameUrls` reads it, and the report
+ *   is kept; that is how the marketing plugin's `runJs` step stays reported.
+ * - `debugger eval code:line:col` — Firefox's devtools console, in the
+ *   `fn@location` format WebKit also uses.
+ *
+ * ⚑ A BARE `(<anonymous>)` with no line and column is NOT one of these. It is
+ * how V8 prints a builtin — `at Array.forEach (<anonymous>)`,
+ * `at JSON.parse (<anonymous>)` — and a builtin is called by whoever called
+ * it, including us.
+ */ const ANONYMOUS_SCRIPT_POSITION = /<anonymous>:\d+:\d+|\beval at\s|\bdebugger eval code:\d+:\d+/;
+/** How many frames of this stack are in a script with no URL at all. */ export function anonymousScriptFrameCount(stack) {
+    let count = 0;
+    for (const line of stack.split('\n')){
+        if (STACK_FRAME_LINE.test(line) && ANONYMOUS_SCRIPT_POSITION.test(line)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * Browser notices that are not failures, and that no fix of ours could act on.
+ *
+ * `ResizeObserver loop completed with undelivered notifications` (and its older
+ * wording, `ResizeObserver loop limit exceeded`) is the browser saying it
+ * deferred some resize callbacks to the next frame. Nothing threw: the event
+ * carries no error object and no stack, and every observer is still
+ * delivered. It arrived from the Besigner on 2026-09-26 and paged. Dropped, on
+ * the browser's exact wording.
+ */ const BENIGN_BROWSER_NOTICE = /^(?:Uncaught )?(?:Error: )?ResizeObserver loop (?:completed with undelivered notifications|limit exceeded)/;
+export function isBenignBrowserNotice(message) {
+    return BENIGN_BROWSER_NOTICE.test(message);
+}
+/**
+ * `kind` for Firebase's `auth/tenant-id-mismatch` — a sibling tab signed in to
+ * another account pool (AGL-3280). The console recovers the tab by reloading
+ * it once it is hidden and deliberately leaves the rejection unhandled so it
+ * is still seen; this label is what lets it be seen by RATE instead of paging
+ * on each of the several rejections one storage event raises.
+ */ export const AUTH_DESYNC_KIND = 'auth-desync';
+/**
+ * `kind` for a chunk the document names and the origin no longer serves
+ * (AGL-3279). Every boundary reloads once for it; what still arrives is the
+ * failure the reload did not cure. One of those is a visitor on a bad
+ * connection; a burst of them is a broken deploy, which only a rate can tell.
+ */ export const CHUNK_LOAD_KIND = 'chunk-load';
+/**
+ * The label for a fault we RECOVER from and still want to see, or undefined.
+ *
+ * These could be ours, so unlike an injected stack they are never dropped:
+ * they are written at full severity under their own `kind`, the per-entry
+ * policy excludes that kind, and a rate policy watches it — the same split
+ * `hydration` already has.
+ */ export function recoveredErrorKind(error) {
+    try {
+        if (isCrossPoolDesync(error)) return AUTH_DESYNC_KIND;
+        if (isStaleBuildError(error)) return CHUNK_LOAD_KIND;
+    } catch (unused) {
+    // A getter that throws leaves the event unlabeled, never unreported.
+    }
+    return undefined;
+}
 /**
  * React's hydration-mismatch family, which a page TRANSLATOR causes and a
  * real render divergence also causes.
@@ -184,6 +276,33 @@ export function isHydrationMismatch(message) {
         return 'Unhandled promise rejection (undescribable)';
     }
 }
+/**
+ * How many frames a thrown error keeps, on a pageview that reports (AGL-3423).
+ *
+ * V8 keeps ten by default, and ten is not enough to find where a render loop
+ * STARTED. The Besigner's one React #185 report (2026-09-24) was a
+ * react-final-form field's `setState` inside final-form's `notify` loop, and
+ * every one of its ten frames was inside those two libraries: the component
+ * whose update fed the loop was cut off below them. Fifty reaches past a
+ * form library's own frames to ours, and still fits the {@link MAX_STACK}
+ * clamp at the length a minified frame line has.
+ */ export const BEACON_STACK_TRACE_LIMIT = 50;
+/**
+ * Raises the engine's frame limit to `limit`, never lowers it. V8 and
+ * JavaScriptCore read `Error.stackTraceLimit`; an engine that does not has no
+ * such number, and is left without one rather than handed a property it
+ * ignores. It applies to errors created after the call, which is why the
+ * beacon sets it at install, at module scope of the app's first client chunk.
+ */ export function raiseStackTraceLimit(limit) {
+    try {
+        const engine = Error;
+        const current = engine.stackTraceLimit;
+        if (typeof current !== 'number' || current >= limit) return;
+        engine.stackTraceLimit = limit;
+    } catch (unused) {
+    // A frozen or exotic `Error` keeps its own limit.
+    }
+}
 let installed = false;
 /**
  * The live beacon's `enqueue`, published for {@link reportHandledError}.
@@ -238,7 +357,11 @@ let installed = false;
     const endpoint = (_ref = options == null ? void 0 : options.endpoint) != null ? _ref : '/api/errors';
     const sampleRate = (_ref1 = options == null ? void 0 : options.sampleRate) != null ? _ref1 : 1;
     const maxPerPage = (_ref2 = options == null ? void 0 : options.maxPerPage) != null ? _ref2 : 10;
-    if (Math.random() >= sampleRate) return;
+    // Only a sampled pageview REPORTS. Every pageview recovers a stale build
+    // (the rejection handler below), because a tab left on a dead deploy is a
+    // visitor's problem whether or not its errors are counted.
+    const sampled = Math.random() < sampleRate;
+    if (sampled) raiseStackTraceLimit(BEACON_STACK_TRACE_LIMIT);
     const seen = new Set();
     let queued = [];
     let sent = 0;
@@ -270,7 +393,7 @@ let installed = false;
     };
     const enqueue = (event)=>{
         var _event_stack;
-        if (sent >= maxPerPage) return;
+        if (!sampled || sent >= maxPerPage) return;
         // Message + first stack line: enough identity to collapse a render loop
         // without collapsing distinct errors that share a message.
         const key = `${event.message}\x00${((_event_stack = event.stack) != null ? _event_stack : '').split('\n', 2).join('\n')}`;
@@ -280,18 +403,18 @@ let installed = false;
         queued.push(event);
         if (!timer) timer = setTimeout(flush, FLUSH_DELAY_MS);
     };
-    // Published AFTER the sample-rate return above, so an unsampled pageview
-    // reports nothing by either door rather than one by one and none by the
-    // other.
-    publishEvent = enqueue;
+    // Null on an unsampled pageview, so it reports nothing by either door
+    // rather than one by one and none by the other.
+    publishEvent = sampled ? enqueue : null;
     window.addEventListener('error', (event)=>{
         try {
-            var _ref;
+            var _ref, _recoveredErrorKind;
             const error = event.error;
             const message = clamp((_ref = error == null ? void 0 : error.message) != null ? _ref : event.message, MAX_MESSAGE);
             // Cross-origin scripts yield an opaque "Script error." with nothing
             // actionable attached; reporting it would only create a noisy group.
             if (!message || message === 'Script error.') return;
+            if (isBenignBrowserNotice(message)) return;
             const pageUrl = scrubUrl(window.location.href);
             const fullStack = (error == null ? void 0 : error.stack) ? String(error.stack) : undefined;
             // A webview or extension that evaluated its own code into our page —
@@ -302,9 +425,12 @@ let installed = false;
             if (fullStack && isInjectedThirdPartyFrame(fullStack, pageUrl)) return;
             const stack = fullStack ? clamp(fullStack, MAX_STACK) : undefined;
             enqueue({
-                // MARKED, not dropped: a translator causes these and so does a real
-                // render divergence, and only a rate tells them apart.
-                kind: isHydrationMismatch(message) ? 'hydration' : 'error',
+                // MARKED, not dropped: a translator causes a hydration mismatch and
+                // so does a real render divergence, and a recovered fault is still a
+                // fault. Only a rate tells either apart from noise.
+                kind: (_recoveredErrorKind = recoveredErrorKind(error != null ? error : {
+                    message
+                })) != null ? _recoveredErrorKind : isHydrationMismatch(message) ? 'hydration' : 'error',
                 message,
                 stack,
                 source: scrubUrl(event.filename) || undefined,
@@ -318,14 +444,27 @@ let installed = false;
     });
     window.addEventListener('unhandledrejection', (event)=>{
         try {
+            var _recoveredErrorKind;
+            // An `import()` of a chunk this document names and the origin dropped,
+            // which no boundary saw. Recovered by a reload once the tab is hidden,
+            // and, like a boundary's reload, not reported: see
+            // `recoverStaleBuildRejection`. A tab whose recovery is spent still
+            // reports it, as `chunk-load`.
+            if (recoverStaleBuildRejection(event.reason)) return;
             const reason = event.reason;
             const message = clamp(describeRejectionReason(event.reason), MAX_MESSAGE);
             if (!message) return;
+            const pageUrl = scrubUrl(window.location.href);
+            const fullStack = (reason == null ? void 0 : reason.stack) ? String(reason.stack) : undefined;
+            // The same injected-code drop as an uncaught error: a rejection raised
+            // by a devtools snippet or an automation driver's `evaluate` is no more
+            // ours for having been a promise.
+            if (fullStack && isInjectedThirdPartyFrame(fullStack, pageUrl)) return;
             enqueue({
-                kind: 'unhandledrejection',
+                kind: (_recoveredErrorKind = recoveredErrorKind(event.reason)) != null ? _recoveredErrorKind : 'unhandledrejection',
                 message,
-                stack: (reason == null ? void 0 : reason.stack) ? clamp(reason.stack, MAX_STACK) : undefined,
-                url: scrubUrl(window.location.href)
+                stack: fullStack ? clamp(fullStack, MAX_STACK) : undefined,
+                url: pageUrl
             });
         } catch (unused) {
         // Never rethrow from an error handler.