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

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/error-beacon.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 * First-party browser error beacon (AGL-1538).\n *\n * Crashlytics does not exist for web, and adding a third-party error vendor\n * is a subprocessor-list decision that was explicitly deferred. This is the\n * first-party alternative: `window.onerror` / `unhandledrejection` handlers\n * that batch uncaught failures to the app's own `/api/errors` route, which\n * forwards them to Google Cloud Error Reporting — a processor already on the\n * list, alerting through the GCP stack that already pages (AGL-1502).\n *\n * Design constraints, in order:\n *\n * - **It must never become the outage.** Everything is wrapped; a failure to\n *   report is silence, not a thrown error. Batches are capped per page so an\n *   error thrown in a loop cannot DDoS our own API — after `maxPerPage`\n *   events the beacon disarms for the rest of the pageview.\n * - **No PII.** URLs are scrubbed to origin + pathname (query strings and\n *   fragments carry tokens and search terms), no user id, no cookies —\n *   the payload is the error text and where in the CODE it happened.\n *   Cross-origin scripts surface as the browser's opaque \"Script error.\"\n *   with no stack; those are dropped since they cannot be acted on.\n * - **Dedupe.** One page throwing the same error on every frame reports it\n *   once.\n *\n * Framework-free on purpose: the console mounts it from its root layout, the\n * tenant runtime from its own, and neither needs React here. Deliberately NO\n * 'use client' directive — inside this shared lib the directive forks the\n * module graph (AGL-52); every importer is already a client module.\n */\n\nimport { isForeignScriptUrl, stackFrameUrls } from './foreign-script'\n\nexport interface ErrorBeaconEvent {\n  /** 'error' | 'unhandledrejection' — which handler caught it. */\n  kind: string\n  /** Error message, clamped. */\n  message: string\n  /** Stack trace when the thrown value carried one, clamped. */\n  stack?: string\n  /** Script URL for stackless `window.onerror` events, scrubbed. */\n  source?: string\n  line?: number\n  col?: number\n  /** Page URL, scrubbed to origin + pathname. */\n  url: string\n}\n\nexport interface ErrorBeaconOptions {\n  /** POST target; same-origin. Default `/api/errors`. */\n  endpoint?: string\n  /** 0..1 — fraction of pageviews that report at all. Default 1. */\n  sampleRate?: number\n  /** Max events reported per pageview before the beacon disarms. */\n  maxPerPage?: number\n}\n\nconst MAX_MESSAGE = 1_024\nconst MAX_STACK = 8_192\nconst FLUSH_DELAY_MS = 2_000\n\n/** Origin + pathname only — query strings and fragments never leave. */\nfunction scrubUrl(raw: string | null | undefined): string {\n  if (!raw) return ''\n  try {\n    const url = new URL(String(raw), window.location.href)\n    return `${url.origin}${url.pathname}`\n  } catch {\n    return ''\n  }\n}\n\nfunction clamp(value: unknown, max: number): string {\n  return String(value ?? '').slice(0, max)\n}\n\n/**\n * Was this thrown by a script somebody ELSE evaluated into our page?\n *\n * Two tells, both read off the frames' URLs and neither off a function name —\n * a name would be a denylist needing a new entry per vendor.\n *\n * **Every frame is the DOCUMENT.** Measured 2026-09-02 (AGL-2523) on\n * aglyn.com/pricing, reported as an error of ours:\n *\n *     sendDataToNative@https://aglyn.com/pricing:1:1325\n *     sendPageHideMessage@https://aglyn.com/pricing:1:4139\n *     @https://aglyn.com/pricing:1:6257\n *\n * `sendDataToNative` is the Meta in-app browser's native bridge, injected by\n * the Facebook/Instagram webview. In WebKit's format the code was evaluated\n * inline, so every frame is the document rather than a script we served.\n *\n * **Every frame is under a FOREIGN scheme.** Measured 2026-09-10 (AGL-2786) on\n * aglyn.com, the same bridge in the Android webview:\n *\n *     at sendDataToNative (iabjs://navigation_performance_logger_android:1:10632)\n *\n * That webview names its scripts under its own `iabjs://` scheme, and\n * extensions do the same under theirs — see `FOREIGN_SCRIPT_SCHEMES`. A frame\n * may carry either tell. Nothing we ship can be fixed in response to any of\n * them, which is the same test the opaque `Script error.` cut already applies.\n *\n * ⚑ Deliberately `every`, and deliberately compared against the document\n * rather than against our asset path. A rule like \"no frame under\n * `/_next/static/`\" would delete EVERY error from a self-hosted deployment\n * that serves its assets from a CDN, because none of its frames would match.\n * Comparing to the document cannot fail that way: a CDN frame is not the\n * document either, so it keeps the report.\n *\n * The cost is honest and small: a throw from one of our own inline\n * bootstrap scripts looks the same and is dropped with it. That trade buys a\n * rule that needs no maintenance as new webviews and extensions appear.\n */\nexport function isInjectedThirdPartyFrame(\n  stack: string,\n  documentUrl: string,\n): boolean {\n  const urls = stackFrameUrls(stack)\n  // No frames parsed is not evidence of anything — keep the report.\n  if (!urls.length) return false\n  return urls.every(\n    (url) => isForeignScriptUrl(url) || scrubUrl(url) === documentUrl,\n  )\n}\n\n/**\n * React's hydration-mismatch family, which a page TRANSLATOR causes and a\n * real render divergence also causes.\n *\n * These are `onRecoverableError` reports, not crashes: React has already\n * re-rendered on the client and the visitor has a working page. They arrive\n * here as uncaught errors only because React re-throws them to `reportError`.\n *\n * They are marked rather than dropped, and the distinction is the whole\n * design. Dropping would hide a real hydration regression, which is a genuine\n * and expensive bug; the entries stay in `client-errors` at full severity and\n * still group in Error Reporting. What the mark buys is that the log-match\n * policy can stop paging on a single report, while a rate-based policy on the\n * same mark still catches a systemic one.\n *\n * ⚠️ THE MARK IS NOT A VERDICT, and the one cluster this repo has measured is\n * why. Eight #418 reports arrived inside a nine-minute window on 2026-09-01,\n * on one build, and the three pages they came from were exactly the three\n * carrying a form — `/`, `/pricing` and the solutions pages reported nothing\n * in the same window, which no browser-side rewrite would respect. A placed\n * form was expanding inside its own grafted subtree, so every page carrying\n * one shipped six nested `<form>` elements; nested forms are invalid HTML, the\n * parser dropped the inner ones, and the client tree disagreed with the server\n * tree. The visible cost was a submission the route never received, because\n * the native submit came from an unhandled ancestor and the browser fell back\n * to a GET with the visitor's name, email and message in the address bar. The\n * reports stopped because the nesting was fixed, roughly a quarter of an hour\n * after the last one.\n *\n * So a rate low enough not to page is a reason to READ the entry — the page\n * it names, and whether the set of pages has a shape — never a reason to\n * assume somebody's extension.\n */\nconst HYDRATION_MINIFIED = /Minified React error #(?:418|423|425)\\b/\nconst HYDRATION_TEXT =\n  /Hydration failed because|Text content does not match server-rendered HTML|There was an error while hydrating/\n\nexport function isHydrationMismatch(message: string): boolean {\n  return HYDRATION_MINIFIED.test(message) || HYDRATION_TEXT.test(message)\n}\n\n/**\n * WHAT A REJECTED PROMISE ACTUALLY CARRIED (AGL-3279).\n *\n * `unhandledrejection` hands over whatever was passed to `reject`, and only\n * an `Error` brings a message and a stack. A rejection with anything else —\n * an API's `{ code, message }` object, a `DOMException` from an aborted\n * fetch, a bare string, a `Response` — used to be reported as the literal\n * words \"Unhandled promise rejection\" with no stack and no other field,\n * which names the handler rather than the failure. One such report arrived\n * on 2026-09-21 from the Besigner editor and there is nothing in it to act\n * on: no message, no stack, no code, nothing but the page.\n *\n * So the value is DESCRIBED rather than defaulted. In order of how much a\n * reader can do with it: the error's own message; a string as itself; a\n * `name`/`code`/`message` shape assembled from whatever of those it has —\n * the shape every Firebase, DOM and fetch rejection takes; the value's own\n * `toString` when it says more than `[object Object]`; and last its own\n * keys, which at least name what kind of thing rejected.\n *\n * Nothing here may throw: a getter on the reason can, `toString` can, and\n * a describer that throws inside the rejection handler loses the report it\n * was called to improve.\n */\nexport function describeRejectionReason(reason: unknown): string {\n  try {\n    if (reason instanceof Error && reason.message) return reason.message\n    if (typeof reason === 'string') return reason\n    if (reason === null || reason === undefined) {\n      return `Unhandled promise rejection (${String(reason)})`\n    }\n    if (typeof reason !== 'object') {\n      return `Unhandled promise rejection (${typeof reason}: ${String(reason)})`\n    }\n    const shape = reason as Record<string, unknown>\n    const named = [\n      shape['name'] ?? shape['code'] ?? '',\n      shape['message'] ?? shape['statusText'] ?? '',\n    ]\n      .map((part) => String(part ?? '').trim())\n      .filter(Boolean)\n    if (named.length) return named.join(': ')\n    const printed = String(reason)\n    if (printed && printed !== '[object Object]') return printed\n    const keys = Object.keys(shape).slice(0, 12).join(', ')\n    return keys\n      ? `Unhandled promise rejection (object with ${keys})`\n      : 'Unhandled promise rejection (empty object)'\n  } catch {\n    return 'Unhandled promise rejection (undescribable)'\n  }\n}\n\nlet installed = false\n\n/**\n * The live beacon's `enqueue`, published for {@link reportHandledError}.\n *\n * Null until `installErrorBeacon` runs, and null forever on a surface that\n * never installs one — so a caught error reported from a page with no beacon\n * is silently dropped rather than throwing inside somebody's error handler.\n */\nlet publishEvent: ((event: ErrorBeaconEvent) => void) | null = null\n\n/**\n * Re-export so `error-beacon` stays the one name a caller has to know for\n * browser error reporting. The definition lives in its own module because a\n * boundary that imports it must not pull the installer below into a chunk\n * every visitor downloads.\n */\nexport { redispatchCaughtError } from './redispatch-caught-error'\n\n/**\n * Report an error the code ALREADY CAUGHT.\n *\n * The two window handlers below see only what nothing caught. A `catch` that\n * swallows its error is invisible to them by construction, which is the whole\n * failure mode this exists for: a background write that can only fail\n * silently is one that stays broken for as long as nobody thinks to look.\n *\n * It rides the same queue as an uncaught error, which is the point — the\n * dedupe collapses a failure that repeats on every edit into one report, and\n * `maxPerPage` bounds it, so a call site in a loop cannot turn a broken\n * feature into a flood. Reporting is never worth an exception of its own, so\n * every path here returns rather than throws.\n */\nexport function reportHandledError(\n  error: unknown,\n  options?: { kind?: string },\n): void {\n  try {\n    if (!publishEvent) return\n    const thrown = error as Error | undefined\n    const message = clamp(\n      thrown?.message ?? (typeof error === 'string' ? error : ''),\n      MAX_MESSAGE,\n    )\n    if (!message) return\n    publishEvent({\n      kind: clamp(options?.kind ?? 'handled', 32),\n      message,\n      stack: thrown?.stack ? clamp(thrown.stack, MAX_STACK) : undefined,\n      url: scrubUrl(window.location.href),\n    })\n  } catch {\n    // An observer that throws is worse than one that misses an event.\n  }\n}\n\n/**\n * Installs the handlers once per page. Safe to call from module scope of a\n * client bundle: it no-ops during SSR and on repeat calls.\n */\nexport function installErrorBeacon(options?: ErrorBeaconOptions): void {\n  if (typeof window === 'undefined' || installed) return\n  installed = true\n\n  const endpoint = options?.endpoint ?? '/api/errors'\n  const sampleRate = options?.sampleRate ?? 1\n  const maxPerPage = options?.maxPerPage ?? 10\n  if (Math.random() >= sampleRate) return\n\n  const seen = new Set<string>()\n  let queued: ErrorBeaconEvent[] = []\n  let sent = 0\n  let timer: ReturnType<typeof setTimeout> | null = null\n\n  const flush = () => {\n    timer = null\n    if (!queued.length) return\n    const batch = queued\n    queued = []\n    try {\n      const body = JSON.stringify({ events: batch })\n      // sendBeacon survives unloads and never blocks; keepalive fetch is the\n      // fallback for browsers that refuse the payload.\n      if (!navigator.sendBeacon?.(endpoint, body)) {\n        void fetch(endpoint, {\n          method: 'POST',\n          body,\n          keepalive: true,\n          headers: { 'Content-Type': 'application/json' },\n        }).catch((): undefined => undefined)\n      }\n    } catch {\n      // Reporting never breaks the page.\n    }\n  }\n\n  const enqueue = (event: ErrorBeaconEvent) => {\n    if (sent >= maxPerPage) return\n    // Message + first stack line: enough identity to collapse a render loop\n    // without collapsing distinct errors that share a message.\n    const key = `${event.message}\\x00${(event.stack ?? '').split('\\n', 2).join('\\n')}`\n    if (seen.has(key)) return\n    seen.add(key)\n    sent += 1\n    queued.push(event)\n    if (!timer) timer = setTimeout(flush, FLUSH_DELAY_MS)\n  }\n  // Published AFTER the sample-rate return above, so an unsampled pageview\n  // reports nothing by either door rather than one by one and none by the\n  // other.\n  publishEvent = enqueue\n\n  window.addEventListener('error', (event) => {\n    try {\n      const error = event.error as Error | undefined\n      const message = clamp(error?.message ?? event.message, MAX_MESSAGE)\n      // Cross-origin scripts yield an opaque \"Script error.\" with nothing\n      // actionable attached; reporting it would only create a noisy group.\n      if (!message || message === 'Script error.') return\n      const pageUrl = scrubUrl(window.location.href)\n      const fullStack = error?.stack ? String(error.stack) : undefined\n      // A webview or extension that evaluated its own code into our page —\n      // see `isInjectedThirdPartyFrame`. Nothing we ship can be changed in\n      // response, so it is dropped on the same test as `Script error.`.\n      // Judged on the WHOLE stack, before the clamp: a frame of ours past the\n      // clamp still makes the error ours.\n      if (fullStack && isInjectedThirdPartyFrame(fullStack, pageUrl)) return\n      const stack = fullStack ? clamp(fullStack, MAX_STACK) : undefined\n      enqueue({\n        // MARKED, not dropped: a translator causes these and so does a real\n        // render divergence, and only a rate tells them apart.\n        kind: isHydrationMismatch(message) ? 'hydration' : 'error',\n        message,\n        stack,\n        source: scrubUrl(event.filename) || undefined,\n        line: typeof event.lineno === 'number' ? event.lineno : undefined,\n        col: typeof event.colno === 'number' ? event.colno : undefined,\n        url: pageUrl,\n      })\n    } catch {\n      // Never rethrow from an error handler.\n    }\n  })\n\n  window.addEventListener('unhandledrejection', (event) => {\n    try {\n      const reason = event.reason as Error | undefined\n      const message = clamp(describeRejectionReason(event.reason), MAX_MESSAGE)\n      if (!message) return\n      enqueue({\n        kind: 'unhandledrejection',\n        message,\n        stack: reason?.stack ? clamp(reason.stack, MAX_STACK) : undefined,\n        url: scrubUrl(window.location.href),\n      })\n    } catch {\n      // Never rethrow from an error handler.\n    }\n  })\n\n  // A batch waiting out its debounce when the page hides would be lost;\n  // `pagehide`/`visibilitychange` are the last reliable moments to send.\n  window.addEventListener('pagehide', flush)\n  document.addEventListener('visibilitychange', () => {\n    if (document.visibilityState === 'hidden') flush()\n  })\n}\n"],"names":["isForeignScriptUrl","stackFrameUrls","MAX_MESSAGE","MAX_STACK","FLUSH_DELAY_MS","scrubUrl","raw","url","URL","String","window","location","href","origin","pathname","clamp","value","max","slice","isInjectedThirdPartyFrame","stack","documentUrl","urls","length","every","HYDRATION_MINIFIED","HYDRATION_TEXT","isHydrationMismatch","message","test","describeRejectionReason","reason","shape","Error","undefined","named","map","part","trim","filter","Boolean","join","printed","keys","Object","installed","publishEvent","redispatchCaughtError","reportHandledError","error","options","thrown","kind","installErrorBeacon","endpoint","sampleRate","maxPerPage","Math","random","seen","Set","queued","sent","timer","flush","batch","body","JSON","stringify","events","navigator","sendBeacon","fetch","method","keepalive","headers","catch","enqueue","event","key","split","has","add","push","setTimeout","addEventListener","pageUrl","fullStack","source","filename","line","lineno","col","colno","document","visibilityState"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GAED,SAASA,kBAAkB,EAAEC,cAAc,QAAQ,sBAAkB;AA0BrE,MAAMC,cAAc;AACpB,MAAMC,YAAY;AAClB,MAAMC,iBAAiB;AAEvB,sEAAsE,GACtE,SAASC,SAASC,GAA8B;IAC9C,IAAI,CAACA,KAAK,OAAO;IACjB,IAAI;QACF,MAAMC,MAAM,IAAIC,IAAIC,OAAOH,MAAMI,OAAOC,QAAQ,CAACC,IAAI;QACrD,OAAO,GAAGL,IAAIM,MAAM,GAAGN,IAAIO,QAAQ,EAAE;IACvC,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,SAASC,MAAMC,KAAc,EAAEC,GAAW;IACxC,OAAOR,OAAOO,gBAAAA,QAAS,IAAIE,KAAK,CAAC,GAAGD;AACtC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCC,GACD,OAAO,SAASE,0BACdC,KAAa,EACbC,WAAmB;IAEnB,MAAMC,OAAOrB,eAAemB;IAC5B,kEAAkE;IAClE,IAAI,CAACE,KAAKC,MAAM,EAAE,OAAO;IACzB,OAAOD,KAAKE,KAAK,CACf,CAACjB,MAAQP,mBAAmBO,QAAQF,SAASE,SAASc;AAE1D;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,MAAMI,qBAAqB;AAC3B,MAAMC,iBACJ;AAEF,OAAO,SAASC,oBAAoBC,OAAe;IACjD,OAAOH,mBAAmBI,IAAI,CAACD,YAAYF,eAAeG,IAAI,CAACD;AACjE;AAEA;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASE,wBAAwBC,MAAe;IACrD,IAAI;YAWAC,MAAAA,aACAA,OAAAA;QAXF,IAAID,kBAAkBE,SAASF,OAAOH,OAAO,EAAE,OAAOG,OAAOH,OAAO;QACpE,IAAI,OAAOG,WAAW,UAAU,OAAOA;QACvC,IAAIA,WAAW,QAAQA,WAAWG,WAAW;YAC3C,OAAO,CAAC,6BAA6B,EAAEzB,OAAOsB,QAAQ,CAAC,CAAC;QAC1D;QACA,IAAI,OAAOA,WAAW,UAAU;YAC9B,OAAO,CAAC,6BAA6B,EAAE,OAAOA,OAAO,EAAE,EAAEtB,OAAOsB,QAAQ,CAAC,CAAC;QAC5E;QACA,MAAMC,QAAQD;QACd,MAAMI,QAAQ;aACZH,QAAAA,cAAAA,KAAK,CAAC,OAAO,YAAbA,cAAiBA,KAAK,CAAC,OAAO,YAA9BA,OAAkC;aAClCA,SAAAA,iBAAAA,KAAK,CAAC,UAAU,YAAhBA,iBAAoBA,KAAK,CAAC,aAAa,YAAvCA,QAA2C;SAC5C,CACEI,GAAG,CAAC,CAACC,OAAS5B,OAAO4B,eAAAA,OAAQ,IAAIC,IAAI,IACrCC,MAAM,CAACC;QACV,IAAIL,MAAMZ,MAAM,EAAE,OAAOY,MAAMM,IAAI,CAAC;QACpC,MAAMC,UAAUjC,OAAOsB;QACvB,IAAIW,WAAWA,YAAY,mBAAmB,OAAOA;QACrD,MAAMC,OAAOC,OAAOD,IAAI,CAACX,OAAOd,KAAK,CAAC,GAAG,IAAIuB,IAAI,CAAC;QAClD,OAAOE,OACH,CAAC,yCAAyC,EAAEA,KAAK,CAAC,CAAC,GACnD;IACN,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,IAAIE,YAAY;AAEhB;;;;;;CAMC,GACD,IAAIC,eAA2D;AAE/D;;;;;CAKC,GACD,SAASC,qBAAqB,QAAQ,+BAA2B;AAEjE;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,mBACdC,KAAc,EACdC,OAA2B;IAE3B,IAAI;;QACF,IAAI,CAACJ,cAAc;QACnB,MAAMK,SAASF;QACf,MAAMrB,UAAUb,cACdoC,0BAAAA,OAAQvB,OAAO,mBAAK,OAAOqB,UAAU,WAAWA,QAAQ,IACxD/C;QAEF,IAAI,CAAC0B,SAAS;QACdkB,aAAa;YACXM,MAAMrC,eAAMmC,2BAAAA,QAASE,IAAI,oBAAI,WAAW;YACxCxB;YACAR,OAAO+B,CAAAA,0BAAAA,OAAQ/B,KAAK,IAAGL,MAAMoC,OAAO/B,KAAK,EAAEjB,aAAa+B;YACxD3B,KAAKF,SAASK,OAAOC,QAAQ,CAACC,IAAI;QACpC;IACF,EAAE,eAAM;IACN,kEAAkE;IACpE;AACF;AAEA;;;CAGC,GACD,OAAO,SAASyC,mBAAmBH,OAA4B;;IAC7D,IAAI,OAAOxC,WAAW,eAAemC,WAAW;IAChDA,YAAY;IAEZ,MAAMS,mBAAWJ,2BAAAA,QAASI,QAAQ,mBAAI;IACtC,MAAMC,sBAAaL,2BAAAA,QAASK,UAAU,oBAAI;IAC1C,MAAMC,sBAAaN,2BAAAA,QAASM,UAAU,oBAAI;IAC1C,IAAIC,KAAKC,MAAM,MAAMH,YAAY;IAEjC,MAAMI,OAAO,IAAIC;IACjB,IAAIC,SAA6B,EAAE;IACnC,IAAIC,OAAO;IACX,IAAIC,QAA8C;IAElD,MAAMC,QAAQ;QACZD,QAAQ;QACR,IAAI,CAACF,OAAOtC,MAAM,EAAE;QACpB,MAAM0C,QAAQJ;QACdA,SAAS,EAAE;QACX,IAAI;YACF,MAAMK,OAAOC,KAAKC,SAAS,CAAC;gBAAEC,QAAQJ;YAAM;YAC5C,uEAAuE;YACvE,iDAAiD;YACjD,IAAI,EAACK,UAAUC,UAAU,oBAApBD,UAAUC,UAAU,MAApBD,WAAuBhB,UAAUY,QAAO;gBAC3C,KAAKM,MAAMlB,UAAU;oBACnBmB,QAAQ;oBACRP;oBACAQ,WAAW;oBACXC,SAAS;wBAAE,gBAAgB;oBAAmB;gBAChD,GAAGC,KAAK,CAAC,IAAiB1C;YAC5B;QACF,EAAE,eAAM;QACN,mCAAmC;QACrC;IACF;IAEA,MAAM2C,UAAU,CAACC;YAIqBA;QAHpC,IAAIhB,QAAQN,YAAY;QACxB,wEAAwE;QACxE,2DAA2D;QAC3D,MAAMuB,MAAM,GAAGD,MAAMlD,OAAO,CAAC,IAAI,EAAE,EAACkD,eAAAA,MAAM1D,KAAK,YAAX0D,eAAe,IAAIE,KAAK,CAAC,MAAM,GAAGvC,IAAI,CAAC,OAAO;QAClF,IAAIkB,KAAKsB,GAAG,CAACF,MAAM;QACnBpB,KAAKuB,GAAG,CAACH;QACTjB,QAAQ;QACRD,OAAOsB,IAAI,CAACL;QACZ,IAAI,CAACf,OAAOA,QAAQqB,WAAWpB,OAAO5D;IACxC;IACA,yEAAyE;IACzE,wEAAwE;IACxE,SAAS;IACT0C,eAAe+B;IAEfnE,OAAO2E,gBAAgB,CAAC,SAAS,CAACP;QAChC,IAAI;;YACF,MAAM7B,QAAQ6B,MAAM7B,KAAK;YACzB,MAAMrB,UAAUb,cAAMkC,yBAAAA,MAAOrB,OAAO,mBAAIkD,MAAMlD,OAAO,EAAE1B;YACvD,oEAAoE;YACpE,qEAAqE;YACrE,IAAI,CAAC0B,WAAWA,YAAY,iBAAiB;YAC7C,MAAM0D,UAAUjF,SAASK,OAAOC,QAAQ,CAACC,IAAI;YAC7C,MAAM2E,YAAYtC,CAAAA,yBAAAA,MAAO7B,KAAK,IAAGX,OAAOwC,MAAM7B,KAAK,IAAIc;YACvD,qEAAqE;YACrE,qEAAqE;YACrE,kEAAkE;YAClE,wEAAwE;YACxE,oCAAoC;YACpC,IAAIqD,aAAapE,0BAA0BoE,WAAWD,UAAU;YAChE,MAAMlE,QAAQmE,YAAYxE,MAAMwE,WAAWpF,aAAa+B;YACxD2C,QAAQ;gBACN,oEAAoE;gBACpE,uDAAuD;gBACvDzB,MAAMzB,oBAAoBC,WAAW,cAAc;gBACnDA;gBACAR;gBACAoE,QAAQnF,SAASyE,MAAMW,QAAQ,KAAKvD;gBACpCwD,MAAM,OAAOZ,MAAMa,MAAM,KAAK,WAAWb,MAAMa,MAAM,GAAGzD;gBACxD0D,KAAK,OAAOd,MAAMe,KAAK,KAAK,WAAWf,MAAMe,KAAK,GAAG3D;gBACrD3B,KAAK+E;YACP;QACF,EAAE,eAAM;QACN,uCAAuC;QACzC;IACF;IAEA5E,OAAO2E,gBAAgB,CAAC,sBAAsB,CAACP;QAC7C,IAAI;YACF,MAAM/C,SAAS+C,MAAM/C,MAAM;YAC3B,MAAMH,UAAUb,MAAMe,wBAAwBgD,MAAM/C,MAAM,GAAG7B;YAC7D,IAAI,CAAC0B,SAAS;YACdiD,QAAQ;gBACNzB,MAAM;gBACNxB;gBACAR,OAAOW,CAAAA,0BAAAA,OAAQX,KAAK,IAAGL,MAAMgB,OAAOX,KAAK,EAAEjB,aAAa+B;gBACxD3B,KAAKF,SAASK,OAAOC,QAAQ,CAACC,IAAI;YACpC;QACF,EAAE,eAAM;QACN,uCAAuC;QACzC;IACF;IAEA,sEAAsE;IACtE,uEAAuE;IACvEF,OAAO2E,gBAAgB,CAAC,YAAYrB;IACpC8B,SAAST,gBAAgB,CAAC,oBAAoB;QAC5C,IAAIS,SAASC,eAAe,KAAK,UAAU/B;IAC7C;AACF"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/error-beacon.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 * First-party browser error beacon (AGL-1538).\n *\n * Crashlytics does not exist for web, and adding a third-party error vendor\n * is a subprocessor-list decision that was explicitly deferred. This is the\n * first-party alternative: `window.onerror` / `unhandledrejection` handlers\n * that batch uncaught failures to the app's own `/api/errors` route, which\n * forwards them to Google Cloud Error Reporting — a processor already on the\n * list, alerting through the GCP stack that already pages (AGL-1502).\n *\n * Design constraints, in order:\n *\n * - **It must never become the outage.** Everything is wrapped; a failure to\n *   report is silence, not a thrown error. Batches are capped per page so an\n *   error thrown in a loop cannot DDoS our own API — after `maxPerPage`\n *   events the beacon disarms for the rest of the pageview.\n * - **No PII.** URLs are scrubbed to origin + pathname (query strings and\n *   fragments carry tokens and search terms), no user id, no cookies —\n *   the payload is the error text and where in the CODE it happened.\n *   Cross-origin scripts surface as the browser's opaque \"Script error.\"\n *   with no stack; those are dropped since they cannot be acted on.\n * - **Dedupe.** One page throwing the same error on every frame reports it\n *   once.\n *\n * Framework-free on purpose: the console mounts it from its root layout, the\n * tenant runtime from its own, and neither needs React here. Deliberately NO\n * 'use client' directive — inside this shared lib the directive forks the\n * module graph (AGL-52); every importer is already a client module.\n */\n\nimport { isCrossPoolDesync } from './cross-pool-desync'\nimport { isForeignScriptUrl, stackFrameUrls } from './foreign-script'\nimport { isStaleBuildError, recoverStaleBuildRejection } from './stale-build-error'\n\nexport interface ErrorBeaconEvent {\n  /**\n   * Which handler caught it — 'error' | 'unhandledrejection' — or the\n   * family it was labeled with: 'hydration', {@link AUTH_DESYNC_KIND},\n   * {@link CHUNK_LOAD_KIND}, or a caller's own kind for a handled error.\n   * Lands at `jsonPayload.kind`, where the alert policies filter on it.\n   */\n  kind: string\n  /** Error message, clamped. */\n  message: string\n  /** Stack trace when the thrown value carried one, clamped. */\n  stack?: string\n  /** Script URL for stackless `window.onerror` events, scrubbed. */\n  source?: string\n  line?: number\n  col?: number\n  /** Page URL, scrubbed to origin + pathname. */\n  url: string\n}\n\nexport interface ErrorBeaconOptions {\n  /** POST target; same-origin. Default `/api/errors`. */\n  endpoint?: string\n  /** 0..1 — fraction of pageviews that report at all. Default 1. */\n  sampleRate?: number\n  /** Max events reported per pageview before the beacon disarms. */\n  maxPerPage?: number\n}\n\nconst MAX_MESSAGE = 1_024\nconst MAX_STACK = 8_192\nconst FLUSH_DELAY_MS = 2_000\n\n/** Origin + pathname only — query strings and fragments never leave. */\nfunction scrubUrl(raw: string | null | undefined): string {\n  if (!raw) return ''\n  try {\n    const url = new URL(String(raw), window.location.href)\n    return `${url.origin}${url.pathname}`\n  } catch {\n    return ''\n  }\n}\n\nfunction clamp(value: unknown, max: number): string {\n  return String(value ?? '').slice(0, max)\n}\n\n/**\n * Was this thrown by a script somebody ELSE evaluated into our page?\n *\n * Three tells, all read off the frames' positions and none off a function\n * name — a name would be a denylist needing a new entry per vendor.\n *\n * **Every frame is the DOCUMENT.** Measured 2026-09-02 (AGL-2523) on\n * aglyn.com/pricing, reported as an error of ours:\n *\n *     sendDataToNative@https://aglyn.com/pricing:1:1325\n *     sendPageHideMessage@https://aglyn.com/pricing:1:4139\n *     @https://aglyn.com/pricing:1:6257\n *\n * `sendDataToNative` is the Meta in-app browser's native bridge, injected by\n * the Facebook/Instagram webview. In WebKit's format the code was evaluated\n * inline, so every frame is the document rather than a script we served.\n *\n * **Every frame is under a FOREIGN scheme.** Measured 2026-09-10 (AGL-2786) on\n * aglyn.com, the same bridge in the Android webview:\n *\n *     at sendDataToNative (iabjs://navigation_performance_logger_android:1:10632)\n *\n * That webview names its scripts under its own `iabjs://` scheme, and\n * extensions do the same under theirs — see `FOREIGN_SCRIPT_SCHEMES`.\n *\n * **Every frame is a script with NO URL** (AGL-3423). Measured on the\n * sign-up page and on aglyn.com/solutions/agencies:\n *\n *     at eval (<anonymous>)\n *     at predicate (eval at evaluate (:234:30), <anonymous>:11:37)\n *\n *     at <anonymous>:1:54\n *     at <anonymous>:1:64\n *\n * An automation driver's `evaluate` and a snippet pasted into devtools. Every\n * script we serve has a URL — a chunk, a CDN asset, or the document for an\n * inline one — so a frame whose position is `<anonymous>:line:col`, or code\n * `eval`'d by such a frame, was not served by us. See\n * {@link anonymousScriptFrameCount} for exactly which frames count.\n *\n * ⚑ Deliberately `every`, and deliberately compared against the document\n * rather than against our asset path. A rule like \"no frame under\n * `/_next/static/`\" would delete EVERY error from a self-hosted deployment\n * that serves its assets from a CDN, because none of its frames would match.\n * Comparing to the document cannot fail that way: a CDN frame is not the\n * document either, so it keeps the report.\n *\n * A stack may mix the tells frame by frame. Nothing we ship can be fixed in\n * response to any of them, which is the same test the opaque `Script error.`\n * cut already applies.\n *\n * The cost is honest and small: a throw from one of our own inline\n * bootstrap scripts looks the same and is dropped with it. That trade buys a\n * rule that needs no maintenance as new webviews and extensions appear.\n */\nexport function isInjectedThirdPartyFrame(\n  stack: string,\n  documentUrl: string,\n): boolean {\n  const urls = stackFrameUrls(stack)\n  // No frames parsed is not evidence of anything — keep the report. A stack\n  // with neither a URL nor an anonymous-script frame is exactly that: an\n  // empty frame list must never read as \"every frame is injected\".\n  if (!urls.length && !anonymousScriptFrameCount(stack)) return false\n  // Anonymous frames need no test of their own — they are injected by\n  // definition — so `every` over the URLs is `every` over the whole stack.\n  // One URL of ours, even as the origin of an `eval`, keeps the report.\n  return urls.every(\n    (url) => isForeignScriptUrl(url) || scrubUrl(url) === documentUrl,\n  )\n}\n\n/** A frame line, in V8's `at …` format or WebKit/Firefox's `fn@location`. */\nconst STACK_FRAME_LINE = /^\\s*at\\s|@/\n\n/**\n * A position in a script that has no URL.\n *\n * - `<anonymous>:line:col` — V8's name for such a script, both for a top-level\n *   snippet and as the position of code run through `eval`/`new Function`.\n * - `eval at …` — V8's origin of `eval`'d code. When OUR script ran the eval\n *   its URL is inside this origin, `stackFrameUrls` reads it, and the report\n *   is kept; that is how the marketing plugin's `runJs` step stays reported.\n * - `debugger eval code:line:col` — Firefox's devtools console, in the\n *   `fn@location` format WebKit also uses.\n *\n * ⚑ A BARE `(<anonymous>)` with no line and column is NOT one of these. It is\n * how V8 prints a builtin — `at Array.forEach (<anonymous>)`,\n * `at JSON.parse (<anonymous>)` — and a builtin is called by whoever called\n * it, including us.\n */\nconst ANONYMOUS_SCRIPT_POSITION =\n  /<anonymous>:\\d+:\\d+|\\beval at\\s|\\bdebugger eval code:\\d+:\\d+/\n\n/** How many frames of this stack are in a script with no URL at all. */\nexport function anonymousScriptFrameCount(stack: string): number {\n  let count = 0\n  for (const line of stack.split('\\n')) {\n    if (STACK_FRAME_LINE.test(line) && ANONYMOUS_SCRIPT_POSITION.test(line)) {\n      count += 1\n    }\n  }\n  return count\n}\n\n/**\n * Browser notices that are not failures, and that no fix of ours could act on.\n *\n * `ResizeObserver loop completed with undelivered notifications` (and its older\n * wording, `ResizeObserver loop limit exceeded`) is the browser saying it\n * deferred some resize callbacks to the next frame. Nothing threw: the event\n * carries no error object and no stack, and every observer is still\n * delivered. It arrived from the Besigner on 2026-09-26 and paged. Dropped, on\n * the browser's exact wording.\n */\nconst BENIGN_BROWSER_NOTICE =\n  /^(?:Uncaught )?(?:Error: )?ResizeObserver loop (?:completed with undelivered notifications|limit exceeded)/\n\nexport function isBenignBrowserNotice(message: string): boolean {\n  return BENIGN_BROWSER_NOTICE.test(message)\n}\n\n/**\n * `kind` for Firebase's `auth/tenant-id-mismatch` — a sibling tab signed in to\n * another account pool (AGL-3280). The console recovers the tab by reloading\n * it once it is hidden and deliberately leaves the rejection unhandled so it\n * is still seen; this label is what lets it be seen by RATE instead of paging\n * on each of the several rejections one storage event raises.\n */\nexport const AUTH_DESYNC_KIND = 'auth-desync'\n\n/**\n * `kind` for a chunk the document names and the origin no longer serves\n * (AGL-3279). Every boundary reloads once for it; what still arrives is the\n * failure the reload did not cure. One of those is a visitor on a bad\n * connection; a burst of them is a broken deploy, which only a rate can tell.\n */\nexport const CHUNK_LOAD_KIND = 'chunk-load'\n\n/**\n * The label for a fault we RECOVER from and still want to see, or undefined.\n *\n * These could be ours, so unlike an injected stack they are never dropped:\n * they are written at full severity under their own `kind`, the per-entry\n * policy excludes that kind, and a rate policy watches it — the same split\n * `hydration` already has.\n */\nexport function recoveredErrorKind(error: unknown): string | undefined {\n  try {\n    if (isCrossPoolDesync(error)) return AUTH_DESYNC_KIND\n    if (isStaleBuildError(error)) return CHUNK_LOAD_KIND\n  } catch {\n    // A getter that throws leaves the event unlabeled, never unreported.\n  }\n  return undefined\n}\n\n/**\n * React's hydration-mismatch family, which a page TRANSLATOR causes and a\n * real render divergence also causes.\n *\n * These are `onRecoverableError` reports, not crashes: React has already\n * re-rendered on the client and the visitor has a working page. They arrive\n * here as uncaught errors only because React re-throws them to `reportError`.\n *\n * They are marked rather than dropped, and the distinction is the whole\n * design. Dropping would hide a real hydration regression, which is a genuine\n * and expensive bug; the entries stay in `client-errors` at full severity and\n * still group in Error Reporting. What the mark buys is that the log-match\n * policy can stop paging on a single report, while a rate-based policy on the\n * same mark still catches a systemic one.\n *\n * ⚠️ THE MARK IS NOT A VERDICT, and the one cluster this repo has measured is\n * why. Eight #418 reports arrived inside a nine-minute window on 2026-09-01,\n * on one build, and the three pages they came from were exactly the three\n * carrying a form — `/`, `/pricing` and the solutions pages reported nothing\n * in the same window, which no browser-side rewrite would respect. A placed\n * form was expanding inside its own grafted subtree, so every page carrying\n * one shipped six nested `<form>` elements; nested forms are invalid HTML, the\n * parser dropped the inner ones, and the client tree disagreed with the server\n * tree. The visible cost was a submission the route never received, because\n * the native submit came from an unhandled ancestor and the browser fell back\n * to a GET with the visitor's name, email and message in the address bar. The\n * reports stopped because the nesting was fixed, roughly a quarter of an hour\n * after the last one.\n *\n * So a rate low enough not to page is a reason to READ the entry — the page\n * it names, and whether the set of pages has a shape — never a reason to\n * assume somebody's extension.\n */\nconst HYDRATION_MINIFIED = /Minified React error #(?:418|423|425)\\b/\nconst HYDRATION_TEXT =\n  /Hydration failed because|Text content does not match server-rendered HTML|There was an error while hydrating/\n\nexport function isHydrationMismatch(message: string): boolean {\n  return HYDRATION_MINIFIED.test(message) || HYDRATION_TEXT.test(message)\n}\n\n/**\n * WHAT A REJECTED PROMISE ACTUALLY CARRIED (AGL-3279).\n *\n * `unhandledrejection` hands over whatever was passed to `reject`, and only\n * an `Error` brings a message and a stack. A rejection with anything else —\n * an API's `{ code, message }` object, a `DOMException` from an aborted\n * fetch, a bare string, a `Response` — used to be reported as the literal\n * words \"Unhandled promise rejection\" with no stack and no other field,\n * which names the handler rather than the failure. One such report arrived\n * on 2026-09-21 from the Besigner editor and there is nothing in it to act\n * on: no message, no stack, no code, nothing but the page.\n *\n * So the value is DESCRIBED rather than defaulted. In order of how much a\n * reader can do with it: the error's own message; a string as itself; a\n * `name`/`code`/`message` shape assembled from whatever of those it has —\n * the shape every Firebase, DOM and fetch rejection takes; the value's own\n * `toString` when it says more than `[object Object]`; and last its own\n * keys, which at least name what kind of thing rejected.\n *\n * Nothing here may throw: a getter on the reason can, `toString` can, and\n * a describer that throws inside the rejection handler loses the report it\n * was called to improve.\n */\nexport function describeRejectionReason(reason: unknown): string {\n  try {\n    if (reason instanceof Error && reason.message) return reason.message\n    if (typeof reason === 'string') return reason\n    if (reason === null || reason === undefined) {\n      return `Unhandled promise rejection (${String(reason)})`\n    }\n    if (typeof reason !== 'object') {\n      return `Unhandled promise rejection (${typeof reason}: ${String(reason)})`\n    }\n    const shape = reason as Record<string, unknown>\n    const named = [\n      shape['name'] ?? shape['code'] ?? '',\n      shape['message'] ?? shape['statusText'] ?? '',\n    ]\n      .map((part) => String(part ?? '').trim())\n      .filter(Boolean)\n    if (named.length) return named.join(': ')\n    const printed = String(reason)\n    if (printed && printed !== '[object Object]') return printed\n    const keys = Object.keys(shape).slice(0, 12).join(', ')\n    return keys\n      ? `Unhandled promise rejection (object with ${keys})`\n      : 'Unhandled promise rejection (empty object)'\n  } catch {\n    return 'Unhandled promise rejection (undescribable)'\n  }\n}\n\n/**\n * How many frames a thrown error keeps, on a pageview that reports (AGL-3423).\n *\n * V8 keeps ten by default, and ten is not enough to find where a render loop\n * STARTED. The Besigner's one React #185 report (2026-09-24) was a\n * react-final-form field's `setState` inside final-form's `notify` loop, and\n * every one of its ten frames was inside those two libraries: the component\n * whose update fed the loop was cut off below them. Fifty reaches past a\n * form library's own frames to ours, and still fits the {@link MAX_STACK}\n * clamp at the length a minified frame line has.\n */\nexport const BEACON_STACK_TRACE_LIMIT = 50\n\n/**\n * Raises the engine's frame limit to `limit`, never lowers it. V8 and\n * JavaScriptCore read `Error.stackTraceLimit`; an engine that does not has no\n * such number, and is left without one rather than handed a property it\n * ignores. It applies to errors created after the call, which is why the\n * beacon sets it at install, at module scope of the app's first client chunk.\n */\nexport function raiseStackTraceLimit(limit: number): void {\n  try {\n    const engine = Error as ErrorConstructor & { stackTraceLimit?: number }\n    const current = engine.stackTraceLimit\n    if (typeof current !== 'number' || current >= limit) return\n    engine.stackTraceLimit = limit\n  } catch {\n    // A frozen or exotic `Error` keeps its own limit.\n  }\n}\n\nlet installed = false\n\n/**\n * The live beacon's `enqueue`, published for {@link reportHandledError}.\n *\n * Null until `installErrorBeacon` runs, and null forever on a surface that\n * never installs one — so a caught error reported from a page with no beacon\n * is silently dropped rather than throwing inside somebody's error handler.\n */\nlet publishEvent: ((event: ErrorBeaconEvent) => void) | null = null\n\n/**\n * Re-export so `error-beacon` stays the one name a caller has to know for\n * browser error reporting. The definition lives in its own module because a\n * boundary that imports it must not pull the installer below into a chunk\n * every visitor downloads.\n */\nexport { redispatchCaughtError } from './redispatch-caught-error'\n\n/**\n * Report an error the code ALREADY CAUGHT.\n *\n * The two window handlers below see only what nothing caught. A `catch` that\n * swallows its error is invisible to them by construction, which is the whole\n * failure mode this exists for: a background write that can only fail\n * silently is one that stays broken for as long as nobody thinks to look.\n *\n * It rides the same queue as an uncaught error, which is the point — the\n * dedupe collapses a failure that repeats on every edit into one report, and\n * `maxPerPage` bounds it, so a call site in a loop cannot turn a broken\n * feature into a flood. Reporting is never worth an exception of its own, so\n * every path here returns rather than throws.\n */\nexport function reportHandledError(\n  error: unknown,\n  options?: { kind?: string },\n): void {\n  try {\n    if (!publishEvent) return\n    const thrown = error as Error | undefined\n    const message = clamp(\n      thrown?.message ?? (typeof error === 'string' ? error : ''),\n      MAX_MESSAGE,\n    )\n    if (!message) return\n    publishEvent({\n      kind: clamp(options?.kind ?? 'handled', 32),\n      message,\n      stack: thrown?.stack ? clamp(thrown.stack, MAX_STACK) : undefined,\n      url: scrubUrl(window.location.href),\n    })\n  } catch {\n    // An observer that throws is worse than one that misses an event.\n  }\n}\n\n/**\n * Installs the handlers once per page. Safe to call from module scope of a\n * client bundle: it no-ops during SSR and on repeat calls.\n */\nexport function installErrorBeacon(options?: ErrorBeaconOptions): void {\n  if (typeof window === 'undefined' || installed) return\n  installed = true\n\n  const endpoint = options?.endpoint ?? '/api/errors'\n  const sampleRate = options?.sampleRate ?? 1\n  const maxPerPage = options?.maxPerPage ?? 10\n  // Only a sampled pageview REPORTS. Every pageview recovers a stale build\n  // (the rejection handler below), because a tab left on a dead deploy is a\n  // visitor's problem whether or not its errors are counted.\n  const sampled = Math.random() < sampleRate\n  if (sampled) raiseStackTraceLimit(BEACON_STACK_TRACE_LIMIT)\n\n  const seen = new Set<string>()\n  let queued: ErrorBeaconEvent[] = []\n  let sent = 0\n  let timer: ReturnType<typeof setTimeout> | null = null\n\n  const flush = () => {\n    timer = null\n    if (!queued.length) return\n    const batch = queued\n    queued = []\n    try {\n      const body = JSON.stringify({ events: batch })\n      // sendBeacon survives unloads and never blocks; keepalive fetch is the\n      // fallback for browsers that refuse the payload.\n      if (!navigator.sendBeacon?.(endpoint, body)) {\n        void fetch(endpoint, {\n          method: 'POST',\n          body,\n          keepalive: true,\n          headers: { 'Content-Type': 'application/json' },\n        }).catch((): undefined => undefined)\n      }\n    } catch {\n      // Reporting never breaks the page.\n    }\n  }\n\n  const enqueue = (event: ErrorBeaconEvent) => {\n    if (!sampled || sent >= maxPerPage) return\n    // Message + first stack line: enough identity to collapse a render loop\n    // without collapsing distinct errors that share a message.\n    const key = `${event.message}\\x00${(event.stack ?? '').split('\\n', 2).join('\\n')}`\n    if (seen.has(key)) return\n    seen.add(key)\n    sent += 1\n    queued.push(event)\n    if (!timer) timer = setTimeout(flush, FLUSH_DELAY_MS)\n  }\n  // Null on an unsampled pageview, so it reports nothing by either door\n  // rather than one by one and none by the other.\n  publishEvent = sampled ? enqueue : null\n\n  window.addEventListener('error', (event) => {\n    try {\n      const error = event.error as Error | undefined\n      const message = clamp(error?.message ?? event.message, MAX_MESSAGE)\n      // Cross-origin scripts yield an opaque \"Script error.\" with nothing\n      // actionable attached; reporting it would only create a noisy group.\n      if (!message || message === 'Script error.') return\n      if (isBenignBrowserNotice(message)) return\n      const pageUrl = scrubUrl(window.location.href)\n      const fullStack = error?.stack ? String(error.stack) : undefined\n      // A webview or extension that evaluated its own code into our page —\n      // see `isInjectedThirdPartyFrame`. Nothing we ship can be changed in\n      // response, so it is dropped on the same test as `Script error.`.\n      // Judged on the WHOLE stack, before the clamp: a frame of ours past the\n      // clamp still makes the error ours.\n      if (fullStack && isInjectedThirdPartyFrame(fullStack, pageUrl)) return\n      const stack = fullStack ? clamp(fullStack, MAX_STACK) : undefined\n      enqueue({\n        // MARKED, not dropped: a translator causes a hydration mismatch and\n        // so does a real render divergence, and a recovered fault is still a\n        // fault. Only a rate tells either apart from noise.\n        kind:\n          recoveredErrorKind(error ?? { message }) ??\n          (isHydrationMismatch(message) ? 'hydration' : 'error'),\n        message,\n        stack,\n        source: scrubUrl(event.filename) || undefined,\n        line: typeof event.lineno === 'number' ? event.lineno : undefined,\n        col: typeof event.colno === 'number' ? event.colno : undefined,\n        url: pageUrl,\n      })\n    } catch {\n      // Never rethrow from an error handler.\n    }\n  })\n\n  window.addEventListener('unhandledrejection', (event) => {\n    try {\n      // An `import()` of a chunk this document names and the origin dropped,\n      // which no boundary saw. Recovered by a reload once the tab is hidden,\n      // and, like a boundary's reload, not reported: see\n      // `recoverStaleBuildRejection`. A tab whose recovery is spent still\n      // reports it, as `chunk-load`.\n      if (recoverStaleBuildRejection(event.reason)) return\n      const reason = event.reason as Error | undefined\n      const message = clamp(describeRejectionReason(event.reason), MAX_MESSAGE)\n      if (!message) return\n      const pageUrl = scrubUrl(window.location.href)\n      const fullStack = reason?.stack ? String(reason.stack) : undefined\n      // The same injected-code drop as an uncaught error: a rejection raised\n      // by a devtools snippet or an automation driver's `evaluate` is no more\n      // ours for having been a promise.\n      if (fullStack && isInjectedThirdPartyFrame(fullStack, pageUrl)) return\n      enqueue({\n        kind: recoveredErrorKind(event.reason) ?? 'unhandledrejection',\n        message,\n        stack: fullStack ? clamp(fullStack, MAX_STACK) : undefined,\n        url: pageUrl,\n      })\n    } catch {\n      // Never rethrow from an error handler.\n    }\n  })\n\n  // A batch waiting out its debounce when the page hides would be lost;\n  // `pagehide`/`visibilitychange` are the last reliable moments to send.\n  window.addEventListener('pagehide', flush)\n  document.addEventListener('visibilitychange', () => {\n    if (document.visibilityState === 'hidden') flush()\n  })\n}\n"],"names":["isCrossPoolDesync","isForeignScriptUrl","stackFrameUrls","isStaleBuildError","recoverStaleBuildRejection","MAX_MESSAGE","MAX_STACK","FLUSH_DELAY_MS","scrubUrl","raw","url","URL","String","window","location","href","origin","pathname","clamp","value","max","slice","isInjectedThirdPartyFrame","stack","documentUrl","urls","length","anonymousScriptFrameCount","every","STACK_FRAME_LINE","ANONYMOUS_SCRIPT_POSITION","count","line","split","test","BENIGN_BROWSER_NOTICE","isBenignBrowserNotice","message","AUTH_DESYNC_KIND","CHUNK_LOAD_KIND","recoveredErrorKind","error","undefined","HYDRATION_MINIFIED","HYDRATION_TEXT","isHydrationMismatch","describeRejectionReason","reason","shape","Error","named","map","part","trim","filter","Boolean","join","printed","keys","Object","BEACON_STACK_TRACE_LIMIT","raiseStackTraceLimit","limit","engine","current","stackTraceLimit","installed","publishEvent","redispatchCaughtError","reportHandledError","options","thrown","kind","installErrorBeacon","endpoint","sampleRate","maxPerPage","sampled","Math","random","seen","Set","queued","sent","timer","flush","batch","body","JSON","stringify","events","navigator","sendBeacon","fetch","method","keepalive","headers","catch","enqueue","event","key","has","add","push","setTimeout","addEventListener","pageUrl","fullStack","source","filename","lineno","col","colno","document","visibilityState"],"mappings":"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"}

package/src/lib/app-utils/expand-repeatables.d.ts

@@ -116,27 +116,27 @@ export declare function repeatedRecords(node: unknown, dataset: RepeatableDatase
 /**
  * Does this tree contain anything {@link expandRepeatables} would expand?
  *
- * The datasets read is the largest on the render path — up to two pages of
- * {@link REPEAT_MAX_RECORDS} records for every dataset a page repeats over —
- * and a page that repeats over nothing should pay none of it (AGL-1440).
+ * The rows read is the largest on the render path — up to two pages of
+ * {@link REPEAT_MAX_RECORDS} records for every key a page repeats over — and a
+ * page that repeats over nothing should pay none of it (AGL-1440).
  *
  * Any gate on that read has to ask EXACTLY the question the expansion asks,
- * which is why this and {@link repeatDatasetKeys} share the one predicate
+ * which is why this and {@link repeatKeys} share the one predicate
  * `expandRepeatables` looks keys up with, {@link repeatKey}. A gate that is
  * even slightly stricter than the expansion is not a saving: it is a published
  * page that quietly renders one template row where the author put a list.
  */
 export declare function hasRepeatableNodes(nodes: Record<NodeId, unknown> | null | undefined): boolean;
 /**
- * Every dataset key this tree repeats over — a dataset id or a display name,
- * exactly as {@link expandRepeatables} looks it up — sorted and without
- * repeats.
+ * Every key this tree repeats over, exactly as {@link expandRepeatables} looks
+ * it up — sorted and without repeats.
  *
- * What the tenant compose reads, so a page loads the datasets it renders and
- * not every dataset its site may see. Built on the same predicate as
+ * What the tenant compose asks the repeat-rows contract for
+ * (`plugin-manager/repeat-rows.ts`), so a page loads the rows it renders and
+ * not everything its site may see. Built on the same predicate as
  * {@link hasRepeatableNodes} for the reason given there.
  */
-export declare function repeatDatasetKeys(nodes: Record<NodeId, unknown> | null | undefined): string[];
+export declare function repeatKeys(nodes: Record<NodeId, unknown> | null | undefined): string[];
 /**
  * Repeats (AGL-103, AGL-3111): any node carrying `props.repeatDataset` (a
  * dataset id or display name) renders once per record of that dataset, with

package/src/lib/app-utils/expand-repeatables.js

@@ -169,12 +169,12 @@ function substituteValue(value, context) {
 /**
  * Does this tree contain anything {@link expandRepeatables} would expand?
  *
- * The datasets read is the largest on the render path — up to two pages of
- * {@link REPEAT_MAX_RECORDS} records for every dataset a page repeats over —
- * and a page that repeats over nothing should pay none of it (AGL-1440).
+ * The rows read is the largest on the render path — up to two pages of
+ * {@link REPEAT_MAX_RECORDS} records for every key a page repeats over — and a
+ * page that repeats over nothing should pay none of it (AGL-1440).
  *
  * Any gate on that read has to ask EXACTLY the question the expansion asks,
- * which is why this and {@link repeatDatasetKeys} share the one predicate
+ * which is why this and {@link repeatKeys} share the one predicate
  * `expandRepeatables` looks keys up with, {@link repeatKey}. A gate that is
  * even slightly stricter than the expansion is not a saving: it is a published
  * page that quietly renders one template row where the author put a list.
@@ -183,14 +183,14 @@ function substituteValue(value, context) {
     return Object.values(nodes).some((node)=>repeatKey(node) !== '');
 }
 /**
- * Every dataset key this tree repeats over — a dataset id or a display name,
- * exactly as {@link expandRepeatables} looks it up — sorted and without
- * repeats.
+ * Every key this tree repeats over, exactly as {@link expandRepeatables} looks
+ * it up — sorted and without repeats.
  *
- * What the tenant compose reads, so a page loads the datasets it renders and
- * not every dataset its site may see. Built on the same predicate as
+ * What the tenant compose asks the repeat-rows contract for
+ * (`plugin-manager/repeat-rows.ts`), so a page loads the rows it renders and
+ * not everything its site may see. Built on the same predicate as
  * {@link hasRepeatableNodes} for the reason given there.
- */ export function repeatDatasetKeys(nodes) {
+ */ export function repeatKeys(nodes) {
     const keys = new Set();
     for (const node of Object.values(nodes != null ? nodes : {})){
         const key = repeatKey(node);

package/src/lib/app-utils/expand-repeatables.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/expand-repeatables.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 { AglynNodeSchema, NodeId } from '../foundation'\nimport {\n  applyDatasetQuery,\n  parseDatasetFilter,\n  parseDatasetSort,\n} from './dataset-query'\n\n/** Namespaces cloned template ids per container/record. */\nexport const REPEAT_NODE_ID_PREFIX = 'rep__'\n\n/**\n * `{{item.field}}` token, plus an optional single reference hop\n * (`{{item.author.name}}`, AGL-180). One hop only — the pattern itself is\n * the depth guard, so cycles can't recurse.\n */\nconst ITEM_TOKEN_PATTERN =\n  /\\{\\{\\s*item\\.([A-Za-z][A-Za-z0-9_]*)(?:\\.([A-Za-z][A-Za-z0-9_]*))?\\s*\\}\\}/g\n\n/** Hard bound on rows a single repeatable renders, before `repeatLimit`. */\nexport const REPEAT_MAX_RECORDS = 100\n\nexport interface RepeatableDataset {\n  /**\n   * Row value maps, in display order. Rows carry `$id` (needed to resolve\n   * incoming references); values may be typed (AGL-177), stringified at\n   * substitution.\n   */\n  records: Array<Record<string, unknown>>\n  /** Typed model (AGL-177); required for reference-hop bindings. */\n  model?: import('./dataset-models').DatasetModel\n}\n\ninterface SubstituteContext {\n  record: Record<string, unknown>\n  /** Model of the repeated dataset (reference hops need field configs). */\n  model?: import('./dataset-models').DatasetModel\n  /** All host datasets keyed by id (and name) for hop resolution. */\n  datasetsByKey?: Record<string, RepeatableDataset | undefined>\n}\n\nconst displayValue = (value: unknown): string =>\n  Array.isArray(value) ? value.join(', ') : String(value)\n\n/** Resolves `{{item.ref.field}}`: FKey(s) → target document field value. */\nfunction resolveReferenceHop(\n  context: SubstituteContext,\n  fieldId: string,\n  targetFieldId: string,\n): string | null {\n  const field = context.model?.fields?.[fieldId]\n  if (field?.type !== 'reference' || !field.reference?.datasetId) return null\n  const target = context.datasetsByKey?.[field.reference.datasetId]\n  if (!target) return null\n  const keys = context.record[fieldId]\n  const ids = Array.isArray(keys) ? keys : keys != null ? [keys] : []\n  const resolved = ids\n    .map((id) => {\n      const match = target.records.find((row) => row['$id'] === id)\n      const value = match?.[targetFieldId]\n      return value != null ? displayValue(value) : null\n    })\n    .filter((value): value is string => value != null)\n  return resolved.length ? resolved.join(', ') : null\n}\n\nfunction substituteValue(\n  value: unknown,\n  context: SubstituteContext,\n): unknown {\n  const { record } = context\n  if (typeof value === 'string') {\n    return value.replace(\n      ITEM_TOKEN_PATTERN,\n      (token, field: string, hop?: string) => {\n        if (hop) {\n          const resolved = resolveReferenceHop(context, field, hop)\n          return resolved != null ? resolved : token\n        }\n        return record[field] != null ? displayValue(record[field]) : token\n      },\n    )\n  }\n  if (Array.isArray(value)) {\n    return value.map((entry) => substituteValue(entry, context))\n  }\n  if (value && typeof value === 'object') {\n    const next: Record<string, unknown> = {}\n    for (const [key, entry] of Object.entries(value)) {\n      next[key] = substituteValue(entry, context)\n    }\n    return next\n  }\n  return value\n}\n\n/**\n * The key a node repeats over, trimmed, or `''` when it repeats over nothing.\n *\n * The one predicate every repeat question is asked through: the expansion, the\n * datasets-read gate below, the reusable-component graft that moves a\n * placement's repeat onto the element it becomes, and the besigner's preview\n * and badge. Two copies of it are how a `.trim()` on one side and not the\n * other becomes an empty list on a customer's page.\n */\nexport const repeatKey = (node: unknown): string => {\n  const key = (node as { props?: { repeatDataset?: unknown } })?.props\n    ?.repeatDataset\n  return typeof key === 'string' ? key.trim() : ''\n}\n\n/**\n * Makes an element that holds children repeat ITSELF, once per record, instead\n * of what is inside it (AGL-3111): a card whose contents are the design, rather\n * than a list whose contents are the item.\n *\n * Persisted in screen, layout and component documents — never rename. `'true'`\n * counts too, because a switch round-tripped through a text-shaped store comes\n * back as the string.\n */\nexport const REPEAT_SELF_PROP = 'repeatSelf'\n\n/**\n * Every prop that directs a repeat. They are instructions to the composition,\n * never attributes of the element: the expansion consumes them from every node\n * it expands and every copy it makes, so a published element never carries\n * one. Persisted — never rename.\n */\nexport const REPEAT_DIRECTIVE_PROPS: readonly string[] = [\n  'repeatDataset',\n  'repeatLimit',\n  'repeatFilter',\n  'repeatSort',\n  REPEAT_SELF_PROP,\n]\n\n/**\n * What a repeating node copies once per record (AGL-3111).\n *\n * - `children` — what is inside it. The node stays one element around the\n *   copies: the list, grid or gallery they fill. This is how a Stack has\n *   always repeated (AGL-103), and a stored Stack names neither scope.\n * - `self` — the node itself, with everything inside it. What a leaf and a\n *   component instance repeat, and what any element carrying\n *   {@link REPEAT_SELF_PROP} repeats.\n */\nexport type RepeatScope = 'self' | 'children'\n\n/**\n * Which scope a repeating node has, read off the node alone so the published\n * page's composition and the besigner decide it identically.\n *\n * {@link REPEAT_SELF_PROP} decides it whenever the node carries one, which is\n * every repeat the Attributes panel writes. Without one the node's own shape\n * decides, and it decides CONSERVATIVELY: anything that holds a child list —\n * a Stack, empty or not — keeps repeating its children, and only a node with\n * no child list at all repeats itself. A stored repeat predates the prop, so\n * this branch is the one that has to render it unchanged, and an author who\n * named a dataset before filling the container in would otherwise come back to\n * a hundred empty copies of it.\n *\n * A component instance never reaches that branch: the graft stamps the prop on\n * the element it becomes, whose children are the component's own.\n */\nexport function repeatScope(node: unknown): RepeatScope {\n  const { props, nodes } = (node ?? {}) as {\n    props?: Record<string, unknown>\n    nodes?: unknown\n  }\n  // `'true'`/`'false'` too: a switch round-tripped through a text-shaped\n  // store comes back as the string it was written as.\n  const self = props?.[REPEAT_SELF_PROP]\n  if (self === true || self === 'true') return 'self'\n  if (self === false || self === 'false') return 'children'\n  return Array.isArray(nodes) ? 'children' : 'self'\n}\n\n/**\n * One record's values put into `{{item.field}}` tokens, anywhere in a props\n * map — the substitution {@link expandRepeatables} makes on every copy it\n * builds, for a caller that already knows which record it is rendering.\n *\n * The besigner's canvas is that caller (AGL-3111): the element an author\n * edits IS the first copy, so it draws with the first record's values while\n * the node it saves keeps the tokens. Exported rather than reimplemented\n * because a canvas that resolved a token differently from the page would be\n * showing the author a page that does not exist.\n */\nexport function substituteRecordTokens<T>(\n  props: T,\n  context: {\n    record: Record<string, unknown>\n    /** Model of the repeated rows; reference hops need field configs. */\n    model?: import('./dataset-models').DatasetModel\n    /** Rows by key, for a one-hop reference (AGL-180). */\n    datasetsByKey?: Record<string, RepeatableDataset | undefined>\n  },\n): T {\n  return substituteValue(props, context) as T\n}\n\n/** The node minus its repeat directives, or the node itself when it has none. */\nexport function withoutRepeatDirective<N>(node: N): N {\n  const props = (node as { props?: Record<string, unknown> })?.props\n  if (!props || !REPEAT_DIRECTIVE_PROPS.some((key) => key in props)) {\n    return node\n  }\n  const kept = { ...props }\n  for (const key of REPEAT_DIRECTIVE_PROPS) delete kept[key]\n  return { ...node, props: kept }\n}\n\n/**\n * The records a repeating node renders, in order (AGL-181): its filter and sort\n * evaluated over the rows, then its limit, never past\n * {@link REPEAT_MAX_RECORDS}. An unparseable filter or sort fails open.\n *\n * Shared by the expansion and the besigner's canvas preview and badge, so the\n * canvas can never show a copy or a count the published page does not.\n */\nexport function repeatedRecords(\n  node: unknown,\n  dataset: RepeatableDataset | undefined,\n): Array<Record<string, unknown>> {\n  const props = ((node as { props?: unknown })?.props ?? {}) as Record<\n    string,\n    unknown\n  >\n  const where = parseDatasetFilter(String(props['repeatFilter'] ?? ''))\n  const orderBy = parseDatasetSort(String(props['repeatSort'] ?? ''))\n  const limit = Number(props['repeatLimit'])\n  return applyDatasetQuery(dataset?.model, dataset?.records ?? [], {\n    ...(where ? { where: [where] } : {}),\n    ...(orderBy ? { orderBy } : {}),\n  }).slice(\n    0,\n    Number.isFinite(limit) && limit > 0\n      ? Math.min(limit, REPEAT_MAX_RECORDS)\n      : REPEAT_MAX_RECORDS,\n  )\n}\n\n/**\n * Does this tree contain anything {@link expandRepeatables} would expand?\n *\n * The datasets read is the largest on the render path — up to two pages of\n * {@link REPEAT_MAX_RECORDS} records for every dataset a page repeats over —\n * and a page that repeats over nothing should pay none of it (AGL-1440).\n *\n * Any gate on that read has to ask EXACTLY the question the expansion asks,\n * which is why this and {@link repeatDatasetKeys} share the one predicate\n * `expandRepeatables` looks keys up with, {@link repeatKey}. A gate that is\n * even slightly stricter than the expansion is not a saving: it is a published\n * page that quietly renders one template row where the author put a list.\n */\nexport function hasRepeatableNodes(\n  nodes: Record<NodeId, unknown> | null | undefined,\n): boolean {\n  if (!nodes) return false\n  return Object.values(nodes).some((node) => repeatKey(node) !== '')\n}\n\n/**\n * Every dataset key this tree repeats over — a dataset id or a display name,\n * exactly as {@link expandRepeatables} looks it up — sorted and without\n * repeats.\n *\n * What the tenant compose reads, so a page loads the datasets it renders and\n * not every dataset its site may see. Built on the same predicate as\n * {@link hasRepeatableNodes} for the reason given there.\n */\nexport function repeatDatasetKeys(\n  nodes: Record<NodeId, unknown> | null | undefined,\n): string[] {\n  const keys = new Set<string>()\n  for (const node of Object.values(nodes ?? {})) {\n    const key = repeatKey(node)\n    if (key) keys.add(key)\n  }\n  return [...keys].sort()\n}\n\n/**\n * Repeats (AGL-103, AGL-3111): any node carrying `props.repeatDataset` (a\n * dataset id or display name) renders once per record of that dataset, with\n * `{{item.field}}` tokens in the copied string props replaced by the record's\n * values (unknown fields keep the literal token, like variable bindings).\n *\n * What is copied is the node's {@link repeatScope}:\n *\n * - `children` — its children are the item template. The node stays, and its\n *   child list becomes the copies, record by record. Its own props are not the\n *   template, so no token in them is substituted.\n * - `self` — the node and everything inside it are the template. The copies\n *   take the node's place in its parent's child list, and every prop in the\n *   subtree is substituted, the node's own included.\n *\n * - Copy ids are namespaced `rep__{repeatId}__{index}__…` — the repeat's own\n *   id, then the template node's — so repeats never collide, including inside\n *   grafted reusable components. A self-scoped node's first copy is\n *   `rep__{id}__0__{id}`. Run this AFTER `composeReusableComponentNodes` and\n *   BEFORE binding resolution.\n * - Rows are the node's {@link repeatedRecords}.\n * - The repeat directives ({@link REPEAT_DIRECTIVE_PROPS}) are consumed: every\n *   node this expands, and every copy it makes, comes out without them.\n * - Repeats do not nest. A repeat inside another repeat's template is copied\n *   with its directives consumed, so it renders once in each copy.\n * - An unknown dataset, no matching records, an empty template, or a\n *   self-scoped node its parent does not list (the document root, say) leave\n *   the node rendering once, as written (fail-open: a deleted dataset must\n *   never take a published screen down).\n * - Inputs are never mutated; templates stay in the map unreferenced.\n */\nexport function expandRepeatables<N extends AglynNodeSchema = AglynNodeSchema>(\n  nodes: Record<NodeId, N>,\n  datasetsByKey: Record<string, RepeatableDataset | undefined> | undefined,\n): Record<NodeId, N> {\n  if (!datasetsByKey) return nodes\n  const repeatIds = Object.entries(nodes).filter(\n    ([, node]) => repeatKey(node) !== '',\n  )\n  if (!repeatIds.length) return nodes\n\n  const next: Record<NodeId, N> = { ...nodes }\n  for (const [repeatId, repeated] of repeatIds) {\n    const dataset = datasetsByKey[repeatKey(repeated)]\n    const records = repeatedRecords(repeated, dataset)\n    const self = repeatScope(repeated) === 'self'\n    // The copies' parent: the node itself, or — for a self-scoped node — the\n    // parent whose child list the copies take its place in, read from `next`\n    // so two self-scoped siblings both land in the list the other has left.\n    const parentId = (self ? repeated.parentId : repeatId) as NodeId\n    const siblings = next[parentId]?.nodes\n    const slot = Array.isArray(siblings)\n      ? (siblings as NodeId[]).indexOf(repeatId)\n      : -1\n    const templateIds = self\n      ? [repeatId]\n      : Array.isArray(repeated.nodes)\n        ? (repeated.nodes as NodeId[])\n        : []\n    next[repeatId] = withoutRepeatDirective(next[repeatId])\n    if (!records.length || !templateIds.length || (self && slot < 0)) continue\n\n    const copyIds: NodeId[] = []\n    records.forEach((record, index) => {\n      const prefix = `${REPEAT_NODE_ID_PREFIX}${repeatId}__${index}__`\n      const prefixId = (id: NodeId) => `${prefix}${id}`\n      const cloneSubtree = (id: NodeId, clonedParentId: NodeId) => {\n        const node = nodes[id]\n        if (!node) return\n        const clonedChildren = Array.isArray(node.nodes)\n          ? (node.nodes as NodeId[])\n          : undefined\n        next[prefixId(id)] = withoutRepeatDirective({\n          ...node,\n          $id: prefixId(id),\n          parentId: clonedParentId,\n          props: substituteValue(node.props ?? {}, {\n            record,\n            model: dataset?.model,\n            datasetsByKey,\n          }) as any,\n          ...(clonedChildren && {\n            nodes: clonedChildren.map((childId) => prefixId(childId)),\n          }),\n        })\n        clonedChildren?.forEach((childId) =>\n          cloneSubtree(childId, prefixId(id)),\n        )\n      }\n      for (const templateId of templateIds) {\n        cloneSubtree(templateId, parentId)\n        copyIds.push(prefixId(templateId))\n      }\n    })\n    if (self) {\n      const listed = [...(next[parentId].nodes as NodeId[])]\n      listed.splice(slot, 1, ...copyIds)\n      next[parentId] = { ...next[parentId], nodes: listed }\n    } else {\n      next[repeatId] = { ...next[repeatId], nodes: copyIds }\n    }\n  }\n  return next\n}\n\nexport default expandRepeatables\n"],"names":["applyDatasetQuery","parseDatasetFilter","parseDatasetSort","REPEAT_NODE_ID_PREFIX","ITEM_TOKEN_PATTERN","REPEAT_MAX_RECORDS","displayValue","value","Array","isArray","join","String","resolveReferenceHop","context","fieldId","targetFieldId","field","model","fields","type","reference","datasetId","target","datasetsByKey","keys","record","ids","resolved","map","id","match","records","find","row","filter","length","substituteValue","replace","token","hop","entry","next","key","Object","entries","repeatKey","node","props","repeatDataset","trim","REPEAT_SELF_PROP","REPEAT_DIRECTIVE_PROPS","repeatScope","nodes","self","substituteRecordTokens","withoutRepeatDirective","some","kept","repeatedRecords","dataset","where","orderBy","limit","Number","slice","isFinite","Math","min","hasRepeatableNodes","values","repeatDatasetKeys","Set","add","sort","expandRepeatables","repeatIds","repeatId","repeated","parentId","siblings","slot","indexOf","templateIds","copyIds","forEach","index","prefix","prefixId","cloneSubtree","clonedParentId","clonedChildren","undefined","$id","childId","templateId","push","listed","splice"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/expand-repeatables.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 { AglynNodeSchema, NodeId } from '../foundation'\nimport {\n  applyDatasetQuery,\n  parseDatasetFilter,\n  parseDatasetSort,\n} from './dataset-query'\n\n/** Namespaces cloned template ids per container/record. */\nexport const REPEAT_NODE_ID_PREFIX = 'rep__'\n\n/**\n * `{{item.field}}` token, plus an optional single reference hop\n * (`{{item.author.name}}`, AGL-180). One hop only — the pattern itself is\n * the depth guard, so cycles can't recurse.\n */\nconst ITEM_TOKEN_PATTERN =\n  /\\{\\{\\s*item\\.([A-Za-z][A-Za-z0-9_]*)(?:\\.([A-Za-z][A-Za-z0-9_]*))?\\s*\\}\\}/g\n\n/** Hard bound on rows a single repeatable renders, before `repeatLimit`. */\nexport const REPEAT_MAX_RECORDS = 100\n\nexport interface RepeatableDataset {\n  /**\n   * Row value maps, in display order. Rows carry `$id` (needed to resolve\n   * incoming references); values may be typed (AGL-177), stringified at\n   * substitution.\n   */\n  records: Array<Record<string, unknown>>\n  /** Typed model (AGL-177); required for reference-hop bindings. */\n  model?: import('./dataset-models').DatasetModel\n}\n\ninterface SubstituteContext {\n  record: Record<string, unknown>\n  /** Model of the repeated dataset (reference hops need field configs). */\n  model?: import('./dataset-models').DatasetModel\n  /** All host datasets keyed by id (and name) for hop resolution. */\n  datasetsByKey?: Record<string, RepeatableDataset | undefined>\n}\n\nconst displayValue = (value: unknown): string =>\n  Array.isArray(value) ? value.join(', ') : String(value)\n\n/** Resolves `{{item.ref.field}}`: FKey(s) → target document field value. */\nfunction resolveReferenceHop(\n  context: SubstituteContext,\n  fieldId: string,\n  targetFieldId: string,\n): string | null {\n  const field = context.model?.fields?.[fieldId]\n  if (field?.type !== 'reference' || !field.reference?.datasetId) return null\n  const target = context.datasetsByKey?.[field.reference.datasetId]\n  if (!target) return null\n  const keys = context.record[fieldId]\n  const ids = Array.isArray(keys) ? keys : keys != null ? [keys] : []\n  const resolved = ids\n    .map((id) => {\n      const match = target.records.find((row) => row['$id'] === id)\n      const value = match?.[targetFieldId]\n      return value != null ? displayValue(value) : null\n    })\n    .filter((value): value is string => value != null)\n  return resolved.length ? resolved.join(', ') : null\n}\n\nfunction substituteValue(\n  value: unknown,\n  context: SubstituteContext,\n): unknown {\n  const { record } = context\n  if (typeof value === 'string') {\n    return value.replace(\n      ITEM_TOKEN_PATTERN,\n      (token, field: string, hop?: string) => {\n        if (hop) {\n          const resolved = resolveReferenceHop(context, field, hop)\n          return resolved != null ? resolved : token\n        }\n        return record[field] != null ? displayValue(record[field]) : token\n      },\n    )\n  }\n  if (Array.isArray(value)) {\n    return value.map((entry) => substituteValue(entry, context))\n  }\n  if (value && typeof value === 'object') {\n    const next: Record<string, unknown> = {}\n    for (const [key, entry] of Object.entries(value)) {\n      next[key] = substituteValue(entry, context)\n    }\n    return next\n  }\n  return value\n}\n\n/**\n * The key a node repeats over, trimmed, or `''` when it repeats over nothing.\n *\n * The one predicate every repeat question is asked through: the expansion, the\n * datasets-read gate below, the reusable-component graft that moves a\n * placement's repeat onto the element it becomes, and the besigner's preview\n * and badge. Two copies of it are how a `.trim()` on one side and not the\n * other becomes an empty list on a customer's page.\n */\nexport const repeatKey = (node: unknown): string => {\n  const key = (node as { props?: { repeatDataset?: unknown } })?.props\n    ?.repeatDataset\n  return typeof key === 'string' ? key.trim() : ''\n}\n\n/**\n * Makes an element that holds children repeat ITSELF, once per record, instead\n * of what is inside it (AGL-3111): a card whose contents are the design, rather\n * than a list whose contents are the item.\n *\n * Persisted in screen, layout and component documents — never rename. `'true'`\n * counts too, because a switch round-tripped through a text-shaped store comes\n * back as the string.\n */\nexport const REPEAT_SELF_PROP = 'repeatSelf'\n\n/**\n * Every prop that directs a repeat. They are instructions to the composition,\n * never attributes of the element: the expansion consumes them from every node\n * it expands and every copy it makes, so a published element never carries\n * one. Persisted — never rename.\n */\nexport const REPEAT_DIRECTIVE_PROPS: readonly string[] = [\n  'repeatDataset',\n  'repeatLimit',\n  'repeatFilter',\n  'repeatSort',\n  REPEAT_SELF_PROP,\n]\n\n/**\n * What a repeating node copies once per record (AGL-3111).\n *\n * - `children` — what is inside it. The node stays one element around the\n *   copies: the list, grid or gallery they fill. This is how a Stack has\n *   always repeated (AGL-103), and a stored Stack names neither scope.\n * - `self` — the node itself, with everything inside it. What a leaf and a\n *   component instance repeat, and what any element carrying\n *   {@link REPEAT_SELF_PROP} repeats.\n */\nexport type RepeatScope = 'self' | 'children'\n\n/**\n * Which scope a repeating node has, read off the node alone so the published\n * page's composition and the besigner decide it identically.\n *\n * {@link REPEAT_SELF_PROP} decides it whenever the node carries one, which is\n * every repeat the Attributes panel writes. Without one the node's own shape\n * decides, and it decides CONSERVATIVELY: anything that holds a child list —\n * a Stack, empty or not — keeps repeating its children, and only a node with\n * no child list at all repeats itself. A stored repeat predates the prop, so\n * this branch is the one that has to render it unchanged, and an author who\n * named a dataset before filling the container in would otherwise come back to\n * a hundred empty copies of it.\n *\n * A component instance never reaches that branch: the graft stamps the prop on\n * the element it becomes, whose children are the component's own.\n */\nexport function repeatScope(node: unknown): RepeatScope {\n  const { props, nodes } = (node ?? {}) as {\n    props?: Record<string, unknown>\n    nodes?: unknown\n  }\n  // `'true'`/`'false'` too: a switch round-tripped through a text-shaped\n  // store comes back as the string it was written as.\n  const self = props?.[REPEAT_SELF_PROP]\n  if (self === true || self === 'true') return 'self'\n  if (self === false || self === 'false') return 'children'\n  return Array.isArray(nodes) ? 'children' : 'self'\n}\n\n/**\n * One record's values put into `{{item.field}}` tokens, anywhere in a props\n * map — the substitution {@link expandRepeatables} makes on every copy it\n * builds, for a caller that already knows which record it is rendering.\n *\n * The besigner's canvas is that caller (AGL-3111): the element an author\n * edits IS the first copy, so it draws with the first record's values while\n * the node it saves keeps the tokens. Exported rather than reimplemented\n * because a canvas that resolved a token differently from the page would be\n * showing the author a page that does not exist.\n */\nexport function substituteRecordTokens<T>(\n  props: T,\n  context: {\n    record: Record<string, unknown>\n    /** Model of the repeated rows; reference hops need field configs. */\n    model?: import('./dataset-models').DatasetModel\n    /** Rows by key, for a one-hop reference (AGL-180). */\n    datasetsByKey?: Record<string, RepeatableDataset | undefined>\n  },\n): T {\n  return substituteValue(props, context) as T\n}\n\n/** The node minus its repeat directives, or the node itself when it has none. */\nexport function withoutRepeatDirective<N>(node: N): N {\n  const props = (node as { props?: Record<string, unknown> })?.props\n  if (!props || !REPEAT_DIRECTIVE_PROPS.some((key) => key in props)) {\n    return node\n  }\n  const kept = { ...props }\n  for (const key of REPEAT_DIRECTIVE_PROPS) delete kept[key]\n  return { ...node, props: kept }\n}\n\n/**\n * The records a repeating node renders, in order (AGL-181): its filter and sort\n * evaluated over the rows, then its limit, never past\n * {@link REPEAT_MAX_RECORDS}. An unparseable filter or sort fails open.\n *\n * Shared by the expansion and the besigner's canvas preview and badge, so the\n * canvas can never show a copy or a count the published page does not.\n */\nexport function repeatedRecords(\n  node: unknown,\n  dataset: RepeatableDataset | undefined,\n): Array<Record<string, unknown>> {\n  const props = ((node as { props?: unknown })?.props ?? {}) as Record<\n    string,\n    unknown\n  >\n  const where = parseDatasetFilter(String(props['repeatFilter'] ?? ''))\n  const orderBy = parseDatasetSort(String(props['repeatSort'] ?? ''))\n  const limit = Number(props['repeatLimit'])\n  return applyDatasetQuery(dataset?.model, dataset?.records ?? [], {\n    ...(where ? { where: [where] } : {}),\n    ...(orderBy ? { orderBy } : {}),\n  }).slice(\n    0,\n    Number.isFinite(limit) && limit > 0\n      ? Math.min(limit, REPEAT_MAX_RECORDS)\n      : REPEAT_MAX_RECORDS,\n  )\n}\n\n/**\n * Does this tree contain anything {@link expandRepeatables} would expand?\n *\n * The rows read is the largest on the render path — up to two pages of\n * {@link REPEAT_MAX_RECORDS} records for every key a page repeats over — and a\n * page that repeats over nothing should pay none of it (AGL-1440).\n *\n * Any gate on that read has to ask EXACTLY the question the expansion asks,\n * which is why this and {@link repeatKeys} share the one predicate\n * `expandRepeatables` looks keys up with, {@link repeatKey}. A gate that is\n * even slightly stricter than the expansion is not a saving: it is a published\n * page that quietly renders one template row where the author put a list.\n */\nexport function hasRepeatableNodes(\n  nodes: Record<NodeId, unknown> | null | undefined,\n): boolean {\n  if (!nodes) return false\n  return Object.values(nodes).some((node) => repeatKey(node) !== '')\n}\n\n/**\n * Every key this tree repeats over, exactly as {@link expandRepeatables} looks\n * it up — sorted and without repeats.\n *\n * What the tenant compose asks the repeat-rows contract for\n * (`plugin-manager/repeat-rows.ts`), so a page loads the rows it renders and\n * not everything its site may see. Built on the same predicate as\n * {@link hasRepeatableNodes} for the reason given there.\n */\nexport function repeatKeys(\n  nodes: Record<NodeId, unknown> | null | undefined,\n): string[] {\n  const keys = new Set<string>()\n  for (const node of Object.values(nodes ?? {})) {\n    const key = repeatKey(node)\n    if (key) keys.add(key)\n  }\n  return [...keys].sort()\n}\n\n/**\n * Repeats (AGL-103, AGL-3111): any node carrying `props.repeatDataset` (a\n * dataset id or display name) renders once per record of that dataset, with\n * `{{item.field}}` tokens in the copied string props replaced by the record's\n * values (unknown fields keep the literal token, like variable bindings).\n *\n * What is copied is the node's {@link repeatScope}:\n *\n * - `children` — its children are the item template. The node stays, and its\n *   child list becomes the copies, record by record. Its own props are not the\n *   template, so no token in them is substituted.\n * - `self` — the node and everything inside it are the template. The copies\n *   take the node's place in its parent's child list, and every prop in the\n *   subtree is substituted, the node's own included.\n *\n * - Copy ids are namespaced `rep__{repeatId}__{index}__…` — the repeat's own\n *   id, then the template node's — so repeats never collide, including inside\n *   grafted reusable components. A self-scoped node's first copy is\n *   `rep__{id}__0__{id}`. Run this AFTER `composeReusableComponentNodes` and\n *   BEFORE binding resolution.\n * - Rows are the node's {@link repeatedRecords}.\n * - The repeat directives ({@link REPEAT_DIRECTIVE_PROPS}) are consumed: every\n *   node this expands, and every copy it makes, comes out without them.\n * - Repeats do not nest. A repeat inside another repeat's template is copied\n *   with its directives consumed, so it renders once in each copy.\n * - An unknown dataset, no matching records, an empty template, or a\n *   self-scoped node its parent does not list (the document root, say) leave\n *   the node rendering once, as written (fail-open: a deleted dataset must\n *   never take a published screen down).\n * - Inputs are never mutated; templates stay in the map unreferenced.\n */\nexport function expandRepeatables<N extends AglynNodeSchema = AglynNodeSchema>(\n  nodes: Record<NodeId, N>,\n  datasetsByKey: Record<string, RepeatableDataset | undefined> | undefined,\n): Record<NodeId, N> {\n  if (!datasetsByKey) return nodes\n  const repeatIds = Object.entries(nodes).filter(\n    ([, node]) => repeatKey(node) !== '',\n  )\n  if (!repeatIds.length) return nodes\n\n  const next: Record<NodeId, N> = { ...nodes }\n  for (const [repeatId, repeated] of repeatIds) {\n    const dataset = datasetsByKey[repeatKey(repeated)]\n    const records = repeatedRecords(repeated, dataset)\n    const self = repeatScope(repeated) === 'self'\n    // The copies' parent: the node itself, or — for a self-scoped node — the\n    // parent whose child list the copies take its place in, read from `next`\n    // so two self-scoped siblings both land in the list the other has left.\n    const parentId = (self ? repeated.parentId : repeatId) as NodeId\n    const siblings = next[parentId]?.nodes\n    const slot = Array.isArray(siblings)\n      ? (siblings as NodeId[]).indexOf(repeatId)\n      : -1\n    const templateIds = self\n      ? [repeatId]\n      : Array.isArray(repeated.nodes)\n        ? (repeated.nodes as NodeId[])\n        : []\n    next[repeatId] = withoutRepeatDirective(next[repeatId])\n    if (!records.length || !templateIds.length || (self && slot < 0)) continue\n\n    const copyIds: NodeId[] = []\n    records.forEach((record, index) => {\n      const prefix = `${REPEAT_NODE_ID_PREFIX}${repeatId}__${index}__`\n      const prefixId = (id: NodeId) => `${prefix}${id}`\n      const cloneSubtree = (id: NodeId, clonedParentId: NodeId) => {\n        const node = nodes[id]\n        if (!node) return\n        const clonedChildren = Array.isArray(node.nodes)\n          ? (node.nodes as NodeId[])\n          : undefined\n        next[prefixId(id)] = withoutRepeatDirective({\n          ...node,\n          $id: prefixId(id),\n          parentId: clonedParentId,\n          props: substituteValue(node.props ?? {}, {\n            record,\n            model: dataset?.model,\n            datasetsByKey,\n          }) as any,\n          ...(clonedChildren && {\n            nodes: clonedChildren.map((childId) => prefixId(childId)),\n          }),\n        })\n        clonedChildren?.forEach((childId) =>\n          cloneSubtree(childId, prefixId(id)),\n        )\n      }\n      for (const templateId of templateIds) {\n        cloneSubtree(templateId, parentId)\n        copyIds.push(prefixId(templateId))\n      }\n    })\n    if (self) {\n      const listed = [...(next[parentId].nodes as NodeId[])]\n      listed.splice(slot, 1, ...copyIds)\n      next[parentId] = { ...next[parentId], nodes: listed }\n    } else {\n      next[repeatId] = { ...next[repeatId], nodes: copyIds }\n    }\n  }\n  return next\n}\n\nexport default expandRepeatables\n"],"names":["applyDatasetQuery","parseDatasetFilter","parseDatasetSort","REPEAT_NODE_ID_PREFIX","ITEM_TOKEN_PATTERN","REPEAT_MAX_RECORDS","displayValue","value","Array","isArray","join","String","resolveReferenceHop","context","fieldId","targetFieldId","field","model","fields","type","reference","datasetId","target","datasetsByKey","keys","record","ids","resolved","map","id","match","records","find","row","filter","length","substituteValue","replace","token","hop","entry","next","key","Object","entries","repeatKey","node","props","repeatDataset","trim","REPEAT_SELF_PROP","REPEAT_DIRECTIVE_PROPS","repeatScope","nodes","self","substituteRecordTokens","withoutRepeatDirective","some","kept","repeatedRecords","dataset","where","orderBy","limit","Number","slice","isFinite","Math","min","hasRepeatableNodes","values","repeatKeys","Set","add","sort","expandRepeatables","repeatIds","repeatId","repeated","parentId","siblings","slot","indexOf","templateIds","copyIds","forEach","index","prefix","prefixId","cloneSubtree","clonedParentId","clonedChildren","undefined","$id","childId","templateId","push","listed","splice"],"mappings":"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"}

package/src/lib/app-utils/host-events.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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 PluginHostEventType } from './plugin-host-events.generated';
+/**
+ * HOST EVENTS: what happened on a site that an automation can start on
+ * (AGL-128).
+ *
+ * SERVER DOORS ONLY. An event exists because a request handler that already
+ * performed the write called `emitHostEvent` beside it; nothing watches the
+ * database. So a record created by a console user's client-direct Firestore
+ * write fires nothing, and an event is only as complete as the set of server
+ * paths that raise it.
+ *
+ * The platform raises one event itself — a page view, from the analytics
+ * collector. Every other event is raised by a plugin's door, and the plugin
+ * DECLARES it under `hostEvents` in `plugins.config.json`: the type a trigger
+ * stores, where it sorts in a picker, how a picker and a run row name it, and
+ * the payload keys it puts in scope. The declarations are compiled, because
+ * the event bus, the trigger pickers and every validator read them with no
+ * plugin loaded. Nothing here names a plugin's event.
+ */
+/** One event a trigger can start on. */
+export interface HostEventDeclaration {
+    /** The plugin whose doors raise it; absent for the platform's own. */
+    pluginId?: string;
+    /** What a stored trigger names. Never renamed. */
+    type: string;
+    /** Where it sorts in every trigger picker. */
+    order: number;
+    /** How a trigger picker and a run history row name it: "Form submitted". */
+    label: string;
+    /**
+     * The payload keys the event puts in scope, for the filter expression and
+     * the step conditions — the thing an author has to know to write
+     * `lifecycleStage == "customer"` and has nowhere else to read. Documented
+     * from the door that raises it: an entry may describe keys no fixed list
+     * can enumerate ("every submitted field by name").
+     */
+    payloadKeys?: readonly string[];
+}
+/** The events the platform raises itself, with no plugin loaded. */
+declare const PLATFORM_HOST_EVENTS: readonly [{
+    readonly type: "pageView";
+    readonly order: 20;
+    readonly label: "Page viewed";
+    readonly payloadKeys: readonly ["path"];
+}];
+export type HostEventType = (typeof PLATFORM_HOST_EVENTS)[number]['type'] | PluginHostEventType;
+/** Every host event, the platform's and the plugins', in picker order. */
+export declare const HOST_EVENTS: readonly HostEventDeclaration[];
+/** Every host event's type, in picker order. */
+export declare const HOST_EVENT_TYPES: readonly HostEventType[];
+/** How each event reads in a trigger picker and a run history row. */
+export declare const HOST_EVENT_LABELS: Partial<Record<HostEventType, string>>;
+/** The payload keys each event puts in scope, where they are documented. */
+export declare const HOST_EVENT_PAYLOAD_KEYS: Partial<Record<HostEventType, readonly string[]>>;
+/**
+ * `formSubmission` → `Form submitted`; a custom event keeps its own name,
+ * because the author chose it and it is already the word they think in.
+ */
+export declare function hostEventLabel(event: string | undefined | null): string;
+/**
+ * One sentence naming what a trigger's filter and conditions can read, or
+ * `null` for an event whose payload is not documented — a custom event, or
+ * one whose door documents none.
+ */
+export declare function hostEventPayloadHint(event: string | undefined | null): string | null;
+export {};

package/src/lib/app-utils/host-events.js

@@ -0,0 +1,62 @@
+/**
+ * @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 { PLUGIN_HOST_EVENTS } from "./plugin-host-events.generated.js";
+/** The events the platform raises itself, with no plugin loaded. */ const PLATFORM_HOST_EVENTS = [
+    {
+        type: 'pageView',
+        order: 20,
+        label: 'Page viewed',
+        payloadKeys: [
+            'path'
+        ]
+    }
+];
+/** Every host event, the platform's and the plugins', in picker order. */ export const HOST_EVENTS = [
+    ...PLATFORM_HOST_EVENTS,
+    ...PLUGIN_HOST_EVENTS
+].sort((a, b)=>a.order - b.order);
+/** Every host event's type, in picker order. */ export const HOST_EVENT_TYPES = HOST_EVENTS.map((event)=>event.type);
+/** How each event reads in a trigger picker and a run history row. */ export const HOST_EVENT_LABELS = Object.fromEntries(HOST_EVENTS.map((event)=>[
+        event.type,
+        event.label
+    ]));
+/** The payload keys each event puts in scope, where they are documented. */ export const HOST_EVENT_PAYLOAD_KEYS = Object.fromEntries(HOST_EVENTS.filter((event)=>{
+    var _event_payloadKeys;
+    return (_event_payloadKeys = event.payloadKeys) == null ? void 0 : _event_payloadKeys.length;
+}).map((event)=>[
+        event.type,
+        event.payloadKeys
+    ]));
+/**
+ * `formSubmission` → `Form submitted`; a custom event keeps its own name,
+ * because the author chose it and it is already the word they think in.
+ */ export function hostEventLabel(event) {
+    var _HOST_EVENT_LABELS_key;
+    const key = String(event != null ? event : '').trim();
+    if (!key) return 'Event';
+    return (_HOST_EVENT_LABELS_key = HOST_EVENT_LABELS[key]) != null ? _HOST_EVENT_LABELS_key : key;
+}
+/**
+ * One sentence naming what a trigger's filter and conditions can read, or
+ * `null` for an event whose payload is not documented — a custom event, or
+ * one whose door documents none.
+ */ export function hostEventPayloadHint(event) {
+    const keys = HOST_EVENT_PAYLOAD_KEYS[String(event != null ? event : '')];
+    if (!(keys == null ? void 0 : keys.length)) return null;
+    return `In scope: ${keys.join(', ')}.`;
+}
+
+//# sourceMappingURL=host-events.js.map

package/src/lib/app-utils/host-events.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/host-events.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  PLUGIN_HOST_EVENTS,\n  type PluginHostEventType,\n} from './plugin-host-events.generated'\n\n/**\n * HOST EVENTS: what happened on a site that an automation can start on\n * (AGL-128).\n *\n * SERVER DOORS ONLY. An event exists because a request handler that already\n * performed the write called `emitHostEvent` beside it; nothing watches the\n * database. So a record created by a console user's client-direct Firestore\n * write fires nothing, and an event is only as complete as the set of server\n * paths that raise it.\n *\n * The platform raises one event itself — a page view, from the analytics\n * collector. Every other event is raised by a plugin's door, and the plugin\n * DECLARES it under `hostEvents` in `plugins.config.json`: the type a trigger\n * stores, where it sorts in a picker, how a picker and a run row name it, and\n * the payload keys it puts in scope. The declarations are compiled, because\n * the event bus, the trigger pickers and every validator read them with no\n * plugin loaded. Nothing here names a plugin's event.\n */\n\n/** One event a trigger can start on. */\nexport interface HostEventDeclaration {\n  /** The plugin whose doors raise it; absent for the platform's own. */\n  pluginId?: string\n  /** What a stored trigger names. Never renamed. */\n  type: string\n  /** Where it sorts in every trigger picker. */\n  order: number\n  /** How a trigger picker and a run history row name it: \"Form submitted\". */\n  label: string\n  /**\n   * The payload keys the event puts in scope, for the filter expression and\n   * the step conditions — the thing an author has to know to write\n   * `lifecycleStage == \"customer\"` and has nowhere else to read. Documented\n   * from the door that raises it: an entry may describe keys no fixed list\n   * can enumerate (\"every submitted field by name\").\n   */\n  payloadKeys?: readonly string[]\n}\n\n/** The events the platform raises itself, with no plugin loaded. */\nconst PLATFORM_HOST_EVENTS = [\n  { type: 'pageView', order: 20, label: 'Page viewed', payloadKeys: ['path'] },\n] as const satisfies readonly HostEventDeclaration[]\n\nexport type HostEventType =\n  | (typeof PLATFORM_HOST_EVENTS)[number]['type']\n  | PluginHostEventType\n\n/** Every host event, the platform's and the plugins', in picker order. */\nexport const HOST_EVENTS: readonly HostEventDeclaration[] = [\n  ...PLATFORM_HOST_EVENTS,\n  ...PLUGIN_HOST_EVENTS,\n].sort((a, b) => a.order - b.order)\n\n/** Every host event's type, in picker order. */\nexport const HOST_EVENT_TYPES: readonly HostEventType[] = HOST_EVENTS.map(\n  (event) => event.type as HostEventType,\n)\n\n/** How each event reads in a trigger picker and a run history row. */\nexport const HOST_EVENT_LABELS: Partial<Record<HostEventType, string>> =\n  Object.fromEntries(HOST_EVENTS.map((event) => [event.type, event.label]))\n\n/** The payload keys each event puts in scope, where they are documented. */\nexport const HOST_EVENT_PAYLOAD_KEYS: Partial<Record<HostEventType, readonly string[]>> =\n  Object.fromEntries(\n    HOST_EVENTS.filter((event) => event.payloadKeys?.length).map((event) => [\n      event.type,\n      event.payloadKeys,\n    ]),\n  )\n\n/**\n * `formSubmission` → `Form submitted`; a custom event keeps its own name,\n * because the author chose it and it is already the word they think in.\n */\nexport function hostEventLabel(event: string | undefined | null): string {\n  const key = String(event ?? '').trim()\n  if (!key) return 'Event'\n  return HOST_EVENT_LABELS[key as HostEventType] ?? key\n}\n\n/**\n * One sentence naming what a trigger's filter and conditions can read, or\n * `null` for an event whose payload is not documented — a custom event, or\n * one whose door documents none.\n */\nexport function hostEventPayloadHint(\n  event: string | undefined | null,\n): string | null {\n  const keys = HOST_EVENT_PAYLOAD_KEYS[String(event ?? '') as HostEventType]\n  if (!keys?.length) return null\n  return `In scope: ${keys.join(', ')}.`\n}\n"],"names":["PLUGIN_HOST_EVENTS","PLATFORM_HOST_EVENTS","type","order","label","payloadKeys","HOST_EVENTS","sort","a","b","HOST_EVENT_TYPES","map","event","HOST_EVENT_LABELS","Object","fromEntries","HOST_EVENT_PAYLOAD_KEYS","filter","length","hostEventLabel","key","String","trim","hostEventPayloadHint","keys","join"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,kBAAkB,QAEb,oCAAgC;AAyCvC,kEAAkE,GAClE,MAAMC,uBAAuB;IAC3B;QAAEC,MAAM;QAAYC,OAAO;QAAIC,OAAO;QAAeC,aAAa;YAAC;SAAO;IAAC;CAC5E;AAMD,wEAAwE,GACxE,OAAO,MAAMC,cAA+C;OACvDL;OACAD;CACJ,CAACO,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEL,KAAK,GAAGM,EAAEN,KAAK,EAAC;AAEnC,8CAA8C,GAC9C,OAAO,MAAMO,mBAA6CJ,YAAYK,GAAG,CACvE,CAACC,QAAUA,MAAMV,IAAI,EACtB;AAED,oEAAoE,GACpE,OAAO,MAAMW,oBACXC,OAAOC,WAAW,CAACT,YAAYK,GAAG,CAAC,CAACC,QAAU;QAACA,MAAMV,IAAI;QAAEU,MAAMR,KAAK;KAAC,GAAE;AAE3E,0EAA0E,GAC1E,OAAO,MAAMY,0BACXF,OAAOC,WAAW,CAChBT,YAAYW,MAAM,CAAC,CAACL;QAAUA;YAAAA,qBAAAA,MAAMP,WAAW,qBAAjBO,mBAAmBM,MAAM;GAAEP,GAAG,CAAC,CAACC,QAAU;QACtEA,MAAMV,IAAI;QACVU,MAAMP,WAAW;KAClB,GACF;AAEH;;;CAGC,GACD,OAAO,SAASc,eAAeP,KAAgC;QAGtDC;IAFP,MAAMO,MAAMC,OAAOT,gBAAAA,QAAS,IAAIU,IAAI;IACpC,IAAI,CAACF,KAAK,OAAO;IACjB,QAAOP,yBAAAA,iBAAiB,CAACO,IAAqB,YAAvCP,yBAA2CO;AACpD;AAEA;;;;CAIC,GACD,OAAO,SAASG,qBACdX,KAAgC;IAEhC,MAAMY,OAAOR,uBAAuB,CAACK,OAAOT,gBAAAA,QAAS,IAAqB;IAC1E,IAAI,EAACY,wBAAAA,KAAMN,MAAM,GAAE,OAAO;IAC1B,OAAO,CAAC,UAAU,EAAEM,KAAKC,IAAI,CAAC,MAAM,CAAC,CAAC;AACxC"}

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

@@ -186,9 +186,31 @@ export declare function lockdownIntentForMethod(method: string | null | undefine
 export declare function lockdownBlocks(state: {
     mode?: LockdownMode;
 } | null | undefined, intent: LockdownIntent): boolean;
-export type LockdownReasonCode = 'security' | 'billing' | 'maintenance' | 'manual';
+export type LockdownReasonCode = 'security'
+/**
+ * Phishing, fraud or malicious content (AGL-3420). On an ACCOUNT it is a
+ * permanent ban: the account is kept only so its address can never sign up
+ * again, and after the lock notice it is sent no mail at all — see
+ * {@link isAccountBanLockdownReason}. Everywhere a lock's strictness is
+ * read from its reason it is at least as strict as `security`.
+ */
+ | 'abuse' | 'billing' | 'maintenance' | 'manual';
 export declare const LOCKDOWN_REASON_CODES: LockdownReasonCode[];
 export declare function isLockdownReasonCode(value: unknown): value is LockdownReasonCode;
+/** Staff-surface labels; the key stays the wire/API identity. */
+export declare const LOCKDOWN_REASON_LABELS: Record<LockdownReasonCode, string>;
+/**
+ * The reasons that mean "a threat, act now": `security`, and `abuse`, which
+ * is a confirmed one. Every rule that is stricter for a security lock — who
+ * is signed out, which bytes stop serving, which tokens rotate — reads it
+ * through here, so a ban is never the milder of the two.
+ */
+export declare function isSecurityClassLockdownReason(reason: unknown): boolean;
+/**
+ * A lock with this reason, on an account, is a permanent ban (AGL-3420):
+ * after its notice the account is sent nothing, by any sender.
+ */
+export declare function isAccountBanLockdownReason(reason: unknown): boolean;
 /** The one shape every enforcement point consumes. */
 export interface LockdownState {
     scope: LockdownScope;
@@ -544,6 +566,13 @@ export interface LockdownNotice {
     body: string;
     /** Shown as the action line; undefined = no contact line (maintenance). */
     contact?: string;
+    /**
+     * The lock is a decision the account holder may appeal — a `security` or
+     * `abuse` lock (AGL-3420) — so the contact line offers the appeal rather
+     * than taking questions. Set by reason, never by staff's message, so a
+     * custom message cannot remove the way to appeal.
+     */
+    appeal?: boolean;
 }
 /**
  * The address on the visitor-facing 503, from operator configuration
@@ -610,6 +639,7 @@ export interface LockdownRefusalBody {
     title?: unknown;
     message?: unknown;
     contact?: unknown;
+    appeal?: unknown;
     untilMs?: unknown;
 }
 /** A 423 body, parsed into something a client surface can render. */
@@ -617,6 +647,8 @@ export interface LockdownRefusalNotice {
     title: string;
     message: string;
     contact?: string;
+    /** The contact line offers an appeal — see {@link LockdownNotice.appeal}. */
+    appeal?: boolean;
     scope?: LockdownScope;
     feature?: LockdownFeatureKey;
     /**