@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/visitor-consent.d.ts

@@ -0,0 +1,757 @@
+/**
+ * @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.
+ */
+/**
+ * Visitor tracking consent (AGL-1498): the single answer to "may this
+ * tracking feature run for this visitor?", shared by every surface that has
+ * to agree about it — the tenant's GA injection, the consent banner, the
+ * marketing runtime's visitor id, the console card that configures it, and
+ * the console preview's region simulator.
+ *
+ * The model, and the honesty bar it was built against:
+ *
+ * - **Strictly necessary — no consent asked, none required.** The cart cookie
+ *   (`aglyn_cart_{hostId}`, commerce checkout), the member session
+ *   (`aglyn_member_{hostId}`, memberships sign-in), the `aglyn-tenant-host`
+ *   preview-host override, popup/announcement dismissal stamps (local-only,
+ *   never transmitted, and blocking them would show MORE popups), the
+ *   first-party pageview beacon (cookieless, stores no visitor identifier —
+ *   AGL-82), and the stored consent choice itself.
+ * - **Consent-gated: `advertising`** (AGL-1649) — GA4's `ad_storage`,
+ *   `ad_user_data` and `ad_personalization`. OFF for every site unless the
+ *   host turns the question on, and granted only by an explicit visitor yes
+ *   to that specific category: never by the implied default, never by a
+ *   record written before the category existed, never by any refusal status.
+ *   A host who needs Ads storage previously had one workaround — switch the
+ *   whole tool off and run their own CMP — which is why this exists.
+ * - **Consent-gated: `analytics`.** Today that is the customer-configured
+ *   Google Analytics tag — a third-party identifier-setting script — plus
+ *   the CROSS-VISIT persistence of the `aglyn:visitor` experiment id (the id
+ *   never leaves the browser, but an indefinite-lifetime identifier is
+ *   disproportionate without a basis; without one it degrades to
+ *   sessionStorage, so variants stay stable within the visit).
+ *
+ * **Two postures, resolved per visitor** (the Squarespace shape, host-chosen):
+ *
+ * - **`opt-in`** — prior consent: nothing gated loads until an explicit
+ *   accept. Applied in regions whose law requires prior consent (EU/EEA/UK),
+ *   whenever the visitor's region is UNKNOWN, and everywhere when the host
+ *   picks `strict` mode. Unknown-geo falls to opt-in deliberately: the
+ *   asymmetry is a few lost analytics events on rare headerless visits
+ *   versus pre-consent tracking of an EU visitor.
+ * - **`opt-out`** — implied consent: gated features are live from first
+ *   paint, no banner and no notice; the visitor's recorded state is
+ *   `implied`, and the always-present "Your Privacy Choices" control is the
+ *   opt-out surface. Applied outside prior-consent regions when the host
+ *   mode is `geo`.
+ *
+ * **GPC (Global Privacy Control)** is honored as an automatic opt-out in
+ * both postures: a visitor whose browser sends it is recorded `gpc-opt-out`
+ * and never tracked, unless they later explicitly accept (the signal is a
+ * default; a specific, informed choice overrides it).
+ *
+ * Enforcement is AT THE SOURCE and MODE-INDEPENDENT: whenever the verdict is
+ * "no", the GA script never loads — not load-then-suppress — and the gate
+ * does not care WHY consent is absent. Because tenant pages are ISR-cached,
+ * both the posture and the verdict are evaluated client-side only — the
+ * cached HTML never varies by region or consent state.
+ */
+/** The host fields this module reads; keeps callers free of the full doc. */
+export interface VisitorConsentHost {
+    analytics?: {
+        gaMeasurementId?: string;
+        /** GTM container (AGL-2486) — gated exactly as the GA id is. */
+        gtmContainerId?: string;
+    } | null;
+    consent?: {
+        /**
+         * Host opt-out of the whole tool (AGL-1498). PERSISTED NAME. `true`
+         * means the host runs their own consent solution (or accepts the
+         * exposure): no banner, no privacy-choices control, and gated features
+         * load for every visitor. Absent means the tool is active.
+         */
+        disabled?: boolean;
+        /**
+         * The host's consent posture (AGL-1498). PERSISTED NAME.
+         * - `'geo'` — geo-conditional: implied consent (tracking on, opt-out
+         *   offered) outside prior-consent regions; a prior-consent banner in
+         *   EU/EEA/UK and wherever the region is unknown.
+         * - `'strict'` — opt-in everywhere: every visitor gets the banner.
+         * Absent behaves as `'geo'` — the field practice (Squarespace) and the
+         * posture the console preselects; recorded here so nobody discovers it
+         * by surprise.
+         */
+        mode?: 'geo' | 'strict';
+        /**
+         * Host opt-in to ASKING about advertising storage (AGL-1649). PERSISTED
+         * NAME. Absent or `false` — the default for every site that exists — means
+         * the visitor is asked about analytics only and the three advertising
+         * signals stay denied, which is where AGL-1622 put them.
+         *
+         * `true` adds a SECOND question to the banner and the privacy-choices
+         * panel. It does not grant anything by itself: it creates the opportunity
+         * for a visitor to say yes, which is the thing a host previously could not
+         * obtain without switching the whole tool off and running their own CMP.
+         *
+         * Strictly `=== true`, like {@link isConsentToolDisabled}: a truthy string
+         * out of a hand-edited host document must not turn a consent category on.
+         */
+        advertising?: boolean;
+    } | null;
+}
+/** The host's configured posture; absent means `'geo'`. */
+export type HostConsentMode = 'geo' | 'strict';
+/** The per-visitor resolved posture. */
+export type VisitorConsentPosture = 'opt-in' | 'opt-out';
+/**
+ * Consent-gated feature categories.
+ *
+ * `advertising` (AGL-1649) is gated ONLY where the host opted in — see
+ * {@link hostAsksAboutAdvertising}. The stored shape is keyed by category, so
+ * this extended rather than migrated, and a record written before it existed
+ * reads as "never asked", never as a grant.
+ */
+export type VisitorConsentCategory = 'analytics' | 'advertising';
+/**
+ * A visitor's recorded consent state. The five are DISTINCT on purpose:
+ * "how many visitors are tracked" (and any future regulator question) needs
+ * to distinguish a visitor who clicked Accept from one who was defaulted in.
+ *
+ * - `implied` — opt-out posture, no action taken: tracking is on.
+ * - `accepted` — explicit yes (either posture): tracking is on.
+ * - `declined` — explicit no to a prior-consent banner: tracking is off.
+ * - `opted-out` — explicit opt-out from the implied default: tracking off.
+ * - `gpc-opt-out` — the browser's GPC signal, honored: tracking off.
+ */
+export type VisitorConsentStatus = 'implied' | 'accepted' | 'declined' | 'opted-out' | 'gpc-opt-out';
+/** The statuses that are a visitor's own click, not a default or a signal. */
+export declare function isExplicitConsentStatus(status: VisitorConsentStatus | null | undefined): boolean;
+/**
+ * Which refusal a "no" is, for a visitor in this state.
+ *
+ * `opted-out` when they were defaulted in, `declined` when they were asked
+ * first. The GATE does not care — both refuse — but the RECORD does: "how many
+ * visitors were tracked before they said no" is a question only these two
+ * answers separate, and it is a question a regulator can ask.
+ *
+ * Lives here rather than in either surface that needs it. Both the consent
+ * overlay and the console's own module were deriving it, and a rule with two
+ * derivations is a rule that eventually means two different things.
+ */
+export declare function refusalStatusFor(stored: {
+    status?: VisitorConsentStatus;
+} | null | undefined, posture: VisitorConsentPosture | null | undefined): VisitorConsentStatus;
+/** Whether a status grants the analytics category. */
+export declare function analyticsGrantedByStatus(status: VisitorConsentStatus): boolean;
+/**
+ * Whether a status can carry an advertising grant at all (AGL-1649; widened by
+ * AGL-2402, narrowed back on 2026-08-24, widened again on 2026-08-25).
+ *
+ * The SAME status set as {@link analyticsGrantedByStatus}, and the agreement is
+ * deliberate: `implied` grants both. Being defaulted in where the law permits a
+ * default is one posture, applied to both categories, and the visitor's opt-out
+ * surface is the same one.
+ *
+ * ## Why it moved three times, because the next person will move it again
+ *
+ * AGL-2402 (`a410d8785`) first made `implied` qualify, on the reasoning that
+ * the rule is safe by GEOGRAPHY: an `implied` record can only ever be written
+ * in the OPT-OUT posture, because {@link resolveConsentPosture} puts the EU 27,
+ * the EEA/EFTA three, the UK, Gibraltar, the EU outermost regions AND any
+ * visitor whose region cannot be determined into opt-in, where
+ * `decideVisitorConsent` records no default at all. That half was always sound
+ * and is still asserted in `visitor-consent-advertising.spec.ts`.
+ *
+ * The half that failed was DISCLOSURE. That commit stated the published Cookie
+ * Policy had been updated first; read against the live page on 2026-08-24 it
+ * said two different things — its "Marketing / advertising" paragraph described
+ * the opt-out posture, while the per-cookie table said `_gac`, `_gcl_au`,
+ * `_fbp` and `_fbc` were "set only where you have allowed advertising cookies"
+ * and "Your choices" repeated it. A policy that says both cannot authorise the
+ * wider behaviour, so the code was narrowed to the strictest thing it said.
+ *
+ * On 2026-08-25 the master moved for real, in the right order: those five
+ * opt-in-only sentences were rewritten in the Cookie Policy gdoc, and only then
+ * did this function follow. The Privacy Policy needed nothing — it already said
+ * *"With your consent, we do 'share' … for cross-context behavioral
+ * advertising"*, named Google and Meta, and described the EU/UK-ask-first vs.
+ * elsewhere-from-first-visit split. The flat "we do not sell or share" denial
+ * that the narrowing reasoned from was a paraphrase in `docs/ANALYTICS.md`, not
+ * a sentence in the document.
+ *
+ * ⛔ Re-narrowing is a POLICY act, not a code change. Move the published
+ * masters first and let this follow — never the other way round. Nine surfaces
+ * describe this rule to a human and `consent-advertising-copy-drift.spec.ts`
+ * fails on all of them the moment the two disagree.
+ *
+ * A `true` here is necessary, never sufficient: the host must ALSO have opted
+ * into asking (see {@link hostAsksAboutAdvertising}), and a refusal — declined,
+ * opted out, or a GPC signal — outranks the default everywhere.
+ */
+export declare function advertisingGrantedByStatus(status: VisitorConsentStatus): boolean;
+/**
+ * Strict GA measurement-id check (AGL-138) — the id lands inside an inline
+ * script, so the format gate is load-bearing, not cosmetic.
+ */
+export declare const GA_MEASUREMENT_ID_PATTERN: RegExp;
+/**
+ * The shape a Meta pixel id has, shared by the LOADER and the console field.
+ *
+ * Declared HERE and not in `advertising-tags.ts`, which the console may not
+ * import: `advertising-tag-gate.spec` case (f) fails any console file that
+ * reaches for that module, because it is what mounts a vendor's script. A
+ * format string is not a vendor, so it lives with the other id patterns and
+ * the loader imports it from here.
+ *
+ * One pattern, because two would be a form that accepts an id the loader then
+ * refuses — the tag never mounts and the operator is left looking at a saved
+ * field and no pixel.
+ */
+export declare const META_PIXEL_ID_PATTERN: RegExp;
+/**
+ * A Google Ads conversion id — `AW-` and digits.
+ *
+ * Distinct from `GA_MEASUREMENT_ID_PATTERN` (`G-…`) on purpose: they are
+ * different products with different ids, and a form that accepted either in
+ * either field would load an analytics id into an ads tag and report nothing.
+ */
+export declare const GOOGLE_ADS_ID_PATTERN: RegExp;
+/**
+ * A LinkedIn Insight partner id — numeric, and short.
+ *
+ * Bounded well under the Meta band rather than sharing it: a partner id is six
+ * or seven digits today, and a pattern loose enough to accept a Meta pixel id
+ * would let a mis-paste into the wrong field validate and then load a tag that
+ * matches nothing.
+ */
+export declare const LINKEDIN_PARTNER_ID_PATTERN: RegExp;
+/** The configured GA id when it is well-formed, else null. */
+export declare function resolveGaMeasurementId(host: VisitorConsentHost | null | undefined): string | null;
+/**
+ * A Google Tag Manager container id — `GTM-` and 5–10 upper-case
+ * alphanumerics.
+ *
+ * Format-checked for the same reason the GA id is: it lands inside an INLINE
+ * SCRIPT on a published page, so anything that is not this shape must never
+ * reach it (AGL-138).
+ */
+export declare const GTM_CONTAINER_ID_PATTERN: RegExp;
+/** The configured GTM container when it is well-formed, else null. */
+export declare function resolveGtmContainerId(host: VisitorConsentHost | null | undefined): string | null;
+/**
+ * Whether the site loads ANY Google tag — a GA property, a GTM container, or
+ * both (AGL-2486).
+ *
+ * The one predicate both consent questions are asked through, because the
+ * alternative is two places that each remember only one of the two. A site
+ * with a container and no GA id is a site that tracks: it was the shape that
+ * would have had `consentGatedCategories` return `[]`, no banner rendered, and
+ * the container loading ungated — which for GTM is worse than for GA, since a
+ * container is exactly the thing that can carry advertising tags.
+ */
+export declare function hostHasGoogleTag(host: VisitorConsentHost | null | undefined): boolean;
+/** Host opt-out of the tool. Absent means ACTIVE — the safe default. */
+export declare function isConsentToolDisabled(host: VisitorConsentHost | null | undefined): boolean;
+/** The host's posture choice; anything but `'strict'` reads as `'geo'`. */
+export declare function resolveHostConsentMode(host: VisitorConsentHost | null | undefined): HostConsentMode;
+/**
+ * The gated categories this site actually uses. Empty means there is
+ * nothing to consent to and no consent UI renders — a banner with no
+ * question behind it is decoration that trains visitors to click banners.
+ */
+export declare function consentGatedCategories(host: VisitorConsentHost | null | undefined): VisitorConsentCategory[];
+/**
+ * Whether this site asks its visitors about advertising storage (AGL-1649).
+ *
+ * Two conditions, both required. The host has to have opted in — the flag is
+ * off for every site that exists and stays off unless someone turns it on —
+ * and the site has to actually have an analytics tag, because advertising
+ * storage here is GA4's `ad_storage` and there is nothing to ask about
+ * without one. A banner with no question behind it is decoration (AGL-1498).
+ */
+export declare function hostAsksAboutAdvertising(host: VisitorConsentHost | null | undefined): boolean;
+/**
+ * Whether the published site runs the consent machinery at all: the tool is
+ * active AND the site uses at least one gated feature.
+ */
+export declare function hostConsentRequired(host: VisitorConsentHost | null | undefined): boolean;
+/**
+ * Regions whose law requires PRIOR consent for non-essential
+ * cookies/identifiers (ePrivacy and its UK retention): the EU 27, the three
+ * EEA/EFTA states, the UK, Gibraltar (UK GDPR extends there), and the EU
+ * outermost regions that carry their own ISO codes. ISO 3166-1 alpha-2,
+ * matching `x-vercel-ip-country`.
+ *
+ * Deliberately NOT a "privacy-law countries" list: plenty of laws (CCPA,
+ * LGPD, PIPEDA) regulate tracking on an opt-out basis, which is exactly what
+ * the opt-out posture plus GPC provides. This set is only the prior-consent
+ * boundary.
+ */
+export declare const PRIOR_CONSENT_COUNTRY_CODES: ReadonlySet<string>;
+/**
+ * The per-visitor posture. Client-evaluated (ISR forbids varying the HTML),
+ * from the country the region endpoint reports.
+ *
+ * Unknown region (`null`) falls to `opt-in` — the ONE place this feature
+ * does not maximize tracking, because the asymmetry is lopsided: a few lost
+ * analytics events on rare headerless visits, versus pre-consent tracking
+ * of an EU visitor, which "track as soon as we legally can" excludes by its
+ * own terms.
+ */
+export declare function resolveConsentPosture(host: VisitorConsentHost | null | undefined, country: string | null | undefined): VisitorConsentPosture;
+/**
+ * Whether this browser sends Global Privacy Control. Read live at decision
+ * time — the signal is the user agent's, not ours to cache.
+ */
+export declare function hasGlobalPrivacyControl(): boolean;
+/**
+ * A visitor's stored consent record. Versioned so a future category
+ * addition can distinguish "declined analytics" from "was never asked about
+ * marketing".
+ */
+export interface StoredVisitorConsent {
+    v: 1;
+    /** Epoch ms of the decision (or of the implied default's recording). */
+    at: number;
+    status: VisitorConsentStatus;
+    /** The category grant, derived from `status` at store time. */
+    analytics: boolean;
+    /**
+     * The advertising grant (AGL-1649). ABSENT on every record written before
+     * the category existed, and absent reads as `false` — "was never asked"
+     * is not "said yes". Reading it the other way would hand Google a basis
+     * for every visitor who ever clicked Allow on an analytics-only banner.
+     *
+     * Carried by an explicit accept, and — since 2026-08-25 — by the opt-out
+     * posture's implied default, on a site whose host turned the question on.
+     * Never by a refusal: declined, opted out and GPC all deny it everywhere.
+     * See {@link advertisingGrantedByStatus} for the order the policy and the
+     * code move in.
+     */
+    advertising?: boolean;
+    /** ISO country at decision time, when known — the `implied,us` shape. */
+    country?: string | null;
+}
+/**
+ * Keyed by hostId, not a bare name: preview deployments and localhost serve
+ * many hosts from one origin, and one site's "yes" must never leak to
+ * another's.
+ */
+export declare const VISITOR_CONSENT_STORAGE_PREFIX = "aglyn:consent:";
+/** The marketing runtime's cross-visit experiment id (`site-runtime.tsx`). */
+export declare const VISITOR_ID_STORAGE_KEY = "aglyn:visitor";
+/** Fired on `window` whenever {@link storeVisitorConsent} records a state. */
+export declare const VISITOR_CONSENT_CHANGED_EVENT = "aglyn:consent:changed";
+/**
+ * Fired on `window` to open the privacy-choices panel — the change-your-mind
+ * path, in BOTH directions. Sites can also link any element to
+ * `#aglyn-consent`; the banner listens for those clicks.
+ */
+export declare const VISITOR_CONSENT_OPEN_EVENT = "aglyn:consent:open";
+export declare function visitorConsentStorageKey(hostId: string): string;
+/**
+ * Cookie-name PREFIXES the analytics grant is answerable for (AGL-1606).
+ *
+ * A prefix sweep rather than a name list, because the names are derived and
+ * configuration-dependent: `_ga` is joined by `_ga_<measurement id without the
+ * `G-`>` per property, by `_gac_<id>` when Google Ads linking is on, and by
+ * `_gid` where the legacy daily id is still issued. Hardcoding the two names a
+ * given site happens to carry today is precisely how a withdrawal leaves an
+ * identifier behind on the next site. `_ga` subsumes `_ga`, `_ga_*` and
+ * `_gac_*`; `_gid` is the only Google analytics cookie that does not start
+ * with it.
+ */
+export declare const ANALYTICS_COOKIE_PREFIXES: readonly string[];
+/**
+ * Cookie-name PREFIXES the ADVERTISING grant is answerable for (AGL-2486).
+ *
+ * These are Google's, and they are separate from the analytics list above for
+ * a reason that is not tidiness: an advertising-only withdrawal must sweep
+ * them while analytics keeps running. Folding them into
+ * {@link ANALYTICS_COOKIE_PREFIXES} would have swept them on ANALYTICS
+ * withdrawal and still not on the case that motivates this — leaving the same
+ * hole, narrower — besides filing a conversion-linker cookie under a category
+ * it does not belong to.
+ *
+ * `_gcl_*` is the conversion linker, written by gtag once `ad_storage` is
+ * granted, and it is the one that started this: it does not begin with `_ga`,
+ * so nothing swept it, on any path.
+ *
+ * ONE PREFIX, deliberately. `_gac_*` (Google Ads linking) was in this list
+ * briefly and is not, because it is written under the ANALYTICS grant and is
+ * already swept by the `_ga` prefix. Listing it here made every
+ * analytics-only GRANT delete it — on a site that never asks the advertising
+ * question `stored.advertising` is always false, so the sweep ran on the way
+ * IN — which broke "cleanup is the withdrawal path only" (AGL-1606). Sweeping
+ * wider is not free when a category nobody was asked about owns the trigger.
+ *
+ * PRECISION MATTERS, because {@link clearCookiesWithPrefixes} is `startsWith`.
+ * `_gcl` cannot reach `_ga`, `_ga_<id>`, `_gac_<id>` or `_gid` — those are
+ * analytics and MUST survive an advertising-only withdrawal.
+ */
+export declare const ADVERTISING_COOKIE_PREFIXES: readonly string[];
+/**
+ * Expire the advertising identifiers, on the same domain ladder as the
+ * analytics sweep (AGL-2486).
+ *
+ * Deleting a cookie that was never set is a no-op; failing to delete one that
+ * was is the defect — so this runs on every non-granting store rather than
+ * only on a transition observed to be a withdrawal, which the record cannot
+ * reliably tell us anyway.
+ */
+export declare function clearAdvertisingCookies(hostname?: string | null): string[];
+/**
+ * The registrable domain of a hostname — the highest name a cookie may be
+ * written at — or `null` when there is none.
+ *
+ * This is the fiddly half of the cleanup. GA's `cookie_domain: 'auto'` walks
+ * UP from the hostname and writes at the highest domain the browser accepts,
+ * which is the registrable domain with a leading dot: a visit to
+ * `www.shop.acme.co.uk` leaves `_ga` on `.acme.co.uk`, not on the exact host.
+ * A deletion aimed at the exact hostname therefore silently no-ops — it writes
+ * a second, host-scoped, already-expired cookie and leaves the real one alone.
+ *
+ * `null` for a single-label host (`localhost`) and for IP literals: those take
+ * host-only cookies, which the undecorated deletion already covers.
+ */
+export declare function registrableCookieDomain(hostname: string | null | undefined): string | null;
+/**
+ * Every `domain=` value a cookie deletion has to try, most specific first and
+ * stopping at the registrable domain.
+ *
+ * The whole ladder rather than the registrable domain alone because
+ * `cookie_domain` is configurable: a host that pins it to `shop.acme.com`
+ * leaves the cookie one rung below where `auto` would. Walking the rungs costs
+ * a handful of no-op writes and removes the guess.
+ *
+ * Empty when there is no registrable domain — the host-only deletion that
+ * {@link clearAnalyticsCookies} always performs is the complete answer there.
+ */
+export declare function analyticsCookieDomains(hostname: string | null | undefined): string[];
+/**
+ * Expire every analytics cookie this browser is carrying, at the host itself
+ * and at every domain up to the registrable one. Returns the names it acted
+ * on, which is what makes the cleanup assertable.
+ *
+ * Best-effort by construction: a cookie written at a path other than `/` is
+ * not reachable this way, and `document.cookie` cannot report which domain a
+ * cookie came from — hence the ladder. Neither limit applies to the cookies GA
+ * actually writes (path `/`, registrable domain).
+ */
+export declare function clearAnalyticsCookies(hostname?: string | null): string[];
+/**
+ * The same sweep for an ARBITRARY prefix set — the generalisation
+ * {@link clearAnalyticsCookies} now delegates to.
+ *
+ * Extracted rather than copied because the hard part is not the prefix match,
+ * it is {@link analyticsCookieDomains}: the ladder from the exact hostname up
+ * to the registrable domain, which exists because a tag written with an `auto`
+ * cookie domain leaves its identifier one or more rungs ABOVE the host. A
+ * second vendor's sweep re-derived by hand would get that wrong the first time
+ * and pass its own test, because a deletion aimed at the wrong domain silently
+ * no-ops — it writes an already-expired host-scoped cookie and reports success.
+ * One implementation, one ladder, one place to fix.
+ *
+ * Meta's `_fbp`/`_fbc` are written exactly like `_ga`: path `/`, registrable
+ * domain, first-party. Nothing here is Google-specific and nothing here is
+ * Meta-specific.
+ */
+export declare function clearCookiesWithPrefixes(prefixes: readonly string[], hostname?: string | null): string[];
+/**
+ * The `window` flag `gtag.js` consults before every hit: with
+ * `window['ga-disable-G-XXXX'] === true` the tag for that property sends
+ * nothing and writes nothing. Google's own documented opt-out mechanism, and
+ * the one that works on a tag which never received a consent-mode default
+ * (AGL-1608) — a case that still exists after AGL-1622, because a tag arriving
+ * through GTM or a host's own CMP is not one this module declared for.
+ */
+export declare const GA_DISABLE_FLAG_PREFIX = "ga-disable-";
+/** A single consent-mode signal value. */
+export type AnalyticsConsentSignal = 'granted' | 'denied';
+/**
+ * The consent-mode signal set this tool is answerable for.
+ *
+ * `ad_storage` and friends are typed as the literal `'denied'`, not as
+ * {@link AnalyticsConsentSignal}: the tool asks a visitor about analytics and
+ * nothing else, so there is no advertising basis on file to grant, in either
+ * direction. Widening them is a change the type has to be edited to allow.
+ */
+export interface AnalyticsConsentSignals {
+    analytics_storage: AnalyticsConsentSignal;
+    ad_storage: 'denied';
+    ad_user_data: 'denied';
+    ad_personalization: 'denied';
+}
+/**
+ * The consent-mode payload for a given analytics grant — ONE source, so the
+ * `default` declared before the tag loads (AGL-1622) and the `update` sent on a
+ * mid-pageview withdrawal (AGL-1608) can never drift apart. Two hand-written
+ * literals that disagree is how a tag ends up believing a state the visitor
+ * never chose.
+ */
+export declare function analyticsConsentSignals(granted: boolean): AnalyticsConsentSignals;
+/** The four signals when advertising is in play (AGL-1649). */
+export interface VisitorConsentSignals {
+    analytics_storage: AnalyticsConsentSignal;
+    ad_storage: AnalyticsConsentSignal;
+    ad_user_data: AnalyticsConsentSignal;
+    ad_personalization: AnalyticsConsentSignal;
+}
+/**
+ * The consent-mode payload for a pair of category grants (AGL-1649).
+ *
+ * A SEPARATE function from {@link analyticsConsentSignals} rather than a
+ * widening of it, deliberately. AGL-1649 says not to widen those three
+ * literals, and the reason survives this change: a caller that only knows
+ * about analytics should be unable to express a grant it has no answer for.
+ * Reaching an advertising grant now requires calling something else and
+ * passing it, which is a thing a reviewer can see in a diff.
+ *
+ * Advertising is clamped to analytics. `ad_storage: 'granted'` with
+ * `analytics_storage: 'denied'` is not a state this tool can reach honestly —
+ * every refusal path (declined, opted out, GPC) withdraws both together — so
+ * the clamp makes the impossible state unrepresentable rather than merely
+ * unreached.
+ */
+export declare function consentModeSignals(grants: {
+    analytics: boolean;
+    advertising: boolean;
+}): VisitorConsentSignals;
+/**
+ * Whether advertising storage may run for this visitor on this site.
+ *
+ * THREE independent conditions, and all of them are load-bearing:
+ *
+ * 1. The host asks about advertising at all. A record that says yes is
+ *    ignored on a site that never turned the category on — which covers a
+ *    host switching it back off, and covers a stale record generally.
+ * 2. The record's status can carry a grant — an explicit accept, and nothing
+ *    else (see {@link advertisingGrantedByStatus}). An `implied` default
+ *    cannot, and every refusal status refuses.
+ * 3. The record actually says yes to this category.
+ *
+ * Absent, unreadable or legacy records all answer `false`, which is the same
+ * answer they gave before the category existed.
+ */
+export declare function advertisingGrantedByRecord(host: VisitorConsentHost | null | undefined, stored: StoredVisitorConsent | null | undefined): boolean;
+/**
+ * The consent-mode `default` declaration that goes in front of the tag
+ * (AGL-1622), for injection into the same inline block that creates
+ * `dataLayer` and calls `gtag('config', …)`.
+ *
+ * ## What this is, and — load-bearing — what it is NOT
+ *
+ * It is NOT a licence to load the tag earlier. It is emitted INSIDE the block
+ * that only renders when the AGL-1498 gate has already said yes, so it is
+ * reached only on a pageview where analytics is granted. On every gated
+ * pageview — an EU/UK/EEA visitor with no explicit accept, an unknown region, a
+ * declined or opted-out visitor, a GPC browser — nothing here renders, no
+ * request goes to `googletagmanager.com`, and this constant is never evaluated
+ * into the page. "The script never LOADS, rather than load-then-suppress" is a
+ * stated AGL-1498 property and it is intact everywhere the gate applies;
+ * `consent-mode-default.spec.tsx` fails if that ever stops being true.
+ *
+ * the decision, 2026-08-14: load-then-restrict is approved for the UNITED
+ * STATES, where the implied-consent posture already permits the load and the
+ * restriction signals act on a tag that is legitimately resident. EU and UK
+ * keep the prior-consent gate exactly as it is, because loading an analytics
+ * tag before consent is the specific thing prior-consent law prohibits. So the
+ * consent-mode mechanism is strictly ADDITIVE to the gate, never a replacement
+ * for it.
+ *
+ * What declaring it actually buys, given the tag is granted by the time it is
+ * read:
+ *
+ * - The advertising signals are denied FROM THE FIRST HIT. Without a default,
+ *   a freshly loaded tag runs with `ad_storage` unrestricted and only becomes
+ *   denied if the visitor happens to withdraw and change their mind again
+ *   (AGL-1608's `update`). The load-time state now matches the tool's actual
+ *   scope instead of being wider than it.
+ * - A later `update` is a transition from a declared state rather than a tag's
+ *   first-ever consent signal, which is the shape GA4's consent-mode reporting
+ *   and any third-party CMP alongside ours both expect.
+ *
+ * The value is a literal, built from {@link analyticsConsentSignals} — no
+ * interpolated input reaches it, which matters because it lands inside an
+ * inline script (the AGL-138 concern).
+ */
+export declare const GA_CONSENT_DEFAULT_SNIPPET: string;
+/**
+ * The same declaration for a visitor who granted ADVERTISING too (AGL-1649).
+ *
+ * A second CONSTANT rather than a parameterised builder, for the reason the
+ * first one is a constant: it lands inside an inline script (the AGL-138
+ * concern), and a constant cannot interpolate anything. Both values are
+ * literals fixed at module load; the only thing the caller chooses is which
+ * of the two to emit.
+ *
+ * Reached only where {@link advertisingGrantedByRecord} says yes — host
+ * opted in, explicit accept, explicit yes to this category — which is
+ * evaluated client-side after hydration, like every other part of this gate.
+ * The ISR property is unaffected: the cached HTML contains neither snippet,
+ * because the whole block is inside the client-side `analyticsAllowed`
+ * condition.
+ *
+ * Declaring the grant as the DEFAULT rather than sending a later `update` is
+ * what keeps the tag's first hit correct. An update would arrive after
+ * `config`, so the session's first pageview — usually the entire session for
+ * a marketing visit — would carry the denied state the visitor did not
+ * choose.
+ */
+export declare const GA_CONSENT_DEFAULT_WITH_ADS_SNIPPET: string;
+/**
+ * Consent-mode URL passthrough for the platform's own tag (AGL-2548).
+ *
+ * The advertising signals in {@link GA_CONSENT_DEFAULT_SNIPPET} are denied, so
+ * on `aglyn.com` gtag writes no `_gcl_aw` cookie and the `gclid` an ad click
+ * arrives with lives only in that first URL. The conversions it should be
+ * credited for fire one hop later, on the console, where the posture grants
+ * advertising storage outside the prior-consent regions — and without this
+ * declaration the click id never makes that hop. The console reports a
+ * conversion with no click behind it, and Google Ads counts nothing.
+ *
+ * `url_passthrough` is Google's mechanism for exactly this state: while
+ * `ad_storage` is denied, gtag appends the click identifiers to links into the
+ * cross-domain-linked hosts as URL parameters instead of setting a cookie. The
+ * receiving tag reads them under its own consent state. Nothing is stored on
+ * the denying surface, so the marketing site's opt-in advertising posture is
+ * unchanged; the click id simply survives the link it was always meant to
+ * survive.
+ *
+ * `ads_data_redaction` is the companion Google documents alongside it: with
+ * `ad_storage` denied, the ad click identifiers are stripped from the hits this
+ * tag sends and its network requests go to a cookieless endpoint. Declared
+ * together so a denied visitor is measured with less, not merely differently.
+ *
+ * Both are `set` calls, so they must precede `gtag('config', …)` in the same
+ * inline block — a `set` applies to hits processed after it, and the session's
+ * first pageview is the one carrying the click.
+ *
+ * PLATFORM ID ONLY. A customer's tag is configured with their id and their
+ * consent posture; how their ad click ids travel is theirs to decide, and a
+ * passthrough declared on their behalf would rewrite links on their site.
+ */
+export declare const GA_CLICK_ID_PASSTHROUGH_SNIPPET: string;
+/**
+ * The measurement ids whose tag is actually RESIDENT in this page.
+ *
+ * Discovered from the page rather than taken from the host document on
+ * purpose: what has to be silenced is whatever gtag.js is currently loaded and
+ * configured for, which is not always what the host record configures — a tag
+ * can arrive through GTM, and a stale `<script>` from earlier in the pageview
+ * is exactly the thing this function exists to find.
+ *
+ * Ids are format-checked before they are used, because each one becomes a
+ * `window` property name.
+ */
+export declare function residentGaMeasurementIds(): string[];
+/**
+ * Make every resident GA tag agree with the consent state, and return the ids
+ * it acted on.
+ *
+ * ## Why deleting the cookies is not enough (AGL-1608)
+ *
+ * The AGL-1498 gate stops the script from LOADING, which is the right
+ * enforcement for a fresh pageview and the wrong tool for a visitor who
+ * withdraws mid-pageview: `gtag.js` has already executed, and React unmounting
+ * the `<script>` element does not unload it. `window.gtag` stays live, GA4
+ * enhanced measurement fires on its own (scroll depth, outbound click, file
+ * download), and the tag re-writes `_ga_<id>` AFTER
+ * {@link clearAnalyticsCookies} has deleted it. Reproduced on aglyn.com: an
+ * opt-out, a hand-run sweep to zero cookies, then one scroll to the footer
+ * brought `_ga_YW5PG16YTM` back.
+ *
+ * Two signals, because they fail differently and neither is guaranteed:
+ * the `ga-disable-<id>` window flag silences a tag that never received a
+ * consent-mode default, and the `consent`/`update` call reaches a tag that
+ * arrived through GTM with its own id this function never saw.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It never touches the gate. Both signals act only on a tag that is already
+ * resident — which, by construction, only exists after a grant. AGL-1622 later
+ * added a consent-mode DEFAULT ({@link GA_CONSENT_DEFAULT_SNIPPET}), but inside
+ * the gated block and therefore only on a pageview the gate already allowed:
+ * load-then-restrict is additive to "the script never LOADS", not a
+ * replacement for it, and the prior-consent regions are unaffected.
+ *
+ * Symmetric on purpose: a visitor who opts out and changes their mind in the
+ * same pageview would otherwise stay silently unmeasured until they navigated,
+ * because the re-rendered `<Script>` cannot re-execute an already-loaded tag.
+ * The re-grant restores whatever the CALLER passes — analytics alone on a site
+ * that never asks the advertising question (`advertising` defaults to false),
+ * and both categories where the visitor's record grants both (AGL-1649). The
+ * clamp in {@link consentModeSignals} still makes ads-without-analytics
+ * unrepresentable, so a withdrawal can never restore advertising alone.
+ */
+export declare function setResidentAnalyticsTags(granted: boolean, advertising?: boolean): string[];
+/**
+ * The stored record, or null when there is none (never resolved, storage
+ * unavailable, or an unrecognized shape — treated alike: not yet decided).
+ */
+export declare function readStoredVisitorConsent(hostId: string | null | undefined): StoredVisitorConsent | null;
+/**
+ * Record a consent state and make the page agree with it immediately.
+ *
+ * Storing the record is itself strictly-necessary storage (it is how a "no"
+ * is remembered), so it is exempt from the consent it records. Any
+ * non-granting state also REMOVES the identifiers the grant allowed —
+ * the persistent `aglyn:visitor` id AND the GA cookies
+ * ({@link clearAnalyticsCookies}): opting out cleans up, it does not merely
+ * stop adding (AGL-1606) — and SILENCES the tag that is already running
+ * ({@link setResidentAnalyticsTags}), without which the cleanup un-does itself
+ * within the same pageview (AGL-1608). Listeners hear about it via
+ * {@link VISITOR_CONSENT_CHANGED_EVENT} so the GA gate and the runtime react
+ * without a reload.
+ *
+ * The two cleanups are deliberately in SEPARATE try blocks: private mode
+ * throws on `localStorage` while cookies still work, and a withdrawal must
+ * not lose the cookie sweep to that.
+ */
+export declare function storeVisitorConsent(hostId: string, state: {
+    status: VisitorConsentStatus;
+    country?: string | null;
+    /**
+     * The visitor's answer to the advertising question (AGL-1649). Omitted
+     * by every caller that does not ask one, and omitted means NO.
+     */
+    advertising?: boolean;
+}): StoredVisitorConsent;
+/**
+ * The GA gate's whole verdict: may the analytics category run for this
+ * visitor, on this site, right now?
+ *
+ * - Consent machinery not required (no gated features, or host opted out of
+ *   the tool) → yes.
+ * - Required and the recorded state grants analytics (`accepted` or
+ *   `implied`) → yes.
+ * - Required and anything else — declined, opted out, GPC, or NOT YET
+ *   RESOLVED → no. Undecided is not a maybe: the script stays out until a
+ *   state that grants it exists. The gate never asks WHY consent is absent,
+ *   which is what keeps it posture-independent.
+ */
+export declare function isAnalyticsAllowed(host: VisitorConsentHost | null | undefined, stored: StoredVisitorConsent | null): boolean;
+/**
+ * Where the marketing runtime may keep its experiment visitor id.
+ *
+ * `local` — the id persists across visits. `session` — the id lives in
+ * sessionStorage: variants stay stable within the visit and the identifier
+ * dies with the tab. The downgrade applies while the consent machinery is
+ * active for this site and analytics is not granted; the id itself never
+ * leaves the browser either way (the experiment beacons are aggregate — no
+ * visitor id on the wire).
+ */
+export declare function resolveVisitorIdPersistence(host: VisitorConsentHost | null | undefined, stored: StoredVisitorConsent | null): 'local' | 'session';