@aglyn/aglyn 1.0.0-beta.224 → 1.0.0-beta.225

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.224",
+  "version": "1.0.0-beta.225",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -37,16 +37,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.224",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.224",
-    "@aglyn/shared-data-types": "1.0.0-beta.224",
-    "@aglyn/shared-util-email": "1.0.0-beta.224",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.224",
-    "@aglyn/shared-util-http": "1.0.0-beta.224",
-    "@aglyn/shared-util-logger": "1.0.0-beta.224",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.224",
-    "@aglyn/shared-util-tools": "1.0.0-beta.224",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.224",
+    "@aglyn/shared-data-enums": "1.0.0-beta.225",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.225",
+    "@aglyn/shared-data-types": "1.0.0-beta.225",
+    "@aglyn/shared-util-email": "1.0.0-beta.225",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.225",
+    "@aglyn/shared-util-http": "1.0.0-beta.225",
+    "@aglyn/shared-util-logger": "1.0.0-beta.225",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.225",
+    "@aglyn/shared-util-tools": "1.0.0-beta.225",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.225",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",

package/src/lib/app-utils/advertising-tag-mounts.js

@@ -25,6 +25,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // `site-analytics-independence.spec.ts` walks and which must stay independent
 // of the site-plugin gate.
 import { ADVERTISING_TAG_ATTRIBUTE, restoreAdvertisingTags, revokeAdvertisingTags } from "./advertising-tags.js";
+import { usePageIdle } from "./page-idle.js";
 import { VISITOR_CONSENT_CHANGED_EVENT } from "./visitor-consent.js";
 import Script from "next/script";
 import { Fragment, useEffect, useRef } from "react";
@@ -83,7 +84,14 @@ export default function AdvertisingTagMounts({ active, tags, resolve, nonce, sha
     }, [
         active
     ]);
-    if (!active || tags.length === 0) return null;
+    // Nothing is injected before the page has loaded and gone idle (AGL-3581).
+    // The withdrawal listener above is NOT behind this: a visitor who refuses
+    // before the page idles has nothing to tear down, and one who refuses after
+    // needs the listener already there. Every surface reads the same store, so
+    // a page that mounts its own loader flips in the same render as this one
+    // and `sharedLibraries` still describes it (AGL-2681).
+    const pageIsIdle = usePageIdle();
+    if (!active || tags.length === 0 || !pageIsIdle) return null;
     return /*#__PURE__*/ _jsx(_Fragment, {
         children: tags.map(({ vendor, accountId })=>// A PAIR per vendor, inline boot first and library second — the same
             // shape as the GA `ga-init` / `ga-src` pair, and for the same reason:

package/src/lib/app-utils/advertising-tag-mounts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/advertising-tag-mounts.tsx"],"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// NO `'use client'` here, and it is a lint rule rather than a preference\n// (AGL-52): a directive inside `@aglyn/aglyn` makes the bundler split a\n// duplicate module graph, and the second canvas/emitter singleton renders the\n// tenant site blank. Every component that mounts this one carries the\n// directive itself, which is where the client boundary belongs.\n//\n// Deep app-utils modules, never the `@aglyn/aglyn` barrel (AGL-1550): this\n// file is reached from `site-analytics.tsx`, whose import closure\n// `site-analytics-independence.spec.ts` walks and which must stay independent\n// of the site-plugin gate.\nimport {\n  ADVERTISING_TAG_ATTRIBUTE,\n  type ResolvedAdvertisingTag,\n  restoreAdvertisingTags,\n  revokeAdvertisingTags,\n} from './advertising-tags'\nimport { VISITOR_CONSENT_CHANGED_EVENT } from './visitor-consent'\nimport Script from 'next/script'\nimport { Fragment, useEffect, useRef, type ReactElement } from 'react'\n\n/**\n * The MOUNT and the WITHDRAWAL for consent-gated advertising tags, with no\n * opinion about where the verdict came from.\n *\n * ## Why this is a shared component and not a second copy per surface\n *\n * Aglyn runs advertising tags on three first-party surfaces and they resolve\n * consent through three different mechanisms: the tenant runtime reads a host\n * document and a per-host record, the console reads the platform record its\n * own posture machinery wrote, and the docs site reads the registrable-domain\n * mirror of that record. Those are genuinely different questions.\n *\n * What is NOT different is what happens once the answer is known: mount an\n * inline boot and a library per vendor, and — the half that is easy to forget\n * and impossible to retrofit — stop them the moment the answer changes. A\n * second copy of that half is how one surface comes to keep firing after\n * consent is withdrawn on another, because the copy that was not updated\n * still looks exactly like the one that was.\n *\n * So the verdict is a PROP and the machinery is shared. Each surface answers\n * its own question with its own resolver; none of them owns a teardown.\n *\n * ## Why it renders even when the answer is no\n *\n * Because the withdrawal path needs a listener. A visitor who accepts and then\n * turns advertising off must stop being tracked in THAT pageview, and by then\n * the vendor library has executed — React dropping the `<Script>` does not\n * unload it (AGL-1608). So this component stays mounted whenever the surface\n * participates at all, and subscribes to\n * {@link VISITOR_CONSENT_CHANGED_EVENT}; the teardown runs from the event,\n * synchronously with the visitor's click, rather than waiting on a re-render.\n *\n * Both paths run and they agree, which is deliberate: the render gate is what\n * keeps the tag out of a fresh pageview, the listener is what removes one that\n * is already there, and neither can do the other's job.\n */\nexport interface AdvertisingTagMountsProps {\n  /**\n   * Whether this surface participates in the gate AT ALL.\n   *\n   * False installs nothing — no listener, no scripts. That is the clause that\n   * keeps the tenant runtime's teardown off a customer's site: we did not load\n   * their pixel, we do not know what basis it runs on, and reaching into their\n   * page to kill it would be its own breach. `revokeAdvertisingTags` is\n   * additionally attribute-scoped, so there are two independent scopes.\n   */\n  readonly active: boolean\n  /** The verdict for THIS render: the tags that may exist right now. */\n  readonly tags: readonly ResolvedAdvertisingTag[]\n  /**\n   * Re-read the verdict from live state, for the withdrawal listener.\n   *\n   * A callback rather than the `tags` prop, because the listener fires from\n   * the visitor's own click in the same tick as the record is written — the\n   * props for the current render are by definition the state before it.\n   */\n  readonly resolve: () => readonly ResolvedAdvertisingTag[]\n  /**\n   * The request's CSP nonce, stamped onto BOTH elements of every pair.\n   *\n   * A surface that enforces a nonce'd `script-src` refuses an inline script\n   * that does not carry it, and the boot half of every pair is inline. Next's\n   * `<Script>` stamps a nonce only when one reaches it: the automatic path\n   * reads `HeadManagerContext`, and the App Router's client provider carries\n   * no nonce at all — so a pair mounted after hydration, which is the only\n   * time this component ever mounts one, is unnonced unless the caller hands\n   * the value down. An explicit prop wins inside `next/script`\n   * (`restProps.nonce || nonce`), which is what makes this the one door.\n   *\n   * The failure without it is silent and lopsided: the library beside the\n   * boot has a `src` the policy allows, so the vendor's code loads and runs\n   * against an account nobody configured, and the conversions this surface\n   * sends are lost with nothing in the page but a CSP violation.\n   *\n   * Absent on a surface that sends no `script-src`: nothing is stamped, and\n   * nothing is refused.\n   */\n  readonly nonce?: string\n  /**\n   * Libraries the HOST PAGE mounts itself, named by the needle a vendor\n   * declares in `sharesLibrary` (AGL-2681).\n   *\n   * {@link sharedLibraryPresent} reads the document at render time, and that\n   * is the right instrument for a loader some other party put there. It is\n   * the wrong one for a loader the SAME render is about to create. On the\n   * tenant the GA pair and this component both wait on `consent.ready`, so\n   * the first render that may emit either emits both — GA's `<Script>` is not\n   * in the document yet when this component looks, the check honestly says\n   * \"absent\", and the visitor downloads `gtag.js` twice: once as ours with\n   * `?id=AW-…`, once as gtag's own destination fetch for the `config` that\n   * follows. Measured on `aglyn.com/solutions/small-business` with\n   * advertising granted: two 147 KiB loaders for one account.\n   *\n   * A page that KNOWS it renders the library says so here, from the same\n   * condition that renders it, and the document check stays as the fallback\n   * for loaders it does not know about. Naming the needle rather than passing\n   * a boolean keeps the declaration per library: a page that mounts gtag has\n   * said nothing about the Meta pixel.\n   */\n  readonly sharedLibraries?: readonly string[]\n}\n\n/**\n * Is a library matching `needle` already in the document?\n *\n * Read at RENDER time rather than in an effect: the decision is whether to\n * emit a `<Script>` at all, and by the time an effect could answer, Next has\n * already appended it. `document` is guarded because this component renders on\n * the server too, where nothing is mounted and the honest answer is \"no\" — the\n * client render then re-evaluates with the real document.\n *\n * Blind to a loader the current render is creating alongside this one — see\n * `sharedLibraries` on the props for the case that needs the page to say so.\n */\nexport function sharedLibraryPresent(needle: string): boolean {\n  if (typeof document === 'undefined') return false\n  try {\n    return Boolean(document.querySelector(`script[src*=\"${needle}\"]`))\n  } catch {\n    // A hostile or absent DOM: assume nothing is mounted, which mounts our\n    // own copy — the cost is a duplicate fetch, never a missing tag.\n    return false\n  }\n}\n\nexport default function AdvertisingTagMounts({\n  active,\n  tags,\n  resolve,\n  nonce,\n  sharedLibraries,\n}: AdvertisingTagMountsProps): ReactElement | null {\n  /** Declared by the page, or found in the document: either means \"ride it\". */\n  const libraryProvided = (needle: string): boolean =>\n    (sharedLibraries?.includes(needle) ?? false) || sharedLibraryPresent(needle)\n  /*\n   * The resolver is held in a ref rather than listed as an effect dependency.\n   *\n   * Every caller passes a closure over its own live consent state, so the\n   * function identity changes on every render; depending on it would tear the\n   * listener down and re-install it each time, and a withdrawal that landed in\n   * that window would find no subscriber. The ref makes the subscription's\n   * lifetime `active`, which is the only thing that genuinely changes it,\n   * while the callback it invokes is always the newest one.\n   */\n  const resolveRef = useRef(resolve)\n  resolveRef.current = resolve\n\n  useEffect(() => {\n    if (!active) return undefined\n    const sync = () => {\n      if (resolveRef.current().length === 0) {\n        revokeAdvertisingTags()\n      } else {\n        // Symmetric: a visitor who withdrew and changed their mind inside one\n        // pageview would otherwise stay un-tracked until they navigated,\n        // because a re-rendered `<Script>` cannot re-execute a library the\n        // browser already ran.\n        restoreAdvertisingTags()\n      }\n    }\n    window.addEventListener(VISITOR_CONSENT_CHANGED_EVENT, sync)\n    return () => window.removeEventListener(VISITOR_CONSENT_CHANGED_EVENT, sync)\n  }, [active])\n\n  if (!active || tags.length === 0) return null\n\n  return (\n    <>\n      {tags.map(({ vendor, accountId }) => (\n        // A PAIR per vendor, inline boot first and library second — the same\n        // shape as the GA `ga-init` / `ga-src` pair, and for the same reason:\n        // the boot defines the vendor's queue shim and declares the consent\n        // state, so nothing the library later drains was queued under a state\n        // nobody chose. Both elements carry the teardown's scope marker; only\n        // elements carrying it are ever revoked, removed or cookie-swept.\n        <Fragment key={vendor.id}>\n          <Script\n            id={`ad-tag-${vendor.id}-init`}\n            strategy=\"afterInteractive\"\n            nonce={nonce}\n            {...{ [ADVERTISING_TAG_ATTRIBUTE]: vendor.id }}\n          >\n            {vendor.bootSnippet ? vendor.bootSnippet(accountId) : ''}\n          </Script>\n          {/* Skipped when another loader already brought this library in\n              (AGL-1152). Google Ads shares `gtag.js` with the GA4 measurement\n              id and with a GTM container, so a surface with both configured\n              would fetch it twice and define `gtag()` twice — and the boot\n              above would be the second voice in a consent conversation the\n              first one already had. One library, several `config` calls, is\n              how gtag carries several products. The page's own declaration is\n              consulted first (AGL-2681): the document cannot yet show a loader\n              this same render is creating. */}\n          {vendor.sharesLibrary && libraryProvided(vendor.sharesLibrary) ? null : (\n            <Script\n              id={`ad-tag-${vendor.id}-src`}\n              strategy=\"afterInteractive\"\n              nonce={nonce}\n              {...{ [ADVERTISING_TAG_ATTRIBUTE]: vendor.id }}\n              // `scriptSrcFor` where the vendor has one: gtag reads the\n              // container out of the loader's query, so the copy we bring\n              // ourselves has to name the account. See `scriptSrcFor`.\n              src={\n                vendor.scriptSrcFor\n                  ? vendor.scriptSrcFor(accountId)\n                  : vendor.scriptSrc\n              }\n            />\n          )}\n        </Fragment>\n      ))}\n    </>\n  )\n}\n"],"names":["ADVERTISING_TAG_ATTRIBUTE","restoreAdvertisingTags","revokeAdvertisingTags","VISITOR_CONSENT_CHANGED_EVENT","Script","Fragment","useEffect","useRef","sharedLibraryPresent","needle","document","Boolean","querySelector","AdvertisingTagMounts","active","tags","resolve","nonce","sharedLibraries","libraryProvided","includes","resolveRef","current","undefined","sync","length","window","addEventListener","removeEventListener","map","vendor","accountId","id","strategy","bootSnippet","sharesLibrary","src","scriptSrcFor","scriptSrc"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,yEAAyE;AACzE,wEAAwE;AACxE,8EAA8E;AAC9E,sEAAsE;AACtE,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,kEAAkE;AAClE,8EAA8E;AAC9E,2BAA2B;AAC3B,SACEA,yBAAyB,EAEzBC,sBAAsB,EACtBC,qBAAqB,QAChB,wBAAoB;AAC3B,SAASC,6BAA6B,QAAQ,uBAAmB;AACjE,OAAOC,YAAY,cAAa;AAChC,SAASC,QAAQ,EAAEC,SAAS,EAAEC,MAAM,QAA2B,QAAO;AAwGtE;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,qBAAqBC,MAAc;IACjD,IAAI,OAAOC,aAAa,aAAa,OAAO;IAC5C,IAAI;QACF,OAAOC,QAAQD,SAASE,aAAa,CAAC,CAAC,aAAa,EAAEH,OAAO,EAAE,CAAC;IAClE,EAAE,eAAM;QACN,uEAAuE;QACvE,iEAAiE;QACjE,OAAO;IACT;AACF;AAEA,eAAe,SAASI,qBAAqB,EAC3CC,MAAM,EACNC,IAAI,EACJC,OAAO,EACPC,KAAK,EACLC,eAAe,EACW;IAC1B,4EAA4E,GAC5E,MAAMC,kBAAkB,CAACV;;eACvB,SAACS,mCAAAA,gBAAiBE,QAAQ,CAACX,0BAAW,UAAUD,qBAAqBC;;IACvE;;;;;;;;;GASC,GACD,MAAMY,aAAad,OAAOS;IAC1BK,WAAWC,OAAO,GAAGN;IAErBV,UAAU;QACR,IAAI,CAACQ,QAAQ,OAAOS;QACpB,MAAMC,OAAO;YACX,IAAIH,WAAWC,OAAO,GAAGG,MAAM,KAAK,GAAG;gBACrCvB;YACF,OAAO;gBACL,sEAAsE;gBACtE,iEAAiE;gBACjE,mEAAmE;gBACnE,uBAAuB;gBACvBD;YACF;QACF;QACAyB,OAAOC,gBAAgB,CAACxB,+BAA+BqB;QACvD,OAAO,IAAME,OAAOE,mBAAmB,CAACzB,+BAA+BqB;IACzE,GAAG;QAACV;KAAO;IAEX,IAAI,CAACA,UAAUC,KAAKU,MAAM,KAAK,GAAG,OAAO;IAEzC,qBACE;kBACGV,KAAKc,GAAG,CAAC,CAAC,EAAEC,MAAM,EAAEC,SAAS,EAAE,GAC9B,qEAAqE;YACrE,sEAAsE;YACtE,oEAAoE;YACpE,sEAAsE;YACtE,sEAAsE;YACtE,kEAAkE;0BAClE,MAAC1B;;kCACC,KAACD;wBACC4B,IAAI,CAAC,OAAO,EAAEF,OAAOE,EAAE,CAAC,KAAK,CAAC;wBAC9BC,UAAS;wBACThB,OAAOA;wBACD,CAACjB,0BAA0B,EAAE8B,OAAOE,EAAE;kCAE3CF,OAAOI,WAAW,GAAGJ,OAAOI,WAAW,CAACH,aAAa;;oBAWvDD,OAAOK,aAAa,IAAIhB,gBAAgBW,OAAOK,aAAa,IAAI,qBAC/D,KAAC/B;wBACC4B,IAAI,CAAC,OAAO,EAAEF,OAAOE,EAAE,CAAC,IAAI,CAAC;wBAC7BC,UAAS;wBACThB,OAAOA;wBACD,CAACjB,0BAA0B,EAAE8B,OAAOE,EAAE;wBAC5C,0DAA0D;wBAC1D,4DAA4D;wBAC5D,yDAAyD;wBACzDI,KACEN,OAAOO,YAAY,GACfP,OAAOO,YAAY,CAACN,aACpBD,OAAOQ,SAAS;;;eA9BbR,OAAOE,EAAE;;AAsChC"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/advertising-tag-mounts.tsx"],"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// NO `'use client'` here, and it is a lint rule rather than a preference\n// (AGL-52): a directive inside `@aglyn/aglyn` makes the bundler split a\n// duplicate module graph, and the second canvas/emitter singleton renders the\n// tenant site blank. Every component that mounts this one carries the\n// directive itself, which is where the client boundary belongs.\n//\n// Deep app-utils modules, never the `@aglyn/aglyn` barrel (AGL-1550): this\n// file is reached from `site-analytics.tsx`, whose import closure\n// `site-analytics-independence.spec.ts` walks and which must stay independent\n// of the site-plugin gate.\nimport {\n  ADVERTISING_TAG_ATTRIBUTE,\n  type ResolvedAdvertisingTag,\n  restoreAdvertisingTags,\n  revokeAdvertisingTags,\n} from './advertising-tags'\nimport { usePageIdle } from './page-idle'\nimport { VISITOR_CONSENT_CHANGED_EVENT } from './visitor-consent'\nimport Script from 'next/script'\nimport { Fragment, useEffect, useRef, type ReactElement } from 'react'\n\n/**\n * The MOUNT and the WITHDRAWAL for consent-gated advertising tags, with no\n * opinion about where the verdict came from.\n *\n * ## Why this is a shared component and not a second copy per surface\n *\n * Aglyn runs advertising tags on three first-party surfaces and they resolve\n * consent through three different mechanisms: the tenant runtime reads a host\n * document and a per-host record, the console reads the platform record its\n * own posture machinery wrote, and the docs site reads the registrable-domain\n * mirror of that record. Those are genuinely different questions.\n *\n * What is NOT different is what happens once the answer is known: mount an\n * inline boot and a library per vendor, and — the half that is easy to forget\n * and impossible to retrofit — stop them the moment the answer changes. A\n * second copy of that half is how one surface comes to keep firing after\n * consent is withdrawn on another, because the copy that was not updated\n * still looks exactly like the one that was.\n *\n * So the verdict is a PROP and the machinery is shared. Each surface answers\n * its own question with its own resolver; none of them owns a teardown.\n *\n * ## Why it renders even when the answer is no\n *\n * Because the withdrawal path needs a listener. A visitor who accepts and then\n * turns advertising off must stop being tracked in THAT pageview, and by then\n * the vendor library has executed — React dropping the `<Script>` does not\n * unload it (AGL-1608). So this component stays mounted whenever the surface\n * participates at all, and subscribes to\n * {@link VISITOR_CONSENT_CHANGED_EVENT}; the teardown runs from the event,\n * synchronously with the visitor's click, rather than waiting on a re-render.\n *\n * Both paths run and they agree, which is deliberate: the render gate is what\n * keeps the tag out of a fresh pageview, the listener is what removes one that\n * is already there, and neither can do the other's job.\n */\nexport interface AdvertisingTagMountsProps {\n  /**\n   * Whether this surface participates in the gate AT ALL.\n   *\n   * False installs nothing — no listener, no scripts. That is the clause that\n   * keeps the tenant runtime's teardown off a customer's site: we did not load\n   * their pixel, we do not know what basis it runs on, and reaching into their\n   * page to kill it would be its own breach. `revokeAdvertisingTags` is\n   * additionally attribute-scoped, so there are two independent scopes.\n   */\n  readonly active: boolean\n  /** The verdict for THIS render: the tags that may exist right now. */\n  readonly tags: readonly ResolvedAdvertisingTag[]\n  /**\n   * Re-read the verdict from live state, for the withdrawal listener.\n   *\n   * A callback rather than the `tags` prop, because the listener fires from\n   * the visitor's own click in the same tick as the record is written — the\n   * props for the current render are by definition the state before it.\n   */\n  readonly resolve: () => readonly ResolvedAdvertisingTag[]\n  /**\n   * The request's CSP nonce, stamped onto BOTH elements of every pair.\n   *\n   * A surface that enforces a nonce'd `script-src` refuses an inline script\n   * that does not carry it, and the boot half of every pair is inline. Next's\n   * `<Script>` stamps a nonce only when one reaches it: the automatic path\n   * reads `HeadManagerContext`, and the App Router's client provider carries\n   * no nonce at all — so a pair mounted after hydration, which is the only\n   * time this component ever mounts one, is unnonced unless the caller hands\n   * the value down. An explicit prop wins inside `next/script`\n   * (`restProps.nonce || nonce`), which is what makes this the one door.\n   *\n   * The failure without it is silent and lopsided: the library beside the\n   * boot has a `src` the policy allows, so the vendor's code loads and runs\n   * against an account nobody configured, and the conversions this surface\n   * sends are lost with nothing in the page but a CSP violation.\n   *\n   * Absent on a surface that sends no `script-src`: nothing is stamped, and\n   * nothing is refused.\n   */\n  readonly nonce?: string\n  /**\n   * Libraries the HOST PAGE mounts itself, named by the needle a vendor\n   * declares in `sharesLibrary` (AGL-2681).\n   *\n   * {@link sharedLibraryPresent} reads the document at render time, and that\n   * is the right instrument for a loader some other party put there. It is\n   * the wrong one for a loader the SAME render is about to create. On the\n   * tenant the GA pair and this component both wait on `consent.ready`, so\n   * the first render that may emit either emits both — GA's `<Script>` is not\n   * in the document yet when this component looks, the check honestly says\n   * \"absent\", and the visitor downloads `gtag.js` twice: once as ours with\n   * `?id=AW-…`, once as gtag's own destination fetch for the `config` that\n   * follows. Measured on `aglyn.com/solutions/small-business` with\n   * advertising granted: two 147 KiB loaders for one account.\n   *\n   * A page that KNOWS it renders the library says so here, from the same\n   * condition that renders it, and the document check stays as the fallback\n   * for loaders it does not know about. Naming the needle rather than passing\n   * a boolean keeps the declaration per library: a page that mounts gtag has\n   * said nothing about the Meta pixel.\n   */\n  readonly sharedLibraries?: readonly string[]\n}\n\n/**\n * Is a library matching `needle` already in the document?\n *\n * Read at RENDER time rather than in an effect: the decision is whether to\n * emit a `<Script>` at all, and by the time an effect could answer, Next has\n * already appended it. `document` is guarded because this component renders on\n * the server too, where nothing is mounted and the honest answer is \"no\" — the\n * client render then re-evaluates with the real document.\n *\n * Blind to a loader the current render is creating alongside this one — see\n * `sharedLibraries` on the props for the case that needs the page to say so.\n */\nexport function sharedLibraryPresent(needle: string): boolean {\n  if (typeof document === 'undefined') return false\n  try {\n    return Boolean(document.querySelector(`script[src*=\"${needle}\"]`))\n  } catch {\n    // A hostile or absent DOM: assume nothing is mounted, which mounts our\n    // own copy — the cost is a duplicate fetch, never a missing tag.\n    return false\n  }\n}\n\nexport default function AdvertisingTagMounts({\n  active,\n  tags,\n  resolve,\n  nonce,\n  sharedLibraries,\n}: AdvertisingTagMountsProps): ReactElement | null {\n  /** Declared by the page, or found in the document: either means \"ride it\". */\n  const libraryProvided = (needle: string): boolean =>\n    (sharedLibraries?.includes(needle) ?? false) || sharedLibraryPresent(needle)\n  /*\n   * The resolver is held in a ref rather than listed as an effect dependency.\n   *\n   * Every caller passes a closure over its own live consent state, so the\n   * function identity changes on every render; depending on it would tear the\n   * listener down and re-install it each time, and a withdrawal that landed in\n   * that window would find no subscriber. The ref makes the subscription's\n   * lifetime `active`, which is the only thing that genuinely changes it,\n   * while the callback it invokes is always the newest one.\n   */\n  const resolveRef = useRef(resolve)\n  resolveRef.current = resolve\n\n  useEffect(() => {\n    if (!active) return undefined\n    const sync = () => {\n      if (resolveRef.current().length === 0) {\n        revokeAdvertisingTags()\n      } else {\n        // Symmetric: a visitor who withdrew and changed their mind inside one\n        // pageview would otherwise stay un-tracked until they navigated,\n        // because a re-rendered `<Script>` cannot re-execute a library the\n        // browser already ran.\n        restoreAdvertisingTags()\n      }\n    }\n    window.addEventListener(VISITOR_CONSENT_CHANGED_EVENT, sync)\n    return () => window.removeEventListener(VISITOR_CONSENT_CHANGED_EVENT, sync)\n  }, [active])\n\n  // Nothing is injected before the page has loaded and gone idle (AGL-3581).\n  // The withdrawal listener above is NOT behind this: a visitor who refuses\n  // before the page idles has nothing to tear down, and one who refuses after\n  // needs the listener already there. Every surface reads the same store, so\n  // a page that mounts its own loader flips in the same render as this one\n  // and `sharedLibraries` still describes it (AGL-2681).\n  const pageIsIdle = usePageIdle()\n\n  if (!active || tags.length === 0 || !pageIsIdle) return null\n\n  return (\n    <>\n      {tags.map(({ vendor, accountId }) => (\n        // A PAIR per vendor, inline boot first and library second — the same\n        // shape as the GA `ga-init` / `ga-src` pair, and for the same reason:\n        // the boot defines the vendor's queue shim and declares the consent\n        // state, so nothing the library later drains was queued under a state\n        // nobody chose. Both elements carry the teardown's scope marker; only\n        // elements carrying it are ever revoked, removed or cookie-swept.\n        <Fragment key={vendor.id}>\n          <Script\n            id={`ad-tag-${vendor.id}-init`}\n            strategy=\"afterInteractive\"\n            nonce={nonce}\n            {...{ [ADVERTISING_TAG_ATTRIBUTE]: vendor.id }}\n          >\n            {vendor.bootSnippet ? vendor.bootSnippet(accountId) : ''}\n          </Script>\n          {/* Skipped when another loader already brought this library in\n              (AGL-1152). Google Ads shares `gtag.js` with the GA4 measurement\n              id and with a GTM container, so a surface with both configured\n              would fetch it twice and define `gtag()` twice — and the boot\n              above would be the second voice in a consent conversation the\n              first one already had. One library, several `config` calls, is\n              how gtag carries several products. The page's own declaration is\n              consulted first (AGL-2681): the document cannot yet show a loader\n              this same render is creating. */}\n          {vendor.sharesLibrary && libraryProvided(vendor.sharesLibrary) ? null : (\n            <Script\n              id={`ad-tag-${vendor.id}-src`}\n              strategy=\"afterInteractive\"\n              nonce={nonce}\n              {...{ [ADVERTISING_TAG_ATTRIBUTE]: vendor.id }}\n              // `scriptSrcFor` where the vendor has one: gtag reads the\n              // container out of the loader's query, so the copy we bring\n              // ourselves has to name the account. See `scriptSrcFor`.\n              src={\n                vendor.scriptSrcFor\n                  ? vendor.scriptSrcFor(accountId)\n                  : vendor.scriptSrc\n              }\n            />\n          )}\n        </Fragment>\n      ))}\n    </>\n  )\n}\n"],"names":["ADVERTISING_TAG_ATTRIBUTE","restoreAdvertisingTags","revokeAdvertisingTags","usePageIdle","VISITOR_CONSENT_CHANGED_EVENT","Script","Fragment","useEffect","useRef","sharedLibraryPresent","needle","document","Boolean","querySelector","AdvertisingTagMounts","active","tags","resolve","nonce","sharedLibraries","libraryProvided","includes","resolveRef","current","undefined","sync","length","window","addEventListener","removeEventListener","pageIsIdle","map","vendor","accountId","id","strategy","bootSnippet","sharesLibrary","src","scriptSrcFor","scriptSrc"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,yEAAyE;AACzE,wEAAwE;AACxE,8EAA8E;AAC9E,sEAAsE;AACtE,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,kEAAkE;AAClE,8EAA8E;AAC9E,2BAA2B;AAC3B,SACEA,yBAAyB,EAEzBC,sBAAsB,EACtBC,qBAAqB,QAChB,wBAAoB;AAC3B,SAASC,WAAW,QAAQ,iBAAa;AACzC,SAASC,6BAA6B,QAAQ,uBAAmB;AACjE,OAAOC,YAAY,cAAa;AAChC,SAASC,QAAQ,EAAEC,SAAS,EAAEC,MAAM,QAA2B,QAAO;AAwGtE;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,qBAAqBC,MAAc;IACjD,IAAI,OAAOC,aAAa,aAAa,OAAO;IAC5C,IAAI;QACF,OAAOC,QAAQD,SAASE,aAAa,CAAC,CAAC,aAAa,EAAEH,OAAO,EAAE,CAAC;IAClE,EAAE,eAAM;QACN,uEAAuE;QACvE,iEAAiE;QACjE,OAAO;IACT;AACF;AAEA,eAAe,SAASI,qBAAqB,EAC3CC,MAAM,EACNC,IAAI,EACJC,OAAO,EACPC,KAAK,EACLC,eAAe,EACW;IAC1B,4EAA4E,GAC5E,MAAMC,kBAAkB,CAACV;;eACvB,SAACS,mCAAAA,gBAAiBE,QAAQ,CAACX,0BAAW,UAAUD,qBAAqBC;;IACvE;;;;;;;;;GASC,GACD,MAAMY,aAAad,OAAOS;IAC1BK,WAAWC,OAAO,GAAGN;IAErBV,UAAU;QACR,IAAI,CAACQ,QAAQ,OAAOS;QACpB,MAAMC,OAAO;YACX,IAAIH,WAAWC,OAAO,GAAGG,MAAM,KAAK,GAAG;gBACrCxB;YACF,OAAO;gBACL,sEAAsE;gBACtE,iEAAiE;gBACjE,mEAAmE;gBACnE,uBAAuB;gBACvBD;YACF;QACF;QACA0B,OAAOC,gBAAgB,CAACxB,+BAA+BqB;QACvD,OAAO,IAAME,OAAOE,mBAAmB,CAACzB,+BAA+BqB;IACzE,GAAG;QAACV;KAAO;IAEX,2EAA2E;IAC3E,0EAA0E;IAC1E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,uDAAuD;IACvD,MAAMe,aAAa3B;IAEnB,IAAI,CAACY,UAAUC,KAAKU,MAAM,KAAK,KAAK,CAACI,YAAY,OAAO;IAExD,qBACE;kBACGd,KAAKe,GAAG,CAAC,CAAC,EAAEC,MAAM,EAAEC,SAAS,EAAE,GAC9B,qEAAqE;YACrE,sEAAsE;YACtE,oEAAoE;YACpE,sEAAsE;YACtE,sEAAsE;YACtE,kEAAkE;0BAClE,MAAC3B;;kCACC,KAACD;wBACC6B,IAAI,CAAC,OAAO,EAAEF,OAAOE,EAAE,CAAC,KAAK,CAAC;wBAC9BC,UAAS;wBACTjB,OAAOA;wBACD,CAAClB,0BAA0B,EAAEgC,OAAOE,EAAE;kCAE3CF,OAAOI,WAAW,GAAGJ,OAAOI,WAAW,CAACH,aAAa;;oBAWvDD,OAAOK,aAAa,IAAIjB,gBAAgBY,OAAOK,aAAa,IAAI,qBAC/D,KAAChC;wBACC6B,IAAI,CAAC,OAAO,EAAEF,OAAOE,EAAE,CAAC,IAAI,CAAC;wBAC7BC,UAAS;wBACTjB,OAAOA;wBACD,CAAClB,0BAA0B,EAAEgC,OAAOE,EAAE;wBAC5C,0DAA0D;wBAC1D,4DAA4D;wBAC5D,yDAAyD;wBACzDI,KACEN,OAAOO,YAAY,GACfP,OAAOO,YAAY,CAACN,aACpBD,OAAOQ,SAAS;;;eA9BbR,OAAOE,EAAE;;AAsChC"}

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

@@ -1887,6 +1887,12 @@ export interface CrmPicklistTarget {
     keyField?: string;
     facet?: true;
     arrayKey?: string;
+    /**
+     * The field holding the GROUP of the value the record holds (AGL-3577) —
+     * a lead's `leadSourceDirection` — which every move that can change a
+     * label's group (a regroup, an add, a rename, a delete) rewrites.
+     */
+    groupField?: string;
 }
 /** A standard picklist field of the CRM. */
 export interface CrmPicklistDefinition extends PicklistSpec {
@@ -2006,6 +2012,7 @@ export declare const CRM_PICKLIST_DEFINITIONS: readonly [{
         readonly object: "lead";
         readonly field: "leadSource";
         readonly keyField: "leadSourceKey";
+        readonly groupField: "leadSourceDirection";
     }, {
         readonly object: "contact";
         readonly field: "leadSource";
@@ -2950,6 +2957,22 @@ export declare function crmPicklistKey(value: unknown): string | null;
 /** A lead's lead source as the list compares it: the picklist's key, `null` for none. */
 export declare const CRM_LEAD_SOURCE_KEY_FIELD = "leadSourceKey";
 export declare function crmLeadSourceKey(value: unknown): string | null;
+export declare const CRM_LEAD_SOURCE_DIRECTION_FIELD = "leadSourceDirection";
+/** The directions a lead source can have: the Lead source picklist's groups. */
+export declare const CRM_LEAD_SOURCE_DIRECTIONS: readonly ["inbound", "outbound"];
+export type CrmLeadSourceDirection = (typeof CRM_LEAD_SOURCE_DIRECTIONS)[number];
+export declare function isCrmLeadSourceDirection(value: unknown): value is CrmLeadSourceDirection;
+/** The direction `label` has in the org's lead source list — `null` for none. */
+export declare function crmLeadSourceDirection(leadSources: PicklistValueSet, label: unknown): CrmLeadSourceDirection | null;
+/** What a list-field writer knows beyond the record. */
+export interface CrmListFieldsContext {
+    /**
+     * The org's Lead source list as every reader takes it
+     * (`effectiveCrmLeadSourcePicklist`), which a lead's direction is read
+     * off. Without it a lead holding a lead source keeps the direction it has.
+     */
+    leadSources?: PicklistValueSet | null;
+}
 /** What a lead's search box reads (AGL-3246). */
 export declare const CRM_LEAD_SEARCH_SOURCES: readonly ["name", "email", "company", "jobTitle", "tags"];
 /**
@@ -2966,12 +2989,14 @@ export declare const CRM_LEAD_SCOPED_CAMPAIGNS_FIELD = "scopedCampaignIds";
  * the status — `new` for a lead nobody has touched, written so `status in
  * [new, working]` finds it — the lead source key and the address verdict.
  */
-export declare function crmLeadListFields(record: object): {
+export declare function crmLeadListFields(record: object, context?: CrmListFieldsContext): {
     searchTokens: string[];
     scopedSearchTokens: string[];
     scopedCampaignIds: string[];
     status: CrmLeadStatus;
     leadSourceKey: string | null;
+    /** Absent when the lead holds a lead source and no list was given. */
+    leadSourceDirection?: CrmLeadSourceDirection | null;
     emailStatus: string;
     industryKey: string | null;
     ratingKey: string | null;
@@ -3065,13 +3090,16 @@ export declare function crmContactListFields(record: object): {
  * {@link crmListFields} over the document it wrote.
  */
 export declare const CRM_LIST_FIELD_INPUTS: Readonly<Record<CrmListCollection, readonly string[]>>;
-/** Every list field of one record, from the record as stored. */
-export declare function crmListFields(collection: CrmListCollection, record: object): Record<string, unknown>;
+/**
+ * Every list field of one record, from the record as stored — and, for a
+ * lead's direction, the org's lead source list when `context` holds it.
+ */
+export declare function crmListFields(collection: CrmListCollection, record: object, context?: CrmListFieldsContext): Record<string, unknown>;
 /**
  * The list fields a stored record carries WRONGLY — the patch that brings
  * it level, `{}` when it already is. What a restamp and a backfill write.
  */
-export declare function crmListFieldsPatch(collection: CrmListCollection, record: object): Record<string, unknown>;
+export declare function crmListFieldsPatch(collection: CrmListCollection, record: object, context?: CrmListFieldsContext): Record<string, unknown>;
 /**
  * The field each collection's list ORDERS or asks `null` of, which a record
  * must therefore carry even when it has no value: a contact, a company and a
@@ -3087,6 +3115,6 @@ export declare const CRM_LIST_NULLABLE_FIELD: Readonly<Record<CrmListCollection,
  * does not set it — nothing is scheduled against a record that did not
  * exist, and a task created undated is still one its views must reach.
  */
-export declare function crmNewRecordListFields(collection: CrmListCollection, record: object): Record<string, unknown>;
+export declare function crmNewRecordListFields(collection: CrmListCollection, record: object, context?: CrmListFieldsContext): Record<string, unknown>;
 /** Whether a patch touches a field the collection's list fields are computed from. */
 export declare function crmListFieldsTouched(collection: CrmListCollection, patch: Record<string, unknown>): boolean;

package/src/lib/app-utils/crm.js

@@ -2384,10 +2384,12 @@ export function isCrmPicklistObject(value) {
     ],
     targets: [
         // The key the Leads list filters by moves with the label (AGL-3321).
+        // So is its direction, the value's group (AGL-3577).
         {
             object: 'lead',
             field: 'leadSource',
-            keyField: 'leadSourceKey'
+            keyField: 'leadSourceKey',
+            groupField: 'leadSourceDirection'
         },
         // A contact's lead source is each holder's own, like the rest of its profile.
         {
@@ -3832,9 +3834,11 @@ const CRM_VIEW_SOURCE_FIELD = CRM_CONTACT_VIEW_FIELDS.source;
  *                         address (`none` when there is none) and a contact's
  *                         per-holder facet values (`facetKeys`).
  *
- * All of them are DERIVED: a pure function of the document, computed here
- * and nowhere else, and written by every path that writes one of its inputs
- * — see `CRM_LIST_FIELD_INPUTS` — so a record a list cannot find is a writer
+ * All of them are DERIVED: a pure function of the document — save a lead's
+ * `leadSourceDirection`, which is the document and the org's lead source
+ * list (see `crmLeadSourceDirection`) — computed here and nowhere else,
+ * and written by every path that writes one of its inputs — see
+ * `CRM_LIST_FIELD_INPUTS` — so a record a list cannot find is a writer
  * that forgot, never a second formula that disagrees. A server writer that
  * holds the whole document spreads `crmListFields`; one that patched a field
  * restamps the record from what was stored (`restampCrmListFields` in the
@@ -3922,6 +3926,45 @@ export function crmEmailStatusKey(record) {
 export function crmLeadSourceKey(value) {
     return crmPicklistKey(value);
 }
+/*------------------------------------------
+ * A LEAD'S LEAD SOURCE DIRECTION (AGL-3577).
+ *
+ * The group of the Lead source picklist its value sits in — Inbound for a
+ * person who came to the organization, Outbound for one it went to — or
+ * `null` for no lead source, a value in no group, or a label the list does
+ * not hold. STORED on the lead as `leadSourceDirection`, so the Leads list
+ * asks `leadSourceDirection == inbound` — one equality, however many values
+ * the group holds. (It was asked as `leadSourceKey in [...]` over the
+ * group's values, and Inbound holds more than one `in` may.)
+ *
+ * The one list field that is not a function of the record alone: it is
+ * read off the org's list. So a writer passes that list
+ * ({@link CrmListFieldsContext}) or, without it, writes the direction only
+ * where it needs no list — `null` for a lead with no lead source — and
+ * leaves a held value's direction as stored. Every move of the list that
+ * can change a label's group rewrites the leads holding it (the
+ * `groupField` of the picklist's lead target).
+ *-----------------------------------------*/ export const CRM_LEAD_SOURCE_DIRECTION_FIELD = 'leadSourceDirection';
+/** The directions a lead source can have: the Lead source picklist's groups. */ export const CRM_LEAD_SOURCE_DIRECTIONS = [
+    'inbound',
+    'outbound'
+];
+export function isCrmLeadSourceDirection(value) {
+    return CRM_LEAD_SOURCE_DIRECTIONS.includes(value);
+}
+/** The direction `label` has in the org's lead source list — `null` for none. */ export function crmLeadSourceDirection(leadSources, label) {
+    var _picklistValueByLabel;
+    const group = (_picklistValueByLabel = picklistValueByLabel(leadSources, label)) == null ? void 0 : _picklistValueByLabel.group;
+    return isCrmLeadSourceDirection(group) ? group : null;
+}
+/** A lead's direction field — see the block above. */ function leadSourceDirectionField(lead, context) {
+    if (!crmLeadSourceKey(lead['leadSource'])) return {
+        leadSourceDirection: null
+    };
+    return context.leadSources ? {
+        leadSourceDirection: crmLeadSourceDirection(context.leadSources, lead['leadSource'])
+    } : {};
+}
 /** What a lead's search box reads (AGL-3246). */ export const CRM_LEAD_SEARCH_SOURCES = [
     'name',
     'email',
@@ -3945,12 +3988,13 @@ function leadCampaignIds(lead) {
  * will be once written): the search tokens, its campaigns behind its scope,
  * the status — `new` for a lead nobody has touched, written so `status in
  * [new, working]` finds it — the lead source key and the address verdict.
- */ export function crmLeadListFields(record) {
+ */ export function crmLeadListFields(record, context = {}) {
     const lead = record;
     return _extends({}, crmSearchFields(lead['visibleTo'], CRM_LEAD_SEARCH_SOURCES.map((field)=>lead[field])), {
         scopedCampaignIds: scopedSearchTokens(lead['visibleTo'], leadCampaignIds(lead)),
         status: crmLeadStatus(lead),
-        leadSourceKey: crmLeadSourceKey(lead['leadSource']),
+        leadSourceKey: crmLeadSourceKey(lead['leadSource'])
+    }, leadSourceDirectionField(lead, context), {
         emailStatus: crmEmailStatusKey(lead),
         // The Industry and Rating the Leads list filters by (AGL-3513).
         industryKey: crmPicklistKey(lead['industry']),
@@ -4186,10 +4230,13 @@ export function crmContactListFields(record) {
         'title'
     ]
 };
-/** Every list field of one record, from the record as stored. */ export function crmListFields(collection, record) {
+/**
+ * Every list field of one record, from the record as stored — and, for a
+ * lead's direction, the org's lead source list when `context` holds it.
+ */ export function crmListFields(collection, record, context = {}) {
     switch(collection){
         case 'leads':
-            return crmLeadListFields(record);
+            return crmLeadListFields(record, context);
         case 'contacts':
             return crmContactListFields(record);
         case 'companies':
@@ -4209,8 +4256,8 @@ const sameValue = (a, b)=>{
 /**
  * The list fields a stored record carries WRONGLY — the patch that brings
  * it level, `{}` when it already is. What a restamp and a backfill write.
- */ export function crmListFieldsPatch(collection, record) {
-    const fields = crmListFields(collection, record);
+ */ export function crmListFieldsPatch(collection, record, context = {}) {
+    const fields = crmListFields(collection, record, context);
     const stored = record;
     const patch = {};
     for (const [field, value] of Object.entries(fields)){
@@ -4237,8 +4284,8 @@ const sameValue = (a, b)=>{
  * the collection's {@link CRM_LIST_NULLABLE_FIELD} as `null` when the record
  * does not set it — nothing is scheduled against a record that did not
  * exist, and a task created undated is still one its views must reach.
- */ export function crmNewRecordListFields(collection, record) {
-    const fields = crmListFields(collection, record);
+ */ export function crmNewRecordListFields(collection, record, context = {}) {
+    const fields = crmListFields(collection, record, context);
     const nullable = CRM_LIST_NULLABLE_FIELD[collection];
     const stored = record[nullable != null ? nullable : ''];
     if (!nullable || nullable in record && stored !== undefined) return fields;