@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +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"}

package/src/lib/app-utils/advertising-tags.d.ts

@@ -0,0 +1,307 @@
+/**
+ * @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 AnalyticsEnvironment } from './analytics-environment';
+import { type StoredVisitorConsent, type VisitorConsentHost } from './visitor-consent';
+/**
+ * The attribute every script element this module renders carries.
+ *
+ * Load-bearing for the teardown, not decoration. {@link revokeAdvertisingTags}
+ * acts ONLY on elements carrying it, so a vendor tag a customer pasted into
+ * their own site's Custom HTML is never touched by our withdrawal path — we
+ * did not load it, we do not know what basis it runs on, and silently killing
+ * it would be us configuring a customer's site. Its value is the vendor id.
+ */
+export declare const ADVERTISING_TAG_ATTRIBUTE = "data-aglyn-ad-tag";
+/**
+ * One advertising vendor, described completely enough to LOAD it and — the
+ * half that is easy to forget and impossible to retrofit — to STOP it.
+ *
+ * Every field exists because withdrawal needs it. A vendor that cannot be
+ * revoked, whose script cannot be found in the document, and whose cookies are
+ * not named, cannot be consent-gated at all; requiring the descriptor to
+ * answer all three is what stops a future vendor being added load-only.
+ *
+ * TWO SHAPES, since AGL-2486. A vendor we MOUNT answers all three and every
+ * field below is required of it. A {@link AdvertisingVendor.sweepOnly} vendor
+ * answers only the third, because there is no script of ours to find or stop —
+ * its cookies are a side effect of a tag another module owns. The mount fields
+ * are therefore optional at the type level and mandatory in practice for
+ * anything without that flag, which `advertising-tag-gate.spec.tsx` asserts.
+ * `cookiePrefixes` stays required of BOTH: naming the cookies is the one thing
+ * no vendor is excused from, and it is what the Cookie Policy is written from.
+ */
+export interface AdvertisingVendor {
+    /** Stable key: the `analytics.adTags` map key and the attribute value. */
+    readonly id: string;
+    /** Human name, for the cookie policy and the consent copy. */
+    readonly label: string;
+    /**
+     * A vendor this module never LOADS — its cookies are a side effect of a tag
+     * some other module owns (today: the GA4 gtag that `site-analytics.tsx`
+     * mounts, which writes `_gcl_*` once `ad_storage` is granted). AGL-2486.
+     *
+     * It is a member of this registry because the registry's job is every
+     * advertising artifact that touches the browser, and because the disclosure
+     * guard in `cookie-inventory.spec.ts` keys on `cookiePrefixes` — a vendor
+     * missing from here is a vendor missing from the Cookie Policy. Meta being
+     * present while Google was absent is the asymmetry that produced the gap.
+     *
+     * Such a vendor declares `id`, `label` and `cookiePrefixes` and NOTHING
+     * else: there is no script to mount, none to remove, and no vendor-specific
+     * consent call — GA's own consent-mode signals carry the state. The mount
+     * fields below are therefore optional, and `advertising-tag-gate.spec.tsx`
+     * asserts every vendor WITHOUT this flag still declares all of them, so the
+     * original invariant — a vendor that cannot be revoked cannot be gated —
+     * survives for everything that does load.
+     */
+    readonly sweepOnly?: true;
+    /**
+     * Sweep this vendor's cookies even when no marked element is present.
+     *
+     * The element check is an OWNERSHIP test, not a liveness one: a pixel we did
+     * not load is a pixel running on a basis that is not ours to withdraw, so
+     * its cookies are not ours to clear either. `alwaysSweep` is for a vendor
+     * whose cookies cannot belong to anybody else's tag on our surfaces —
+     * Google's `_gcl_*`, which a GTM container or a bare gtag writes without any
+     * marker of ours ever existing. That is the AGL-2486 case, and it is a
+     * property of the COOKIE rather than of the loader.
+     */
+    readonly alwaysSweep?: true;
+    /**
+     * Strict format check on the configured account id. The id lands inside an
+     * inline script, so this is load-bearing exactly as
+     * `GA_MEASUREMENT_ID_PATTERN` is (the AGL-138 concern).
+     */
+    readonly accountIdPattern?: RegExp;
+    /** The vendor library URL. Constant — no interpolation reaches it. */
+    readonly scriptSrc?: string;
+    /**
+     * The library URL for a vendor whose LOADER carries the account id.
+     *
+     * Most vendors take their id in the boot snippet and fetch a constant URL,
+     * which is what {@link scriptSrc} is. `gtag.js` is the exception: Google's
+     * documented install is `gtag/js?id=<account>`, and the id in the query is
+     * what tells the loader which container's configuration to fetch. Without
+     * it the library still returns 200 and still defines `gtag()`, so nothing
+     * anywhere reports an error — it simply registers no container, and every
+     * `config` for the account queues against a runtime that will never serve
+     * it. Measured on `app.aglyn.com` (AGL-2559): the bare loader left
+     * `google_tag_data.tidr.container` holding the GA4 id and an EMPTY string,
+     * with no request to `googleadservices` at all.
+     *
+     * Present, it wins over {@link scriptSrc}. `scriptSrc` stays the vendor's
+     * base URL, because it is what {@link sharesLibrary}, {@link scriptMatch}
+     * and the CSP origin list are all matched against, and none of those may
+     * vary per account.
+     *
+     * The id reaching a URL is the same load-bearing check as the id reaching an
+     * inline script: it is interpolated only after `accountIdPattern` passed.
+     */
+    readonly scriptSrcFor?: (accountId: string) => string;
+    /**
+     * A substring of a library URL this vendor SHARES with another loader.
+     *
+     * Set it and the tag mounts its boot snippet but skips its own `<script>`
+     * when a matching one is already in the document. Google Ads is the case:
+     * `gtag.js` is the same library the GA4 measurement id loads, so a site with
+     * both configured would fetch it twice, define `gtag()` twice, and — the
+     * part that actually corrupts data — push a second `consent default` that
+     * re-denies what the first one granted, mid-pageview.
+     *
+     * The boot snippet still runs, because a `config` for a SECOND product is
+     * exactly how gtag is meant to carry two: one library, two configs, no
+     * double count.
+     */
+    readonly sharesLibrary?: string;
+    /**
+     * Substring that identifies a RESIDENT script element for this vendor,
+     * used together with {@link ADVERTISING_TAG_ATTRIBUTE} at teardown.
+     */
+    readonly scriptMatch?: string;
+    /** Cookie-name prefixes this vendor sets, swept on withdrawal. */
+    readonly cookiePrefixes: readonly string[];
+    /** The inline boot snippet, built from a FORMAT-CHECKED account id. */
+    readonly bootSnippet?: (accountId: string) => string;
+    /**
+     * Tell a RESIDENT tag what the visitor decided. The vendor's own documented
+     * opt-out mechanism — the `ga-disable-<id>` analogue — reached through
+     * whatever global it left behind. Called in both directions, so a visitor
+     * who withdraws and changes their mind in one pageview is not silently
+     * unmeasured until they navigate.
+     */
+    readonly setConsent?: (scope: Record<string, unknown>, granted: boolean) => void;
+}
+/**
+ * Meta (Facebook/Instagram) Pixel.
+ *
+ * ## What happens to `_fbp` / `_fbc` on withdrawal: they are DELETED
+ *
+ * Not merely stopped. The decision is inherited, not invented: AGL-1606
+ * settled that a withdrawal "cleans up, it does not merely stop adding" for
+ * the GA equivalents, and there is no honest reading under which Meta's
+ * first-party identifiers get a softer rule than Google's. Both are
+ * browser-lifetime identifiers written by an advertising tag under a consent
+ * the visitor has just withdrawn.
+ *
+ * They are swept with the SAME ladder as `_ga` — the exact hostname and every
+ * domain up to the registrable one — because Meta writes them the same way GA
+ * does: path `/`, first-party, at the registrable domain. A deletion aimed at
+ * the exact hostname would silently no-op.
+ *
+ * Two limits, stated rather than glossed. Any copy Meta already ingested is
+ * gone from our reach — deletion stops future joins, it does not retract past
+ * ones; the CPRA opt-out title on the control is about the ongoing "share",
+ * which this does stop. And a cookie written at a path other than `/` is not
+ * reachable through `document.cookie`; Meta does not write one.
+ *
+ * ## Why `consent revoke` is called BEFORE the sweep
+ *
+ * `fbq('consent', 'revoke')` is Meta's documented CMP control and the exact
+ * counterpart of the `ga-disable-<id>` flag. Skipping it and going straight to
+ * the cookies reproduces AGL-1608: the resident pixel's next automatic event
+ * re-writes `_fbp` and the sweep un-does itself inside the same pageview.
+ */
+export declare const META_PIXEL_VENDOR: AdvertisingVendor;
+/**
+ * Google advertising storage — a SWEEP-ONLY vendor (AGL-2486).
+ *
+ * There is no Google ad script for this module to load. `_gcl_*` and `_gac_*`
+ * are written by the GA4 gtag that `site-analytics.tsx` already mounts, once
+ * the visitor's `ad_storage` is granted. So the tag is somebody else's to
+ * mount and somebody else's to signal; what belongs here is the half nobody
+ * owned, which is the cookies.
+ *
+ * `_gcl_au` is the specific reason this exists. It does not begin with `_ga`,
+ * so {@link ANALYTICS_COOKIE_PREFIXES} never reached it, and `revokeAdvertisingTags`
+ * could not either — that function acts on marked script ELEMENTS, and there
+ * has never been one for Google. The cookie therefore survived every
+ * withdrawal on every surface. See {@link ADVERTISING_COOKIE_PREFIXES} for why
+ * the prefix is `_gcl` ALONE and cannot reach `_ga`/`_gid`.
+ *
+ * ⚠️ `_gac` is NOT in that list and must not be added back. It is written
+ * under the analytics loader, sits in the `Google Analytics` row of
+ * `apps/console/constants/cookie-inventory.ts`, and is already swept by the
+ * `_ga` prefix; `advertising-cookie-sweep.spec.ts` pins it as analytics-owned.
+ * An earlier version of this comment named it here, and a published Cookie
+ * Policy line describing `_gac` as advertising-gated traces to exactly that.
+ *
+ * The prefixes are IMPORTED rather than restated. They are consumed in two
+ * places — the universal sweep in `storeVisitorConsent` and the element-scoped
+ * one below — and a second copy would be a second thing to forget.
+ */
+export declare const GOOGLE_ADS_VENDOR: AdvertisingVendor;
+/**
+ * LinkedIn Insight Tag.
+ *
+ * ## Cookies, and why the prefix list is long
+ *
+ * LinkedIn writes more names than the other two and they do not share a stem:
+ * `li_sugr` and `UserMatchHistory` are the retargeting identifiers, `bcookie`
+ * and `lidc` are set on the `.linkedin.com` domain by the loader, and
+ * `AnalyticsSyncHistory` records the last sync. A prefix list that named only
+ * `li_` would leave three of them behind on withdrawal — the AGL-2486 shape,
+ * where a sweep looks thorough because it cleared the ones that happen to
+ * share a prefix.
+ *
+ * ⚠️ `bcookie` and `lidc` are written at `.linkedin.com`, a domain a page on
+ * our origin cannot delete through `document.cookie`. The sweep removes what
+ * it can reach and the element removal stops the tag writing more; the rest is
+ * LinkedIn's to hold, and saying so is better than a sweep that quietly
+ * half-works.
+ */
+export declare const LINKEDIN_INSIGHT_VENDOR: AdvertisingVendor;
+/**
+ * Every vendor this gate knows how to tear down — which is a SUPERSET of the
+ * vendors it knows how to load, now that a sweep-only member exists.
+ */
+export declare const ADVERTISING_VENDORS: readonly AdvertisingVendor[];
+/**
+ * The host fields this module reads, on top of the consent ones.
+ *
+ * `adTags` maps a vendor id to that vendor's account id. NO host document
+ * carries it today; see the module comment on why deployment is a separate,
+ * reviewable data change rather than a consequence of merging this.
+ */
+export interface AdvertisingTagHost extends VisitorConsentHost {
+    analytics?: {
+        gaMeasurementId?: string;
+        /** Vendor id → account id. Absent on every site that exists. */
+        adTags?: Record<string, string> | null;
+    } | null;
+}
+/** A vendor that may load, paired with the id it was configured with. */
+export interface ResolvedAdvertisingTag {
+    readonly vendor: AdvertisingVendor;
+    readonly accountId: string;
+}
+/**
+ * The whole verdict: which advertising tags may exist in this document, for
+ * this visitor, on this site, right now?
+ *
+ * Pure, and empty is the answer to every question it cannot answer — an absent
+ * host, an unreadable record, an unknown vendor id, a malformed account id.
+ * See the module comment for the six conditions and why each one is separate.
+ *
+ * `stored` is the CLIENT-resolved record. Like the GA gate, this is evaluated
+ * after hydration only: tenant pages are ISR-cached, so the server HTML must
+ * be identical for every visitor and cannot carry a tag one of them granted.
+ *
+ * `internal` is read the same way and for the same reason. Taking it as a
+ * defaulted parameter rather than calling into the browser mid-verdict is what
+ * keeps this function testable in both directions — a gate that can only be
+ * exercised one way is the shape that ships broken (AGL-2067).
+ */
+export declare function resolveAdvertisingTags(host: AdvertisingTagHost | null | undefined, stored: StoredVisitorConsent | null | undefined, env?: AnalyticsEnvironment, internal?: boolean): ResolvedAdvertisingTag[];
+/** Every vendor whose tag this module loaded and that is still resident. */
+export declare function residentAdvertisingVendors(): AdvertisingVendor[];
+/**
+ * Stop every advertising tag THIS MODULE loaded, and return the vendor ids it
+ * acted on — which is what makes the withdrawal assertable rather than
+ * assumed.
+ *
+ * Three steps, in this order and for these reasons:
+ *
+ * 1. **Revoke on the resident tag.** The gate cannot unload a script that has
+ *    already executed. This is the vendor's own kill switch and it is what
+ *    actually stops the next automatic event.
+ * 2. **Remove the script elements.** So the structural property the gate
+ *    asserts — the vendor's script is not in this document — is restored and
+ *    not merely claimed. React unmounting its `<Script>` does not reliably do
+ *    this: `next/script` injects into the head and leaves it there.
+ * 3. **Sweep the cookies.** Last, because steps 1 and 2 are what stop them
+ *    coming straight back (AGL-1608).
+ *
+ * Acts only on tags carrying {@link ADVERTISING_TAG_ATTRIBUTE}. On a customer
+ * site — where this module never loaded anything — it is a no-op that touches
+ * no cookie, which is the only correct behaviour: their pixel, if any, runs on
+ * a basis that is not ours to withdraw.
+ */
+export declare function revokeAdvertisingTags(hostname?: string | null): string[];
+/**
+ * Re-grant on a tag that is still resident — the symmetric half.
+ *
+ * A visitor who withdraws and changes their mind inside one pageview would
+ * otherwise stay silently un-tracked until they navigated, because a re-
+ * rendered `<Script>` cannot re-execute a library the browser already ran.
+ * `setResidentAnalyticsTags` is symmetric for exactly this reason and this is
+ * the same move for a second channel.
+ *
+ * Returns the vendor ids it reached; empty when nothing is resident, which is
+ * the normal case — a re-grant after the elements were removed goes through
+ * the gate and loads a fresh tag instead.
+ */
+export declare function restoreAdvertisingTags(): string[];