From 09233de34052f9c70882b92fbaf1a0fa8fd1ed17 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 19:29:29 -0400
Subject: [PATCH 01/17] init react-airgap

---
 packages/react-airgap/package.json            |  57 ++
 packages/react-airgap/src/index.ts            |  11 +
 .../src/next/tracking-script.test.ts          |  79 +++
 .../react-airgap/src/next/tracking-script.tsx | 292 +++++++++
 packages/react-airgap/tsconfig.json           |  14 +
 packages/react-airgap/tsdown.config.ts        |   8 +
 pnpm-lock.yaml                                | 564 ++++++++++++++++++
 pnpm-workspace.yaml                           |   7 +-
 tsconfig.json                                 |   1 +
 9 files changed, 1032 insertions(+), 1 deletion(-)
 create mode 100644 packages/react-airgap/package.json
 create mode 100644 packages/react-airgap/src/index.ts
 create mode 100644 packages/react-airgap/src/next/tracking-script.test.ts
 create mode 100644 packages/react-airgap/src/next/tracking-script.tsx
 create mode 100644 packages/react-airgap/tsconfig.json
 create mode 100644 packages/react-airgap/tsdown.config.ts

diff --git a/packages/react-airgap/package.json b/packages/react-airgap/package.json
new file mode 100644
index 00000000..a29fe23a
--- /dev/null
+++ b/packages/react-airgap/package.json
@@ -0,0 +1,57 @@
+{
+  "name": "@transcend-io/react-airgap",
+  "version": "0.0.0",
+  "description": "React components for the Transcend Airgap library.",
+  "homepage": "https://github.com/transcend-io/tools/tree/main/packages/react-airgap",
+  "license": "Apache-2.0",
+  "author": "Transcend Inc.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/transcend-io/tools.git",
+    "directory": "packages/react-airgap"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "@transcend-io/source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check:exports": "attw --pack . --ignore-rules cjs-resolves-to-esm",
+    "check:publint": "publint --level warning --strict --pack pnpm"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "next": "catalog:",
+    "publint": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "peerDependencies": {
+    "next": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}
diff --git a/packages/react-airgap/src/index.ts b/packages/react-airgap/src/index.ts
new file mode 100644
index 00000000..5494e500
--- /dev/null
+++ b/packages/react-airgap/src/index.ts
@@ -0,0 +1,11 @@
+'use client';
+
+export {
+  allOf,
+  anyOf,
+  default as TrackingScript,
+  onConsent,
+  onEvent,
+  onPromise,
+} from './next/tracking-script.js';
+export type { LoadTrigger, OnEventOptions, TrackingScriptProps } from './next/tracking-script.js';
diff --git a/packages/react-airgap/src/next/tracking-script.test.ts b/packages/react-airgap/src/next/tracking-script.test.ts
new file mode 100644
index 00000000..63ffed8c
--- /dev/null
+++ b/packages/react-airgap/src/next/tracking-script.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, test, vi } from 'vitest';
+
+import { allOf, anyOf, onEvent, onPromise, type LoadTrigger } from './tracking-script.js';
+
+describe('tracking script triggers', () => {
+  test('onEvent loads once when the event fires', () => {
+    const target = new EventTarget();
+    const load = vi.fn();
+    const cleanup = onEvent('ready', { target })(load);
+
+    target.dispatchEvent(new Event('ready'));
+    target.dispatchEvent(new Event('ready'));
+
+    expect(load).toHaveBeenCalledTimes(1);
+    cleanup?.();
+  });
+
+  test('onEvent loads immediately when the latch is already open', () => {
+    const target = new EventTarget();
+    const load = vi.fn();
+
+    onEvent('ready', { target, latch: () => true })(load);
+
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  test('onPromise loads when the promise resolves', async () => {
+    const load = vi.fn();
+
+    onPromise(Promise.resolve())(load);
+    await Promise.resolve();
+
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  test('anyOf loads once when the first trigger fires and cleans up every trigger', () => {
+    const triggerCallbacks: Array<() => void> = [];
+    const firstCleanup = vi.fn();
+    const secondCleanup = vi.fn();
+    const first: LoadTrigger = (load) => {
+      triggerCallbacks[0] = load;
+      return firstCleanup;
+    };
+    const second: LoadTrigger = (load) => {
+      triggerCallbacks[1] = load;
+      return secondCleanup;
+    };
+    const load = vi.fn();
+
+    const cleanup = anyOf(first, second)(load);
+    triggerCallbacks[0]?.();
+    triggerCallbacks[1]?.();
+    cleanup?.();
+
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(firstCleanup).toHaveBeenCalledTimes(1);
+    expect(secondCleanup).toHaveBeenCalledTimes(1);
+  });
+
+  test('allOf waits for every trigger and ignores duplicate trigger calls', () => {
+    const triggerCallbacks: Array<() => void> = [];
+    const first: LoadTrigger = (load) => {
+      triggerCallbacks[0] = load;
+    };
+    const second: LoadTrigger = (load) => {
+      triggerCallbacks[1] = load;
+    };
+    const load = vi.fn();
+
+    allOf(first, second)(load);
+    triggerCallbacks[0]?.();
+    triggerCallbacks[0]?.();
+    expect(load).not.toHaveBeenCalled();
+
+    triggerCallbacks[1]?.();
+
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/react-airgap/src/next/tracking-script.tsx b/packages/react-airgap/src/next/tracking-script.tsx
new file mode 100644
index 00000000..da8226ab
--- /dev/null
+++ b/packages/react-airgap/src/next/tracking-script.tsx
@@ -0,0 +1,292 @@
+'use client';
+
+/**
+ * TrackingScript — a drop-in wrapper around `next/script` that defers script
+ * injection until one or more triggers fire (custom events, promises, or
+ * Transcend airgap consent).
+ *
+ * Supports both forms of `next/script`:
+ *   <TrackingScript src="https://cdn.example.com/tag.js" loadAfter={...} />
+ *   <TrackingScript id="gtm-init" loadAfter={...}>{`...inline JS...`}</TrackingScript>
+ *
+ * SSR: like `<Script strategy="afterInteractive">`, this renders nothing
+ * server-side. Initial client render also returns null, so there is no
+ * hydration mismatch. `strategy="beforeInteractive"` is unsupported (the
+ * component will warn in development) because gating happens after hydration.
+ */
+
+import Script, { type ScriptProps } from 'next/script';
+import { type ReactElement, type ReactNode, useEffect, useState } from 'react';
+
+/* -------------------------------------------------------------------------- */
+/*                                  Triggers                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A subscription function: receives a `load` callback, calls it when the gate
+ * opens, optionally returns a cleanup. This shape handles already-fired
+ * events, promises, observables, and airgap's ready queue with one API.
+ */
+export type LoadTrigger = (load: () => void) => void | (() => void);
+
+export interface OnEventOptions {
+  /** Event target to subscribe to. Defaults to `window` in the browser. */
+  target?: EventTarget;
+  /** Returns true when the trigger condition already happened before mount. */
+  latch?: () => boolean;
+}
+
+interface AirgapConsentApi {
+  /** Resolve consent status for the required tracking purposes. */
+  isConsented(trackingPurposes: Set<string>): boolean;
+  /** Subscribe to airgap changes that may affect consent resolution. */
+  watch?: (callback: () => void) => void | (() => void);
+}
+
+type AirgapReadyCallback = (airgap: AirgapConsentApi) => void;
+
+interface AirgapReadyApi {
+  /** Queue of callbacks to dispatch once airgap is ready. */
+  readyQueue?: AirgapReadyCallback[];
+  /** Subscribe to the airgap ready event. */
+  ready(callback: AirgapReadyCallback): void;
+}
+
+interface WindowWithAirgap extends Window {
+  /** Transcend airgap API or preload stub. */
+  airgap?: Partial<AirgapReadyApi>;
+}
+
+/**
+ * Fire on a DOM event. Pass `latch` to short-circuit if the condition is
+ * already true (handy for events that may have already fired before mount).
+ */
+export const onEvent =
+  (name: string, opts?: OnEventOptions): LoadTrigger =>
+  (load) => {
+    const target = opts?.target ?? (typeof window !== 'undefined' ? window : null);
+    if (!target) return;
+    if (opts?.latch?.()) {
+      load();
+      return;
+    }
+    const handler = () => load();
+    target.addEventListener(name, handler, { once: true });
+    return () => target.removeEventListener(name, handler);
+  };
+
+/** Fire when a Promise resolves. */
+export const onPromise =
+  (promise: Promise<unknown>): LoadTrigger =>
+  (load) => {
+    let cancelled = false;
+    void promise.then(
+      () => {
+        if (!cancelled) load();
+      },
+      () => undefined,
+    );
+    return () => {
+      cancelled = true;
+    };
+  };
+
+/**
+ * Fire when Transcend airgap.js is ready AND (optionally) the listed purposes
+ * are consented. Subscribes to `airgap.watch` so the gate re-evaluates when
+ * the user changes consent — e.g. opt-in later causes the script to load.
+ */
+export const onConsent =
+  (purposes?: string[]): LoadTrigger =>
+  (load) => {
+    if (typeof window === 'undefined') return;
+    // `airgap.ready` handles "already loaded" via its readyQueue, so this is
+    // safe whether airgap has arrived yet or not.
+    const w = window as WindowWithAirgap;
+    if (!w.airgap?.ready) {
+      // Stub the ready queue so we don't drop the callback if airgap hasn't
+      // attached yet. The real airgap will drain `readyQueue` on load.
+      const queue: AirgapReadyCallback[] = [];
+      w.airgap = {
+        ...w.airgap,
+        readyQueue: queue,
+        ready(callback) {
+          queue.push(callback);
+        },
+      };
+    }
+    let fired = false;
+    let unwatch: undefined | (() => void);
+    const airgapReady = w.airgap as AirgapReadyApi;
+    airgapReady.ready((airgap) => {
+      const required = purposes ? new Set(purposes) : null;
+      const check = () => {
+        if (fired) return;
+        if (!required || airgap.isConsented(required)) {
+          fired = true;
+          load();
+          unwatch?.();
+        }
+      };
+      check();
+      if (!fired) {
+        const cleanup = airgap.watch?.(check);
+        if (typeof cleanup === 'function') unwatch = cleanup;
+      }
+    });
+    return () => {
+      unwatch?.();
+    };
+  };
+
+/** Fire when ANY of the given triggers fires (logical OR). */
+export const anyOf =
+  (...triggers: LoadTrigger[]): LoadTrigger =>
+  (load) => {
+    let fired = false;
+    const fireOnce = () => {
+      if (!fired) {
+        fired = true;
+        load();
+      }
+    };
+    const cleanups = triggers.map((t) => t(fireOnce));
+    return () => cleanups.forEach((c) => typeof c === 'function' && c());
+  };
+
+/** Fire only when ALL of the given triggers have fired (logical AND). */
+export const allOf =
+  (...triggers: LoadTrigger[]): LoadTrigger =>
+  (load) => {
+    if (triggers.length === 0) {
+      load();
+      return;
+    }
+    const fired = new Set<number>();
+    const cleanups = triggers.map((trigger, index) =>
+      trigger(() => {
+        if (fired.has(index)) return;
+        fired.add(index);
+        if (fired.size === triggers.length) load();
+      }),
+    );
+    return () => cleanups.forEach((c) => typeof c === 'function' && c());
+  };
+
+/* -------------------------------------------------------------------------- */
+/*                                 Component                                  */
+/* -------------------------------------------------------------------------- */
+
+export interface TrackingScriptProps extends ScriptProps {
+  /**
+   * Wait for these triggers before injecting the underlying `<Script>`.
+   * - Single trigger: fire when it opens.
+   * - Array: fires when ALL open (logical AND). Use `anyOf(...)` for OR.
+   */
+  loadAfter: LoadTrigger | LoadTrigger[];
+  /** Called once if the gate later closes (e.g. user revokes consent). */
+  onUnload?: () => void;
+  /** Inline script body (for `<TrackingScript id="...">{`...`}</TrackingScript>`). */
+  children?: ReactNode;
+}
+
+export default function TrackingScript({
+  loadAfter,
+  onUnload,
+  children,
+  ...scriptProps
+}: TrackingScriptProps): ReactElement | null {
+  const [open, setOpen] = useState(false);
+
+  // Dev-only guard: `beforeInteractive` requires the script to be SSR'd, which
+  // this wrapper deliberately prevents. Warn loudly rather than silently
+  // degrade.
+  if (process.env.NODE_ENV !== 'production' && scriptProps.strategy === 'beforeInteractive') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[TrackingScript] strategy="beforeInteractive" is not supported — the script is gated client-side and cannot appear in SSR HTML. Use "afterInteractive" or "lazyOnload".',
+    );
+  }
+
+  useEffect(() => {
+    const triggers = Array.isArray(loadAfter) ? loadAfter : [loadAfter];
+    let cancelled = false;
+    const fired = new Set<number>();
+    if (triggers.length === 0) {
+      setOpen(true);
+      return;
+    }
+    const cleanups = triggers.map((trigger, index) =>
+      trigger(() => {
+        if (cancelled || fired.has(index)) return;
+        fired.add(index);
+        if (fired.size === triggers.length) setOpen(true);
+      }),
+    );
+    return () => {
+      cancelled = true;
+      cleanups.forEach((c) => typeof c === 'function' && c());
+    };
+    // `loadAfter` should be referentially stable. Memoize triggers at the
+    // call site if they depend on changing values.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Fire onUnload if the component unmounts after the script was injected.
+  useEffect(() => {
+    return () => {
+      if (open) onUnload?.();
+    };
+  }, [open, onUnload]);
+
+  if (!open) return null;
+
+  // Support both external (`src`) and inline (`children`) forms.
+  return <Script {...scriptProps}>{children}</Script>;
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Examples                                  */
+/* -------------------------------------------------------------------------- */
+
+/*
+import TrackingScript, { onEvent, onConsent, onPromise, anyOf, allOf } from './tracking-script';
+
+// 1. External script gated on a custom event
+<TrackingScript
+  src="https://example.com/heavy.js"
+  strategy="lazyOnload"
+  loadAfter={onEvent('app:bootstrapped')}
+/>
+
+// 2. External script gated on airgap + Analytics consent
+<TrackingScript
+  src="https://cdn.intake-lr.com/logger-1.min.js"
+  strategy="afterInteractive"
+  loadAfter={onConsent(['Analytics'])}
+/>
+
+// 3. Inline GTM bootstrap gated on consent (note: requires `id`)
+<TrackingScript
+  id="gtm-init"
+  strategy="afterInteractive"
+  loadAfter={onConsent(['Analytics', 'Advertising'])}
+>{`
+  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});
+  var f=d.getElementsByTagName(s)[0],j=d.createElement(s);j.async=true;
+  j.src='https://www.googletagmanager.com/gtm.js?id='+i;f.parentNode.insertBefore(j,f);
+  })(window,document,'script','dataLayer','GTM-XXXX');
+`}</TrackingScript>
+
+// 4. Compound: consent AND (custom event OR 5s timeout)
+<TrackingScript
+  src="https://s.go-mpulse.net/boomerang/3C8QM-..."
+  loadAfter={allOf(
+    onConsent(['Analytics']),
+    anyOf(
+      onEvent('route:settled'),
+      onPromise(new Promise((r) => setTimeout(r, 5000))),
+    ),
+  )}
+/>
+*/
diff --git a/packages/react-airgap/tsconfig.json b/packages/react-airgap/tsconfig.json
new file mode 100644
index 00000000..4d330f66
--- /dev/null
+++ b/packages/react-airgap/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
diff --git a/packages/react-airgap/tsdown.config.ts b/packages/react-airgap/tsdown.config.ts
new file mode 100644
index 00000000..7ab4ad4c
--- /dev/null
+++ b/packages/react-airgap/tsdown.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsdown';
+
+import sharedConfig from '../../tsdown.config.base.ts';
+
+export default defineConfig({
+  ...sharedConfig,
+  entry: ['src/index.ts'],
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ad1dee36..2e8fcfec 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21,12 +21,21 @@ catalogs:
     '@types/node':
       specifier: ^22.19.15
       version: 22.19.15
+    '@types/react':
+      specifier: ^19.2.15
+      version: 19.2.15
+    '@types/react-dom':
+      specifier: ^19.2.3
+      version: 19.2.3
     '@types/semver':
       specifier: ^7.7.1
       version: 7.7.1
     husky:
       specifier: ^9.1.7
       version: 9.1.7
+    next:
+      specifier: ^16.2.6
+      version: 16.2.6
     oxfmt:
       specifier: ^0.38.0
       version: 0.38.0
@@ -36,6 +45,12 @@ catalogs:
     publint:
       specifier: ^0.3.18
       version: 0.3.18
+    react:
+      specifier: ^19.2.6
+      version: 19.2.6
+    react-dom:
+      specifier: ^19.2.6
+      version: 19.2.6
     semver:
       specifier: ^7.7.4
       version: 7.7.4
@@ -733,6 +748,42 @@ importers:
         specifier: 'catalog:'
         version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
 
+  packages/react-airgap:
+    devDependencies:
+      '@arethetypeswrong/cli':
+        specifier: 'catalog:'
+        version: 0.18.2
+      '@types/node':
+        specifier: 'catalog:'
+        version: 22.19.15
+      '@types/react':
+        specifier: 'catalog:'
+        version: 19.2.15
+      '@types/react-dom':
+        specifier: 'catalog:'
+        version: 19.2.3(@types/react@19.2.15)
+      next:
+        specifier: 'catalog:'
+        version: 16.2.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      publint:
+        specifier: 'catalog:'
+        version: 0.3.18
+      react:
+        specifier: 'catalog:'
+        version: 19.2.6
+      react-dom:
+        specifier: 'catalog:'
+        version: 19.2.6(react@19.2.6)
+      tsdown:
+        specifier: 'catalog:'
+        version: 0.21.2(@arethetypeswrong/core@0.18.2)(publint@0.3.18)(typescript@6.0.3)
+      typescript:
+        specifier: 'catalog:'
+        version: 6.0.3
+      vitest:
+        specifier: 'catalog:'
+        version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
+
   packages/sdk:
     dependencies:
       '@transcend-io/airgap.js-types':
@@ -1182,6 +1233,159 @@ packages:
     peerDependencies:
       hono: ^4
 
+  '@img/colour@1.1.0':
+    resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
+    engines: {node: '>=18'}
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    resolution: {integrity: sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-darwin-x64@0.34.5':
+    resolution: {integrity: sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    resolution: {integrity: sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    resolution: {integrity: sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linux-arm64@0.34.5':
+    resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-arm@0.34.5':
+    resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-s390x@0.34.5':
+    resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-x64@0.34.5':
+    resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-wasm32@0.34.5':
+    resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [wasm32]
+
+  '@img/sharp-win32-arm64@0.34.5':
+    resolution: {integrity: sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@img/sharp-win32-ia32@0.34.5':
+    resolution: {integrity: sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@img/sharp-win32-x64@0.34.5':
+    resolution: {integrity: sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [win32]
+
   '@inquirer/external-editor@1.0.3':
     resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==}
     engines: {node: '>=18'}
@@ -1229,6 +1433,61 @@ packages:
   '@napi-rs/wasm-runtime@1.1.1':
     resolution: {integrity: sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A==}
 
+  '@next/env@16.2.6':
+    resolution: {integrity: sha512-gd8HoHN4ufj73WmR3JmVolrpJR47ILK6LouP5xElPglaVxir6e1a7VzvTvDWkOoPXT9rkkTzyCxBu4yeZfZwcw==}
+
+  '@next/swc-darwin-arm64@16.2.6':
+    resolution: {integrity: sha512-ZJGkkcNfYgrrMkqOdZ7zoLa1TOy0qpcMfk/z4Mh/FKUz40gVO+HNQWqmLxf67Z5WB64DRp0dhEbyHfel+6sJUg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@next/swc-darwin-x64@16.2.6':
+    resolution: {integrity: sha512-v/YLBHIY132Ced3puBJ7YJKw1lqsCrgcNo2aRJlCEyQrrCeRJlvGlnmxhPxNQI3KE3N1DN5r9TPNPvka3nq5RQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@next/swc-linux-arm64-gnu@16.2.6':
+    resolution: {integrity: sha512-RPOvqlYBbcQjkz9VQQDZ2T2bARIjXZV1KFlt+V2Mr6SW/e4I9fcKsaA0hdyf2FHoTlsV2xnBd5Y912rP/1Ce6w==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@next/swc-linux-arm64-musl@16.2.6':
+    resolution: {integrity: sha512-URUTu1+dMkxJsPFgm+OeEvq9wf5sujw0EvgYy80TDGHTSLTnIHeqb0Eu8A3sC95IRgjejQL+kC4mw+4yPxiAXA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@next/swc-linux-x64-gnu@16.2.6':
+    resolution: {integrity: sha512-DOj182mPV8G3UkrayLoREM5YEYI+Dk5wv7Ox9xl1fFibAELEsFD0lDPfHIeILlutMMfdyhlzYPELG3peuKaurw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@next/swc-linux-x64-musl@16.2.6':
+    resolution: {integrity: sha512-HKQ5SP/V/ub73UvF7n/zeJlxk2kLmtL7Wzrg4WfmkjmNos5onJ2tKu7yZOPdL18A6Svfn3max29ym+ry7NkK4g==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@next/swc-win32-arm64-msvc@16.2.6':
+    resolution: {integrity: sha512-LZXpTlPyS5v7HhSmnvsLGP3iIYgYOBnc8r8ArlT55sGHV89bR2HlDdBjWQ+PY6SJMmk8TuVGFuxalnP3k/0Dwg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@next/swc-win32-x64-msvc@16.2.6':
+    resolution: {integrity: sha512-F0+4i0h9J6C4eE3EAPWsoCk7UW/dbzOjyzxY0qnDUOYFu6FFmdZ6l97/XdV3/Nz3VYyO7UWjyEJUXkGqcoXfMA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
   '@nodelib/fs.scandir@2.1.5':
     resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
     engines: {node: '>= 8'}
@@ -1752,6 +2011,9 @@ packages:
   '@stricli/core@1.2.6':
     resolution: {integrity: sha512-j5fa1wyOLrP9WJqqLFEJeQviqb3cK46K+FXTuISEkG/H5C820YfKDoVQ3CDVdM5WLhEx1ARdpiW6+hU4tYHjCQ==}
 
+  '@swc/helpers@0.5.15':
+    resolution: {integrity: sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==}
+
   '@textlint/ast-node-types@12.6.1':
     resolution: {integrity: sha512-uzlJ+ZsCAyJm+lBi7j0UeBbj+Oy6w/VWoGJ3iHRHE5eZ8Z4iK66mq+PG/spupmbllLtz77OJbY89BYqgFyjXmA==}
 
@@ -1900,6 +2162,14 @@ packages:
   '@types/range-parser@1.2.7':
     resolution: {integrity: sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==}
 
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react@19.2.15':
+    resolution: {integrity: sha512-eRwcGNHve+E8qtEQSSRl6urh+rFop4v8gm6O8rGv25CodbvFdLjA1vVQ1KkiFE0w0UPOnb8tDiFKL5lp0rtY5Q==}
+
   '@types/semver@7.7.1':
     resolution: {integrity: sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==}
 
@@ -2043,6 +2313,11 @@ packages:
   base64-js@1.5.1:
     resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
 
+  baseline-browser-mapping@2.10.32:
+    resolution: {integrity: sha512-wbPvpyjJPC0zdfdKXxqEL3Ea+bOMD/87X4lftiJkkaBiuG6ALQy1SLmEd7BSmVCuwCQsBrCamgBoLyfFDD1EPg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
   better-path-resolve@1.0.0:
     resolution: {integrity: sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==}
     engines: {node: '>=4'}
@@ -2109,6 +2384,9 @@ packages:
   camel-case@4.1.2:
     resolution: {integrity: sha512-gxGWBrTT1JuMx6R+o5PTXMmUnhnVzLQ9SNutD4YqKtI6ap897t3tKECYla6gCWEkplXnlNybEkZg9GEGxKFCgw==}
 
+  caniuse-lite@1.0.30001793:
+    resolution: {integrity: sha512-iwSsYWaCOoh26cV8NwNRViHlrfUvYsHDfRVcbtmw0Kg6PJIZZXwMkj1442FYLBGkeUf1juAsU3DTfxW579mrPA==}
+
   capital-case@1.0.4:
     resolution: {integrity: sha512-ds37W8CytHgwnhGGTi88pcPyR15qoNkOpYwmMMfnWqqWgESapLqvDx6huFjQ5vqWSn2Z06173XNA7LtMOeUh1A==}
 
@@ -2178,6 +2456,9 @@ packages:
     resolution: {integrity: sha512-FxqpkPPwu1HjuN93Omfm4h8uIanXofW0RxVEW3k5RKx+mJJYSthzNhp32Kzxxy3YAEZ/Dc/EWN1vZRY0+kOhbw==}
     engines: {node: '>= 10'}
 
+  client-only@0.0.1:
+    resolution: {integrity: sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==}
+
   cliui@7.0.4:
     resolution: {integrity: sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==}
 
@@ -2234,6 +2515,9 @@ packages:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
 
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
   csv-parse@5.6.0:
     resolution: {integrity: sha512-l3nz3euub2QMg5ouu5U09Ew9Wf6/wQ8I++ch1loQ0ljmzhmfZYrH9fflS22i/PQEvsPvxCwxgz5q7UB8K1JO4Q==}
 
@@ -2295,6 +2579,10 @@ packages:
     resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==}
     engines: {node: '>=8'}
 
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
   detect-node@2.1.0:
     resolution: {integrity: sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==}
 
@@ -3197,6 +3485,27 @@ packages:
       fp-ts: ^2.0.0
       monocle-ts: ^2.0.0
 
+  next@16.2.6:
+    resolution: {integrity: sha512-qOVgKJg1+At15NpeUP+eJgCHvTCgXsogweq87Ri/Ix7PkqQHg4sdaXmSFqKlgaIXE4kW0g25LE68W87UANlHtw==}
+    engines: {node: '>=20.9.0'}
+    hasBin: true
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+      '@playwright/test': ^1.51.1
+      babel-plugin-react-compiler: '*'
+      react: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      react-dom: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      sass: ^1.3.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      '@playwright/test':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+      sass:
+        optional: true
+
   no-case@3.0.4:
     resolution: {integrity: sha512-fgAN3jGAh+RoxUGZHTSOLJIqUc2wmoBwGR4tbpNAKmmovFoWq0OdRkb0VkldReO2a2iBT/OEulG9XSUc10r3zg==}
 
@@ -3369,6 +3678,10 @@ packages:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
 
+  postcss@8.4.31:
+    resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
   postcss@8.5.8:
     resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
     engines: {node: ^10 || ^12 || >=14}
@@ -3416,6 +3729,15 @@ packages:
     resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
     engines: {node: '>= 0.10'}
 
+  react-dom@19.2.6:
+    resolution: {integrity: sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g==}
+    peerDependencies:
+      react: ^19.2.6
+
+  react@19.2.6:
+    resolution: {integrity: sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==}
+    engines: {node: '>=0.10.0'}
+
   read-yaml-file@1.1.0:
     resolution: {integrity: sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==}
     engines: {node: '>=6'}
@@ -3554,6 +3876,9 @@ packages:
   safer-buffer@2.1.2:
     resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
 
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
   semver-compare@1.0.0:
     resolution: {integrity: sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==}
 
@@ -3592,6 +3917,10 @@ packages:
   setprototypeof@1.2.0:
     resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
 
+  sharp@0.34.5:
+    resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+
   shebang-command@2.0.0:
     resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
     engines: {node: '>=8'}
@@ -3703,6 +4032,19 @@ packages:
     resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
     engines: {node: '>=4'}
 
+  styled-jsx@5.1.6:
+    resolution: {integrity: sha512-qSVyDTeMotdvQYoHWLNGwRFJHC+i+ZvdBRYosOFgC+Wg1vx4frN2/RG/NA7SYqqvKNLf39P2LSRA2pu6n0XYZA==}
+    engines: {node: '>= 12.0.0'}
+    peerDependencies:
+      '@babel/core': '*'
+      babel-plugin-macros: '*'
+      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0 || ^19.0.0-0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      babel-plugin-macros:
+        optional: true
+
   supports-color@7.2.0:
     resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
     engines: {node: '>=8'}
@@ -4488,6 +4830,103 @@ snapshots:
     dependencies:
       hono: 4.12.12
 
+  '@img/colour@1.1.0':
+    optional: true
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-darwin-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-linux-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-arm@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-s390x@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-wasm32@0.34.5':
+    dependencies:
+      '@emnapi/runtime': 1.8.1
+    optional: true
+
+  '@img/sharp-win32-arm64@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-ia32@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-x64@0.34.5':
+    optional: true
+
   '@inquirer/external-editor@1.0.3(@types/node@22.19.15)':
     dependencies:
       chardet: 2.1.1
@@ -4560,6 +4999,32 @@ snapshots:
       '@tybys/wasm-util': 0.10.1
     optional: true
 
+  '@next/env@16.2.6': {}
+
+  '@next/swc-darwin-arm64@16.2.6':
+    optional: true
+
+  '@next/swc-darwin-x64@16.2.6':
+    optional: true
+
+  '@next/swc-linux-arm64-gnu@16.2.6':
+    optional: true
+
+  '@next/swc-linux-arm64-musl@16.2.6':
+    optional: true
+
+  '@next/swc-linux-x64-gnu@16.2.6':
+    optional: true
+
+  '@next/swc-linux-x64-musl@16.2.6':
+    optional: true
+
+  '@next/swc-win32-arm64-msvc@16.2.6':
+    optional: true
+
+  '@next/swc-win32-x64-msvc@16.2.6':
+    optional: true
+
   '@nodelib/fs.scandir@2.1.5':
     dependencies:
       '@nodelib/fs.stat': 2.0.5
@@ -4832,6 +5297,10 @@ snapshots:
 
   '@stricli/core@1.2.6': {}
 
+  '@swc/helpers@0.5.15':
+    dependencies:
+      tslib: 2.8.1
+
   '@textlint/ast-node-types@12.6.1': {}
 
   '@textlint/markdown-to-ast@12.6.1':
@@ -5002,6 +5471,14 @@ snapshots:
 
   '@types/range-parser@1.2.7': {}
 
+  '@types/react-dom@19.2.3(@types/react@19.2.15)':
+    dependencies:
+      '@types/react': 19.2.15
+
+  '@types/react@19.2.15':
+    dependencies:
+      csstype: 3.2.3
+
   '@types/semver@7.7.1': {}
 
   '@types/send@1.2.1':
@@ -5151,6 +5628,8 @@ snapshots:
 
   base64-js@1.5.1: {}
 
+  baseline-browser-mapping@2.10.32: {}
+
   better-path-resolve@1.0.0:
     dependencies:
       is-windows: 1.0.2
@@ -5232,6 +5711,8 @@ snapshots:
       pascal-case: 3.1.2
       tslib: 2.8.1
 
+  caniuse-lite@1.0.30001793: {}
+
   capital-case@1.0.4:
     dependencies:
       no-case: 3.0.4
@@ -5305,6 +5786,8 @@ snapshots:
 
   cli-width@3.0.0: {}
 
+  client-only@0.0.1: {}
+
   cliui@7.0.4:
     dependencies:
       string-width: 4.2.3
@@ -5358,6 +5841,8 @@ snapshots:
       shebang-command: 2.0.0
       which: 2.0.2
 
+  csstype@3.2.3: {}
+
   csv-parse@5.6.0: {}
 
   data-view-buffer@1.0.2:
@@ -5414,6 +5899,9 @@ snapshots:
 
   detect-indent@6.1.0: {}
 
+  detect-libc@2.1.2:
+    optional: true
+
   detect-node@2.1.0: {}
 
   dir-glob@3.0.1:
@@ -6457,6 +6945,30 @@ snapshots:
       fp-ts: 2.16.11
       monocle-ts: 2.3.13(fp-ts@2.16.11)
 
+  next@16.2.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@next/env': 16.2.6
+      '@swc/helpers': 0.5.15
+      baseline-browser-mapping: 2.10.32
+      caniuse-lite: 1.0.30001793
+      postcss: 8.4.31
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      styled-jsx: 5.1.6(react@19.2.6)
+    optionalDependencies:
+      '@next/swc-darwin-arm64': 16.2.6
+      '@next/swc-darwin-x64': 16.2.6
+      '@next/swc-linux-arm64-gnu': 16.2.6
+      '@next/swc-linux-arm64-musl': 16.2.6
+      '@next/swc-linux-x64-gnu': 16.2.6
+      '@next/swc-linux-x64-musl': 16.2.6
+      '@next/swc-win32-arm64-msvc': 16.2.6
+      '@next/swc-win32-x64-msvc': 16.2.6
+      sharp: 0.34.5
+    transitivePeerDependencies:
+      - '@babel/core'
+      - babel-plugin-macros
+
   no-case@3.0.4:
     dependencies:
       lower-case: 2.0.2
@@ -6650,6 +7162,12 @@ snapshots:
 
   possible-typed-array-names@1.1.0: {}
 
+  postcss@8.4.31:
+    dependencies:
+      nanoid: 3.3.11
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
   postcss@8.5.8:
     dependencies:
       nanoid: 3.3.11
@@ -6698,6 +7216,13 @@ snapshots:
       iconv-lite: 0.7.2
       unpipe: 1.0.0
 
+  react-dom@19.2.6(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      scheduler: 0.27.0
+
+  react@19.2.6: {}
+
   read-yaml-file@1.1.0:
     dependencies:
       graceful-fs: 4.2.11
@@ -6910,6 +7435,8 @@ snapshots:
 
   safer-buffer@2.1.2: {}
 
+  scheduler@0.27.0: {}
+
   semver-compare@1.0.0: {}
 
   semver@7.7.4: {}
@@ -6973,6 +7500,38 @@ snapshots:
 
   setprototypeof@1.2.0: {}
 
+  sharp@0.34.5:
+    dependencies:
+      '@img/colour': 1.1.0
+      detect-libc: 2.1.2
+      semver: 7.7.4
+    optionalDependencies:
+      '@img/sharp-darwin-arm64': 0.34.5
+      '@img/sharp-darwin-x64': 0.34.5
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+      '@img/sharp-libvips-linux-arm': 1.2.4
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+      '@img/sharp-libvips-linux-x64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+      '@img/sharp-linux-arm': 0.34.5
+      '@img/sharp-linux-arm64': 0.34.5
+      '@img/sharp-linux-ppc64': 0.34.5
+      '@img/sharp-linux-riscv64': 0.34.5
+      '@img/sharp-linux-s390x': 0.34.5
+      '@img/sharp-linux-x64': 0.34.5
+      '@img/sharp-linuxmusl-arm64': 0.34.5
+      '@img/sharp-linuxmusl-x64': 0.34.5
+      '@img/sharp-wasm32': 0.34.5
+      '@img/sharp-win32-arm64': 0.34.5
+      '@img/sharp-win32-ia32': 0.34.5
+      '@img/sharp-win32-x64': 0.34.5
+    optional: true
+
   shebang-command@2.0.0:
     dependencies:
       shebang-regex: 3.0.0
@@ -7091,6 +7650,11 @@ snapshots:
 
   strip-bom@3.0.0: {}
 
+  styled-jsx@5.1.6(react@19.2.6):
+    dependencies:
+      client-only: 0.0.1
+      react: 19.2.6
+
   supports-color@7.2.0:
     dependencies:
       has-flag: 4.0.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index c586b3e2..8de26747 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -9,11 +9,16 @@ catalog:
   '@transcend-io/internationalization': ^2.3.2
   '@types/json-schema': ^7.0.15
   '@types/node': ^22.19.15
+  '@types/react': ^19.2.15
+  '@types/react-dom': ^19.2.3
   '@types/semver': ^7.7.1
   husky: ^9.1.7
+  next: ^16.2.6
   oxfmt: ^0.38.0
   oxlint: ^1.53.0
   publint: ^0.3.18
+  react: ^19.2.6
+  react-dom: ^19.2.6
   semver: ^7.7.4
   syncpack: ^14.2.0
   tsdown: ^0.21.2
@@ -22,8 +27,8 @@ catalog:
   vitest: ^4.0.18
   zod: ^4.3.6
 
-# Only install npm packages that are at least 3 days old
 minimumReleaseAge: 4320
+
 minimumReleaseAgeExclude:
   - '@transcend-io/*'
 
diff --git a/tsconfig.json b/tsconfig.json
index 99f34d37..39e47e0f 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -16,6 +16,7 @@
     { "path": "./packages/mcp/mcp-server-preferences" },
     { "path": "./packages/mcp/mcp-server-workflows" },
     { "path": "./packages/privacy-types" },
+    { "path": "./packages/react-airgap" },
     { "path": "./packages/sdk" },
     { "path": "./packages/type-utils" },
     { "path": "./packages/utils" }

From 3626887f5fdc35f4355d4972940bc43d093343b4 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 19:43:50 -0400
Subject: [PATCH 02/17] Simplify react-airgap script gating

---
 packages/react-airgap/src/index.ts            |  11 +-
 .../src/next/tracking-script.test.ts          |  96 ++----
 .../react-airgap/src/next/tracking-script.tsx | 287 +++---------------
 3 files changed, 73 insertions(+), 321 deletions(-)

diff --git a/packages/react-airgap/src/index.ts b/packages/react-airgap/src/index.ts
index 5494e500..5610c864 100644
--- a/packages/react-airgap/src/index.ts
+++ b/packages/react-airgap/src/index.ts
@@ -1,11 +1,4 @@
 'use client';
 
-export {
-  allOf,
-  anyOf,
-  default as TrackingScript,
-  onConsent,
-  onEvent,
-  onPromise,
-} from './next/tracking-script.js';
-export type { LoadTrigger, OnEventOptions, TrackingScriptProps } from './next/tracking-script.js';
+export { default as TrackingScript } from './next/tracking-script.js';
+export type { LoadAfter, TrackingScriptProps } from './next/tracking-script.js';
diff --git a/packages/react-airgap/src/next/tracking-script.test.ts b/packages/react-airgap/src/next/tracking-script.test.ts
index 63ffed8c..22a8f079 100644
--- a/packages/react-airgap/src/next/tracking-script.test.ts
+++ b/packages/react-airgap/src/next/tracking-script.test.ts
@@ -1,79 +1,43 @@
-import { describe, expect, test, vi } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
-import { allOf, anyOf, onEvent, onPromise, type LoadTrigger } from './tracking-script.js';
+import { waitForLoadAfter } from './tracking-script.js';
 
-describe('tracking script triggers', () => {
-  test('onEvent loads once when the event fires', () => {
-    const target = new EventTarget();
-    const load = vi.fn();
-    const cleanup = onEvent('ready', { target })(load);
+describe('waitForLoadAfter', () => {
+  test('resolves after a single promise resolves', async () => {
+    const value = {};
 
-    target.dispatchEvent(new Event('ready'));
-    target.dispatchEvent(new Event('ready'));
+    const result = await waitForLoadAfter(Promise.resolve(value));
 
-    expect(load).toHaveBeenCalledTimes(1);
-    cleanup?.();
+    expect(result).toBe(value);
   });
 
-  test('onEvent loads immediately when the latch is already open', () => {
-    const target = new EventTarget();
-    const load = vi.fn();
-
-    onEvent('ready', { target, latch: () => true })(load);
-
-    expect(load).toHaveBeenCalledTimes(1);
-  });
-
-  test('onPromise loads when the promise resolves', async () => {
-    const load = vi.fn();
-
-    onPromise(Promise.resolve())(load);
+  test('waits for promise composition from the caller', async () => {
+    let resolveFirst!: () => void;
+    let resolveSecond!: () => void;
+    const first = new Promise<void>((resolve) => {
+      resolveFirst = resolve;
+    });
+    const second = new Promise<void>((resolve) => {
+      resolveSecond = resolve;
+    });
+    let resolved = false;
+
+    void waitForLoadAfter(Promise.all([first, second])).then(() => {
+      resolved = true;
+    });
+    resolveFirst();
     await Promise.resolve();
+    expect(resolved).toBe(false);
 
-    expect(load).toHaveBeenCalledTimes(1);
-  });
-
-  test('anyOf loads once when the first trigger fires and cleans up every trigger', () => {
-    const triggerCallbacks: Array<() => void> = [];
-    const firstCleanup = vi.fn();
-    const secondCleanup = vi.fn();
-    const first: LoadTrigger = (load) => {
-      triggerCallbacks[0] = load;
-      return firstCleanup;
-    };
-    const second: LoadTrigger = (load) => {
-      triggerCallbacks[1] = load;
-      return secondCleanup;
-    };
-    const load = vi.fn();
-
-    const cleanup = anyOf(first, second)(load);
-    triggerCallbacks[0]?.();
-    triggerCallbacks[1]?.();
-    cleanup?.();
-
-    expect(load).toHaveBeenCalledTimes(1);
-    expect(firstCleanup).toHaveBeenCalledTimes(1);
-    expect(secondCleanup).toHaveBeenCalledTimes(1);
+    resolveSecond();
+    await Promise.all([first, second]);
+    await Promise.resolve();
+    expect(resolved).toBe(true);
   });
 
-  test('allOf waits for every trigger and ignores duplicate trigger calls', () => {
-    const triggerCallbacks: Array<() => void> = [];
-    const first: LoadTrigger = (load) => {
-      triggerCallbacks[0] = load;
-    };
-    const second: LoadTrigger = (load) => {
-      triggerCallbacks[1] = load;
-    };
-    const load = vi.fn();
-
-    allOf(first, second)(load);
-    triggerCallbacks[0]?.();
-    triggerCallbacks[0]?.();
-    expect(load).not.toHaveBeenCalled();
-
-    triggerCallbacks[1]?.();
+  test('rejects when a load promise rejects', async () => {
+    const error = new Error('gate failed');
 
-    expect(load).toHaveBeenCalledTimes(1);
+    await expect(waitForLoadAfter(Promise.reject(error))).rejects.toThrow(error);
   });
 });
diff --git a/packages/react-airgap/src/next/tracking-script.tsx b/packages/react-airgap/src/next/tracking-script.tsx
index da8226ab..2d14b95c 100644
--- a/packages/react-airgap/src/next/tracking-script.tsx
+++ b/packages/react-airgap/src/next/tracking-script.tsx
@@ -1,198 +1,57 @@
 'use client';
 
-/**
- * TrackingScript — a drop-in wrapper around `next/script` that defers script
- * injection until one or more triggers fire (custom events, promises, or
- * Transcend airgap consent).
- *
- * Supports both forms of `next/script`:
- *   <TrackingScript src="https://cdn.example.com/tag.js" loadAfter={...} />
- *   <TrackingScript id="gtm-init" loadAfter={...}>{`...inline JS...`}</TrackingScript>
- *
- * SSR: like `<Script strategy="afterInteractive">`, this renders nothing
- * server-side. Initial client render also returns null, so there is no
- * hydration mismatch. `strategy="beforeInteractive"` is unsupported (the
- * component will warn in development) because gating happens after hydration.
- */
-
 import Script, { type ScriptProps } from 'next/script';
 import { type ReactElement, type ReactNode, useEffect, useState } from 'react';
 
-/* -------------------------------------------------------------------------- */
-/*                                  Triggers                                  */
-/* -------------------------------------------------------------------------- */
-
 /**
- * A subscription function: receives a `load` callback, calls it when the gate
- * opens, optionally returns a cleanup. This shape handles already-fired
- * events, promises, observables, and airgap's ready queue with one API.
+ * Promise that opens the script gate when it resolves.
+ *
+ * Use normal promise composition at the call site:
+ * - `Promise.all([...])` when every condition must finish.
+ * - `Promise.race([...])` when any condition can open the gate.
  */
-export type LoadTrigger = (load: () => void) => void | (() => void);
-
-export interface OnEventOptions {
-  /** Event target to subscribe to. Defaults to `window` in the browser. */
-  target?: EventTarget;
-  /** Returns true when the trigger condition already happened before mount. */
-  latch?: () => boolean;
-}
-
-interface AirgapConsentApi {
-  /** Resolve consent status for the required tracking purposes. */
-  isConsented(trackingPurposes: Set<string>): boolean;
-  /** Subscribe to airgap changes that may affect consent resolution. */
-  watch?: (callback: () => void) => void | (() => void);
-}
-
-type AirgapReadyCallback = (airgap: AirgapConsentApi) => void;
-
-interface AirgapReadyApi {
-  /** Queue of callbacks to dispatch once airgap is ready. */
-  readyQueue?: AirgapReadyCallback[];
-  /** Subscribe to the airgap ready event. */
-  ready(callback: AirgapReadyCallback): void;
-}
+export type LoadAfter = PromiseLike<unknown>;
 
-interface WindowWithAirgap extends Window {
-  /** Transcend airgap API or preload stub. */
-  airgap?: Partial<AirgapReadyApi>;
+/** Resolve the promise that controls when the script is injected. */
+export function waitForLoadAfter(loadAfter: LoadAfter): Promise<unknown> {
+  return Promise.resolve(loadAfter);
 }
 
-/**
- * Fire on a DOM event. Pass `latch` to short-circuit if the condition is
- * already true (handy for events that may have already fired before mount).
- */
-export const onEvent =
-  (name: string, opts?: OnEventOptions): LoadTrigger =>
-  (load) => {
-    const target = opts?.target ?? (typeof window !== 'undefined' ? window : null);
-    if (!target) return;
-    if (opts?.latch?.()) {
-      load();
-      return;
-    }
-    const handler = () => load();
-    target.addEventListener(name, handler, { once: true });
-    return () => target.removeEventListener(name, handler);
-  };
-
-/** Fire when a Promise resolves. */
-export const onPromise =
-  (promise: Promise<unknown>): LoadTrigger =>
-  (load) => {
-    let cancelled = false;
-    void promise.then(
-      () => {
-        if (!cancelled) load();
-      },
-      () => undefined,
-    );
-    return () => {
-      cancelled = true;
-    };
-  };
-
-/**
- * Fire when Transcend airgap.js is ready AND (optionally) the listed purposes
- * are consented. Subscribes to `airgap.watch` so the gate re-evaluates when
- * the user changes consent — e.g. opt-in later causes the script to load.
- */
-export const onConsent =
-  (purposes?: string[]): LoadTrigger =>
-  (load) => {
-    if (typeof window === 'undefined') return;
-    // `airgap.ready` handles "already loaded" via its readyQueue, so this is
-    // safe whether airgap has arrived yet or not.
-    const w = window as WindowWithAirgap;
-    if (!w.airgap?.ready) {
-      // Stub the ready queue so we don't drop the callback if airgap hasn't
-      // attached yet. The real airgap will drain `readyQueue` on load.
-      const queue: AirgapReadyCallback[] = [];
-      w.airgap = {
-        ...w.airgap,
-        readyQueue: queue,
-        ready(callback) {
-          queue.push(callback);
-        },
-      };
-    }
-    let fired = false;
-    let unwatch: undefined | (() => void);
-    const airgapReady = w.airgap as AirgapReadyApi;
-    airgapReady.ready((airgap) => {
-      const required = purposes ? new Set(purposes) : null;
-      const check = () => {
-        if (fired) return;
-        if (!required || airgap.isConsented(required)) {
-          fired = true;
-          load();
-          unwatch?.();
-        }
-      };
-      check();
-      if (!fired) {
-        const cleanup = airgap.watch?.(check);
-        if (typeof cleanup === 'function') unwatch = cleanup;
-      }
-    });
-    return () => {
-      unwatch?.();
-    };
-  };
-
-/** Fire when ANY of the given triggers fires (logical OR). */
-export const anyOf =
-  (...triggers: LoadTrigger[]): LoadTrigger =>
-  (load) => {
-    let fired = false;
-    const fireOnce = () => {
-      if (!fired) {
-        fired = true;
-        load();
-      }
-    };
-    const cleanups = triggers.map((t) => t(fireOnce));
-    return () => cleanups.forEach((c) => typeof c === 'function' && c());
-  };
-
-/** Fire only when ALL of the given triggers have fired (logical AND). */
-export const allOf =
-  (...triggers: LoadTrigger[]): LoadTrigger =>
-  (load) => {
-    if (triggers.length === 0) {
-      load();
-      return;
-    }
-    const fired = new Set<number>();
-    const cleanups = triggers.map((trigger, index) =>
-      trigger(() => {
-        if (fired.has(index)) return;
-        fired.add(index);
-        if (fired.size === triggers.length) load();
-      }),
-    );
-    return () => cleanups.forEach((c) => typeof c === 'function' && c());
-  };
-
-/* -------------------------------------------------------------------------- */
-/*                                 Component                                  */
-/* -------------------------------------------------------------------------- */
-
 export interface TrackingScriptProps extends ScriptProps {
   /**
-   * Wait for these triggers before injecting the underlying `<Script>`.
-   * - Single trigger: fire when it opens.
-   * - Array: fires when ALL open (logical AND). Use `anyOf(...)` for OR.
+   * Wait for this promise before injecting the underlying `<Script>`.
+   * Use `Promise.all(...)` or `Promise.race(...)` at the call site to compose
+   * multiple conditions. If the promise rejects, the script remains unloaded.
    */
-  loadAfter: LoadTrigger | LoadTrigger[];
-  /** Called once if the gate later closes (e.g. user revokes consent). */
-  onUnload?: () => void;
+  loadAfter: LoadAfter;
   /** Inline script body (for `<TrackingScript id="...">{`...`}</TrackingScript>`). */
   children?: ReactNode;
 }
 
+/**
+ * Client component that renders `next/script` only after `loadAfter` resolves.
+ *
+ * Like `strategy="afterInteractive"`, this renders nothing on the server and
+ * initially renders nothing on the client. `strategy="beforeInteractive"` is
+ * unsupported because the script is gated after hydration.
+ *
+ * @example
+ * ```tsx
+ * const airgapSyncPromise = new Promise((resolve) => {
+ *   self.airgap.ready((airgap) => {
+ *     airgap.addEventListener('sync', resolve, { once: true });
+ *   });
+ * });
+ *
+ * <TrackingScript
+ *   src="https://cdn.example.com/analytics.js"
+ *   strategy="afterInteractive"
+ *   loadAfter={Promise.all([analyticsConsentPromise, airgapSyncPromise])}
+ * />
+ * ```
+ */
 export default function TrackingScript({
   loadAfter,
-  onUnload,
   children,
   ...scriptProps
 }: TrackingScriptProps): ReactElement | null {
@@ -209,84 +68,20 @@ export default function TrackingScript({
   }
 
   useEffect(() => {
-    const triggers = Array.isArray(loadAfter) ? loadAfter : [loadAfter];
     let cancelled = false;
-    const fired = new Set<number>();
-    if (triggers.length === 0) {
-      setOpen(true);
-      return;
-    }
-    const cleanups = triggers.map((trigger, index) =>
-      trigger(() => {
-        if (cancelled || fired.has(index)) return;
-        fired.add(index);
-        if (fired.size === triggers.length) setOpen(true);
-      }),
+    void waitForLoadAfter(loadAfter).then(
+      () => {
+        if (!cancelled) setOpen(true);
+      },
+      () => undefined,
     );
     return () => {
       cancelled = true;
-      cleanups.forEach((c) => typeof c === 'function' && c());
-    };
-    // `loadAfter` should be referentially stable. Memoize triggers at the
-    // call site if they depend on changing values.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  // Fire onUnload if the component unmounts after the script was injected.
-  useEffect(() => {
-    return () => {
-      if (open) onUnload?.();
     };
-  }, [open, onUnload]);
+  }, [loadAfter]);
 
   if (!open) return null;
 
   // Support both external (`src`) and inline (`children`) forms.
   return <Script {...scriptProps}>{children}</Script>;
 }
-
-/* -------------------------------------------------------------------------- */
-/*                                  Examples                                  */
-/* -------------------------------------------------------------------------- */
-
-/*
-import TrackingScript, { onEvent, onConsent, onPromise, anyOf, allOf } from './tracking-script';
-
-// 1. External script gated on a custom event
-<TrackingScript
-  src="https://example.com/heavy.js"
-  strategy="lazyOnload"
-  loadAfter={onEvent('app:bootstrapped')}
-/>
-
-// 2. External script gated on airgap + Analytics consent
-<TrackingScript
-  src="https://cdn.intake-lr.com/logger-1.min.js"
-  strategy="afterInteractive"
-  loadAfter={onConsent(['Analytics'])}
-/>
-
-// 3. Inline GTM bootstrap gated on consent (note: requires `id`)
-<TrackingScript
-  id="gtm-init"
-  strategy="afterInteractive"
-  loadAfter={onConsent(['Analytics', 'Advertising'])}
->{`
-  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});
-  var f=d.getElementsByTagName(s)[0],j=d.createElement(s);j.async=true;
-  j.src='https://www.googletagmanager.com/gtm.js?id='+i;f.parentNode.insertBefore(j,f);
-  })(window,document,'script','dataLayer','GTM-XXXX');
-`}</TrackingScript>
-
-// 4. Compound: consent AND (custom event OR 5s timeout)
-<TrackingScript
-  src="https://s.go-mpulse.net/boomerang/3C8QM-..."
-  loadAfter={allOf(
-    onConsent(['Analytics']),
-    anyOf(
-      onEvent('route:settled'),
-      onPromise(new Promise((r) => setTimeout(r, 5000))),
-    ),
-  )}
-/>
-*/

From 2776c3b32e379d7bb1e2a24e590e219aec1e4ed0 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 19:55:59 -0400
Subject: [PATCH 03/17] airgapReady

---
 packages/react-airgap/README.md               | 85 +++++++++++++++++++
 packages/react-airgap/src/index.ts            |  1 +
 .../src/next/airgap-ready.test.ts             | 51 +++++++++++
 .../react-airgap/src/next/airgap-ready.ts     | 42 +++++++++
 .../react-airgap/src/next/tracking-script.tsx |  8 +-
 5 files changed, 181 insertions(+), 6 deletions(-)
 create mode 100644 packages/react-airgap/README.md
 create mode 100644 packages/react-airgap/src/next/airgap-ready.test.ts
 create mode 100644 packages/react-airgap/src/next/airgap-ready.ts

diff --git a/packages/react-airgap/README.md b/packages/react-airgap/README.md
new file mode 100644
index 00000000..77fd20b2
--- /dev/null
+++ b/packages/react-airgap/README.md
@@ -0,0 +1,85 @@
+# @transcend-io/react-airgap
+
+React helpers for loading scripts after Transcend Airgap is ready.
+
+## TrackingScript
+
+`TrackingScript` is a small client component around `next/script`. It renders
+nothing until its `loadAfter` promise resolves, then renders the underlying
+`<Script>`.
+
+```tsx
+import { airgapReady, TrackingScript } from '@transcend-io/react-airgap';
+
+export function AnalyticsScript() {
+  return (
+    <TrackingScript
+      src="https://cdn.example.com/analytics.js"
+      strategy="afterInteractive"
+      loadAfter={airgapReady()}
+    />
+  );
+}
+```
+
+`strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
+script injection after hydration.
+
+## Custom Gates
+
+The resolved value is ignored, so any `PromiseLike<unknown>` can open the gate.
+
+Use `Promise.all(...)` when every condition must finish:
+
+```tsx
+<TrackingScript
+  src="https://cdn.example.com/analytics.js"
+  strategy="afterInteractive"
+  loadAfter={Promise.all([airgapReady(), analyticsConsentPromise])}
+/>
+```
+
+Use `Promise.race(...)` when any condition can open the gate:
+
+```tsx
+<TrackingScript
+  src="https://cdn.example.com/analytics.js"
+  strategy="lazyOnload"
+  loadAfter={Promise.race([routeSettledPromise, timeoutPromise])}
+/>
+```
+
+To wait for Airgap's `sync` event:
+
+```tsx
+const airgapSyncPromise = new Promise<void>((resolve) => {
+  self.airgap.ready((airgap) => {
+    airgap.addEventListener('sync', () => resolve(), { once: true });
+  });
+});
+
+<TrackingScript
+  src="https://cdn.example.com/analytics.js"
+  strategy="afterInteractive"
+  loadAfter={Promise.all([analyticsConsentPromise, airgapSyncPromise])}
+/>;
+```
+
+## airgapReady
+
+`airgapReady()` resolves when `self.airgap.ready(...)` fires. If airgap.js has
+not loaded yet, it creates the documented ready-queue stub so the callback is
+drained when airgap.js initializes.
+
+```tsx
+import { airgapReady, TrackingScript } from '@transcend-io/react-airgap';
+
+<TrackingScript
+  src="https://cdn.example.com/analytics.js"
+  loadAfter={Promise.all([airgapReady(), analyticsConsentPromise])}
+/>;
+```
+
+When loading airgap.js asynchronously, make sure no trackers load before
+airgap.js is ready. See Transcend's guide to
+[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously.md).
diff --git a/packages/react-airgap/src/index.ts b/packages/react-airgap/src/index.ts
index 5610c864..300b1a5f 100644
--- a/packages/react-airgap/src/index.ts
+++ b/packages/react-airgap/src/index.ts
@@ -1,4 +1,5 @@
 'use client';
 
+export { airgapReady } from './next/airgap-ready.js';
 export { default as TrackingScript } from './next/tracking-script.js';
 export type { LoadAfter, TrackingScriptProps } from './next/tracking-script.js';
diff --git a/packages/react-airgap/src/next/airgap-ready.test.ts b/packages/react-airgap/src/next/airgap-ready.test.ts
new file mode 100644
index 00000000..f7ef584a
--- /dev/null
+++ b/packages/react-airgap/src/next/airgap-ready.test.ts
@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, test } from 'vitest';
+
+import { airgapReady } from './airgap-ready.js';
+
+const originalSelfDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'self');
+
+function setSelf(value: unknown): void {
+  Object.defineProperty(globalThis, 'self', {
+    configurable: true,
+    value,
+  });
+}
+
+afterEach(() => {
+  if (originalSelfDescriptor) {
+    Object.defineProperty(globalThis, 'self', originalSelfDescriptor);
+  } else {
+    Reflect.deleteProperty(globalThis, 'self');
+  }
+});
+
+describe('airgapReady', () => {
+  test('creates a ready queue stub when airgap is not ready yet', async () => {
+    const airgapGlobal = {} as {
+      /** Transcend airgap API or preload stub. */
+      airgap?: {
+        /** Queue of callbacks to dispatch once airgap.js is ready. */
+        readyQueue?: Array<(airgap: unknown) => void>;
+      };
+    };
+    setSelf(airgapGlobal);
+    const ready = airgapReady();
+
+    expect(airgapGlobal.airgap?.readyQueue).toHaveLength(1);
+
+    airgapGlobal.airgap?.readyQueue?.[0]?.({});
+    await expect(ready).resolves.toBeUndefined();
+  });
+
+  test('resolves from an existing airgap ready API', async () => {
+    setSelf({
+      airgap: {
+        ready(callback: (airgap: unknown) => void) {
+          callback({});
+        },
+      },
+    });
+
+    await expect(airgapReady()).resolves.toBeUndefined();
+  });
+});
diff --git a/packages/react-airgap/src/next/airgap-ready.ts b/packages/react-airgap/src/next/airgap-ready.ts
new file mode 100644
index 00000000..03845868
--- /dev/null
+++ b/packages/react-airgap/src/next/airgap-ready.ts
@@ -0,0 +1,42 @@
+type AirgapReadyCallback = (airgap: unknown) => void;
+
+interface AirgapReadyApi {
+  /** Queue of callbacks to dispatch once airgap.js is ready. */
+  readyQueue?: AirgapReadyCallback[];
+  /** Subscribe to the airgap.js ready event. */
+  ready(callback: AirgapReadyCallback): void;
+}
+
+interface GlobalWithAirgap {
+  /** Transcend airgap API or preload stub. */
+  airgap?: Partial<AirgapReadyApi>;
+}
+
+/**
+ * Resolves when `self.airgap.ready(...)` fires.
+ *
+ * If airgap.js has not loaded yet, this creates the documented ready-queue
+ * stub so the callback is drained when airgap.js initializes.
+ */
+export function airgapReady(): Promise<void> {
+  return new Promise((resolve) => {
+    if (typeof self === 'undefined') return;
+
+    const airgapGlobal = self as typeof self & GlobalWithAirgap;
+    const existingAirgap = airgapGlobal.airgap;
+
+    if (!existingAirgap?.ready) {
+      const readyQueue = existingAirgap?.readyQueue ?? [];
+      airgapGlobal.airgap = {
+        ...existingAirgap,
+        readyQueue,
+        ready(callback) {
+          readyQueue.push(callback);
+        },
+      };
+    }
+
+    const airgap = airgapGlobal.airgap as AirgapReadyApi;
+    airgap.ready(() => resolve());
+  });
+}
diff --git a/packages/react-airgap/src/next/tracking-script.tsx b/packages/react-airgap/src/next/tracking-script.tsx
index 2d14b95c..f9dda797 100644
--- a/packages/react-airgap/src/next/tracking-script.tsx
+++ b/packages/react-airgap/src/next/tracking-script.tsx
@@ -37,16 +37,12 @@ export interface TrackingScriptProps extends ScriptProps {
  *
  * @example
  * ```tsx
- * const airgapSyncPromise = new Promise((resolve) => {
- *   self.airgap.ready((airgap) => {
- *     airgap.addEventListener('sync', resolve, { once: true });
- *   });
- * });
+ * import { airgapReady, TrackingScript } from '@transcend-io/react-airgap';
  *
  * <TrackingScript
  *   src="https://cdn.example.com/analytics.js"
  *   strategy="afterInteractive"
- *   loadAfter={Promise.all([analyticsConsentPromise, airgapSyncPromise])}
+ *   loadAfter={Promise.all([airgapReady(), analyticsConsentPromise])}
  * />
  * ```
  */

From 1555bda5ebee3385bd8d9447ec03c9d3774ca785 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 20:08:31 -0400
Subject: [PATCH 04/17] airgap ready nits

---
 packages/react-airgap/README.md               |   2 +-
 packages/react-airgap/src/index.ts            |   2 +-
 .../src/next/airgap-ready.test.ts             |  44 +++++++-
 .../react-airgap/src/next/airgap-ready.ts     |  24 ++++-
 .../src/next/tracking-script.test.ts          |  43 --------
 .../src/next/tracking-script.test.tsx         | 101 ++++++++++++++++++
 .../react-airgap/src/next/tracking-script.tsx |  26 ++---
 7 files changed, 175 insertions(+), 67 deletions(-)
 delete mode 100644 packages/react-airgap/src/next/tracking-script.test.ts
 create mode 100644 packages/react-airgap/src/next/tracking-script.test.tsx

diff --git a/packages/react-airgap/README.md b/packages/react-airgap/README.md
index 77fd20b2..4db0612f 100644
--- a/packages/react-airgap/README.md
+++ b/packages/react-airgap/README.md
@@ -49,7 +49,7 @@ Use `Promise.race(...)` when any condition can open the gate:
 />
 ```
 
-To wait for Airgap's `sync` event:
+To wait for the next Airgap `sync` event:
 
 ```tsx
 const airgapSyncPromise = new Promise<void>((resolve) => {
diff --git a/packages/react-airgap/src/index.ts b/packages/react-airgap/src/index.ts
index 300b1a5f..15a06e2e 100644
--- a/packages/react-airgap/src/index.ts
+++ b/packages/react-airgap/src/index.ts
@@ -2,4 +2,4 @@
 
 export { airgapReady } from './next/airgap-ready.js';
 export { default as TrackingScript } from './next/tracking-script.js';
-export type { LoadAfter, TrackingScriptProps } from './next/tracking-script.js';
+export type { TrackingScriptProps } from './next/tracking-script.js';
diff --git a/packages/react-airgap/src/next/airgap-ready.test.ts b/packages/react-airgap/src/next/airgap-ready.test.ts
index f7ef584a..e9d2d2b2 100644
--- a/packages/react-airgap/src/next/airgap-ready.test.ts
+++ b/packages/react-airgap/src/next/airgap-ready.test.ts
@@ -1,6 +1,4 @@
-import { afterEach, describe, expect, test } from 'vitest';
-
-import { airgapReady } from './airgap-ready.js';
+import { afterEach, describe, expect, test, vi } from 'vitest';
 
 const originalSelfDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'self');
 
@@ -12,6 +10,7 @@ function setSelf(value: unknown): void {
 }
 
 afterEach(() => {
+  vi.resetModules();
   if (originalSelfDescriptor) {
     Object.defineProperty(globalThis, 'self', originalSelfDescriptor);
   } else {
@@ -21,6 +20,7 @@ afterEach(() => {
 
 describe('airgapReady', () => {
   test('creates a ready queue stub when airgap is not ready yet', async () => {
+    const { airgapReady } = await import('./airgap-ready.js');
     const airgapGlobal = {} as {
       /** Transcend airgap API or preload stub. */
       airgap?: {
@@ -38,6 +38,7 @@ describe('airgapReady', () => {
   });
 
   test('resolves from an existing airgap ready API', async () => {
+    const { airgapReady } = await import('./airgap-ready.js');
     setSelf({
       airgap: {
         ready(callback: (airgap: unknown) => void) {
@@ -48,4 +49,41 @@ describe('airgapReady', () => {
 
     await expect(airgapReady()).resolves.toBeUndefined();
   });
+
+  test('resolves immediately when airgap is already initialized', async () => {
+    const { airgapReady } = await import('./airgap-ready.js');
+    const ready = vi.fn();
+    setSelf({
+      airgap: {
+        addEventListener() {
+          // Initialized airgap.js API is an EventTarget.
+        },
+        ready,
+      },
+    });
+
+    await expect(airgapReady()).resolves.toBeUndefined();
+    expect(ready).not.toHaveBeenCalled();
+  });
+
+  test('reuses the same ready promise across calls', async () => {
+    const { airgapReady } = await import('./airgap-ready.js');
+    const airgapGlobal = {} as {
+      /** Transcend airgap API or preload stub. */
+      airgap?: {
+        /** Queue of callbacks to dispatch once airgap.js is ready. */
+        readyQueue?: Array<(airgap: unknown) => void>;
+      };
+    };
+    setSelf(airgapGlobal);
+
+    const firstReady = airgapReady();
+    const secondReady = airgapReady();
+
+    expect(secondReady).toBe(firstReady);
+    expect(airgapGlobal.airgap?.readyQueue).toHaveLength(1);
+
+    airgapGlobal.airgap?.readyQueue?.[0]?.({});
+    await expect(firstReady).resolves.toBeUndefined();
+  });
 });
diff --git a/packages/react-airgap/src/next/airgap-ready.ts b/packages/react-airgap/src/next/airgap-ready.ts
index 03845868..d573a0f2 100644
--- a/packages/react-airgap/src/next/airgap-ready.ts
+++ b/packages/react-airgap/src/next/airgap-ready.ts
@@ -12,6 +12,21 @@ interface GlobalWithAirgap {
   airgap?: Partial<AirgapReadyApi>;
 }
 
+interface InitializedAirgapApi extends AirgapReadyApi {
+  /** EventTarget listener available after airgap.js initializes. */
+  addEventListener: EventTarget['addEventListener'];
+}
+
+let airgapReadyPromise: Promise<void> | undefined;
+
+function isInitializedAirgapApi(
+  airgap: Partial<AirgapReadyApi> | undefined,
+): airgap is InitializedAirgapApi {
+  return (
+    typeof (airgap as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
+  );
+}
+
 /**
  * Resolves when `self.airgap.ready(...)` fires.
  *
@@ -19,12 +34,17 @@ interface GlobalWithAirgap {
  * stub so the callback is drained when airgap.js initializes.
  */
 export function airgapReady(): Promise<void> {
-  return new Promise((resolve) => {
+  airgapReadyPromise ??= new Promise((resolve) => {
     if (typeof self === 'undefined') return;
 
     const airgapGlobal = self as typeof self & GlobalWithAirgap;
     const existingAirgap = airgapGlobal.airgap;
 
+    if (isInitializedAirgapApi(existingAirgap)) {
+      resolve();
+      return;
+    }
+
     if (!existingAirgap?.ready) {
       const readyQueue = existingAirgap?.readyQueue ?? [];
       airgapGlobal.airgap = {
@@ -39,4 +59,6 @@ export function airgapReady(): Promise<void> {
     const airgap = airgapGlobal.airgap as AirgapReadyApi;
     airgap.ready(() => resolve());
   });
+
+  return airgapReadyPromise;
 }
diff --git a/packages/react-airgap/src/next/tracking-script.test.ts b/packages/react-airgap/src/next/tracking-script.test.ts
deleted file mode 100644
index 22a8f079..00000000
--- a/packages/react-airgap/src/next/tracking-script.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { describe, expect, test } from 'vitest';
-
-import { waitForLoadAfter } from './tracking-script.js';
-
-describe('waitForLoadAfter', () => {
-  test('resolves after a single promise resolves', async () => {
-    const value = {};
-
-    const result = await waitForLoadAfter(Promise.resolve(value));
-
-    expect(result).toBe(value);
-  });
-
-  test('waits for promise composition from the caller', async () => {
-    let resolveFirst!: () => void;
-    let resolveSecond!: () => void;
-    const first = new Promise<void>((resolve) => {
-      resolveFirst = resolve;
-    });
-    const second = new Promise<void>((resolve) => {
-      resolveSecond = resolve;
-    });
-    let resolved = false;
-
-    void waitForLoadAfter(Promise.all([first, second])).then(() => {
-      resolved = true;
-    });
-    resolveFirst();
-    await Promise.resolve();
-    expect(resolved).toBe(false);
-
-    resolveSecond();
-    await Promise.all([first, second]);
-    await Promise.resolve();
-    expect(resolved).toBe(true);
-  });
-
-  test('rejects when a load promise rejects', async () => {
-    const error = new Error('gate failed');
-
-    await expect(waitForLoadAfter(Promise.reject(error))).rejects.toThrow(error);
-  });
-});
diff --git a/packages/react-airgap/src/next/tracking-script.test.tsx b/packages/react-airgap/src/next/tracking-script.test.tsx
new file mode 100644
index 00000000..d789f172
--- /dev/null
+++ b/packages/react-airgap/src/next/tracking-script.test.tsx
@@ -0,0 +1,101 @@
+import type { ReactElement } from 'react';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import TrackingScript from './tracking-script.js';
+
+const reactMocks = vi.hoisted(() => ({
+  useEffect: vi.fn(),
+  useState: vi.fn(),
+}));
+
+vi.mock('next/script', () => ({
+  default: function MockScript(): null {
+    return null;
+  },
+}));
+
+vi.mock('react', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('react')>();
+
+  return {
+    ...actual,
+    useEffect: reactMocks.useEffect,
+    useState: reactMocks.useState,
+  };
+});
+
+describe('TrackingScript', () => {
+  beforeEach(() => {
+    reactMocks.useEffect.mockReset();
+    reactMocks.useState.mockReset();
+  });
+
+  test('renders nothing before loadAfter resolves', async () => {
+    let resolveLoad!: () => void;
+    const loadAfter = new Promise<void>((resolve) => {
+      resolveLoad = resolve;
+    });
+    const setOpen = vi.fn();
+    reactMocks.useState.mockReturnValue([false, setOpen]);
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    const result = TrackingScript({
+      loadAfter,
+      src: 'https://cdn.example.com/analytics.js',
+    });
+
+    expect(result).toBeNull();
+    expect(setOpen).not.toHaveBeenCalled();
+
+    resolveLoad();
+    await loadAfter;
+    await Promise.resolve();
+
+    expect(setOpen).toHaveBeenCalledWith(true);
+  });
+
+  test('does not open after unmount', async () => {
+    let resolveLoad!: () => void;
+    const loadAfter = new Promise<void>((resolve) => {
+      resolveLoad = resolve;
+    });
+    const setOpen = vi.fn();
+    const cleanupRef: {
+      /** Effect cleanup callback. */
+      current?: () => void;
+    } = {};
+    reactMocks.useState.mockReturnValue([false, setOpen]);
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => {
+      const cleanup = effect();
+      if (typeof cleanup === 'function') cleanupRef.current = cleanup;
+    });
+
+    TrackingScript({
+      loadAfter,
+      src: 'https://cdn.example.com/analytics.js',
+    });
+    cleanupRef.current?.();
+    resolveLoad();
+    await loadAfter;
+    await Promise.resolve();
+
+    expect(setOpen).not.toHaveBeenCalled();
+  });
+
+  test('renders the underlying script after loadAfter resolves', () => {
+    reactMocks.useState.mockReturnValue([true, vi.fn()]);
+    reactMocks.useEffect.mockImplementation(() => undefined);
+
+    const result = TrackingScript({
+      children: 'window.analytics = true;',
+      id: 'analytics-init',
+      loadAfter: Promise.resolve(),
+      strategy: 'afterInteractive',
+    });
+    const scriptElement = result as ReactElement<Record<string, unknown>>;
+
+    expect(scriptElement.props.id).toBe('analytics-init');
+    expect(scriptElement.props.strategy).toBe('afterInteractive');
+    expect(scriptElement.props.children).toBe('window.analytics = true;');
+  });
+});
diff --git a/packages/react-airgap/src/next/tracking-script.tsx b/packages/react-airgap/src/next/tracking-script.tsx
index f9dda797..808aa980 100644
--- a/packages/react-airgap/src/next/tracking-script.tsx
+++ b/packages/react-airgap/src/next/tracking-script.tsx
@@ -3,27 +3,13 @@
 import Script, { type ScriptProps } from 'next/script';
 import { type ReactElement, type ReactNode, useEffect, useState } from 'react';
 
-/**
- * Promise that opens the script gate when it resolves.
- *
- * Use normal promise composition at the call site:
- * - `Promise.all([...])` when every condition must finish.
- * - `Promise.race([...])` when any condition can open the gate.
- */
-export type LoadAfter = PromiseLike<unknown>;
-
-/** Resolve the promise that controls when the script is injected. */
-export function waitForLoadAfter(loadAfter: LoadAfter): Promise<unknown> {
-  return Promise.resolve(loadAfter);
-}
-
 export interface TrackingScriptProps extends ScriptProps {
   /**
    * Wait for this promise before injecting the underlying `<Script>`.
    * Use `Promise.all(...)` or `Promise.race(...)` at the call site to compose
    * multiple conditions. If the promise rejects, the script remains unloaded.
    */
-  loadAfter: LoadAfter;
+  loadAfter: PromiseLike<unknown>;
   /** Inline script body (for `<TrackingScript id="...">{`...`}</TrackingScript>`). */
   children?: ReactNode;
 }
@@ -37,12 +23,16 @@ export interface TrackingScriptProps extends ScriptProps {
  *
  * @example
  * ```tsx
- * import { airgapReady, TrackingScript } from '@transcend-io/react-airgap';
+ * import { TrackingScript } from '@transcend-io/react-airgap';
+ *
+ * const analyticsReady = new Promise<void>((resolve) => {
+ *   window.addEventListener('analytics:ready', () => resolve(), { once: true });
+ * });
  *
  * <TrackingScript
  *   src="https://cdn.example.com/analytics.js"
  *   strategy="afterInteractive"
- *   loadAfter={Promise.all([airgapReady(), analyticsConsentPromise])}
+ *   loadAfter={analyticsReady}
  * />
  * ```
  */
@@ -65,7 +55,7 @@ export default function TrackingScript({
 
   useEffect(() => {
     let cancelled = false;
-    void waitForLoadAfter(loadAfter).then(
+    void Promise.resolve(loadAfter).then(
       () => {
         if (!cancelled) setOpen(true);
       },

From 2aa56199e7696d0899857ba0e5ef62e5ad65b984 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 21:16:21 -0400
Subject: [PATCH 05/17] add react airgap snippets

---
 packages/react-airgap/.attw.json              |   3 +
 packages/react-airgap/README.md               | 140 ++++++++++--
 packages/react-airgap/package.json            |   8 +
 .../src/{next => }/airgap-ready.test.ts       |  30 +--
 .../src/{next => }/airgap-ready.ts            |  30 +--
 packages/react-airgap/src/index.ts            |   4 +-
 .../src/next/consent-boundary.test.tsx        | 165 ++++++++++++++
 .../src/next/consent-boundary.tsx             | 212 ++++++++++++++++++
 .../src/next/consent-manager.test.tsx         | 194 ++++++++++++++++
 .../react-airgap/src/next/consent-manager.tsx | 131 +++++++++++
 packages/react-airgap/src/next/index.ts       |  12 +
 .../react-airgap/src/next/tracking-script.tsx |   7 +-
 packages/react-airgap/tsdown.config.ts        |   2 +-
 pnpm-lock.yaml                                |   4 +
 14 files changed, 885 insertions(+), 57 deletions(-)
 create mode 100644 packages/react-airgap/.attw.json
 rename packages/react-airgap/src/{next => }/airgap-ready.test.ts (77%)
 rename packages/react-airgap/src/{next => }/airgap-ready.ts (56%)
 create mode 100644 packages/react-airgap/src/next/consent-boundary.test.tsx
 create mode 100644 packages/react-airgap/src/next/consent-boundary.tsx
 create mode 100644 packages/react-airgap/src/next/consent-manager.test.tsx
 create mode 100644 packages/react-airgap/src/next/consent-manager.tsx
 create mode 100644 packages/react-airgap/src/next/index.ts

diff --git a/packages/react-airgap/.attw.json b/packages/react-airgap/.attw.json
new file mode 100644
index 00000000..25cd95e5
--- /dev/null
+++ b/packages/react-airgap/.attw.json
@@ -0,0 +1,3 @@
+{
+  "profile": "node16"
+}
diff --git a/packages/react-airgap/README.md b/packages/react-airgap/README.md
index 4db0612f..25b38551 100644
--- a/packages/react-airgap/README.md
+++ b/packages/react-airgap/README.md
@@ -9,14 +9,17 @@ nothing until its `loadAfter` promise resolves, then renders the underlying
 `<Script>`.
 
 ```tsx
-import { airgapReady, TrackingScript } from '@transcend-io/react-airgap';
+import { airgapReady } from '@transcend-io/react-airgap';
+import { TrackingScript } from '@transcend-io/react-airgap/next';
+
+const loadAfter = airgapReady();
 
 export function AnalyticsScript() {
   return (
     <TrackingScript
       src="https://cdn.example.com/analytics.js"
       strategy="afterInteractive"
-      loadAfter={airgapReady()}
+      loadAfter={loadAfter}
     />
   );
 }
@@ -25,35 +28,42 @@ export function AnalyticsScript() {
 `strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
 script injection after hydration.
 
-## Custom Gates
+### Custom Gates
 
 The resolved value is ignored, so any `PromiseLike<unknown>` can open the gate.
+Create the promise outside render so React does not restart the gate effect on
+every render. The promise names below, such as `analyticsConsentPromise`, are
+app-provided examples.
 
 Use `Promise.all(...)` when every condition must finish:
 
 ```tsx
+const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
+
 <TrackingScript
   src="https://cdn.example.com/analytics.js"
   strategy="afterInteractive"
-  loadAfter={Promise.all([airgapReady(), analyticsConsentPromise])}
-/>
+  loadAfter={loadAfter}
+/>;
 ```
 
 Use `Promise.race(...)` when any condition can open the gate:
 
 ```tsx
+const loadAfter = Promise.race([routeSettledPromise, timeoutPromise]);
+
 <TrackingScript
   src="https://cdn.example.com/analytics.js"
   strategy="lazyOnload"
-  loadAfter={Promise.race([routeSettledPromise, timeoutPromise])}
-/>
+  loadAfter={loadAfter}
+/>;
 ```
 
 To wait for the next Airgap `sync` event:
 
 ```tsx
-const airgapSyncPromise = new Promise<void>((resolve) => {
-  self.airgap.ready((airgap) => {
+const airgapSyncPromise = airgapReady().then((airgap) => {
+  return new Promise<void>((resolve) => {
     airgap.addEventListener('sync', () => resolve(), { once: true });
   });
 });
@@ -61,25 +71,117 @@ const airgapSyncPromise = new Promise<void>((resolve) => {
 <TrackingScript
   src="https://cdn.example.com/analytics.js"
   strategy="afterInteractive"
-  loadAfter={Promise.all([analyticsConsentPromise, airgapSyncPromise])}
+  loadAfter={airgapSyncPromise}
 />;
 ```
 
+You can also gate inline scripts. Like `next/script`, inline scripts should
+include an `id`:
+
+```tsx
+const gtmReadyPromise = airgapReady();
+
+<TrackingScript id="gtm-init" strategy="afterInteractive" loadAfter={gtmReadyPromise}>{`
+  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});
+  var f=d.getElementsByTagName(s)[0],j=d.createElement(s);j.async=true;
+  j.src='https://www.googletagmanager.com/gtm.js?id='+i;f.parentNode.insertBefore(j,f);
+  })(window,document,'script','dataLayer','GTM-XXXX');
+`}</TrackingScript>;
+```
+
 ## airgapReady
 
-`airgapReady()` resolves when `self.airgap.ready(...)` fires. If airgap.js has
-not loaded yet, it creates the documented ready-queue stub so the callback is
-drained when airgap.js initializes.
+`airgapReady()` resolves with the typed `AirgapAPI` when
+`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
+documented ready-queue stub so the callback is drained when airgap.js
+initializes.
 
 ```tsx
-import { airgapReady, TrackingScript } from '@transcend-io/react-airgap';
+import { airgapReady } from '@transcend-io/react-airgap';
+import { TrackingScript } from '@transcend-io/react-airgap/next';
 
-<TrackingScript
-  src="https://cdn.example.com/analytics.js"
-  loadAfter={Promise.all([airgapReady(), analyticsConsentPromise])}
-/>;
+const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
+
+export function AnalyticsScript() {
+  return <TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
+}
 ```
 
 When loading airgap.js asynchronously, make sure no trackers load before
-airgap.js is ready. See Transcend's guide to
+airgap.js is ready. Async loading cannot regulate trackers that initialize
+before Airgap has initialized. See Transcend's guide to
 [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously.md).
+
+## ConsentProvider
+
+`ConsentProvider` loads airgap.js through `next/script` and exposes the loaded
+`airgap` and `transcend` APIs through `useConsentManager()`.
+
+```tsx
+import { ConsentProvider, useConsentManager } from '@transcend-io/react-airgap/next';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ConsentProvider
+      airgapSrc="https://transcend-cdn.com/cm/<bundle-id>/airgap.js"
+      scriptProps={{ strategy: 'afterInteractive' }}
+    >
+      {children}
+    </ConsentProvider>
+  );
+}
+
+export function PrivacyChoicesButton() {
+  const { transcend } = useConsentManager();
+
+  return (
+    <button
+      type="button"
+      disabled={!transcend}
+      onClick={() => void transcend?.showConsentManager()}
+    >
+      Privacy choices
+    </button>
+  );
+}
+```
+
+## ConsentBoundary
+
+`ConsentBoundary` checks the URLs needed by a subtree before mounting its
+children. While the check is pending, or when consent is missing, only the
+fallback renders so gated children cannot start loading network resources.
+
+```tsx
+import {
+  ConsentBoundary,
+  type ConsentBoundaryFallbackProps,
+} from '@transcend-io/react-airgap/next';
+
+function ConsentFallback({
+  missingConsentPurposes,
+  onConsentGiven,
+  status,
+}: ConsentBoundaryFallbackProps) {
+  if (status === 'pending') {
+    return <p>Checking consent...</p>;
+  }
+
+  return (
+    <button type="button" onClick={onConsentGiven}>
+      Allow {Array.from(missingConsentPurposes).join(', ')} trackers
+    </button>
+  );
+}
+
+export function AnalyticsWidgetBoundary() {
+  return (
+    <ConsentBoundary
+      urlsRequiredForRender={['https://www.googletagmanager.com/gtm.js?id=GTM-XXXX']}
+      fallback={ConsentFallback}
+    >
+      <AnalyticsWidget />
+    </ConsentBoundary>
+  );
+}
+```
diff --git a/packages/react-airgap/package.json b/packages/react-airgap/package.json
index a29fe23a..23731e53 100644
--- a/packages/react-airgap/package.json
+++ b/packages/react-airgap/package.json
@@ -21,6 +21,11 @@
       "@transcend-io/source": "./src/index.ts",
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
+    },
+    "./next": {
+      "@transcend-io/source": "./src/next/index.ts",
+      "types": "./dist/next/index.d.mts",
+      "default": "./dist/next/index.mjs"
     }
   },
   "publishConfig": {
@@ -33,6 +38,9 @@
     "check:exports": "attw --pack . --ignore-rules cjs-resolves-to-esm",
     "check:publint": "publint --level warning --strict --pack pnpm"
   },
+  "dependencies": {
+    "@transcend-io/airgap.js-types": "workspace:*"
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "catalog:",
     "@types/node": "catalog:",
diff --git a/packages/react-airgap/src/next/airgap-ready.test.ts b/packages/react-airgap/src/airgap-ready.test.ts
similarity index 77%
rename from packages/react-airgap/src/next/airgap-ready.test.ts
rename to packages/react-airgap/src/airgap-ready.test.ts
index e9d2d2b2..15bfc809 100644
--- a/packages/react-airgap/src/next/airgap-ready.test.ts
+++ b/packages/react-airgap/src/airgap-ready.test.ts
@@ -29,40 +29,43 @@ describe('airgapReady', () => {
       };
     };
     setSelf(airgapGlobal);
+    const readyAirgap = {};
     const ready = airgapReady();
 
     expect(airgapGlobal.airgap?.readyQueue).toHaveLength(1);
 
-    airgapGlobal.airgap?.readyQueue?.[0]?.({});
-    await expect(ready).resolves.toBeUndefined();
+    airgapGlobal.airgap?.readyQueue?.[0]?.(readyAirgap);
+    await expect(ready).resolves.toBe(readyAirgap);
   });
 
   test('resolves from an existing airgap ready API', async () => {
     const { airgapReady } = await import('./airgap-ready.js');
+    const readyAirgap = {};
     setSelf({
       airgap: {
         ready(callback: (airgap: unknown) => void) {
-          callback({});
+          callback(readyAirgap);
         },
       },
     });
 
-    await expect(airgapReady()).resolves.toBeUndefined();
+    await expect(airgapReady()).resolves.toBe(readyAirgap);
   });
 
   test('resolves immediately when airgap is already initialized', async () => {
     const { airgapReady } = await import('./airgap-ready.js');
     const ready = vi.fn();
-    setSelf({
-      airgap: {
-        addEventListener() {
-          // Initialized airgap.js API is an EventTarget.
-        },
-        ready,
+    const initializedAirgap = {
+      addEventListener() {
+        // Initialized airgap.js API is an EventTarget.
       },
+      ready,
+    };
+    setSelf({
+      airgap: initializedAirgap,
     });
 
-    await expect(airgapReady()).resolves.toBeUndefined();
+    await expect(airgapReady()).resolves.toBe(initializedAirgap);
     expect(ready).not.toHaveBeenCalled();
   });
 
@@ -76,6 +79,7 @@ describe('airgapReady', () => {
       };
     };
     setSelf(airgapGlobal);
+    const readyAirgap = {};
 
     const firstReady = airgapReady();
     const secondReady = airgapReady();
@@ -83,7 +87,7 @@ describe('airgapReady', () => {
     expect(secondReady).toBe(firstReady);
     expect(airgapGlobal.airgap?.readyQueue).toHaveLength(1);
 
-    airgapGlobal.airgap?.readyQueue?.[0]?.({});
-    await expect(firstReady).resolves.toBeUndefined();
+    airgapGlobal.airgap?.readyQueue?.[0]?.(readyAirgap);
+    await expect(firstReady).resolves.toBe(readyAirgap);
   });
 });
diff --git a/packages/react-airgap/src/next/airgap-ready.ts b/packages/react-airgap/src/airgap-ready.ts
similarity index 56%
rename from packages/react-airgap/src/next/airgap-ready.ts
rename to packages/react-airgap/src/airgap-ready.ts
index d573a0f2..7086815c 100644
--- a/packages/react-airgap/src/next/airgap-ready.ts
+++ b/packages/react-airgap/src/airgap-ready.ts
@@ -1,27 +1,17 @@
-type AirgapReadyCallback = (airgap: unknown) => void;
+import type { AirgapAPI } from '@transcend-io/airgap.js-types';
 
-interface AirgapReadyApi {
-  /** Queue of callbacks to dispatch once airgap.js is ready. */
-  readyQueue?: AirgapReadyCallback[];
-  /** Subscribe to the airgap.js ready event. */
-  ready(callback: AirgapReadyCallback): void;
-}
+type PreInitAirgapAPI = Pick<AirgapAPI, 'ready' | 'readyQueue'>;
 
 interface GlobalWithAirgap {
   /** Transcend airgap API or preload stub. */
-  airgap?: Partial<AirgapReadyApi>;
-}
-
-interface InitializedAirgapApi extends AirgapReadyApi {
-  /** EventTarget listener available after airgap.js initializes. */
-  addEventListener: EventTarget['addEventListener'];
+  airgap?: AirgapAPI | Partial<PreInitAirgapAPI>;
 }
 
-let airgapReadyPromise: Promise<void> | undefined;
+let airgapReadyPromise: Promise<AirgapAPI> | undefined;
 
 function isInitializedAirgapApi(
-  airgap: Partial<AirgapReadyApi> | undefined,
-): airgap is InitializedAirgapApi {
+  airgap: AirgapAPI | Partial<PreInitAirgapAPI> | undefined,
+): airgap is AirgapAPI {
   return (
     typeof (airgap as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
   );
@@ -33,7 +23,7 @@ function isInitializedAirgapApi(
  * If airgap.js has not loaded yet, this creates the documented ready-queue
  * stub so the callback is drained when airgap.js initializes.
  */
-export function airgapReady(): Promise<void> {
+export function airgapReady(): Promise<AirgapAPI> {
   airgapReadyPromise ??= new Promise((resolve) => {
     if (typeof self === 'undefined') return;
 
@@ -41,7 +31,7 @@ export function airgapReady(): Promise<void> {
     const existingAirgap = airgapGlobal.airgap;
 
     if (isInitializedAirgapApi(existingAirgap)) {
-      resolve();
+      resolve(existingAirgap);
       return;
     }
 
@@ -56,8 +46,8 @@ export function airgapReady(): Promise<void> {
       };
     }
 
-    const airgap = airgapGlobal.airgap as AirgapReadyApi;
-    airgap.ready(() => resolve());
+    const airgap = airgapGlobal.airgap as PreInitAirgapAPI;
+    airgap.ready((readyAirgap) => resolve(readyAirgap));
   });
 
   return airgapReadyPromise;
diff --git a/packages/react-airgap/src/index.ts b/packages/react-airgap/src/index.ts
index 15a06e2e..73c29e6d 100644
--- a/packages/react-airgap/src/index.ts
+++ b/packages/react-airgap/src/index.ts
@@ -1,5 +1,3 @@
 'use client';
 
-export { airgapReady } from './next/airgap-ready.js';
-export { default as TrackingScript } from './next/tracking-script.js';
-export type { TrackingScriptProps } from './next/tracking-script.js';
+export { airgapReady } from './airgap-ready.js';
diff --git a/packages/react-airgap/src/next/consent-boundary.test.tsx b/packages/react-airgap/src/next/consent-boundary.test.tsx
new file mode 100644
index 00000000..64ff823b
--- /dev/null
+++ b/packages/react-airgap/src/next/consent-boundary.test.tsx
@@ -0,0 +1,165 @@
+import type { AirgapAPI, TrackingPurpose } from '@transcend-io/airgap.js-types';
+import type { ReactElement } from 'react';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import {
+  ConsentBoundary,
+  type ConsentBoundaryFallbackProps,
+  getMissingConsentPurposesForUrls,
+} from './consent-boundary.js';
+
+const mocks = vi.hoisted(() => ({
+  useConsentManager: vi.fn(),
+  useEffect: vi.fn(),
+  useState: vi.fn(),
+}));
+
+vi.mock('react', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('react')>();
+
+  return {
+    ...actual,
+    useEffect: mocks.useEffect,
+    useState: mocks.useState,
+  };
+});
+
+vi.mock('./consent-manager.js', () => ({
+  useConsentManager: mocks.useConsentManager,
+}));
+
+describe('ConsentBoundary', () => {
+  beforeEach(() => {
+    mocks.useConsentManager.mockReset();
+    mocks.useEffect.mockReset();
+    mocks.useState.mockReset();
+  });
+
+  test('renders fallback while pending without mounting children', () => {
+    const fallback = vi.fn(() => 'fallback');
+    mocks.useConsentManager.mockReturnValue({});
+    mocks.useState.mockReturnValue([{ status: 'pending' }, vi.fn()]);
+    mocks.useEffect.mockImplementation(() => undefined);
+
+    const result = ConsentBoundary({
+      children: 'blocked children',
+      fallback,
+      urlsRequiredForRender: ['https://example.com/tracker.js'],
+    });
+
+    expect(result).toBe('fallback');
+    expect(fallback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        missingConsentPurposes: new Set<TrackingPurpose>(),
+        status: 'pending',
+      }),
+    );
+  });
+
+  test('renders children after required URLs are allowed', () => {
+    mocks.useConsentManager.mockReturnValue({});
+    mocks.useState.mockReturnValue([{ status: 'allowed' }, vi.fn()]);
+    mocks.useEffect.mockImplementation(() => undefined);
+
+    const result = ConsentBoundary({
+      children: 'allowed children',
+      urlsRequiredForRender: ['https://example.com/tracker.js'],
+    }) as ReactElement<{ children: string }>;
+
+    expect(result.props.children).toBe('allowed children');
+  });
+
+  test('renders fallback with missing purposes when blocked', () => {
+    const missingConsentPurposes = new Set<TrackingPurpose>(['Analytics']);
+    const fallback = vi.fn(() => 'fallback');
+    mocks.useConsentManager.mockReturnValue({});
+    mocks.useState.mockReturnValue([{ missingConsentPurposes, status: 'blocked' }, vi.fn()]);
+    mocks.useEffect.mockImplementation(() => undefined);
+
+    const result = ConsentBoundary({
+      children: 'blocked children',
+      fallback,
+      urlsRequiredForRender: ['https://example.com/tracker.js'],
+    });
+
+    expect(result).toBe('fallback');
+    expect(fallback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        missingConsentPurposes,
+        status: 'blocked',
+      }),
+    );
+  });
+
+  test('opt-in handler grants missing purposes', async () => {
+    const missingConsentPurposes = new Set<TrackingPurpose>(['Analytics']);
+    const setState = vi.fn();
+    const airgap = {
+      getPurposes: vi.fn(),
+      getConsent: vi.fn(() => ({
+        purposes: {
+          Analytics: false,
+          Essential: true,
+        },
+      })),
+      isAllowed: vi.fn(() => Promise.resolve(true)),
+      setConsent: vi.fn(() => Promise.resolve(true)),
+    };
+    let fallbackProps: ConsentBoundaryFallbackProps | undefined;
+    const fallback = vi.fn((props: ConsentBoundaryFallbackProps) => {
+      fallbackProps = props;
+      return 'fallback';
+    });
+    mocks.useConsentManager.mockReturnValue({ airgap });
+    mocks.useState.mockReturnValue([{ missingConsentPurposes, status: 'blocked' }, setState]);
+    mocks.useEffect.mockImplementation(() => undefined);
+
+    ConsentBoundary({
+      children: 'blocked children',
+      fallback,
+      urlsRequiredForRender: ['https://example.com/tracker.js'],
+    });
+    const auth = new Event('click');
+
+    await fallbackProps?.onConsentGiven({
+      nativeEvent: auth,
+    } as Parameters<ConsentBoundaryFallbackProps['onConsentGiven']>[0]);
+
+    expect(airgap.setConsent).toHaveBeenCalledWith(auth, {
+      Analytics: true,
+      Essential: true,
+    });
+    expect(setState).toHaveBeenCalledWith({ status: 'allowed' });
+  });
+});
+
+describe('getMissingConsentPurposesForUrls', () => {
+  test('returns no missing purposes for allowed URLs', async () => {
+    const airgap = {
+      getPurposes: vi.fn(),
+      isAllowed: vi.fn(() => Promise.resolve(true)),
+    };
+
+    await expect(
+      getMissingConsentPurposesForUrls(airgap as unknown as AirgapAPI, [
+        'https://example.com/tracker.js',
+      ]),
+    ).resolves.toEqual(new Set());
+    expect(airgap.getPurposes).not.toHaveBeenCalled();
+  });
+
+  test('expands Unknown to unconsented regime purposes', async () => {
+    const airgap = {
+      getPurposes: vi.fn(() => Promise.resolve(new Set<TrackingPurpose>(['Unknown']))),
+      getRegimePurposes: vi.fn(() => new Set<TrackingPurpose>(['Analytics', 'Advertising'])),
+      isAllowed: vi.fn(() => Promise.resolve(false)),
+      isConsented: vi.fn((purposes: Set<TrackingPurpose>) => purposes.has('Advertising')),
+    };
+
+    await expect(
+      getMissingConsentPurposesForUrls(airgap as unknown as AirgapAPI, [
+        'https://example.com/tracker.js',
+      ]),
+    ).resolves.toEqual(new Set<TrackingPurpose>(['Analytics']));
+  });
+});
diff --git a/packages/react-airgap/src/next/consent-boundary.tsx b/packages/react-airgap/src/next/consent-boundary.tsx
new file mode 100644
index 00000000..80a20a7c
--- /dev/null
+++ b/packages/react-airgap/src/next/consent-boundary.tsx
@@ -0,0 +1,212 @@
+'use client';
+
+import type { AirgapAPI, TrackingConsent, TrackingPurpose } from '@transcend-io/airgap.js-types';
+import {
+  type MouseEventHandler,
+  type ReactElement,
+  type ReactNode,
+  useEffect,
+  useState,
+} from 'react';
+
+import { useConsentManager } from './consent-manager.js';
+
+type ConsentBoundaryState =
+  | { status: 'pending' }
+  | { status: 'allowed' }
+  | {
+      /** Missing-consent state. */
+      status: 'blocked';
+      /** Purposes that must be consented before children can render. */
+      missingConsentPurposes: Set<TrackingPurpose>;
+    }
+  | {
+      /** Error state while resolving URL purposes. */
+      status: 'error';
+      /** Error thrown by the Airgap API. */
+      error: unknown;
+      /** Purposes resolved before the error, if any. */
+      missingConsentPurposes: Set<TrackingPurpose>;
+    };
+
+export type ConsentBoundaryFallbackStatus = Exclude<ConsentBoundaryState['status'], 'allowed'>;
+
+export interface ConsentBoundaryFallbackProps {
+  /** Current boundary state. */
+  status: ConsentBoundaryFallbackStatus;
+  /** Purposes that are missing consent. */
+  missingConsentPurposes: Set<TrackingPurpose>;
+  /** Error thrown while checking consent, when status is `error`. */
+  error?: unknown;
+  /** Opt into the missing consent purposes. */
+  onConsentGiven: MouseEventHandler<HTMLButtonElement>;
+}
+
+export interface ConsentBoundaryProps {
+  /** Children that should only mount after consent allows the required URLs. */
+  children: ReactNode;
+  /** URLs that must be allowed by Airgap before children render. */
+  urlsRequiredForRender: readonly string[];
+  /** Fallback rendered while checking consent or when consent is missing. */
+  fallback?: (props: ConsentBoundaryFallbackProps) => ReactNode;
+}
+
+function getUnconsentedPurposes(
+  airgap: AirgapAPI,
+  purposes: Set<TrackingPurpose>,
+): Set<TrackingPurpose> {
+  const missingConsentPurposes = new Set<TrackingPurpose>();
+
+  for (const purpose of purposes) {
+    if (purpose === 'Unknown') {
+      for (const regimePurpose of airgap.getRegimePurposes()) {
+        if (!airgap.isConsented(new Set([regimePurpose]))) {
+          missingConsentPurposes.add(regimePurpose);
+        }
+      }
+    } else if (!airgap.isConsented(new Set([purpose]))) {
+      missingConsentPurposes.add(purpose);
+    }
+  }
+
+  return missingConsentPurposes;
+}
+
+/**
+ * Resolve which tracking purposes still need consent before URLs can load.
+ */
+export async function getMissingConsentPurposesForUrls(
+  airgap: AirgapAPI,
+  urlsRequiredForRender: readonly string[],
+): Promise<Set<TrackingPurpose>> {
+  const missingConsentPurposes = new Set<TrackingPurpose>();
+
+  await Promise.all(
+    urlsRequiredForRender.map(async (url) => {
+      if (await airgap.isAllowed(url)) return;
+
+      const missingUrlPurposes = getUnconsentedPurposes(airgap, await airgap.getPurposes(url));
+
+      for (const purpose of missingUrlPurposes) {
+        missingConsentPurposes.add(purpose);
+      }
+    }),
+  );
+
+  return missingConsentPurposes;
+}
+
+function DefaultConsentBoundaryFallback({
+  error,
+  missingConsentPurposes,
+  onConsentGiven,
+  status,
+}: ConsentBoundaryFallbackProps): ReactElement {
+  if (status === 'pending') {
+    return <p>Checking consent...</p>;
+  }
+
+  const purposeList = Array.from(missingConsentPurposes).join(', ');
+
+  return (
+    <div>
+      <p>
+        {error
+          ? 'Unable to check consent for this content.'
+          : 'This content requires additional consent to load.'}
+      </p>
+      {purposeList ? <p>Required purposes: {purposeList}</p> : null}
+      <button type="button" onClick={onConsentGiven}>
+        Opt in
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Renders children only after Airgap allows the URLs required by that subtree.
+ */
+export function ConsentBoundary({
+  children,
+  fallback = DefaultConsentBoundaryFallback,
+  urlsRequiredForRender,
+}: ConsentBoundaryProps): ReactNode {
+  const { airgap } = useConsentManager();
+  const [state, setState] = useState<ConsentBoundaryState>({ status: 'pending' });
+
+  useEffect(() => {
+    let cancelled = false;
+
+    if (!airgap) {
+      setState({ status: 'pending' });
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    setState({ status: 'pending' });
+    void getMissingConsentPurposesForUrls(airgap, urlsRequiredForRender).then(
+      (missingConsentPurposes) => {
+        if (cancelled) return;
+
+        setState(
+          missingConsentPurposes.size === 0
+            ? { status: 'allowed' }
+            : { status: 'blocked', missingConsentPurposes },
+        );
+      },
+      (error: unknown) => {
+        if (!cancelled) {
+          setState({
+            error,
+            missingConsentPurposes: new Set(),
+            status: 'error',
+          });
+        }
+      },
+    );
+
+    return () => {
+      cancelled = true;
+    };
+  }, [airgap, urlsRequiredForRender]);
+
+  if (state.status === 'allowed') {
+    return <>{children}</>;
+  }
+
+  const missingConsentPurposes =
+    state.status === 'pending' ? new Set<TrackingPurpose>() : state.missingConsentPurposes;
+
+  const onConsentGiven: MouseEventHandler<HTMLButtonElement> = async (event) => {
+    if (!airgap || missingConsentPurposes.size === 0) return;
+
+    const consent: TrackingConsent = { ...airgap.getConsent().purposes };
+    for (const purpose of missingConsentPurposes) {
+      consent[purpose] = true;
+    }
+
+    const consentUpdated = await airgap.setConsent(event.nativeEvent, consent);
+    if (consentUpdated === false) return;
+
+    const remainingConsentPurposes = await getMissingConsentPurposesForUrls(
+      airgap,
+      urlsRequiredForRender,
+    );
+    setState(
+      remainingConsentPurposes.size === 0
+        ? { status: 'allowed' }
+        : {
+            missingConsentPurposes: remainingConsentPurposes,
+            status: 'blocked',
+          },
+    );
+  };
+
+  return fallback({
+    error: state.status === 'error' ? state.error : undefined,
+    missingConsentPurposes,
+    onConsentGiven,
+    status: state.status,
+  });
+}
diff --git a/packages/react-airgap/src/next/consent-manager.test.tsx b/packages/react-airgap/src/next/consent-manager.test.tsx
new file mode 100644
index 00000000..85d5cccb
--- /dev/null
+++ b/packages/react-airgap/src/next/consent-manager.test.tsx
@@ -0,0 +1,194 @@
+import type { ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { ConsentProvider } from './consent-manager.js';
+
+const reactMocks = vi.hoisted(() => ({
+  useEffect: vi.fn(),
+  useState: vi.fn(),
+}));
+
+vi.mock('next/script', () => ({
+  default: function MockScript(): null {
+    return null;
+  },
+}));
+
+vi.mock('react', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('react')>();
+
+  return {
+    ...actual,
+    useEffect: reactMocks.useEffect,
+    useState: reactMocks.useState,
+  };
+});
+
+const originalSelfDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'self');
+
+function setSelf(value: unknown): void {
+  Object.defineProperty(globalThis, 'self', {
+    configurable: true,
+    value,
+  });
+}
+
+function useUndefinedConsentState(): {
+  /** Airgap setState mock. */
+  setAirgap: ReturnType<typeof vi.fn>;
+  /** Transcend setState mock. */
+  setTranscend: ReturnType<typeof vi.fn>;
+} {
+  const setAirgap = vi.fn();
+  const setTranscend = vi.fn();
+
+  reactMocks.useState
+    .mockReturnValueOnce([undefined, setAirgap])
+    .mockReturnValueOnce([undefined, setTranscend]);
+
+  return { setAirgap, setTranscend };
+}
+
+describe('ConsentProvider', () => {
+  beforeEach(() => {
+    reactMocks.useEffect.mockReset();
+    reactMocks.useState.mockReset();
+  });
+
+  afterEach(() => {
+    if (originalSelfDescriptor) {
+      Object.defineProperty(globalThis, 'self', originalSelfDescriptor);
+    } else {
+      Reflect.deleteProperty(globalThis, 'self');
+    }
+  });
+
+  test('stubs airgap and transcend ready queues', () => {
+    setSelf({});
+    const { setAirgap, setTranscend } = useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: Array<(api: unknown) => void> };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: Array<(api: unknown) => void> };
+    };
+
+    expect(consentGlobals.airgap?.readyQueue).toHaveLength(1);
+    expect(consentGlobals.transcend?.readyQueue).toHaveLength(1);
+
+    const readyAirgap = {};
+    const readyTranscend = {};
+    consentGlobals.airgap?.readyQueue?.[0]?.(readyAirgap);
+    consentGlobals.transcend?.readyQueue?.[0]?.(readyTranscend);
+
+    expect(setAirgap).toHaveBeenCalledWith(readyAirgap);
+    expect(setTranscend).toHaveBeenCalledWith(readyTranscend);
+  });
+
+  test('preserves existing ready queues', () => {
+    const existingAirgapReady = vi.fn();
+    const existingTranscendReady = vi.fn();
+    setSelf({
+      airgap: { readyQueue: [existingAirgapReady] },
+      transcend: { readyQueue: [existingTranscendReady] },
+    });
+    useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: unknown[] };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: unknown[] };
+    };
+
+    expect(consentGlobals.airgap?.readyQueue?.[0]).toBe(existingAirgapReady);
+    expect(consentGlobals.airgap?.readyQueue).toHaveLength(2);
+    expect(consentGlobals.transcend?.readyQueue?.[0]).toBe(existingTranscendReady);
+    expect(consentGlobals.transcend?.readyQueue).toHaveLength(2);
+  });
+
+  test('does not set state after unmount', () => {
+    setSelf({});
+    const { setAirgap, setTranscend } = useUndefinedConsentState();
+    const cleanupRef: {
+      /** Effect cleanup callback. */
+      current?: () => void;
+    } = {};
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => {
+      const cleanup = effect();
+      if (typeof cleanup === 'function') cleanupRef.current = cleanup;
+    });
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: Array<(api: unknown) => void> };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: Array<(api: unknown) => void> };
+    };
+
+    cleanupRef.current?.();
+    consentGlobals.airgap?.readyQueue?.[0]?.({});
+    consentGlobals.transcend?.readyQueue?.[0]?.({});
+
+    expect(setAirgap).not.toHaveBeenCalled();
+    expect(setTranscend).not.toHaveBeenCalled();
+  });
+
+  test('sets state immediately when APIs are already initialized', () => {
+    const readyAirgap = {
+      addEventListener() {
+        // Initialized APIs are EventTargets.
+      },
+    };
+    const readyTranscend = {
+      addEventListener() {
+        // Initialized APIs are EventTargets.
+      },
+    };
+    setSelf({
+      airgap: readyAirgap,
+      transcend: readyTranscend,
+    });
+    const { setAirgap, setTranscend } = useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+
+    expect(setAirgap).toHaveBeenCalledWith(readyAirgap);
+    expect(setTranscend).toHaveBeenCalledWith(readyTranscend);
+  });
+
+  test('renders Script with the provided airgap source', () => {
+    useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation(() => undefined);
+
+    const result = ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+      scriptProps: { id: 'airgap', strategy: 'afterInteractive' },
+    }) as ReactElement<{ children: ReactElement<Record<string, unknown>>[] }>;
+    const [scriptElement] = result.props.children;
+
+    expect(scriptElement?.props.src).toBe('https://transcend-cdn.com/cm/example/airgap.js');
+    expect(scriptElement?.props.id).toBe('airgap');
+    expect(scriptElement?.props.strategy).toBe('afterInteractive');
+  });
+});
diff --git a/packages/react-airgap/src/next/consent-manager.tsx b/packages/react-airgap/src/next/consent-manager.tsx
new file mode 100644
index 00000000..cea29066
--- /dev/null
+++ b/packages/react-airgap/src/next/consent-manager.tsx
@@ -0,0 +1,131 @@
+'use client';
+
+import type { AirgapAPI, PreInitTranscendAPI, TranscendAPI } from '@transcend-io/airgap.js-types';
+import Script, { type ScriptProps } from 'next/script';
+import {
+  type Context,
+  createContext,
+  type ReactElement,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState,
+} from 'react';
+
+type PreInitAirgapAPI = Pick<AirgapAPI, 'ready' | 'readyQueue'>;
+
+type ReadyApi<TApi> = {
+  /** Queue of callbacks to dispatch once the API is ready. */
+  readyQueue?: Array<(api: TApi) => void>;
+  /** Subscribe to the API ready event. */
+  ready(callback: (api: TApi) => void): void;
+};
+
+interface ConsentGlobals {
+  /** airgap.js interface or preload stub. */
+  airgap?: AirgapAPI | Partial<PreInitAirgapAPI>;
+  /** Transcend consent manager interface or preload stub. */
+  transcend?: TranscendAPI | Partial<PreInitTranscendAPI>;
+}
+
+/** The loaded Airgap and Transcend Consent APIs. */
+export interface ConsentAPI {
+  /** The airgap.js core API, once loaded. */
+  airgap?: AirgapAPI;
+  /** The Transcend Consent Manager UI API, once loaded. */
+  transcend?: TranscendAPI;
+}
+
+export interface ConsentProviderProps {
+  /** Child tree that can consume the consent APIs. */
+  children: ReactNode;
+  /** airgap.js script URL from Transcend's developer settings. */
+  airgapSrc: string;
+  /** Additional props forwarded to `next/script`. */
+  scriptProps?: Omit<ScriptProps, 'children' | 'src'>;
+}
+
+/** React context backing `useConsentManager()`. */
+export const ConsentContext: Context<ConsentAPI> = createContext<ConsentAPI>({});
+
+function ensureReadyApi<TApi>(existing: Partial<ReadyApi<TApi>> | undefined): ReadyApi<TApi> {
+  if (existing?.ready) {
+    return existing as ReadyApi<TApi>;
+  }
+
+  const readyQueue = existing?.readyQueue ?? [];
+
+  return {
+    ...existing,
+    readyQueue,
+    ready(callback) {
+      readyQueue.push(callback);
+    },
+  };
+}
+
+function isInitializedApi<TApi extends EventTarget>(
+  api: TApi | Partial<ReadyApi<TApi>> | undefined,
+): api is TApi {
+  return (
+    typeof (api as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
+  );
+}
+
+/**
+ * Provides loaded `airgap` and `transcend` APIs to React children while loading
+ * airgap.js through `next/script`.
+ */
+export function ConsentProvider({
+  airgapSrc,
+  children,
+  scriptProps,
+}: ConsentProviderProps): ReactElement {
+  const [airgap, setAirgap] = useState<AirgapAPI | undefined>();
+  const [transcend, setTranscend] = useState<TranscendAPI | undefined>();
+
+  useEffect(() => {
+    if (typeof self === 'undefined') return;
+
+    let cancelled = false;
+    const consentGlobals = self as typeof self & ConsentGlobals;
+
+    if (isInitializedApi<AirgapAPI>(consentGlobals.airgap)) {
+      setAirgap(consentGlobals.airgap);
+    } else {
+      const airgapReady = ensureReadyApi<AirgapAPI>(consentGlobals.airgap);
+      consentGlobals.airgap = airgapReady;
+      airgapReady.ready((readyAirgap) => {
+        if (!cancelled) setAirgap(readyAirgap);
+      });
+    }
+
+    if (isInitializedApi<TranscendAPI>(consentGlobals.transcend)) {
+      setTranscend(consentGlobals.transcend);
+    } else {
+      const transcendReady = ensureReadyApi<TranscendAPI>(consentGlobals.transcend);
+      consentGlobals.transcend = transcendReady;
+      transcendReady.ready((readyTranscend) => {
+        if (!cancelled) setTranscend(readyTranscend);
+      });
+    }
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return (
+    <>
+      <Script src={airgapSrc} {...scriptProps} />
+      <ConsentContext.Provider value={{ airgap, transcend }}>{children}</ConsentContext.Provider>
+    </>
+  );
+}
+
+/**
+ * Access the Airgap and Transcend Consent APIs loaded by `ConsentProvider`.
+ */
+export function useConsentManager(): ConsentAPI {
+  return useContext(ConsentContext);
+}
diff --git a/packages/react-airgap/src/next/index.ts b/packages/react-airgap/src/next/index.ts
new file mode 100644
index 00000000..4196bd80
--- /dev/null
+++ b/packages/react-airgap/src/next/index.ts
@@ -0,0 +1,12 @@
+'use client';
+
+export { ConsentContext, ConsentProvider, useConsentManager } from './consent-manager.js';
+export type { ConsentAPI, ConsentProviderProps } from './consent-manager.js';
+export { ConsentBoundary, getMissingConsentPurposesForUrls } from './consent-boundary.js';
+export type {
+  ConsentBoundaryFallbackProps,
+  ConsentBoundaryFallbackStatus,
+  ConsentBoundaryProps,
+} from './consent-boundary.js';
+export { default as TrackingScript } from './tracking-script.js';
+export type { TrackingScriptProps } from './tracking-script.js';
diff --git a/packages/react-airgap/src/next/tracking-script.tsx b/packages/react-airgap/src/next/tracking-script.tsx
index 808aa980..6e892d44 100644
--- a/packages/react-airgap/src/next/tracking-script.tsx
+++ b/packages/react-airgap/src/next/tracking-script.tsx
@@ -23,9 +23,14 @@ export interface TrackingScriptProps extends ScriptProps {
  *
  * @example
  * ```tsx
- * import { TrackingScript } from '@transcend-io/react-airgap';
+ * import { TrackingScript } from '@transcend-io/react-airgap/next';
  *
  * const analyticsReady = new Promise<void>((resolve) => {
+ *   if (window.analyticsReady) {
+ *     resolve();
+ *     return;
+ *   }
+ *
  *   window.addEventListener('analytics:ready', () => resolve(), { once: true });
  * });
  *
diff --git a/packages/react-airgap/tsdown.config.ts b/packages/react-airgap/tsdown.config.ts
index 7ab4ad4c..954cce89 100644
--- a/packages/react-airgap/tsdown.config.ts
+++ b/packages/react-airgap/tsdown.config.ts
@@ -4,5 +4,5 @@ import sharedConfig from '../../tsdown.config.base.ts';
 
 export default defineConfig({
   ...sharedConfig,
-  entry: ['src/index.ts'],
+  entry: ['src/index.ts', 'src/next/index.ts'],
 });
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2e8fcfec..3b1d6bca 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -749,6 +749,10 @@ importers:
         version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
 
   packages/react-airgap:
+    dependencies:
+      '@transcend-io/airgap.js-types':
+        specifier: workspace:*
+        version: link:../airgap.js-types
     devDependencies:
       '@arethetypeswrong/cli':
         specifier: 'catalog:'

From 910f8885fbbc795815d84bc1a0d3eab6c5816acb Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 21:46:02 -0400
Subject: [PATCH 06/17] split airgap react packages

---
 package.json                                  |   2 +-
 packages/airgap-react/airgap-nextjs/README.md | 109 +++++++++
 .../airgap-react/airgap-nextjs/package.json   |  61 +++++
 .../airgap-react/airgap-nextjs/src/index.ts   |  12 +
 .../src/next/consent-manager.test.tsx         |   0
 .../src/next/consent-manager.tsx              |  42 +---
 .../src/next/tracking-script.test.tsx         |   2 +-
 .../src/next/tracking-script.tsx              |   4 +-
 .../airgap-nextjs}/tsconfig.json              |   2 +-
 .../airgap-nextjs/tsdown.config.ts            |   8 +
 .../airgap-react}/README.md                   | 105 ++-------
 .../airgap-react}/package.json                |  13 +-
 .../src/core}/airgap-ready.test.ts            |   0
 .../airgap-react/src/core}/airgap-ready.ts    |   0
 .../airgap-react/src/core/consent-boundary.ts |  46 ++++
 .../airgap-react/src/core/consent-manager.ts  |  94 ++++++++
 .../airgap-react/airgap-react/src/index.ts    |  13 ++
 .../src/react}/consent-boundary.test.tsx      |   7 +-
 .../src/react}/consent-boundary.tsx           |  48 +---
 .../src/react/consent-manager.test.tsx        | 218 ++++++++++++++++++
 .../src/react/consent-manager.tsx             | 103 +++++++++
 .../src/react/tracking-script.test.tsx        | 127 ++++++++++
 .../src/react/tracking-script.tsx             |  80 +++++++
 .../airgap-react/airgap-react/tsconfig.json   |  14 ++
 .../airgap-react/tsdown.config.ts             |   8 +
 packages/react-airgap/.attw.json              |   3 -
 packages/react-airgap/src/index.ts            |   3 -
 packages/react-airgap/src/next/index.ts       |  12 -
 packages/react-airgap/tsdown.config.ts        |   8 -
 pnpm-lock.yaml                                | 120 ++++++----
 pnpm-workspace.yaml                           |   1 +
 scripts/package-conventions.test.ts           |  13 +-
 tsconfig.json                                 |   3 +-
 33 files changed, 1029 insertions(+), 252 deletions(-)
 create mode 100644 packages/airgap-react/airgap-nextjs/README.md
 create mode 100644 packages/airgap-react/airgap-nextjs/package.json
 create mode 100644 packages/airgap-react/airgap-nextjs/src/index.ts
 rename packages/{react-airgap => airgap-react/airgap-nextjs}/src/next/consent-manager.test.tsx (100%)
 rename packages/{react-airgap => airgap-react/airgap-nextjs}/src/next/consent-manager.tsx (71%)
 rename packages/{react-airgap => airgap-react/airgap-nextjs}/src/next/tracking-script.test.tsx (98%)
 rename packages/{react-airgap => airgap-react/airgap-nextjs}/src/next/tracking-script.tsx (95%)
 rename packages/{react-airgap => airgap-react/airgap-nextjs}/tsconfig.json (88%)
 create mode 100644 packages/airgap-react/airgap-nextjs/tsdown.config.ts
 rename packages/{react-airgap => airgap-react/airgap-react}/README.md (51%)
 rename packages/{react-airgap => airgap-react/airgap-react}/package.json (82%)
 rename packages/{react-airgap/src => airgap-react/airgap-react/src/core}/airgap-ready.test.ts (100%)
 rename packages/{react-airgap/src => airgap-react/airgap-react/src/core}/airgap-ready.ts (100%)
 create mode 100644 packages/airgap-react/airgap-react/src/core/consent-boundary.ts
 create mode 100644 packages/airgap-react/airgap-react/src/core/consent-manager.ts
 create mode 100644 packages/airgap-react/airgap-react/src/index.ts
 rename packages/{react-airgap/src/next => airgap-react/airgap-react/src/react}/consent-boundary.test.tsx (96%)
 rename packages/{react-airgap/src/next => airgap-react/airgap-react/src/react}/consent-boundary.tsx (77%)
 create mode 100644 packages/airgap-react/airgap-react/src/react/consent-manager.test.tsx
 create mode 100644 packages/airgap-react/airgap-react/src/react/consent-manager.tsx
 create mode 100644 packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx
 create mode 100644 packages/airgap-react/airgap-react/src/react/tracking-script.tsx
 create mode 100644 packages/airgap-react/airgap-react/tsconfig.json
 create mode 100644 packages/airgap-react/airgap-react/tsdown.config.ts
 delete mode 100644 packages/react-airgap/.attw.json
 delete mode 100644 packages/react-airgap/src/index.ts
 delete mode 100644 packages/react-airgap/src/next/index.ts
 delete mode 100644 packages/react-airgap/tsdown.config.ts

diff --git a/package.json b/package.json
index 2c5a39df..c11f25c9 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,7 @@
     "lint:fix:root": "oxlint --fix .",
     "format:root": "oxfmt --write .",
     "format:check:root": "oxfmt --check .",
-    "check:deps:root": "syncpack lint --source \"package.json\" --source \"packages/*/package.json\" --source \"packages/mcp/*/package.json\"",
+    "check:deps:root": "syncpack lint --source \"package.json\" --source \"packages/*/package.json\" --source \"packages/airgap-react/*/package.json\" --source \"packages/mcp/*/package.json\"",
     "prepare": "husky"
   },
   "devDependencies": {
diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
new file mode 100644
index 00000000..13720ca2
--- /dev/null
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -0,0 +1,109 @@
+# @transcend-io/airgap-nextjs
+
+Next.js helpers for loading Airgap and gating trackers. This package has the
+same public features as `@transcend-io/airgap-react`, but uses `next/script`
+for script rendering.
+
+## TrackingScript
+
+`TrackingScript` is a small client component around `next/script`. It renders
+nothing until its `loadAfter` promise resolves, then renders the underlying
+`<Script>`.
+
+```tsx
+import { airgapReady, TrackingScript } from '@transcend-io/airgap-nextjs';
+
+const loadAfter = airgapReady();
+
+export function AnalyticsScript() {
+  return (
+    <TrackingScript
+      src="https://cdn.example.com/analytics.js"
+      strategy="afterInteractive"
+      loadAfter={loadAfter}
+    />
+  );
+}
+```
+
+`strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
+script injection after hydration.
+
+## airgapReady
+
+`airgapReady()` resolves with the typed `AirgapAPI` when
+`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
+documented ready-queue stub so the callback is drained when airgap.js
+initializes.
+
+```tsx
+const airgapSyncPromise = airgapReady().then((airgap) => {
+  return new Promise<void>((resolve) => {
+    airgap.addEventListener('sync', () => resolve(), { once: true });
+  });
+});
+```
+
+When loading airgap.js asynchronously, make sure no trackers load before
+airgap.js is ready. Async loading cannot regulate trackers that initialize
+before Airgap has initialized. See Transcend's guide to
+[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously.md).
+
+## ConsentProvider
+
+`ConsentProvider` loads airgap.js through `next/script` and exposes the loaded
+`airgap` and `transcend` APIs through `useConsentManager()`.
+
+```tsx
+import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-nextjs';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ConsentProvider
+      airgapSrc="https://transcend-cdn.com/cm/<bundle-id>/airgap.js"
+      scriptProps={{ strategy: 'afterInteractive' }}
+    >
+      {children}
+    </ConsentProvider>
+  );
+}
+
+export function PrivacyChoicesButton() {
+  const { transcend } = useConsentManager();
+
+  return (
+    <button
+      type="button"
+      disabled={!transcend}
+      onClick={() => void transcend?.showConsentManager()}
+    >
+      Privacy choices
+    </button>
+  );
+}
+```
+
+## ConsentBoundary
+
+`ConsentBoundary` is re-exported from `@transcend-io/airgap-react` so it shares
+the same behavior in both packages.
+
+```tsx
+import { ConsentBoundary, type ConsentBoundaryFallbackProps } from '@transcend-io/airgap-nextjs';
+
+function ConsentFallback({
+  missingConsentPurposes,
+  onConsentGiven,
+  status,
+}: ConsentBoundaryFallbackProps) {
+  if (status === 'pending') {
+    return <p>Checking consent...</p>;
+  }
+
+  return (
+    <button type="button" onClick={onConsentGiven}>
+      Allow {Array.from(missingConsentPurposes).join(', ')} trackers
+    </button>
+  );
+}
+```
diff --git a/packages/airgap-react/airgap-nextjs/package.json b/packages/airgap-react/airgap-nextjs/package.json
new file mode 100644
index 00000000..a7edc2bb
--- /dev/null
+++ b/packages/airgap-react/airgap-nextjs/package.json
@@ -0,0 +1,61 @@
+{
+  "name": "@transcend-io/airgap-nextjs",
+  "version": "0.0.0",
+  "description": "Next.js components for the Transcend Airgap library.",
+  "homepage": "https://github.com/transcend-io/tools/tree/main/packages/airgap-react/airgap-nextjs",
+  "license": "Apache-2.0",
+  "author": "Transcend Inc.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/transcend-io/tools.git",
+    "directory": "packages/airgap-react/airgap-nextjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "@transcend-io/source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check:exports": "attw --pack . --ignore-rules cjs-resolves-to-esm",
+    "check:publint": "publint --level warning --strict --pack pnpm"
+  },
+  "dependencies": {
+    "@transcend-io/airgap-react": "workspace:*",
+    "@transcend-io/airgap.js-types": "workspace:*"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "next": "catalog:",
+    "publint": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "peerDependencies": {
+    "next": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}
diff --git a/packages/airgap-react/airgap-nextjs/src/index.ts b/packages/airgap-react/airgap-nextjs/src/index.ts
new file mode 100644
index 00000000..8dc1a156
--- /dev/null
+++ b/packages/airgap-react/airgap-nextjs/src/index.ts
@@ -0,0 +1,12 @@
+'use client';
+
+export { airgapReady, ConsentBoundary, useConsentManager } from '@transcend-io/airgap-react';
+export type {
+  ConsentAPI,
+  ConsentBoundaryFallbackProps,
+  ConsentBoundaryProps,
+} from '@transcend-io/airgap-react';
+export { ConsentProvider } from './next/consent-manager.js';
+export type { ConsentProviderProps } from './next/consent-manager.js';
+export { TrackingScript } from './next/tracking-script.js';
+export type { TrackingScriptProps } from './next/tracking-script.js';
diff --git a/packages/react-airgap/src/next/consent-manager.test.tsx b/packages/airgap-react/airgap-nextjs/src/next/consent-manager.test.tsx
similarity index 100%
rename from packages/react-airgap/src/next/consent-manager.test.tsx
rename to packages/airgap-react/airgap-nextjs/src/next/consent-manager.test.tsx
diff --git a/packages/react-airgap/src/next/consent-manager.tsx b/packages/airgap-react/airgap-nextjs/src/next/consent-manager.tsx
similarity index 71%
rename from packages/react-airgap/src/next/consent-manager.tsx
rename to packages/airgap-react/airgap-nextjs/src/next/consent-manager.tsx
index cea29066..6b4f0f3e 100644
--- a/packages/react-airgap/src/next/consent-manager.tsx
+++ b/packages/airgap-react/airgap-nextjs/src/next/consent-manager.tsx
@@ -1,18 +1,12 @@
 'use client';
 
-import type { AirgapAPI, PreInitTranscendAPI, TranscendAPI } from '@transcend-io/airgap.js-types';
+import { ConsentContext, type ConsentAPI } from '@transcend-io/airgap-react';
+import type { AirgapAPI, TranscendAPI } from '@transcend-io/airgap.js-types';
 import Script, { type ScriptProps } from 'next/script';
-import {
-  type Context,
-  createContext,
-  type ReactElement,
-  type ReactNode,
-  useContext,
-  useEffect,
-  useState,
-} from 'react';
+import { type ReactElement, type ReactNode, useEffect, useState } from 'react';
 
 type PreInitAirgapAPI = Pick<AirgapAPI, 'ready' | 'readyQueue'>;
+type PreInitTranscendAPI = Pick<TranscendAPI, 'ready' | 'readyQueue'>;
 
 type ReadyApi<TApi> = {
   /** Queue of callbacks to dispatch once the API is ready. */
@@ -28,14 +22,6 @@ interface ConsentGlobals {
   transcend?: TranscendAPI | Partial<PreInitTranscendAPI>;
 }
 
-/** The loaded Airgap and Transcend Consent APIs. */
-export interface ConsentAPI {
-  /** The airgap.js core API, once loaded. */
-  airgap?: AirgapAPI;
-  /** The Transcend Consent Manager UI API, once loaded. */
-  transcend?: TranscendAPI;
-}
-
 export interface ConsentProviderProps {
   /** Child tree that can consume the consent APIs. */
   children: ReactNode;
@@ -45,9 +31,6 @@ export interface ConsentProviderProps {
   scriptProps?: Omit<ScriptProps, 'children' | 'src'>;
 }
 
-/** React context backing `useConsentManager()`. */
-export const ConsentContext: Context<ConsentAPI> = createContext<ConsentAPI>({});
-
 function ensureReadyApi<TApi>(existing: Partial<ReadyApi<TApi>> | undefined): ReadyApi<TApi> {
   if (existing?.ready) {
     return existing as ReadyApi<TApi>;
@@ -81,8 +64,8 @@ export function ConsentProvider({
   children,
   scriptProps,
 }: ConsentProviderProps): ReactElement {
-  const [airgap, setAirgap] = useState<AirgapAPI | undefined>();
-  const [transcend, setTranscend] = useState<TranscendAPI | undefined>();
+  const [airgap, setAirgap] = useState<ConsentAPI['airgap']>();
+  const [transcend, setTranscend] = useState<ConsentAPI['transcend']>();
 
   useEffect(() => {
     if (typeof self === 'undefined') return;
@@ -93,9 +76,9 @@ export function ConsentProvider({
     if (isInitializedApi<AirgapAPI>(consentGlobals.airgap)) {
       setAirgap(consentGlobals.airgap);
     } else {
-      const airgapReady = ensureReadyApi<AirgapAPI>(consentGlobals.airgap);
-      consentGlobals.airgap = airgapReady;
-      airgapReady.ready((readyAirgap) => {
+      const airgapReadyApi = ensureReadyApi<AirgapAPI>(consentGlobals.airgap);
+      consentGlobals.airgap = airgapReadyApi;
+      airgapReadyApi.ready((readyAirgap) => {
         if (!cancelled) setAirgap(readyAirgap);
       });
     }
@@ -122,10 +105,3 @@ export function ConsentProvider({
     </>
   );
 }
-
-/**
- * Access the Airgap and Transcend Consent APIs loaded by `ConsentProvider`.
- */
-export function useConsentManager(): ConsentAPI {
-  return useContext(ConsentContext);
-}
diff --git a/packages/react-airgap/src/next/tracking-script.test.tsx b/packages/airgap-react/airgap-nextjs/src/next/tracking-script.test.tsx
similarity index 98%
rename from packages/react-airgap/src/next/tracking-script.test.tsx
rename to packages/airgap-react/airgap-nextjs/src/next/tracking-script.test.tsx
index d789f172..64b97e46 100644
--- a/packages/react-airgap/src/next/tracking-script.test.tsx
+++ b/packages/airgap-react/airgap-nextjs/src/next/tracking-script.test.tsx
@@ -1,7 +1,7 @@
 import type { ReactElement } from 'react';
 import { beforeEach, describe, expect, test, vi } from 'vitest';
 
-import TrackingScript from './tracking-script.js';
+import { TrackingScript } from './tracking-script.js';
 
 const reactMocks = vi.hoisted(() => ({
   useEffect: vi.fn(),
diff --git a/packages/react-airgap/src/next/tracking-script.tsx b/packages/airgap-react/airgap-nextjs/src/next/tracking-script.tsx
similarity index 95%
rename from packages/react-airgap/src/next/tracking-script.tsx
rename to packages/airgap-react/airgap-nextjs/src/next/tracking-script.tsx
index 6e892d44..b80a0afb 100644
--- a/packages/react-airgap/src/next/tracking-script.tsx
+++ b/packages/airgap-react/airgap-nextjs/src/next/tracking-script.tsx
@@ -23,7 +23,7 @@ export interface TrackingScriptProps extends ScriptProps {
  *
  * @example
  * ```tsx
- * import { TrackingScript } from '@transcend-io/react-airgap/next';
+ * import { TrackingScript } from '@transcend-io/airgap-nextjs';
  *
  * const analyticsReady = new Promise<void>((resolve) => {
  *   if (window.analyticsReady) {
@@ -41,7 +41,7 @@ export interface TrackingScriptProps extends ScriptProps {
  * />
  * ```
  */
-export default function TrackingScript({
+export function TrackingScript({
   loadAfter,
   children,
   ...scriptProps
diff --git a/packages/react-airgap/tsconfig.json b/packages/airgap-react/airgap-nextjs/tsconfig.json
similarity index 88%
rename from packages/react-airgap/tsconfig.json
rename to packages/airgap-react/airgap-nextjs/tsconfig.json
index 4d330f66..4bfb0879 100644
--- a/packages/react-airgap/tsconfig.json
+++ b/packages/airgap-react/airgap-nextjs/tsconfig.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "jsx": "react-jsx",
diff --git a/packages/airgap-react/airgap-nextjs/tsdown.config.ts b/packages/airgap-react/airgap-nextjs/tsdown.config.ts
new file mode 100644
index 00000000..c92e19a4
--- /dev/null
+++ b/packages/airgap-react/airgap-nextjs/tsdown.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsdown';
+
+import sharedConfig from '../../../tsdown.config.base.ts';
+
+export default defineConfig({
+  ...sharedConfig,
+  entry: ['src/index.ts'],
+});
diff --git a/packages/react-airgap/README.md b/packages/airgap-react/airgap-react/README.md
similarity index 51%
rename from packages/react-airgap/README.md
rename to packages/airgap-react/airgap-react/README.md
index 25b38551..a99bd4d7 100644
--- a/packages/react-airgap/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -1,91 +1,41 @@
-# @transcend-io/react-airgap
+# @transcend-io/airgap-react
 
-React helpers for loading scripts after Transcend Airgap is ready.
+React helpers for loading Airgap and gating trackers without depending on
+Next.js.
 
 ## TrackingScript
 
-`TrackingScript` is a small client component around `next/script`. It renders
-nothing until its `loadAfter` promise resolves, then renders the underlying
-`<Script>`.
+`TrackingScript` injects a script element after its `loadAfter` promise
+resolves.
 
 ```tsx
-import { airgapReady } from '@transcend-io/react-airgap';
-import { TrackingScript } from '@transcend-io/react-airgap/next';
+import { airgapReady, TrackingScript } from '@transcend-io/airgap-react';
 
 const loadAfter = airgapReady();
 
 export function AnalyticsScript() {
-  return (
-    <TrackingScript
-      src="https://cdn.example.com/analytics.js"
-      strategy="afterInteractive"
-      loadAfter={loadAfter}
-    />
-  );
+  return <TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
 }
 ```
 
-`strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
-script injection after hydration.
-
-### Custom Gates
-
 The resolved value is ignored, so any `PromiseLike<unknown>` can open the gate.
 Create the promise outside render so React does not restart the gate effect on
-every render. The promise names below, such as `analyticsConsentPromise`, are
-app-provided examples.
-
-Use `Promise.all(...)` when every condition must finish:
+every render.
 
 ```tsx
 const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
 
-<TrackingScript
-  src="https://cdn.example.com/analytics.js"
-  strategy="afterInteractive"
-  loadAfter={loadAfter}
-/>;
-```
-
-Use `Promise.race(...)` when any condition can open the gate:
-
-```tsx
-const loadAfter = Promise.race([routeSettledPromise, timeoutPromise]);
-
-<TrackingScript
-  src="https://cdn.example.com/analytics.js"
-  strategy="lazyOnload"
-  loadAfter={loadAfter}
-/>;
-```
-
-To wait for the next Airgap `sync` event:
-
-```tsx
-const airgapSyncPromise = airgapReady().then((airgap) => {
-  return new Promise<void>((resolve) => {
-    airgap.addEventListener('sync', () => resolve(), { once: true });
-  });
-});
-
-<TrackingScript
-  src="https://cdn.example.com/analytics.js"
-  strategy="afterInteractive"
-  loadAfter={airgapSyncPromise}
-/>;
+<TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
 ```
 
-You can also gate inline scripts. Like `next/script`, inline scripts should
-include an `id`:
+You can also gate inline scripts:
 
 ```tsx
 const gtmReadyPromise = airgapReady();
 
-<TrackingScript id="gtm-init" strategy="afterInteractive" loadAfter={gtmReadyPromise}>{`
-  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});
-  var f=d.getElementsByTagName(s)[0],j=d.createElement(s);j.async=true;
-  j.src='https://www.googletagmanager.com/gtm.js?id='+i;f.parentNode.insertBefore(j,f);
-  })(window,document,'script','dataLayer','GTM-XXXX');
+<TrackingScript id="gtm-init" loadAfter={gtmReadyPromise}>{`
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({ event: 'gtm.js' });
 `}</TrackingScript>;
 ```
 
@@ -97,14 +47,13 @@ documented ready-queue stub so the callback is drained when airgap.js
 initializes.
 
 ```tsx
-import { airgapReady } from '@transcend-io/react-airgap';
-import { TrackingScript } from '@transcend-io/react-airgap/next';
-
-const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
+import { airgapReady } from '@transcend-io/airgap-react';
 
-export function AnalyticsScript() {
-  return <TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
-}
+const airgapSyncPromise = airgapReady().then((airgap) => {
+  return new Promise<void>((resolve) => {
+    airgap.addEventListener('sync', () => resolve(), { once: true });
+  });
+});
 ```
 
 When loading airgap.js asynchronously, make sure no trackers load before
@@ -114,18 +63,15 @@ before Airgap has initialized. See Transcend's guide to
 
 ## ConsentProvider
 
-`ConsentProvider` loads airgap.js through `next/script` and exposes the loaded
-`airgap` and `transcend` APIs through `useConsentManager()`.
+`ConsentProvider` injects airgap.js with `document.createElement('script')` and
+exposes the loaded `airgap` and `transcend` APIs through `useConsentManager()`.
 
 ```tsx
-import { ConsentProvider, useConsentManager } from '@transcend-io/react-airgap/next';
+import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-react';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return (
-    <ConsentProvider
-      airgapSrc="https://transcend-cdn.com/cm/<bundle-id>/airgap.js"
-      scriptProps={{ strategy: 'afterInteractive' }}
-    >
+    <ConsentProvider airgapSrc="https://transcend-cdn.com/cm/<bundle-id>/airgap.js">
       {children}
     </ConsentProvider>
   );
@@ -153,10 +99,7 @@ children. While the check is pending, or when consent is missing, only the
 fallback renders so gated children cannot start loading network resources.
 
 ```tsx
-import {
-  ConsentBoundary,
-  type ConsentBoundaryFallbackProps,
-} from '@transcend-io/react-airgap/next';
+import { ConsentBoundary, type ConsentBoundaryFallbackProps } from '@transcend-io/airgap-react';
 
 function ConsentFallback({
   missingConsentPurposes,
diff --git a/packages/react-airgap/package.json b/packages/airgap-react/airgap-react/package.json
similarity index 82%
rename from packages/react-airgap/package.json
rename to packages/airgap-react/airgap-react/package.json
index 23731e53..fbf0134b 100644
--- a/packages/react-airgap/package.json
+++ b/packages/airgap-react/airgap-react/package.json
@@ -1,14 +1,14 @@
 {
-  "name": "@transcend-io/react-airgap",
+  "name": "@transcend-io/airgap-react",
   "version": "0.0.0",
   "description": "React components for the Transcend Airgap library.",
-  "homepage": "https://github.com/transcend-io/tools/tree/main/packages/react-airgap",
+  "homepage": "https://github.com/transcend-io/tools/tree/main/packages/airgap-react/airgap-react",
   "license": "Apache-2.0",
   "author": "Transcend Inc.",
   "repository": {
     "type": "git",
     "url": "https://github.com/transcend-io/tools.git",
-    "directory": "packages/react-airgap"
+    "directory": "packages/airgap-react/airgap-react"
   },
   "files": [
     "dist"
@@ -21,11 +21,6 @@
       "@transcend-io/source": "./src/index.ts",
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
-    },
-    "./next": {
-      "@transcend-io/source": "./src/next/index.ts",
-      "types": "./dist/next/index.d.mts",
-      "default": "./dist/next/index.mjs"
     }
   },
   "publishConfig": {
@@ -46,7 +41,6 @@
     "@types/node": "catalog:",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    "next": "catalog:",
     "publint": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
@@ -55,7 +49,6 @@
     "vitest": "catalog:"
   },
   "peerDependencies": {
-    "next": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:"
   },
diff --git a/packages/react-airgap/src/airgap-ready.test.ts b/packages/airgap-react/airgap-react/src/core/airgap-ready.test.ts
similarity index 100%
rename from packages/react-airgap/src/airgap-ready.test.ts
rename to packages/airgap-react/airgap-react/src/core/airgap-ready.test.ts
diff --git a/packages/react-airgap/src/airgap-ready.ts b/packages/airgap-react/airgap-react/src/core/airgap-ready.ts
similarity index 100%
rename from packages/react-airgap/src/airgap-ready.ts
rename to packages/airgap-react/airgap-react/src/core/airgap-ready.ts
diff --git a/packages/airgap-react/airgap-react/src/core/consent-boundary.ts b/packages/airgap-react/airgap-react/src/core/consent-boundary.ts
new file mode 100644
index 00000000..91515a79
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/core/consent-boundary.ts
@@ -0,0 +1,46 @@
+import type { AirgapAPI, TrackingPurpose } from '@transcend-io/airgap.js-types';
+
+function getUnconsentedPurposes(
+  airgap: AirgapAPI,
+  purposes: Set<TrackingPurpose>,
+): Set<TrackingPurpose> {
+  const missingConsentPurposes = new Set<TrackingPurpose>();
+
+  for (const purpose of purposes) {
+    if (purpose === 'Unknown') {
+      for (const regimePurpose of airgap.getRegimePurposes()) {
+        if (!airgap.isConsented(new Set([regimePurpose]))) {
+          missingConsentPurposes.add(regimePurpose);
+        }
+      }
+    } else if (!airgap.isConsented(new Set([purpose]))) {
+      missingConsentPurposes.add(purpose);
+    }
+  }
+
+  return missingConsentPurposes;
+}
+
+/**
+ * Resolve which tracking purposes still need consent before URLs can load.
+ */
+export async function getMissingConsentPurposesForUrls(
+  airgap: AirgapAPI,
+  urlsRequiredForRender: readonly string[],
+): Promise<Set<TrackingPurpose>> {
+  const missingConsentPurposes = new Set<TrackingPurpose>();
+
+  await Promise.all(
+    urlsRequiredForRender.map(async (url) => {
+      if (await airgap.isAllowed(url)) return;
+
+      const missingUrlPurposes = getUnconsentedPurposes(airgap, await airgap.getPurposes(url));
+
+      for (const purpose of missingUrlPurposes) {
+        missingConsentPurposes.add(purpose);
+      }
+    }),
+  );
+
+  return missingConsentPurposes;
+}
diff --git a/packages/airgap-react/airgap-react/src/core/consent-manager.ts b/packages/airgap-react/airgap-react/src/core/consent-manager.ts
new file mode 100644
index 00000000..e6ce52e3
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/core/consent-manager.ts
@@ -0,0 +1,94 @@
+import type { AirgapAPI, PreInitTranscendAPI, TranscendAPI } from '@transcend-io/airgap.js-types';
+
+type PreInitAirgapAPI = Pick<AirgapAPI, 'ready' | 'readyQueue'>;
+
+type ReadyApi<TApi> = {
+  /** Queue of callbacks to dispatch once the API is ready. */
+  readyQueue?: Array<(api: TApi) => void>;
+  /** Subscribe to the API ready event. */
+  ready(callback: (api: TApi) => void): void;
+};
+
+interface ConsentGlobals {
+  /** airgap.js interface or preload stub. */
+  airgap?: AirgapAPI | Partial<PreInitAirgapAPI>;
+  /** Transcend consent manager interface or preload stub. */
+  transcend?: TranscendAPI | Partial<PreInitTranscendAPI>;
+}
+
+/** The loaded Airgap and Transcend Consent APIs. */
+export interface ConsentAPI {
+  /** The airgap.js core API, once loaded. */
+  airgap?: AirgapAPI;
+  /** The Transcend Consent Manager UI API, once loaded. */
+  transcend?: TranscendAPI;
+}
+
+export interface ConsentApiSubscriptionHandlers {
+  /** Called when airgap.js is ready. */
+  onAirgap(airgap: AirgapAPI): void;
+  /** Called when the Transcend Consent Manager API is ready. */
+  onTranscend(transcend: TranscendAPI): void;
+}
+
+function ensureReadyApi<TApi>(existing: Partial<ReadyApi<TApi>> | undefined): ReadyApi<TApi> {
+  if (existing?.ready) {
+    return existing as ReadyApi<TApi>;
+  }
+
+  const readyQueue = existing?.readyQueue ?? [];
+
+  return {
+    ...existing,
+    readyQueue,
+    ready(callback) {
+      readyQueue.push(callback);
+    },
+  };
+}
+
+function isInitializedApi<TApi extends EventTarget>(
+  api: TApi | Partial<ReadyApi<TApi>> | undefined,
+): api is TApi {
+  return (
+    typeof (api as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
+  );
+}
+
+/**
+ * Subscribe to the global Airgap and Transcend ready APIs, creating documented
+ * ready-queue stubs when airgap.js has not initialized yet.
+ */
+export function subscribeConsentApis({
+  onAirgap,
+  onTranscend,
+}: ConsentApiSubscriptionHandlers): () => void {
+  if (typeof self === 'undefined') return () => undefined;
+
+  let cancelled = false;
+  const consentGlobals = self as typeof self & ConsentGlobals;
+
+  if (isInitializedApi<AirgapAPI>(consentGlobals.airgap)) {
+    onAirgap(consentGlobals.airgap);
+  } else {
+    const airgapReady = ensureReadyApi<AirgapAPI>(consentGlobals.airgap);
+    consentGlobals.airgap = airgapReady;
+    airgapReady.ready((readyAirgap) => {
+      if (!cancelled) onAirgap(readyAirgap);
+    });
+  }
+
+  if (isInitializedApi<TranscendAPI>(consentGlobals.transcend)) {
+    onTranscend(consentGlobals.transcend);
+  } else {
+    const transcendReady = ensureReadyApi<TranscendAPI>(consentGlobals.transcend);
+    consentGlobals.transcend = transcendReady;
+    transcendReady.ready((readyTranscend) => {
+      if (!cancelled) onTranscend(readyTranscend);
+    });
+  }
+
+  return () => {
+    cancelled = true;
+  };
+}
diff --git a/packages/airgap-react/airgap-react/src/index.ts b/packages/airgap-react/airgap-react/src/index.ts
new file mode 100644
index 00000000..164a02a6
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/index.ts
@@ -0,0 +1,13 @@
+'use client';
+
+export { airgapReady } from './core/airgap-ready.js';
+export type { ConsentAPI } from './core/consent-manager.js';
+export { ConsentBoundary } from './react/consent-boundary.js';
+export type {
+  ConsentBoundaryFallbackProps,
+  ConsentBoundaryProps,
+} from './react/consent-boundary.js';
+export { ConsentContext, ConsentProvider, useConsentManager } from './react/consent-manager.js';
+export type { ConsentProviderProps } from './react/consent-manager.js';
+export { TrackingScript } from './react/tracking-script.js';
+export type { TrackingScriptProps } from './react/tracking-script.js';
diff --git a/packages/react-airgap/src/next/consent-boundary.test.tsx b/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
similarity index 96%
rename from packages/react-airgap/src/next/consent-boundary.test.tsx
rename to packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
index 64ff823b..1c5de5eb 100644
--- a/packages/react-airgap/src/next/consent-boundary.test.tsx
+++ b/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
@@ -2,11 +2,8 @@ import type { AirgapAPI, TrackingPurpose } from '@transcend-io/airgap.js-types';
 import type { ReactElement } from 'react';
 import { beforeEach, describe, expect, test, vi } from 'vitest';
 
-import {
-  ConsentBoundary,
-  type ConsentBoundaryFallbackProps,
-  getMissingConsentPurposesForUrls,
-} from './consent-boundary.js';
+import { getMissingConsentPurposesForUrls } from '../core/consent-boundary.js';
+import { ConsentBoundary, type ConsentBoundaryFallbackProps } from './consent-boundary.js';
 
 const mocks = vi.hoisted(() => ({
   useConsentManager: vi.fn(),
diff --git a/packages/react-airgap/src/next/consent-boundary.tsx b/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
similarity index 77%
rename from packages/react-airgap/src/next/consent-boundary.tsx
rename to packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
index 80a20a7c..1131d871 100644
--- a/packages/react-airgap/src/next/consent-boundary.tsx
+++ b/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import type { AirgapAPI, TrackingConsent, TrackingPurpose } from '@transcend-io/airgap.js-types';
+import type { TrackingConsent, TrackingPurpose } from '@transcend-io/airgap.js-types';
 import {
   type MouseEventHandler,
   type ReactElement,
@@ -9,6 +9,7 @@ import {
   useState,
 } from 'react';
 
+import { getMissingConsentPurposesForUrls } from '../core/consent-boundary.js';
 import { useConsentManager } from './consent-manager.js';
 
 type ConsentBoundaryState =
@@ -51,51 +52,6 @@ export interface ConsentBoundaryProps {
   fallback?: (props: ConsentBoundaryFallbackProps) => ReactNode;
 }
 
-function getUnconsentedPurposes(
-  airgap: AirgapAPI,
-  purposes: Set<TrackingPurpose>,
-): Set<TrackingPurpose> {
-  const missingConsentPurposes = new Set<TrackingPurpose>();
-
-  for (const purpose of purposes) {
-    if (purpose === 'Unknown') {
-      for (const regimePurpose of airgap.getRegimePurposes()) {
-        if (!airgap.isConsented(new Set([regimePurpose]))) {
-          missingConsentPurposes.add(regimePurpose);
-        }
-      }
-    } else if (!airgap.isConsented(new Set([purpose]))) {
-      missingConsentPurposes.add(purpose);
-    }
-  }
-
-  return missingConsentPurposes;
-}
-
-/**
- * Resolve which tracking purposes still need consent before URLs can load.
- */
-export async function getMissingConsentPurposesForUrls(
-  airgap: AirgapAPI,
-  urlsRequiredForRender: readonly string[],
-): Promise<Set<TrackingPurpose>> {
-  const missingConsentPurposes = new Set<TrackingPurpose>();
-
-  await Promise.all(
-    urlsRequiredForRender.map(async (url) => {
-      if (await airgap.isAllowed(url)) return;
-
-      const missingUrlPurposes = getUnconsentedPurposes(airgap, await airgap.getPurposes(url));
-
-      for (const purpose of missingUrlPurposes) {
-        missingConsentPurposes.add(purpose);
-      }
-    }),
-  );
-
-  return missingConsentPurposes;
-}
-
 function DefaultConsentBoundaryFallback({
   error,
   missingConsentPurposes,
diff --git a/packages/airgap-react/airgap-react/src/react/consent-manager.test.tsx b/packages/airgap-react/airgap-react/src/react/consent-manager.test.tsx
new file mode 100644
index 00000000..90f283f1
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/react/consent-manager.test.tsx
@@ -0,0 +1,218 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { ConsentProvider } from './consent-manager.js';
+
+const reactMocks = vi.hoisted(() => ({
+  useEffect: vi.fn(),
+  useState: vi.fn(),
+}));
+
+vi.mock('react', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('react')>();
+
+  return {
+    ...actual,
+    useEffect: reactMocks.useEffect,
+    useState: reactMocks.useState,
+  };
+});
+
+const originalSelfDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'self');
+const originalDocumentDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'document');
+
+function setSelf(value: unknown): void {
+  Object.defineProperty(globalThis, 'self', {
+    configurable: true,
+    value,
+  });
+}
+
+function setDocument(value: unknown): void {
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value,
+  });
+}
+
+function useUndefinedConsentState(): {
+  /** Airgap setState mock. */
+  setAirgap: ReturnType<typeof vi.fn>;
+  /** Transcend setState mock. */
+  setTranscend: ReturnType<typeof vi.fn>;
+} {
+  const setAirgap = vi.fn();
+  const setTranscend = vi.fn();
+
+  reactMocks.useState
+    .mockReturnValueOnce([undefined, setAirgap])
+    .mockReturnValueOnce([undefined, setTranscend]);
+
+  return { setAirgap, setTranscend };
+}
+
+describe('ConsentProvider', () => {
+  beforeEach(() => {
+    reactMocks.useEffect.mockReset();
+    reactMocks.useState.mockReset();
+  });
+
+  afterEach(() => {
+    if (originalSelfDescriptor) {
+      Object.defineProperty(globalThis, 'self', originalSelfDescriptor);
+    } else {
+      Reflect.deleteProperty(globalThis, 'self');
+    }
+    if (originalDocumentDescriptor) {
+      Object.defineProperty(globalThis, 'document', originalDocumentDescriptor);
+    } else {
+      Reflect.deleteProperty(globalThis, 'document');
+    }
+  });
+
+  test('stubs airgap and transcend ready queues', () => {
+    setSelf({});
+    const { setAirgap, setTranscend } = useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: Array<(api: unknown) => void> };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: Array<(api: unknown) => void> };
+    };
+
+    expect(consentGlobals.airgap?.readyQueue).toHaveLength(1);
+    expect(consentGlobals.transcend?.readyQueue).toHaveLength(1);
+
+    const readyAirgap = {};
+    const readyTranscend = {};
+    consentGlobals.airgap?.readyQueue?.[0]?.(readyAirgap);
+    consentGlobals.transcend?.readyQueue?.[0]?.(readyTranscend);
+
+    expect(setAirgap).toHaveBeenCalledWith(readyAirgap);
+    expect(setTranscend).toHaveBeenCalledWith(readyTranscend);
+  });
+
+  test('preserves existing ready queues', () => {
+    const existingAirgapReady = vi.fn();
+    const existingTranscendReady = vi.fn();
+    setSelf({
+      airgap: { readyQueue: [existingAirgapReady] },
+      transcend: { readyQueue: [existingTranscendReady] },
+    });
+    useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: unknown[] };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: unknown[] };
+    };
+
+    expect(consentGlobals.airgap?.readyQueue?.[0]).toBe(existingAirgapReady);
+    expect(consentGlobals.airgap?.readyQueue).toHaveLength(2);
+    expect(consentGlobals.transcend?.readyQueue?.[0]).toBe(existingTranscendReady);
+    expect(consentGlobals.transcend?.readyQueue).toHaveLength(2);
+  });
+
+  test('does not set state after unmount', () => {
+    setSelf({});
+    const { setAirgap, setTranscend } = useUndefinedConsentState();
+    const cleanups: Array<() => void> = [];
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => {
+      const cleanup = effect();
+      if (typeof cleanup === 'function') cleanups.push(cleanup);
+    });
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: Array<(api: unknown) => void> };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: Array<(api: unknown) => void> };
+    };
+
+    for (const cleanup of cleanups) cleanup();
+    consentGlobals.airgap?.readyQueue?.[0]?.({});
+    consentGlobals.transcend?.readyQueue?.[0]?.({});
+
+    expect(setAirgap).not.toHaveBeenCalled();
+    expect(setTranscend).not.toHaveBeenCalled();
+  });
+
+  test('sets state immediately when APIs are already initialized', () => {
+    const readyAirgap = {
+      addEventListener() {
+        // Initialized APIs are EventTargets.
+      },
+    };
+    const readyTranscend = {
+      addEventListener() {
+        // Initialized APIs are EventTargets.
+      },
+    };
+    setSelf({
+      airgap: readyAirgap,
+      transcend: readyTranscend,
+    });
+    const { setAirgap, setTranscend } = useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    });
+
+    expect(setAirgap).toHaveBeenCalledWith(readyAirgap);
+    expect(setTranscend).toHaveBeenCalledWith(readyTranscend);
+  });
+
+  test('injects a script with the provided airgap source', () => {
+    setSelf({});
+    const appendedScripts: unknown[] = [];
+    setDocument({
+      createElement: vi.fn(() => ({
+        dataset: {},
+        remove: vi.fn(),
+      })),
+      documentElement: {
+        appendChild: vi.fn((script: unknown) => appendedScripts.push(script)),
+      },
+    });
+    useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+      scriptProps: { id: 'airgap' },
+    });
+    const [scriptElement] = appendedScripts as Array<{
+      /** Script async attribute. */
+      async: boolean;
+      /** Script defer attribute. */
+      defer: boolean;
+      /** Script element ID. */
+      id: string;
+      /** Script source URL. */
+      src: string;
+    }>;
+
+    expect(scriptElement?.src).toBe('https://transcend-cdn.com/cm/example/airgap.js');
+    expect(scriptElement?.id).toBe('airgap');
+    expect(scriptElement?.async).toBe(true);
+    expect(scriptElement?.defer).toBe(true);
+  });
+});
diff --git a/packages/airgap-react/airgap-react/src/react/consent-manager.tsx b/packages/airgap-react/airgap-react/src/react/consent-manager.tsx
new file mode 100644
index 00000000..03572a72
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/react/consent-manager.tsx
@@ -0,0 +1,103 @@
+'use client';
+
+import type { AirgapAPI, TranscendAPI } from '@transcend-io/airgap.js-types';
+import {
+  type Context,
+  createContext,
+  type ReactElement,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState,
+} from 'react';
+
+import { type ConsentAPI, subscribeConsentApis } from '../core/consent-manager.js';
+
+export interface ConsentProviderProps {
+  /** Child tree that can consume the consent APIs. */
+  children: ReactNode;
+  /** airgap.js script URL from Transcend's developer settings. */
+  airgapSrc: string;
+  /** Additional attributes for the injected airgap.js script element. */
+  scriptProps?: ReactAirgapScriptProps;
+}
+
+export interface ReactAirgapScriptProps {
+  /** Script element ID. */
+  id?: string;
+  /** Whether to load the script asynchronously. Defaults to true. */
+  async?: boolean;
+  /** Whether to defer script execution. Defaults to true. */
+  defer?: boolean;
+  /** Script nonce for CSP. */
+  nonce?: string;
+  /** Subresource integrity metadata. */
+  integrity?: string;
+  /** CORS setting for the script request. */
+  crossOrigin?: HTMLScriptElement['crossOrigin'];
+  /** Referrer policy for the script request. */
+  referrerPolicy?: HTMLScriptElement['referrerPolicy'];
+  /** Additional data attributes to set on the script element. */
+  dataset?: Record<string, string>;
+}
+
+/** React context backing `useConsentManager()`. */
+export const ConsentContext: Context<ConsentAPI> = createContext<ConsentAPI>({});
+
+function appendAirgapScript(src: string, scriptProps: ReactAirgapScriptProps = {}): () => void {
+  if (typeof document === 'undefined') return () => undefined;
+
+  const script = document.createElement('script');
+  script.src = src;
+  script.async = scriptProps.async ?? true;
+  script.defer = scriptProps.defer ?? true;
+
+  if (scriptProps.id) script.id = scriptProps.id;
+  if (scriptProps.nonce) script.nonce = scriptProps.nonce;
+  if (scriptProps.integrity) script.integrity = scriptProps.integrity;
+  if (scriptProps.crossOrigin) script.crossOrigin = scriptProps.crossOrigin;
+  if (scriptProps.referrerPolicy) script.referrerPolicy = scriptProps.referrerPolicy;
+
+  for (const [key, value] of Object.entries(scriptProps.dataset ?? {})) {
+    script.dataset[key] = value;
+  }
+
+  document.documentElement.appendChild(script);
+
+  return () => {
+    script.remove();
+  };
+}
+
+/**
+ * Provides loaded `airgap` and `transcend` APIs to React children while loading
+ * airgap.js through a DOM script element.
+ */
+export function ConsentProvider({
+  airgapSrc,
+  children,
+  scriptProps,
+}: ConsentProviderProps): ReactElement {
+  const [airgap, setAirgap] = useState<AirgapAPI | undefined>();
+  const [transcend, setTranscend] = useState<TranscendAPI | undefined>();
+
+  useEffect(() => {
+    return subscribeConsentApis({
+      onAirgap: setAirgap,
+      onTranscend: setTranscend,
+    });
+  }, []);
+
+  useEffect(() => appendAirgapScript(airgapSrc, scriptProps), [airgapSrc, scriptProps]);
+
+  return (
+    <ConsentContext.Provider value={{ airgap, transcend }}>{children}</ConsentContext.Provider>
+  );
+}
+
+/**
+ * Access the Airgap and Transcend Consent APIs loaded by `ConsentProvider`.
+ */
+export function useConsentManager(): ConsentAPI {
+  return useContext(ConsentContext);
+}
diff --git a/packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx b/packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx
new file mode 100644
index 00000000..5f6bbe57
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx
@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { TrackingScript } from './tracking-script.js';
+
+const reactMocks = vi.hoisted(() => ({
+  useEffect: vi.fn(),
+}));
+
+vi.mock('react', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('react')>();
+
+  return {
+    ...actual,
+    useEffect: reactMocks.useEffect,
+  };
+});
+
+const originalDocumentDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'document');
+
+function setDocument(value: unknown): void {
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value,
+  });
+}
+
+function stubDocument(): unknown[] {
+  const appendedScripts: unknown[] = [];
+  setDocument({
+    createElement: vi.fn(() => ({
+      dataset: {},
+      remove: vi.fn(),
+    })),
+    documentElement: {
+      appendChild: vi.fn((script: unknown) => appendedScripts.push(script)),
+    },
+  });
+
+  return appendedScripts;
+}
+
+describe('TrackingScript', () => {
+  beforeEach(() => {
+    reactMocks.useEffect.mockReset();
+  });
+
+  afterEach(() => {
+    if (originalDocumentDescriptor) {
+      Object.defineProperty(globalThis, 'document', originalDocumentDescriptor);
+    } else {
+      Reflect.deleteProperty(globalThis, 'document');
+    }
+  });
+
+  test('injects nothing before loadAfter resolves', async () => {
+    let resolveLoad!: () => void;
+    const loadAfter = new Promise<void>((resolve) => {
+      resolveLoad = resolve;
+    });
+    const appendedScripts = stubDocument();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    const result = TrackingScript({
+      loadAfter,
+      src: 'https://cdn.example.com/analytics.js',
+    });
+
+    expect(result).toBeNull();
+    expect(appendedScripts).toHaveLength(0);
+
+    resolveLoad();
+    await loadAfter;
+    await Promise.resolve();
+
+    expect(appendedScripts).toHaveLength(1);
+  });
+
+  test('does not inject after unmount', async () => {
+    let resolveLoad!: () => void;
+    const loadAfter = new Promise<void>((resolve) => {
+      resolveLoad = resolve;
+    });
+    const appendedScripts = stubDocument();
+    const cleanupRef: {
+      /** Effect cleanup callback. */
+      current?: () => void;
+    } = {};
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => {
+      const cleanup = effect();
+      if (typeof cleanup === 'function') cleanupRef.current = cleanup;
+    });
+
+    TrackingScript({
+      loadAfter,
+      src: 'https://cdn.example.com/analytics.js',
+    });
+    cleanupRef.current?.();
+    resolveLoad();
+    await loadAfter;
+    await Promise.resolve();
+
+    expect(appendedScripts).toHaveLength(0);
+  });
+
+  test('injects inline script after loadAfter resolves', async () => {
+    const appendedScripts = stubDocument();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    const result = TrackingScript({
+      children: 'window.analytics = true;',
+      id: 'analytics-init',
+      loadAfter: Promise.resolve(),
+    });
+
+    await Promise.resolve();
+    const [scriptElement] = appendedScripts as Array<{
+      /** Script element ID. */
+      id: string;
+      /** Inline script body. */
+      text: string;
+    }>;
+
+    expect(result).toBeNull();
+    expect(scriptElement?.id).toBe('analytics-init');
+    expect(scriptElement?.text).toBe('window.analytics = true;');
+  });
+});
diff --git a/packages/airgap-react/airgap-react/src/react/tracking-script.tsx b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
new file mode 100644
index 00000000..e4d9785c
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
@@ -0,0 +1,80 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import type { ReactAirgapScriptProps } from './consent-manager.js';
+
+export interface TrackingScriptProps extends ReactAirgapScriptProps {
+  /**
+   * Wait for this promise before injecting the underlying `<Script>`.
+   * Use `Promise.all(...)` or `Promise.race(...)` at the call site to compose
+   * multiple conditions. If the promise rejects, the script remains unloaded.
+   */
+  loadAfter: PromiseLike<unknown>;
+  /** External script URL to inject after `loadAfter` resolves. */
+  src?: string;
+  /** Inline script body. */
+  children?: string;
+}
+
+/**
+ * Client component that injects a script element only after `loadAfter` resolves.
+ *
+ * @example
+ * ```tsx
+ * import { TrackingScript } from '@transcend-io/airgap-react';
+ *
+ * const analyticsReady = new Promise<void>((resolve) => {
+ *   if (window.analyticsReady) {
+ *     resolve();
+ *     return;
+ *   }
+ *
+ *   window.addEventListener('analytics:ready', () => resolve(), { once: true });
+ * });
+ *
+ * <TrackingScript
+ *   src="https://cdn.example.com/analytics.js"
+ *   loadAfter={analyticsReady}
+ * />
+ * ```
+ */
+export function TrackingScript({
+  loadAfter,
+  children,
+  src,
+  ...scriptProps
+}: TrackingScriptProps): null {
+  useEffect(() => {
+    let cancelled = false;
+    let cleanup: (() => void) | undefined;
+    void Promise.resolve(loadAfter).then(
+      () => {
+        if (cancelled || typeof document === 'undefined') return;
+
+        const script = document.createElement('script');
+        if (src) script.src = src;
+        if (children) script.text = children;
+        script.async = scriptProps.async ?? true;
+        script.defer = scriptProps.defer ?? true;
+        if (scriptProps.id) script.id = scriptProps.id;
+        if (scriptProps.nonce) script.nonce = scriptProps.nonce;
+        if (scriptProps.integrity) script.integrity = scriptProps.integrity;
+        if (scriptProps.crossOrigin) script.crossOrigin = scriptProps.crossOrigin;
+        if (scriptProps.referrerPolicy) script.referrerPolicy = scriptProps.referrerPolicy;
+        for (const [key, value] of Object.entries(scriptProps.dataset ?? {})) {
+          script.dataset[key] = value;
+        }
+        document.documentElement.appendChild(script);
+        cleanup = () => script.remove();
+      },
+      () => undefined,
+    );
+    return () => {
+      cancelled = true;
+      cleanup?.();
+    };
+  }, [children, loadAfter, scriptProps, src]);
+
+  return null;
+}
diff --git a/packages/airgap-react/airgap-react/tsconfig.json b/packages/airgap-react/airgap-react/tsconfig.json
new file mode 100644
index 00000000..4bfb0879
--- /dev/null
+++ b/packages/airgap-react/airgap-react/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
diff --git a/packages/airgap-react/airgap-react/tsdown.config.ts b/packages/airgap-react/airgap-react/tsdown.config.ts
new file mode 100644
index 00000000..c92e19a4
--- /dev/null
+++ b/packages/airgap-react/airgap-react/tsdown.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsdown';
+
+import sharedConfig from '../../../tsdown.config.base.ts';
+
+export default defineConfig({
+  ...sharedConfig,
+  entry: ['src/index.ts'],
+});
diff --git a/packages/react-airgap/.attw.json b/packages/react-airgap/.attw.json
deleted file mode 100644
index 25cd95e5..00000000
--- a/packages/react-airgap/.attw.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
-  "profile": "node16"
-}
diff --git a/packages/react-airgap/src/index.ts b/packages/react-airgap/src/index.ts
deleted file mode 100644
index 73c29e6d..00000000
--- a/packages/react-airgap/src/index.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-'use client';
-
-export { airgapReady } from './airgap-ready.js';
diff --git a/packages/react-airgap/src/next/index.ts b/packages/react-airgap/src/next/index.ts
deleted file mode 100644
index 4196bd80..00000000
--- a/packages/react-airgap/src/next/index.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-'use client';
-
-export { ConsentContext, ConsentProvider, useConsentManager } from './consent-manager.js';
-export type { ConsentAPI, ConsentProviderProps } from './consent-manager.js';
-export { ConsentBoundary, getMissingConsentPurposesForUrls } from './consent-boundary.js';
-export type {
-  ConsentBoundaryFallbackProps,
-  ConsentBoundaryFallbackStatus,
-  ConsentBoundaryProps,
-} from './consent-boundary.js';
-export { default as TrackingScript } from './tracking-script.js';
-export type { TrackingScriptProps } from './tracking-script.js';
diff --git a/packages/react-airgap/tsdown.config.ts b/packages/react-airgap/tsdown.config.ts
deleted file mode 100644
index 954cce89..00000000
--- a/packages/react-airgap/tsdown.config.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { defineConfig } from 'tsdown';
-
-import sharedConfig from '../../tsdown.config.base.ts';
-
-export default defineConfig({
-  ...sharedConfig,
-  entry: ['src/index.ts', 'src/next/index.ts'],
-});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3b1d6bca..b1517a05 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -105,6 +105,86 @@ importers:
         specifier: 'catalog:'
         version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
 
+  packages/airgap-react/airgap-nextjs:
+    dependencies:
+      '@transcend-io/airgap-react':
+        specifier: workspace:*
+        version: link:../airgap-react
+      '@transcend-io/airgap.js-types':
+        specifier: workspace:*
+        version: link:../../airgap.js-types
+    devDependencies:
+      '@arethetypeswrong/cli':
+        specifier: 'catalog:'
+        version: 0.18.2
+      '@types/node':
+        specifier: 'catalog:'
+        version: 22.19.15
+      '@types/react':
+        specifier: 'catalog:'
+        version: 19.2.15
+      '@types/react-dom':
+        specifier: 'catalog:'
+        version: 19.2.3(@types/react@19.2.15)
+      next:
+        specifier: 'catalog:'
+        version: 16.2.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      publint:
+        specifier: 'catalog:'
+        version: 0.3.18
+      react:
+        specifier: 'catalog:'
+        version: 19.2.6
+      react-dom:
+        specifier: 'catalog:'
+        version: 19.2.6(react@19.2.6)
+      tsdown:
+        specifier: 'catalog:'
+        version: 0.21.2(@arethetypeswrong/core@0.18.2)(publint@0.3.18)(typescript@6.0.3)
+      typescript:
+        specifier: 'catalog:'
+        version: 6.0.3
+      vitest:
+        specifier: 'catalog:'
+        version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
+
+  packages/airgap-react/airgap-react:
+    dependencies:
+      '@transcend-io/airgap.js-types':
+        specifier: workspace:*
+        version: link:../../airgap.js-types
+    devDependencies:
+      '@arethetypeswrong/cli':
+        specifier: 'catalog:'
+        version: 0.18.2
+      '@types/node':
+        specifier: 'catalog:'
+        version: 22.19.15
+      '@types/react':
+        specifier: 'catalog:'
+        version: 19.2.15
+      '@types/react-dom':
+        specifier: 'catalog:'
+        version: 19.2.3(@types/react@19.2.15)
+      publint:
+        specifier: 'catalog:'
+        version: 0.3.18
+      react:
+        specifier: 'catalog:'
+        version: 19.2.6
+      react-dom:
+        specifier: 'catalog:'
+        version: 19.2.6(react@19.2.6)
+      tsdown:
+        specifier: 'catalog:'
+        version: 0.21.2(@arethetypeswrong/core@0.18.2)(publint@0.3.18)(typescript@6.0.3)
+      typescript:
+        specifier: 'catalog:'
+        version: 6.0.3
+      vitest:
+        specifier: 'catalog:'
+        version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
+
   packages/airgap.js-types:
     dependencies:
       '@transcend-io/internationalization':
@@ -748,46 +828,6 @@ importers:
         specifier: 'catalog:'
         version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
 
-  packages/react-airgap:
-    dependencies:
-      '@transcend-io/airgap.js-types':
-        specifier: workspace:*
-        version: link:../airgap.js-types
-    devDependencies:
-      '@arethetypeswrong/cli':
-        specifier: 'catalog:'
-        version: 0.18.2
-      '@types/node':
-        specifier: 'catalog:'
-        version: 22.19.15
-      '@types/react':
-        specifier: 'catalog:'
-        version: 19.2.15
-      '@types/react-dom':
-        specifier: 'catalog:'
-        version: 19.2.3(@types/react@19.2.15)
-      next:
-        specifier: 'catalog:'
-        version: 16.2.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      publint:
-        specifier: 'catalog:'
-        version: 0.3.18
-      react:
-        specifier: 'catalog:'
-        version: 19.2.6
-      react-dom:
-        specifier: 'catalog:'
-        version: 19.2.6(react@19.2.6)
-      tsdown:
-        specifier: 'catalog:'
-        version: 0.21.2(@arethetypeswrong/core@0.18.2)(publint@0.3.18)(typescript@6.0.3)
-      typescript:
-        specifier: 'catalog:'
-        version: 6.0.3
-      vitest:
-        specifier: 'catalog:'
-        version: 4.0.18(@types/node@22.19.15)(tsx@4.21.0)
-
   packages/sdk:
     dependencies:
       '@transcend-io/airgap.js-types':
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 8de26747..5056c667 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,5 +1,6 @@
 packages:
   - packages/*
+  - packages/airgap-react/*
   - packages/mcp/*
 
 catalog:
diff --git a/scripts/package-conventions.test.ts b/scripts/package-conventions.test.ts
index 14249b9c..cbf374e3 100644
--- a/scripts/package-conventions.test.ts
+++ b/scripts/package-conventions.test.ts
@@ -269,11 +269,14 @@ function getWorkspacePackages(): WorkspacePackage[] {
     .map((entry) => `packages/${entry.name}`)
     .filter((directory) => fileExists(`${directory}/package.json`));
 
-  const mcpRoot = join(packagesRoot, 'mcp');
-  const nested = readdirSync(mcpRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => `packages/mcp/${entry.name}`)
-    .filter((directory) => fileExists(`${directory}/package.json`));
+  const nestedRoots = ['airgap-react', 'mcp'];
+  const nested = nestedRoots.flatMap((nestedRoot) => {
+    const packageRoot = join(packagesRoot, nestedRoot);
+    return readdirSync(packageRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => `packages/${nestedRoot}/${entry.name}`)
+      .filter((directory) => fileExists(`${directory}/package.json`));
+  });
 
   return [...topLevel, ...nested]
     .sort((a, b) => a.localeCompare(b))
diff --git a/tsconfig.json b/tsconfig.json
index 39e47e0f..a09e72a8 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -3,6 +3,8 @@
   "files": [],
   "references": [
     { "path": "./packages/airgap.js-types" },
+    { "path": "./packages/airgap-react/airgap-nextjs" },
+    { "path": "./packages/airgap-react/airgap-react" },
     { "path": "./packages/cli" },
     { "path": "./packages/internationalization" },
     { "path": "./packages/mcp/mcp" },
@@ -16,7 +18,6 @@
     { "path": "./packages/mcp/mcp-server-preferences" },
     { "path": "./packages/mcp/mcp-server-workflows" },
     { "path": "./packages/privacy-types" },
-    { "path": "./packages/react-airgap" },
     { "path": "./packages/sdk" },
     { "path": "./packages/type-utils" },
     { "path": "./packages/utils" }

From ca1bb9c0bc9447e9b1b88cf183382311211985a1 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 21:52:36 -0400
Subject: [PATCH 07/17] clarify airgap consent hook naming

---
 packages/airgap-react/airgap-nextjs/README.md              | 7 ++++---
 packages/airgap-react/airgap-nextjs/src/index.ts           | 4 ++--
 ...nsent-manager.test.tsx => use-consent-manager.test.tsx} | 2 +-
 .../next/{consent-manager.tsx => use-consent-manager.tsx}  | 0
 packages/airgap-react/airgap-react/README.md               | 7 ++++---
 .../src/core/{consent-manager.ts => consent-apis.ts}       | 0
 packages/airgap-react/airgap-react/src/index.ts            | 6 +++---
 .../airgap-react/src/react/consent-boundary.test.tsx       | 2 +-
 .../airgap-react/src/react/consent-boundary.tsx            | 2 +-
 .../airgap-react/src/react/tracking-script.tsx             | 2 +-
 ...nsent-manager.test.tsx => use-consent-manager.test.tsx} | 2 +-
 .../react/{consent-manager.tsx => use-consent-manager.tsx} | 2 +-
 12 files changed, 19 insertions(+), 17 deletions(-)
 rename packages/airgap-react/airgap-nextjs/src/next/{consent-manager.test.tsx => use-consent-manager.test.tsx} (99%)
 rename packages/airgap-react/airgap-nextjs/src/next/{consent-manager.tsx => use-consent-manager.tsx} (100%)
 rename packages/airgap-react/airgap-react/src/core/{consent-manager.ts => consent-apis.ts} (100%)
 rename packages/airgap-react/airgap-react/src/react/{consent-manager.test.tsx => use-consent-manager.test.tsx} (99%)
 rename packages/airgap-react/airgap-react/src/react/{consent-manager.tsx => use-consent-manager.tsx} (99%)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index 13720ca2..3796e24f 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -49,10 +49,11 @@ airgap.js is ready. Async loading cannot regulate trackers that initialize
 before Airgap has initialized. See Transcend's guide to
 [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously.md).
 
-## ConsentProvider
+## useConsentManager
 
-`ConsentProvider` loads airgap.js through `next/script` and exposes the loaded
-`airgap` and `transcend` APIs through `useConsentManager()`.
+`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. Wrap
+your app in `ConsentProvider` once so it can load airgap.js through
+`next/script` and populate the hook.
 
 ```tsx
 import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-nextjs';
diff --git a/packages/airgap-react/airgap-nextjs/src/index.ts b/packages/airgap-react/airgap-nextjs/src/index.ts
index 8dc1a156..8fbc6b83 100644
--- a/packages/airgap-react/airgap-nextjs/src/index.ts
+++ b/packages/airgap-react/airgap-nextjs/src/index.ts
@@ -6,7 +6,7 @@ export type {
   ConsentBoundaryFallbackProps,
   ConsentBoundaryProps,
 } from '@transcend-io/airgap-react';
-export { ConsentProvider } from './next/consent-manager.js';
-export type { ConsentProviderProps } from './next/consent-manager.js';
+export { ConsentProvider } from './next/use-consent-manager.js';
+export type { ConsentProviderProps } from './next/use-consent-manager.js';
 export { TrackingScript } from './next/tracking-script.js';
 export type { TrackingScriptProps } from './next/tracking-script.js';
diff --git a/packages/airgap-react/airgap-nextjs/src/next/consent-manager.test.tsx b/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.test.tsx
similarity index 99%
rename from packages/airgap-react/airgap-nextjs/src/next/consent-manager.test.tsx
rename to packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.test.tsx
index 85d5cccb..67a1e97a 100644
--- a/packages/airgap-react/airgap-nextjs/src/next/consent-manager.test.tsx
+++ b/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.test.tsx
@@ -1,7 +1,7 @@
 import type { ReactElement } from 'react';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
-import { ConsentProvider } from './consent-manager.js';
+import { ConsentProvider } from './use-consent-manager.js';
 
 const reactMocks = vi.hoisted(() => ({
   useEffect: vi.fn(),
diff --git a/packages/airgap-react/airgap-nextjs/src/next/consent-manager.tsx b/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.tsx
similarity index 100%
rename from packages/airgap-react/airgap-nextjs/src/next/consent-manager.tsx
rename to packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.tsx
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index a99bd4d7..611637b2 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -61,10 +61,11 @@ airgap.js is ready. Async loading cannot regulate trackers that initialize
 before Airgap has initialized. See Transcend's guide to
 [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously.md).
 
-## ConsentProvider
+## useConsentManager
 
-`ConsentProvider` injects airgap.js with `document.createElement('script')` and
-exposes the loaded `airgap` and `transcend` APIs through `useConsentManager()`.
+`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. Wrap
+your app in `ConsentProvider` once so it can inject airgap.js with
+`document.createElement('script')` and populate the hook.
 
 ```tsx
 import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-react';
diff --git a/packages/airgap-react/airgap-react/src/core/consent-manager.ts b/packages/airgap-react/airgap-react/src/core/consent-apis.ts
similarity index 100%
rename from packages/airgap-react/airgap-react/src/core/consent-manager.ts
rename to packages/airgap-react/airgap-react/src/core/consent-apis.ts
diff --git a/packages/airgap-react/airgap-react/src/index.ts b/packages/airgap-react/airgap-react/src/index.ts
index 164a02a6..cf31f633 100644
--- a/packages/airgap-react/airgap-react/src/index.ts
+++ b/packages/airgap-react/airgap-react/src/index.ts
@@ -1,13 +1,13 @@
 'use client';
 
 export { airgapReady } from './core/airgap-ready.js';
-export type { ConsentAPI } from './core/consent-manager.js';
+export type { ConsentAPI } from './core/consent-apis.js';
 export { ConsentBoundary } from './react/consent-boundary.js';
 export type {
   ConsentBoundaryFallbackProps,
   ConsentBoundaryProps,
 } from './react/consent-boundary.js';
-export { ConsentContext, ConsentProvider, useConsentManager } from './react/consent-manager.js';
-export type { ConsentProviderProps } from './react/consent-manager.js';
+export { ConsentContext, ConsentProvider, useConsentManager } from './react/use-consent-manager.js';
+export type { ConsentProviderProps } from './react/use-consent-manager.js';
 export { TrackingScript } from './react/tracking-script.js';
 export type { TrackingScriptProps } from './react/tracking-script.js';
diff --git a/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx b/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
index 1c5de5eb..dbb540a1 100644
--- a/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
+++ b/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
@@ -21,7 +21,7 @@ vi.mock('react', async (importOriginal) => {
   };
 });
 
-vi.mock('./consent-manager.js', () => ({
+vi.mock('./use-consent-manager.js', () => ({
   useConsentManager: mocks.useConsentManager,
 }));
 
diff --git a/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx b/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
index 1131d871..315aba61 100644
--- a/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
+++ b/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
@@ -10,7 +10,7 @@ import {
 } from 'react';
 
 import { getMissingConsentPurposesForUrls } from '../core/consent-boundary.js';
-import { useConsentManager } from './consent-manager.js';
+import { useConsentManager } from './use-consent-manager.js';
 
 type ConsentBoundaryState =
   | { status: 'pending' }
diff --git a/packages/airgap-react/airgap-react/src/react/tracking-script.tsx b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
index e4d9785c..ca98042e 100644
--- a/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
+++ b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
@@ -2,7 +2,7 @@
 
 import { useEffect } from 'react';
 
-import type { ReactAirgapScriptProps } from './consent-manager.js';
+import type { ReactAirgapScriptProps } from './use-consent-manager.js';
 
 export interface TrackingScriptProps extends ReactAirgapScriptProps {
   /**
diff --git a/packages/airgap-react/airgap-react/src/react/consent-manager.test.tsx b/packages/airgap-react/airgap-react/src/react/use-consent-manager.test.tsx
similarity index 99%
rename from packages/airgap-react/airgap-react/src/react/consent-manager.test.tsx
rename to packages/airgap-react/airgap-react/src/react/use-consent-manager.test.tsx
index 90f283f1..f92ad090 100644
--- a/packages/airgap-react/airgap-react/src/react/consent-manager.test.tsx
+++ b/packages/airgap-react/airgap-react/src/react/use-consent-manager.test.tsx
@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
-import { ConsentProvider } from './consent-manager.js';
+import { ConsentProvider } from './use-consent-manager.js';
 
 const reactMocks = vi.hoisted(() => ({
   useEffect: vi.fn(),
diff --git a/packages/airgap-react/airgap-react/src/react/consent-manager.tsx b/packages/airgap-react/airgap-react/src/react/use-consent-manager.tsx
similarity index 99%
rename from packages/airgap-react/airgap-react/src/react/consent-manager.tsx
rename to packages/airgap-react/airgap-react/src/react/use-consent-manager.tsx
index 03572a72..05cf9fbe 100644
--- a/packages/airgap-react/airgap-react/src/react/consent-manager.tsx
+++ b/packages/airgap-react/airgap-react/src/react/use-consent-manager.tsx
@@ -11,7 +11,7 @@ import {
   useState,
 } from 'react';
 
-import { type ConsentAPI, subscribeConsentApis } from '../core/consent-manager.js';
+import { type ConsentAPI, subscribeConsentApis } from '../core/consent-apis.js';
 
 export interface ConsentProviderProps {
   /** Child tree that can consume the consent APIs. */

From 8bd2fdee0b2f4889ed6e6ae10c6f11ef4e66aa46 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 22:04:19 -0400
Subject: [PATCH 08/17] make consent hook provider optional

---
 packages/airgap-react/airgap-nextjs/README.md |  32 ++-
 .../src/next/use-consent-manager.test.tsx     | 184 ++----------------
 .../src/next/use-consent-manager.tsx          |  89 +--------
 packages/airgap-react/airgap-react/README.md  |  32 ++-
 .../airgap-react/src/core/airgap-ready.ts     |  39 +---
 .../airgap-react/src/core/consent-apis.ts     |  75 +++----
 .../airgap-react/src/core/ready-api.ts        |  68 +++++++
 .../airgap-react/airgap-react/src/index.ts    |   2 +-
 .../airgap-react/src/react/script-element.ts  |  57 ++++++
 .../src/react/tracking-script.tsx             |  22 +--
 .../src/react/use-consent-manager.test.tsx    | 155 ++++++++++++++-
 .../src/react/use-consent-manager.tsx         |  78 +++-----
 12 files changed, 432 insertions(+), 401 deletions(-)
 create mode 100644 packages/airgap-react/airgap-react/src/core/ready-api.ts
 create mode 100644 packages/airgap-react/airgap-react/src/react/script-element.ts

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index 3796e24f..f45160f4 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -51,9 +51,12 @@ before Airgap has initialized. See Transcend's guide to
 
 ## useConsentManager
 
-`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. Wrap
-your app in `ConsentProvider` once so it can load airgap.js through
-`next/script` and populate the hook.
+`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. If your
+app already loads airgap.js, the hook observes the existing `self.airgap` and
+`self.transcend` globals without a provider.
+
+Use `ConsentProvider` when you want this package to load airgap.js through
+`next/script`:
 
 ```tsx
 import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-nextjs';
@@ -84,10 +87,31 @@ export function PrivacyChoicesButton() {
 }
 ```
 
+If Airgap is loaded elsewhere, call the hook directly:
+
+```tsx
+import { useConsentManager } from '@transcend-io/airgap-nextjs';
+
+export function PrivacyChoicesButton() {
+  const { transcend } = useConsentManager();
+
+  return (
+    <button
+      type="button"
+      disabled={!transcend}
+      onClick={() => void transcend?.showConsentManager()}
+    >
+      Privacy choices
+    </button>
+  );
+}
+```
+
 ## ConsentBoundary
 
 `ConsentBoundary` is re-exported from `@transcend-io/airgap-react` so it shares
-the same behavior in both packages.
+the same behavior in both packages. It uses `useConsentManager()`, so it works
+with `ConsentProvider` or with Airgap globals loaded separately.
 
 ```tsx
 import { ConsentBoundary, type ConsentBoundaryFallbackProps } from '@transcend-io/airgap-nextjs';
diff --git a/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.test.tsx b/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.test.tsx
index 67a1e97a..08fa11a3 100644
--- a/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.test.tsx
+++ b/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.test.tsx
@@ -1,185 +1,17 @@
+import { ConsentProvider as ReactConsentProvider } from '@transcend-io/airgap-react';
 import type { ReactElement } from 'react';
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 
 import { ConsentProvider } from './use-consent-manager.js';
 
-const reactMocks = vi.hoisted(() => ({
-  useEffect: vi.fn(),
-  useState: vi.fn(),
-}));
-
 vi.mock('next/script', () => ({
   default: function MockScript(): null {
     return null;
   },
 }));
 
-vi.mock('react', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('react')>();
-
-  return {
-    ...actual,
-    useEffect: reactMocks.useEffect,
-    useState: reactMocks.useState,
-  };
-});
-
-const originalSelfDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'self');
-
-function setSelf(value: unknown): void {
-  Object.defineProperty(globalThis, 'self', {
-    configurable: true,
-    value,
-  });
-}
-
-function useUndefinedConsentState(): {
-  /** Airgap setState mock. */
-  setAirgap: ReturnType<typeof vi.fn>;
-  /** Transcend setState mock. */
-  setTranscend: ReturnType<typeof vi.fn>;
-} {
-  const setAirgap = vi.fn();
-  const setTranscend = vi.fn();
-
-  reactMocks.useState
-    .mockReturnValueOnce([undefined, setAirgap])
-    .mockReturnValueOnce([undefined, setTranscend]);
-
-  return { setAirgap, setTranscend };
-}
-
 describe('ConsentProvider', () => {
-  beforeEach(() => {
-    reactMocks.useEffect.mockReset();
-    reactMocks.useState.mockReset();
-  });
-
-  afterEach(() => {
-    if (originalSelfDescriptor) {
-      Object.defineProperty(globalThis, 'self', originalSelfDescriptor);
-    } else {
-      Reflect.deleteProperty(globalThis, 'self');
-    }
-  });
-
-  test('stubs airgap and transcend ready queues', () => {
-    setSelf({});
-    const { setAirgap, setTranscend } = useUndefinedConsentState();
-    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
-
-    ConsentProvider({
-      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
-      children: 'children',
-    });
-    const consentGlobals = self as typeof self & {
-      /** airgap.js preload stub. */
-      airgap?: { readyQueue?: Array<(api: unknown) => void> };
-      /** Transcend preload stub. */
-      transcend?: { readyQueue?: Array<(api: unknown) => void> };
-    };
-
-    expect(consentGlobals.airgap?.readyQueue).toHaveLength(1);
-    expect(consentGlobals.transcend?.readyQueue).toHaveLength(1);
-
-    const readyAirgap = {};
-    const readyTranscend = {};
-    consentGlobals.airgap?.readyQueue?.[0]?.(readyAirgap);
-    consentGlobals.transcend?.readyQueue?.[0]?.(readyTranscend);
-
-    expect(setAirgap).toHaveBeenCalledWith(readyAirgap);
-    expect(setTranscend).toHaveBeenCalledWith(readyTranscend);
-  });
-
-  test('preserves existing ready queues', () => {
-    const existingAirgapReady = vi.fn();
-    const existingTranscendReady = vi.fn();
-    setSelf({
-      airgap: { readyQueue: [existingAirgapReady] },
-      transcend: { readyQueue: [existingTranscendReady] },
-    });
-    useUndefinedConsentState();
-    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
-
-    ConsentProvider({
-      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
-      children: 'children',
-    });
-    const consentGlobals = self as typeof self & {
-      /** airgap.js preload stub. */
-      airgap?: { readyQueue?: unknown[] };
-      /** Transcend preload stub. */
-      transcend?: { readyQueue?: unknown[] };
-    };
-
-    expect(consentGlobals.airgap?.readyQueue?.[0]).toBe(existingAirgapReady);
-    expect(consentGlobals.airgap?.readyQueue).toHaveLength(2);
-    expect(consentGlobals.transcend?.readyQueue?.[0]).toBe(existingTranscendReady);
-    expect(consentGlobals.transcend?.readyQueue).toHaveLength(2);
-  });
-
-  test('does not set state after unmount', () => {
-    setSelf({});
-    const { setAirgap, setTranscend } = useUndefinedConsentState();
-    const cleanupRef: {
-      /** Effect cleanup callback. */
-      current?: () => void;
-    } = {};
-    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => {
-      const cleanup = effect();
-      if (typeof cleanup === 'function') cleanupRef.current = cleanup;
-    });
-
-    ConsentProvider({
-      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
-      children: 'children',
-    });
-    const consentGlobals = self as typeof self & {
-      /** airgap.js preload stub. */
-      airgap?: { readyQueue?: Array<(api: unknown) => void> };
-      /** Transcend preload stub. */
-      transcend?: { readyQueue?: Array<(api: unknown) => void> };
-    };
-
-    cleanupRef.current?.();
-    consentGlobals.airgap?.readyQueue?.[0]?.({});
-    consentGlobals.transcend?.readyQueue?.[0]?.({});
-
-    expect(setAirgap).not.toHaveBeenCalled();
-    expect(setTranscend).not.toHaveBeenCalled();
-  });
-
-  test('sets state immediately when APIs are already initialized', () => {
-    const readyAirgap = {
-      addEventListener() {
-        // Initialized APIs are EventTargets.
-      },
-    };
-    const readyTranscend = {
-      addEventListener() {
-        // Initialized APIs are EventTargets.
-      },
-    };
-    setSelf({
-      airgap: readyAirgap,
-      transcend: readyTranscend,
-    });
-    const { setAirgap, setTranscend } = useUndefinedConsentState();
-    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
-
-    ConsentProvider({
-      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
-      children: 'children',
-    });
-
-    expect(setAirgap).toHaveBeenCalledWith(readyAirgap);
-    expect(setTranscend).toHaveBeenCalledWith(readyTranscend);
-  });
-
   test('renders Script with the provided airgap source', () => {
-    useUndefinedConsentState();
-    reactMocks.useEffect.mockImplementation(() => undefined);
-
     const result = ConsentProvider({
       airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
       children: 'children',
@@ -191,4 +23,16 @@ describe('ConsentProvider', () => {
     expect(scriptElement?.props.id).toBe('airgap');
     expect(scriptElement?.props.strategy).toBe('afterInteractive');
   });
+
+  test('wraps children with the React consent provider', () => {
+    const result = ConsentProvider({
+      airgapSrc: 'https://transcend-cdn.com/cm/example/airgap.js',
+      children: 'children',
+    }) as ReactElement<{ children: ReactElement<Record<string, unknown>>[] }>;
+    const [, reactProviderElement] = result.props.children;
+
+    expect(reactProviderElement?.type).toBe(ReactConsentProvider);
+    expect(reactProviderElement?.props.children).toBe('children');
+    expect(reactProviderElement?.props.airgapSrc).toBeUndefined();
+  });
 });
diff --git a/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.tsx b/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.tsx
index 6b4f0f3e..f559466f 100644
--- a/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.tsx
+++ b/packages/airgap-react/airgap-nextjs/src/next/use-consent-manager.tsx
@@ -1,60 +1,19 @@
 'use client';
 
-import { ConsentContext, type ConsentAPI } from '@transcend-io/airgap-react';
-import type { AirgapAPI, TranscendAPI } from '@transcend-io/airgap.js-types';
+import {
+  ConsentProvider as ReactConsentProvider,
+  type ConsentProviderProps as ReactConsentProviderProps,
+} from '@transcend-io/airgap-react';
 import Script, { type ScriptProps } from 'next/script';
-import { type ReactElement, type ReactNode, useEffect, useState } from 'react';
+import { type ReactElement } from 'react';
 
-type PreInitAirgapAPI = Pick<AirgapAPI, 'ready' | 'readyQueue'>;
-type PreInitTranscendAPI = Pick<TranscendAPI, 'ready' | 'readyQueue'>;
-
-type ReadyApi<TApi> = {
-  /** Queue of callbacks to dispatch once the API is ready. */
-  readyQueue?: Array<(api: TApi) => void>;
-  /** Subscribe to the API ready event. */
-  ready(callback: (api: TApi) => void): void;
-};
-
-interface ConsentGlobals {
-  /** airgap.js interface or preload stub. */
-  airgap?: AirgapAPI | Partial<PreInitAirgapAPI>;
-  /** Transcend consent manager interface or preload stub. */
-  transcend?: TranscendAPI | Partial<PreInitTranscendAPI>;
-}
-
-export interface ConsentProviderProps {
-  /** Child tree that can consume the consent APIs. */
-  children: ReactNode;
+export interface ConsentProviderProps extends Pick<ReactConsentProviderProps, 'children'> {
   /** airgap.js script URL from Transcend's developer settings. */
   airgapSrc: string;
   /** Additional props forwarded to `next/script`. */
   scriptProps?: Omit<ScriptProps, 'children' | 'src'>;
 }
 
-function ensureReadyApi<TApi>(existing: Partial<ReadyApi<TApi>> | undefined): ReadyApi<TApi> {
-  if (existing?.ready) {
-    return existing as ReadyApi<TApi>;
-  }
-
-  const readyQueue = existing?.readyQueue ?? [];
-
-  return {
-    ...existing,
-    readyQueue,
-    ready(callback) {
-      readyQueue.push(callback);
-    },
-  };
-}
-
-function isInitializedApi<TApi extends EventTarget>(
-  api: TApi | Partial<ReadyApi<TApi>> | undefined,
-): api is TApi {
-  return (
-    typeof (api as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
-  );
-}
-
 /**
  * Provides loaded `airgap` and `transcend` APIs to React children while loading
  * airgap.js through `next/script`.
@@ -64,44 +23,10 @@ export function ConsentProvider({
   children,
   scriptProps,
 }: ConsentProviderProps): ReactElement {
-  const [airgap, setAirgap] = useState<ConsentAPI['airgap']>();
-  const [transcend, setTranscend] = useState<ConsentAPI['transcend']>();
-
-  useEffect(() => {
-    if (typeof self === 'undefined') return;
-
-    let cancelled = false;
-    const consentGlobals = self as typeof self & ConsentGlobals;
-
-    if (isInitializedApi<AirgapAPI>(consentGlobals.airgap)) {
-      setAirgap(consentGlobals.airgap);
-    } else {
-      const airgapReadyApi = ensureReadyApi<AirgapAPI>(consentGlobals.airgap);
-      consentGlobals.airgap = airgapReadyApi;
-      airgapReadyApi.ready((readyAirgap) => {
-        if (!cancelled) setAirgap(readyAirgap);
-      });
-    }
-
-    if (isInitializedApi<TranscendAPI>(consentGlobals.transcend)) {
-      setTranscend(consentGlobals.transcend);
-    } else {
-      const transcendReady = ensureReadyApi<TranscendAPI>(consentGlobals.transcend);
-      consentGlobals.transcend = transcendReady;
-      transcendReady.ready((readyTranscend) => {
-        if (!cancelled) setTranscend(readyTranscend);
-      });
-    }
-
-    return () => {
-      cancelled = true;
-    };
-  }, []);
-
   return (
     <>
       <Script src={airgapSrc} {...scriptProps} />
-      <ConsentContext.Provider value={{ airgap, transcend }}>{children}</ConsentContext.Provider>
+      <ReactConsentProvider>{children}</ReactConsentProvider>
     </>
   );
 }
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index 611637b2..e05a9131 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -63,9 +63,11 @@ before Airgap has initialized. See Transcend's guide to
 
 ## useConsentManager
 
-`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. Wrap
-your app in `ConsentProvider` once so it can inject airgap.js with
-`document.createElement('script')` and populate the hook.
+`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. If your
+app already loads airgap.js, the hook observes the existing `self.airgap` and
+`self.transcend` globals without a provider.
+
+Use `ConsentProvider` when you want this package to inject airgap.js for you:
 
 ```tsx
 import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-react';
@@ -93,11 +95,33 @@ export function PrivacyChoicesButton() {
 }
 ```
 
+If Airgap is loaded elsewhere, call the hook directly:
+
+```tsx
+import { useConsentManager } from '@transcend-io/airgap-react';
+
+export function PrivacyChoicesButton() {
+  const { transcend } = useConsentManager();
+
+  return (
+    <button
+      type="button"
+      disabled={!transcend}
+      onClick={() => void transcend?.showConsentManager()}
+    >
+      Privacy choices
+    </button>
+  );
+}
+```
+
 ## ConsentBoundary
 
 `ConsentBoundary` checks the URLs needed by a subtree before mounting its
 children. While the check is pending, or when consent is missing, only the
-fallback renders so gated children cannot start loading network resources.
+fallback renders so gated children cannot start loading network resources. It
+uses `useConsentManager()`, so it works with `ConsentProvider` or with Airgap
+globals loaded separately.
 
 ```tsx
 import { ConsentBoundary, type ConsentBoundaryFallbackProps } from '@transcend-io/airgap-react';
diff --git a/packages/airgap-react/airgap-react/src/core/airgap-ready.ts b/packages/airgap-react/airgap-react/src/core/airgap-ready.ts
index 7086815c..d772a2a3 100644
--- a/packages/airgap-react/airgap-react/src/core/airgap-ready.ts
+++ b/packages/airgap-react/airgap-react/src/core/airgap-ready.ts
@@ -1,22 +1,14 @@
 import type { AirgapAPI } from '@transcend-io/airgap.js-types';
 
-type PreInitAirgapAPI = Pick<AirgapAPI, 'ready' | 'readyQueue'>;
+import { type ReadyApi, observeReadyApi } from './ready-api.js';
 
 interface GlobalWithAirgap {
   /** Transcend airgap API or preload stub. */
-  airgap?: AirgapAPI | Partial<PreInitAirgapAPI>;
+  airgap?: AirgapAPI | Partial<ReadyApi<AirgapAPI>>;
 }
 
 let airgapReadyPromise: Promise<AirgapAPI> | undefined;
 
-function isInitializedAirgapApi(
-  airgap: AirgapAPI | Partial<PreInitAirgapAPI> | undefined,
-): airgap is AirgapAPI {
-  return (
-    typeof (airgap as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
-  );
-}
-
 /**
  * Resolves when `self.airgap.ready(...)` fires.
  *
@@ -28,26 +20,13 @@ export function airgapReady(): Promise<AirgapAPI> {
     if (typeof self === 'undefined') return;
 
     const airgapGlobal = self as typeof self & GlobalWithAirgap;
-    const existingAirgap = airgapGlobal.airgap;
-
-    if (isInitializedAirgapApi(existingAirgap)) {
-      resolve(existingAirgap);
-      return;
-    }
-
-    if (!existingAirgap?.ready) {
-      const readyQueue = existingAirgap?.readyQueue ?? [];
-      airgapGlobal.airgap = {
-        ...existingAirgap,
-        readyQueue,
-        ready(callback) {
-          readyQueue.push(callback);
-        },
-      };
-    }
-
-    const airgap = airgapGlobal.airgap as PreInitAirgapAPI;
-    airgap.ready((readyAirgap) => resolve(readyAirgap));
+    observeReadyApi<AirgapAPI>({
+      api: airgapGlobal.airgap,
+      onReady: resolve,
+      setApi(airgap) {
+        airgapGlobal.airgap = airgap;
+      },
+    });
   });
 
   return airgapReadyPromise;
diff --git a/packages/airgap-react/airgap-react/src/core/consent-apis.ts b/packages/airgap-react/airgap-react/src/core/consent-apis.ts
index e6ce52e3..63fc0504 100644
--- a/packages/airgap-react/airgap-react/src/core/consent-apis.ts
+++ b/packages/airgap-react/airgap-react/src/core/consent-apis.ts
@@ -1,13 +1,8 @@
 import type { AirgapAPI, PreInitTranscendAPI, TranscendAPI } from '@transcend-io/airgap.js-types';
 
-type PreInitAirgapAPI = Pick<AirgapAPI, 'ready' | 'readyQueue'>;
+import { type ReadyApi, isInitializedReadyApi, observeReadyApi } from './ready-api.js';
 
-type ReadyApi<TApi> = {
-  /** Queue of callbacks to dispatch once the API is ready. */
-  readyQueue?: Array<(api: TApi) => void>;
-  /** Subscribe to the API ready event. */
-  ready(callback: (api: TApi) => void): void;
-};
+type PreInitAirgapAPI = ReadyApi<AirgapAPI>;
 
 interface ConsentGlobals {
   /** airgap.js interface or preload stub. */
@@ -31,30 +26,21 @@ export interface ConsentApiSubscriptionHandlers {
   onTranscend(transcend: TranscendAPI): void;
 }
 
-function ensureReadyApi<TApi>(existing: Partial<ReadyApi<TApi>> | undefined): ReadyApi<TApi> {
-  if (existing?.ready) {
-    return existing as ReadyApi<TApi>;
-  }
+export function getInitializedConsentApis(): ConsentAPI {
+  if (typeof self === 'undefined') return {};
 
-  const readyQueue = existing?.readyQueue ?? [];
+  const consentGlobals = self as typeof self & ConsentGlobals;
 
   return {
-    ...existing,
-    readyQueue,
-    ready(callback) {
-      readyQueue.push(callback);
-    },
+    airgap: isInitializedReadyApi<AirgapAPI>(consentGlobals.airgap)
+      ? consentGlobals.airgap
+      : undefined,
+    transcend: isInitializedReadyApi<TranscendAPI>(consentGlobals.transcend)
+      ? consentGlobals.transcend
+      : undefined,
   };
 }
 
-function isInitializedApi<TApi extends EventTarget>(
-  api: TApi | Partial<ReadyApi<TApi>> | undefined,
-): api is TApi {
-  return (
-    typeof (api as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
-  );
-}
-
 /**
  * Subscribe to the global Airgap and Transcend ready APIs, creating documented
  * ready-queue stubs when airgap.js has not initialized yet.
@@ -68,27 +54,28 @@ export function subscribeConsentApis({
   let cancelled = false;
   const consentGlobals = self as typeof self & ConsentGlobals;
 
-  if (isInitializedApi<AirgapAPI>(consentGlobals.airgap)) {
-    onAirgap(consentGlobals.airgap);
-  } else {
-    const airgapReady = ensureReadyApi<AirgapAPI>(consentGlobals.airgap);
-    consentGlobals.airgap = airgapReady;
-    airgapReady.ready((readyAirgap) => {
-      if (!cancelled) onAirgap(readyAirgap);
-    });
-  }
-
-  if (isInitializedApi<TranscendAPI>(consentGlobals.transcend)) {
-    onTranscend(consentGlobals.transcend);
-  } else {
-    const transcendReady = ensureReadyApi<TranscendAPI>(consentGlobals.transcend);
-    consentGlobals.transcend = transcendReady;
-    transcendReady.ready((readyTranscend) => {
-      if (!cancelled) onTranscend(readyTranscend);
-    });
-  }
+  const cleanupAirgap = observeReadyApi({
+    api: consentGlobals.airgap,
+    onReady(airgap) {
+      if (!cancelled) onAirgap(airgap);
+    },
+    setApi(airgap) {
+      consentGlobals.airgap = airgap;
+    },
+  });
+  const cleanupTranscend = observeReadyApi({
+    api: consentGlobals.transcend,
+    onReady(transcend) {
+      if (!cancelled) onTranscend(transcend);
+    },
+    setApi(transcend) {
+      consentGlobals.transcend = transcend;
+    },
+  });
 
   return () => {
     cancelled = true;
+    cleanupAirgap();
+    cleanupTranscend();
   };
 }
diff --git a/packages/airgap-react/airgap-react/src/core/ready-api.ts b/packages/airgap-react/airgap-react/src/core/ready-api.ts
new file mode 100644
index 00000000..53bd5e26
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/core/ready-api.ts
@@ -0,0 +1,68 @@
+export type ReadyApi<TApi> = {
+  /** Queue of callbacks to dispatch once the API is ready. */
+  readyQueue?: Array<(api: TApi) => void>;
+  /** Subscribe to the API ready event. */
+  ready(callback: (api: TApi) => void): void;
+};
+
+export interface ReadyApiObserverOptions<TApi extends EventTarget> {
+  /** Current global API or pre-init stub. */
+  api: TApi | Partial<ReadyApi<TApi>> | undefined;
+  /** Called when a pre-init stub should be assigned back to the global. */
+  setApi(api: ReadyApi<TApi>): void;
+  /** Called when the API is initialized. */
+  onReady(api: TApi): void;
+}
+
+export function isInitializedReadyApi<TApi extends EventTarget>(
+  api: TApi | Partial<ReadyApi<TApi>> | undefined,
+): api is TApi {
+  return (
+    typeof (api as { addEventListener?: unknown } | undefined)?.addEventListener === 'function'
+  );
+}
+
+function ensureReadyApi<TApi>(existing: Partial<ReadyApi<TApi>> | undefined): ReadyApi<TApi> {
+  if (existing?.ready) {
+    return existing as ReadyApi<TApi>;
+  }
+
+  const readyQueue = existing?.readyQueue ?? [];
+
+  return {
+    ...existing,
+    readyQueue,
+    ready(callback) {
+      readyQueue.push(callback);
+    },
+  };
+}
+
+/**
+ * Observe an Airgap-style global ready API, creating the documented pre-init
+ * ready queue stub if the API has not loaded yet.
+ */
+export function observeReadyApi<TApi extends EventTarget>({
+  api,
+  onReady,
+  setApi,
+}: ReadyApiObserverOptions<TApi>): () => void {
+  let cancelled = false;
+
+  if (isInitializedReadyApi<TApi>(api)) {
+    onReady(api);
+    return () => {
+      cancelled = true;
+    };
+  }
+
+  const readyApi = ensureReadyApi<TApi>(api);
+  setApi(readyApi);
+  readyApi.ready((readyApiValue) => {
+    if (!cancelled) onReady(readyApiValue);
+  });
+
+  return () => {
+    cancelled = true;
+  };
+}
diff --git a/packages/airgap-react/airgap-react/src/index.ts b/packages/airgap-react/airgap-react/src/index.ts
index cf31f633..e543fd99 100644
--- a/packages/airgap-react/airgap-react/src/index.ts
+++ b/packages/airgap-react/airgap-react/src/index.ts
@@ -7,7 +7,7 @@ export type {
   ConsentBoundaryFallbackProps,
   ConsentBoundaryProps,
 } from './react/consent-boundary.js';
-export { ConsentContext, ConsentProvider, useConsentManager } from './react/use-consent-manager.js';
+export { ConsentProvider, useConsentManager } from './react/use-consent-manager.js';
 export type { ConsentProviderProps } from './react/use-consent-manager.js';
 export { TrackingScript } from './react/tracking-script.js';
 export type { TrackingScriptProps } from './react/tracking-script.js';
diff --git a/packages/airgap-react/airgap-react/src/react/script-element.ts b/packages/airgap-react/airgap-react/src/react/script-element.ts
new file mode 100644
index 00000000..c683338a
--- /dev/null
+++ b/packages/airgap-react/airgap-react/src/react/script-element.ts
@@ -0,0 +1,57 @@
+export interface ReactAirgapScriptProps {
+  /** Script element ID. */
+  id?: string;
+  /** Whether to load the script asynchronously. Defaults to true. */
+  async?: boolean;
+  /** Whether to defer script execution. Defaults to true. */
+  defer?: boolean;
+  /** Script nonce for CSP. */
+  nonce?: string;
+  /** Subresource integrity metadata. */
+  integrity?: string;
+  /** CORS setting for the script request. */
+  crossOrigin?: HTMLScriptElement['crossOrigin'];
+  /** Referrer policy for the script request. */
+  referrerPolicy?: HTMLScriptElement['referrerPolicy'];
+  /** Additional data attributes to set on the script element. */
+  dataset?: Record<string, string>;
+}
+
+export interface AppendScriptElementOptions {
+  /** External script URL. */
+  src?: string;
+  /** Inline script body. */
+  text?: string;
+  /** Additional script attributes. */
+  scriptProps?: ReactAirgapScriptProps;
+}
+
+export function appendScriptElement({
+  scriptProps = {},
+  src,
+  text,
+}: AppendScriptElementOptions): () => void {
+  if (typeof document === 'undefined' || (!src && !text)) return () => undefined;
+
+  const script = document.createElement('script');
+  if (src) script.src = src;
+  if (text) script.text = text;
+  script.async = scriptProps.async ?? true;
+  script.defer = scriptProps.defer ?? true;
+
+  if (scriptProps.id) script.id = scriptProps.id;
+  if (scriptProps.nonce) script.nonce = scriptProps.nonce;
+  if (scriptProps.integrity) script.integrity = scriptProps.integrity;
+  if (scriptProps.crossOrigin) script.crossOrigin = scriptProps.crossOrigin;
+  if (scriptProps.referrerPolicy) script.referrerPolicy = scriptProps.referrerPolicy;
+
+  for (const [key, value] of Object.entries(scriptProps.dataset ?? {})) {
+    script.dataset[key] = value;
+  }
+
+  document.documentElement.appendChild(script);
+
+  return () => {
+    script.remove();
+  };
+}
diff --git a/packages/airgap-react/airgap-react/src/react/tracking-script.tsx b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
index ca98042e..6f188d84 100644
--- a/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
+++ b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
@@ -2,7 +2,7 @@
 
 import { useEffect } from 'react';
 
-import type { ReactAirgapScriptProps } from './use-consent-manager.js';
+import { type ReactAirgapScriptProps, appendScriptElement } from './script-element.js';
 
 export interface TrackingScriptProps extends ReactAirgapScriptProps {
   /**
@@ -52,21 +52,11 @@ export function TrackingScript({
       () => {
         if (cancelled || typeof document === 'undefined') return;
 
-        const script = document.createElement('script');
-        if (src) script.src = src;
-        if (children) script.text = children;
-        script.async = scriptProps.async ?? true;
-        script.defer = scriptProps.defer ?? true;
-        if (scriptProps.id) script.id = scriptProps.id;
-        if (scriptProps.nonce) script.nonce = scriptProps.nonce;
-        if (scriptProps.integrity) script.integrity = scriptProps.integrity;
-        if (scriptProps.crossOrigin) script.crossOrigin = scriptProps.crossOrigin;
-        if (scriptProps.referrerPolicy) script.referrerPolicy = scriptProps.referrerPolicy;
-        for (const [key, value] of Object.entries(scriptProps.dataset ?? {})) {
-          script.dataset[key] = value;
-        }
-        document.documentElement.appendChild(script);
-        cleanup = () => script.remove();
+        cleanup = appendScriptElement({
+          scriptProps,
+          src,
+          text: children,
+        });
       },
       () => undefined,
     );
diff --git a/packages/airgap-react/airgap-react/src/react/use-consent-manager.test.tsx b/packages/airgap-react/airgap-react/src/react/use-consent-manager.test.tsx
index f92ad090..e4f0da64 100644
--- a/packages/airgap-react/airgap-react/src/react/use-consent-manager.test.tsx
+++ b/packages/airgap-react/airgap-react/src/react/use-consent-manager.test.tsx
@@ -1,9 +1,10 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
-import { ConsentProvider } from './use-consent-manager.js';
+import { ConsentProvider, useConsentManager } from './use-consent-manager.js';
 
 const reactMocks = vi.hoisted(() => ({
   useEffect: vi.fn(),
+  useContext: vi.fn(),
   useState: vi.fn(),
 }));
 
@@ -13,6 +14,7 @@ vi.mock('react', async (importOriginal) => {
   return {
     ...actual,
     useEffect: reactMocks.useEffect,
+    useContext: reactMocks.useContext,
     useState: reactMocks.useState,
   };
 });
@@ -53,6 +55,7 @@ function useUndefinedConsentState(): {
 describe('ConsentProvider', () => {
   beforeEach(() => {
     reactMocks.useEffect.mockReset();
+    reactMocks.useContext.mockReset();
     reactMocks.useState.mockReset();
   });
 
@@ -215,4 +218,154 @@ describe('ConsentProvider', () => {
     expect(scriptElement?.async).toBe(true);
     expect(scriptElement?.defer).toBe(true);
   });
+
+  test('observes consent APIs without injecting a script when airgapSrc is omitted', () => {
+    setSelf({});
+    const appendedScripts: unknown[] = [];
+    setDocument({
+      createElement: vi.fn(() => ({
+        dataset: {},
+        remove: vi.fn(),
+      })),
+      documentElement: {
+        appendChild: vi.fn((script: unknown) => appendedScripts.push(script)),
+      },
+    });
+    useUndefinedConsentState();
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentProvider({
+      children: 'children',
+    });
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: Array<(api: unknown) => void> };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: Array<(api: unknown) => void> };
+    };
+
+    expect(appendedScripts).toHaveLength(0);
+    expect(consentGlobals.airgap?.readyQueue).toHaveLength(1);
+    expect(consentGlobals.transcend?.readyQueue).toHaveLength(1);
+  });
+});
+
+describe('useConsentManager', () => {
+  beforeEach(() => {
+    reactMocks.useEffect.mockReset();
+    reactMocks.useContext.mockReset();
+    reactMocks.useState.mockReset();
+  });
+
+  afterEach(() => {
+    if (originalSelfDescriptor) {
+      Object.defineProperty(globalThis, 'self', originalSelfDescriptor);
+    } else {
+      Reflect.deleteProperty(globalThis, 'self');
+    }
+  });
+
+  test('returns consent APIs from provider context', () => {
+    const consentApis = {
+      airgap: {},
+      transcend: {},
+    };
+    reactMocks.useContext.mockReturnValue(consentApis);
+    reactMocks.useState.mockReturnValue([{}, vi.fn()]);
+    reactMocks.useEffect.mockImplementation(() => undefined);
+
+    expect(useConsentManager()).toBe(consentApis);
+  });
+
+  test('falls back to initialized globals without a provider', () => {
+    const readyAirgap = {
+      addEventListener() {
+        // Initialized APIs are EventTargets.
+      },
+    };
+    const readyTranscend = {
+      addEventListener() {
+        // Initialized APIs are EventTargets.
+      },
+    };
+    setSelf({
+      airgap: readyAirgap,
+      transcend: readyTranscend,
+    });
+    reactMocks.useContext.mockReturnValue(undefined);
+    reactMocks.useState.mockImplementation((initializer: () => unknown) => [
+      initializer(),
+      vi.fn(),
+    ]);
+    reactMocks.useEffect.mockImplementation(() => undefined);
+
+    expect(useConsentManager()).toEqual({
+      airgap: readyAirgap,
+      transcend: readyTranscend,
+    });
+  });
+
+  test('observes ready queues without a provider', () => {
+    setSelf({});
+    const setObservedConsentApis = vi.fn();
+    reactMocks.useContext.mockReturnValue(undefined);
+    reactMocks.useState.mockReturnValue([{}, setObservedConsentApis]);
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    useConsentManager();
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: Array<(api: unknown) => void> };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: Array<(api: unknown) => void> };
+    };
+    const readyAirgap = {};
+    const readyTranscend = {};
+
+    consentGlobals.airgap?.readyQueue?.[0]?.(readyAirgap);
+    consentGlobals.transcend?.readyQueue?.[0]?.(readyTranscend);
+
+    expect(setObservedConsentApis).toHaveBeenCalledTimes(2);
+    expect(setObservedConsentApis).toHaveBeenNthCalledWith(1, expect.any(Function));
+    expect(setObservedConsentApis).toHaveBeenNthCalledWith(2, expect.any(Function));
+
+    const airgapUpdater = setObservedConsentApis.mock.calls[0]?.[0] as (
+      current: unknown,
+    ) => unknown;
+    const transcendUpdater = setObservedConsentApis.mock.calls[1]?.[0] as (
+      current: unknown,
+    ) => unknown;
+
+    expect(airgapUpdater({})).toEqual({ airgap: readyAirgap });
+    expect(transcendUpdater({})).toEqual({ transcend: readyTranscend });
+  });
+
+  test('does not update fallback state after unmount', () => {
+    setSelf({});
+    const setObservedConsentApis = vi.fn();
+    const cleanupRef: {
+      /** Effect cleanup callback. */
+      current?: () => void;
+    } = {};
+    reactMocks.useContext.mockReturnValue(undefined);
+    reactMocks.useState.mockReturnValue([{}, setObservedConsentApis]);
+    reactMocks.useEffect.mockImplementation((effect: () => void | (() => void)) => {
+      const cleanup = effect();
+      if (typeof cleanup === 'function') cleanupRef.current = cleanup;
+    });
+
+    useConsentManager();
+    const consentGlobals = self as typeof self & {
+      /** airgap.js preload stub. */
+      airgap?: { readyQueue?: Array<(api: unknown) => void> };
+      /** Transcend preload stub. */
+      transcend?: { readyQueue?: Array<(api: unknown) => void> };
+    };
+
+    cleanupRef.current?.();
+    consentGlobals.airgap?.readyQueue?.[0]?.({});
+    consentGlobals.transcend?.readyQueue?.[0]?.({});
+
+    expect(setObservedConsentApis).not.toHaveBeenCalled();
+  });
 });
diff --git a/packages/airgap-react/airgap-react/src/react/use-consent-manager.tsx b/packages/airgap-react/airgap-react/src/react/use-consent-manager.tsx
index 05cf9fbe..b5c88432 100644
--- a/packages/airgap-react/airgap-react/src/react/use-consent-manager.tsx
+++ b/packages/airgap-react/airgap-react/src/react/use-consent-manager.tsx
@@ -11,63 +11,26 @@ import {
   useState,
 } from 'react';
 
-import { type ConsentAPI, subscribeConsentApis } from '../core/consent-apis.js';
+import {
+  type ConsentAPI,
+  getInitializedConsentApis,
+  subscribeConsentApis,
+} from '../core/consent-apis.js';
+import { type ReactAirgapScriptProps, appendScriptElement } from './script-element.js';
 
 export interface ConsentProviderProps {
   /** Child tree that can consume the consent APIs. */
   children: ReactNode;
   /** airgap.js script URL from Transcend's developer settings. */
-  airgapSrc: string;
+  airgapSrc?: string;
   /** Additional attributes for the injected airgap.js script element. */
   scriptProps?: ReactAirgapScriptProps;
 }
 
-export interface ReactAirgapScriptProps {
-  /** Script element ID. */
-  id?: string;
-  /** Whether to load the script asynchronously. Defaults to true. */
-  async?: boolean;
-  /** Whether to defer script execution. Defaults to true. */
-  defer?: boolean;
-  /** Script nonce for CSP. */
-  nonce?: string;
-  /** Subresource integrity metadata. */
-  integrity?: string;
-  /** CORS setting for the script request. */
-  crossOrigin?: HTMLScriptElement['crossOrigin'];
-  /** Referrer policy for the script request. */
-  referrerPolicy?: HTMLScriptElement['referrerPolicy'];
-  /** Additional data attributes to set on the script element. */
-  dataset?: Record<string, string>;
-}
-
 /** React context backing `useConsentManager()`. */
-export const ConsentContext: Context<ConsentAPI> = createContext<ConsentAPI>({});
-
-function appendAirgapScript(src: string, scriptProps: ReactAirgapScriptProps = {}): () => void {
-  if (typeof document === 'undefined') return () => undefined;
-
-  const script = document.createElement('script');
-  script.src = src;
-  script.async = scriptProps.async ?? true;
-  script.defer = scriptProps.defer ?? true;
-
-  if (scriptProps.id) script.id = scriptProps.id;
-  if (scriptProps.nonce) script.nonce = scriptProps.nonce;
-  if (scriptProps.integrity) script.integrity = scriptProps.integrity;
-  if (scriptProps.crossOrigin) script.crossOrigin = scriptProps.crossOrigin;
-  if (scriptProps.referrerPolicy) script.referrerPolicy = scriptProps.referrerPolicy;
-
-  for (const [key, value] of Object.entries(scriptProps.dataset ?? {})) {
-    script.dataset[key] = value;
-  }
-
-  document.documentElement.appendChild(script);
-
-  return () => {
-    script.remove();
-  };
-}
+const ConsentContext: Context<ConsentAPI | undefined> = createContext<ConsentAPI | undefined>(
+  undefined,
+);
 
 /**
  * Provides loaded `airgap` and `transcend` APIs to React children while loading
@@ -88,7 +51,7 @@ export function ConsentProvider({
     });
   }, []);
 
-  useEffect(() => appendAirgapScript(airgapSrc, scriptProps), [airgapSrc, scriptProps]);
+  useEffect(() => appendScriptElement({ scriptProps, src: airgapSrc }), [airgapSrc, scriptProps]);
 
   return (
     <ConsentContext.Provider value={{ airgap, transcend }}>{children}</ConsentContext.Provider>
@@ -99,5 +62,22 @@ export function ConsentProvider({
  * Access the Airgap and Transcend Consent APIs loaded by `ConsentProvider`.
  */
 export function useConsentManager(): ConsentAPI {
-  return useContext(ConsentContext);
+  const consentContext = useContext(ConsentContext);
+  const [observedConsentApis, setObservedConsentApis] =
+    useState<ConsentAPI>(getInitializedConsentApis);
+
+  useEffect(() => {
+    if (consentContext) return;
+
+    return subscribeConsentApis({
+      onAirgap(airgap) {
+        setObservedConsentApis((current) => ({ ...current, airgap }));
+      },
+      onTranscend(transcend) {
+        setObservedConsentApis((current) => ({ ...current, transcend }));
+      },
+    });
+  }, [consentContext]);
+
+  return consentContext ?? observedConsentApis;
 }

From f06bfa0e7d33c892802f8bcd9953a116c41d2441 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Wed, 27 May 2026 22:58:27 -0400
Subject: [PATCH 09/17] stabilize airgap react lifecycle

---
 packages/airgap-react/airgap-nextjs/README.md |  2 +-
 packages/airgap-react/airgap-react/README.md  |  2 +-
 .../src/core/airgap-ready.test.ts             | 22 +++++++
 .../airgap-react/src/core/airgap-ready.ts     |  6 +-
 .../src/react/consent-boundary.test.tsx       | 60 +++++++++++++++++++
 .../src/react/consent-boundary.tsx            | 37 +++++++++++-
 .../airgap-react/src/react/script-element.ts  |  3 +-
 .../src/react/tracking-script.test.tsx        | 49 +++++++++++++++
 .../src/react/tracking-script.tsx             | 42 ++++++++++++-
 9 files changed, 212 insertions(+), 11 deletions(-)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index f45160f4..a0ac1f66 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -47,7 +47,7 @@ const airgapSyncPromise = airgapReady().then((airgap) => {
 When loading airgap.js asynchronously, make sure no trackers load before
 airgap.js is ready. Async loading cannot regulate trackers that initialize
 before Airgap has initialized. See Transcend's guide to
-[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously.md).
+[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
 
 ## useConsentManager
 
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index e05a9131..a83ad955 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -59,7 +59,7 @@ const airgapSyncPromise = airgapReady().then((airgap) => {
 When loading airgap.js asynchronously, make sure no trackers load before
 airgap.js is ready. Async loading cannot regulate trackers that initialize
 before Airgap has initialized. See Transcend's guide to
-[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously.md).
+[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
 
 ## useConsentManager
 
diff --git a/packages/airgap-react/airgap-react/src/core/airgap-ready.test.ts b/packages/airgap-react/airgap-react/src/core/airgap-ready.test.ts
index 15bfc809..b87fd239 100644
--- a/packages/airgap-react/airgap-react/src/core/airgap-ready.test.ts
+++ b/packages/airgap-react/airgap-react/src/core/airgap-ready.test.ts
@@ -90,4 +90,26 @@ describe('airgapReady', () => {
     airgapGlobal.airgap?.readyQueue?.[0]?.(readyAirgap);
     await expect(firstReady).resolves.toBe(readyAirgap);
   });
+
+  test('does not cache the no-self promise', async () => {
+    const { airgapReady } = await import('./airgap-ready.js');
+    Reflect.deleteProperty(globalThis, 'self');
+
+    const serverReady = airgapReady();
+    const airgapGlobal = {} as {
+      /** Transcend airgap API or preload stub. */
+      airgap?: {
+        /** Queue of callbacks to dispatch once airgap.js is ready. */
+        readyQueue?: Array<(airgap: unknown) => void>;
+      };
+    };
+    setSelf(airgapGlobal);
+
+    const browserReady = airgapReady();
+    const readyAirgap = {};
+
+    expect(browserReady).not.toBe(serverReady);
+    airgapGlobal.airgap?.readyQueue?.[0]?.(readyAirgap);
+    await expect(browserReady).resolves.toBe(readyAirgap);
+  });
 });
diff --git a/packages/airgap-react/airgap-react/src/core/airgap-ready.ts b/packages/airgap-react/airgap-react/src/core/airgap-ready.ts
index d772a2a3..06272696 100644
--- a/packages/airgap-react/airgap-react/src/core/airgap-ready.ts
+++ b/packages/airgap-react/airgap-react/src/core/airgap-ready.ts
@@ -16,9 +16,11 @@ let airgapReadyPromise: Promise<AirgapAPI> | undefined;
  * stub so the callback is drained when airgap.js initializes.
  */
 export function airgapReady(): Promise<AirgapAPI> {
-  airgapReadyPromise ??= new Promise((resolve) => {
-    if (typeof self === 'undefined') return;
+  if (typeof self === 'undefined') {
+    return new Promise<AirgapAPI>(() => undefined);
+  }
 
+  airgapReadyPromise ??= new Promise((resolve) => {
     const airgapGlobal = self as typeof self & GlobalWithAirgap;
     observeReadyApi<AirgapAPI>({
       api: airgapGlobal.airgap,
diff --git a/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx b/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
index dbb540a1..8aa41880 100644
--- a/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
+++ b/packages/airgap-react/airgap-react/src/react/consent-boundary.test.tsx
@@ -88,6 +88,66 @@ describe('ConsentBoundary', () => {
     );
   });
 
+  test('keys URL effect dependencies by contents', () => {
+    const airgap = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+    const effectDeps: unknown[][] = [];
+    const urlsRequiredForRender = ['https://example.com/tracker.js'];
+    mocks.useConsentManager.mockReturnValue({ airgap });
+    mocks.useState.mockReturnValue([{ status: 'pending' }, vi.fn()]);
+    mocks.useEffect.mockImplementation((_effect: () => void | (() => void), deps?: unknown[]) => {
+      effectDeps.push(deps ?? []);
+    });
+
+    ConsentBoundary({
+      children: 'blocked children',
+      urlsRequiredForRender,
+    });
+
+    expect(effectDeps[0]?.[2]).toBe(JSON.stringify(urlsRequiredForRender));
+    expect(effectDeps[0]).not.toContain(urlsRequiredForRender);
+  });
+
+  test('refreshes consent checks when Airgap consent events fire', () => {
+    const setConsentRefreshCounter = vi.fn();
+    const airgap = {
+      addEventListener: vi.fn(),
+      getPurposes: vi.fn(() => Promise.resolve(new Set<TrackingPurpose>(['Analytics']))),
+      getRegimePurposes: vi.fn(() => new Set<TrackingPurpose>()),
+      isAllowed: vi.fn(() => Promise.resolve(false)),
+      isConsented: vi.fn(() => false),
+      removeEventListener: vi.fn(),
+    };
+    mocks.useConsentManager.mockReturnValue({ airgap });
+    mocks.useState
+      .mockReturnValueOnce([{ status: 'pending' }, vi.fn()])
+      .mockReturnValueOnce([0, setConsentRefreshCounter]);
+    mocks.useEffect.mockImplementation((effect: () => void | (() => void)) => effect());
+
+    ConsentBoundary({
+      children: 'blocked children',
+      urlsRequiredForRender: ['https://example.com/tracker.js'],
+    });
+
+    expect(airgap.addEventListener).toHaveBeenCalledWith('consent-change', expect.any(Function));
+    expect(airgap.addEventListener).toHaveBeenCalledWith(
+      'consent-resolution',
+      expect.any(Function),
+    );
+    expect(airgap.addEventListener).toHaveBeenCalledWith('sync', expect.any(Function));
+
+    const refreshConsentState = airgap.addEventListener.mock.calls[0]?.[1] as () => void;
+    refreshConsentState();
+
+    expect(setConsentRefreshCounter).toHaveBeenCalledWith(expect.any(Function));
+    const refreshUpdater = setConsentRefreshCounter.mock.calls[0]?.[0] as (
+      current: number,
+    ) => number;
+    expect(refreshUpdater(1)).toBe(2);
+  });
+
   test('opt-in handler grants missing purposes', async () => {
     const missingConsentPurposes = new Set<TrackingPurpose>(['Analytics']);
     const setState = vi.fn();
diff --git a/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx b/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
index 315aba61..c394503a 100644
--- a/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
+++ b/packages/airgap-react/airgap-react/src/react/consent-boundary.tsx
@@ -1,6 +1,10 @@
 'use client';
 
-import type { TrackingConsent, TrackingPurpose } from '@transcend-io/airgap.js-types';
+import type {
+  AirgapConsentEventType,
+  TrackingConsent,
+  TrackingPurpose,
+} from '@transcend-io/airgap.js-types';
 import {
   type MouseEventHandler,
   type ReactElement,
@@ -12,6 +16,12 @@ import {
 import { getMissingConsentPurposesForUrls } from '../core/consent-boundary.js';
 import { useConsentManager } from './use-consent-manager.js';
 
+const consentRefreshEvents: AirgapConsentEventType[] = [
+  'consent-change',
+  'consent-resolution',
+  'sync',
+];
+
 type ConsentBoundaryState =
   | { status: 'pending' }
   | { status: 'allowed' }
@@ -89,6 +99,8 @@ export function ConsentBoundary({
 }: ConsentBoundaryProps): ReactNode {
   const { airgap } = useConsentManager();
   const [state, setState] = useState<ConsentBoundaryState>({ status: 'pending' });
+  const [consentRefreshCounter, setConsentRefreshCounter] = useState(0);
+  const urlsRequiredForRenderKey = JSON.stringify(urlsRequiredForRender);
 
   useEffect(() => {
     let cancelled = false;
@@ -101,7 +113,8 @@ export function ConsentBoundary({
     }
 
     setState({ status: 'pending' });
-    void getMissingConsentPurposesForUrls(airgap, urlsRequiredForRender).then(
+    const urlsToCheck = JSON.parse(urlsRequiredForRenderKey) as string[];
+    void getMissingConsentPurposesForUrls(airgap, urlsToCheck).then(
       (missingConsentPurposes) => {
         if (cancelled) return;
 
@@ -125,7 +138,25 @@ export function ConsentBoundary({
     return () => {
       cancelled = true;
     };
-  }, [airgap, urlsRequiredForRender]);
+  }, [airgap, consentRefreshCounter, urlsRequiredForRenderKey]);
+
+  useEffect(() => {
+    if (!airgap) return undefined;
+
+    const refreshConsentState = (): void => {
+      setConsentRefreshCounter((current) => current + 1);
+    };
+
+    for (const eventType of consentRefreshEvents) {
+      airgap.addEventListener(eventType, refreshConsentState);
+    }
+
+    return () => {
+      for (const eventType of consentRefreshEvents) {
+        airgap.removeEventListener(eventType, refreshConsentState);
+      }
+    };
+  }, [airgap]);
 
   if (state.status === 'allowed') {
     return <>{children}</>;
diff --git a/packages/airgap-react/airgap-react/src/react/script-element.ts b/packages/airgap-react/airgap-react/src/react/script-element.ts
index c683338a..44ed8c76 100644
--- a/packages/airgap-react/airgap-react/src/react/script-element.ts
+++ b/packages/airgap-react/airgap-react/src/react/script-element.ts
@@ -49,7 +49,8 @@ export function appendScriptElement({
     script.dataset[key] = value;
   }
 
-  document.documentElement.appendChild(script);
+  const scriptParent = document.head ?? document.body ?? document.documentElement;
+  scriptParent.appendChild(script);
 
   return () => {
     script.remove();
diff --git a/packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx b/packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx
index 5f6bbe57..fa9822d9 100644
--- a/packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx
+++ b/packages/airgap-react/airgap-react/src/react/tracking-script.test.tsx
@@ -31,6 +31,9 @@ function stubDocument(): unknown[] {
       dataset: {},
       remove: vi.fn(),
     })),
+    head: {
+      appendChild: vi.fn((script: unknown) => appendedScripts.push(script)),
+    },
     documentElement: {
       appendChild: vi.fn((script: unknown) => appendedScripts.push(script)),
     },
@@ -75,6 +78,52 @@ describe('TrackingScript', () => {
     expect(appendedScripts).toHaveLength(1);
   });
 
+  test('does not re-inject after rerender when script props are unchanged', async () => {
+    const loadAfter = Promise.resolve();
+    const appendedScripts = stubDocument();
+    let previousDeps: readonly unknown[] | undefined;
+    let previousCleanup: (() => void) | undefined;
+    reactMocks.useEffect.mockImplementation(
+      (effect: () => void | (() => void), deps?: readonly unknown[]) => {
+        const depsChanged =
+          !previousDeps ||
+          !deps ||
+          deps.length !== previousDeps.length ||
+          deps.some((dep, index) => dep !== previousDeps?.[index]);
+
+        if (depsChanged) {
+          previousCleanup?.();
+          const cleanup = effect();
+          previousCleanup = typeof cleanup === 'function' ? cleanup : undefined;
+          previousDeps = deps;
+        }
+      },
+    );
+
+    TrackingScript({
+      dataset: { purpose: 'analytics' },
+      id: 'analytics',
+      loadAfter,
+      src: 'https://cdn.example.com/analytics.js',
+    });
+    await Promise.resolve();
+
+    TrackingScript({
+      dataset: { purpose: 'analytics' },
+      id: 'analytics',
+      loadAfter,
+      src: 'https://cdn.example.com/analytics.js',
+    });
+    await Promise.resolve();
+
+    const [scriptElement] = appendedScripts as Array<{
+      /** Removes the script element. */
+      remove: ReturnType<typeof vi.fn>;
+    }>;
+    expect(appendedScripts).toHaveLength(1);
+    expect(scriptElement?.remove).not.toHaveBeenCalled();
+  });
+
   test('does not inject after unmount', async () => {
     let resolveLoad!: () => void;
     const loadAfter = new Promise<void>((resolve) => {
diff --git a/packages/airgap-react/airgap-react/src/react/tracking-script.tsx b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
index 6f188d84..942cd51f 100644
--- a/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
+++ b/packages/airgap-react/airgap-react/src/react/tracking-script.tsx
@@ -17,6 +17,12 @@ export interface TrackingScriptProps extends ReactAirgapScriptProps {
   children?: string;
 }
 
+function getDatasetDependencyKey(dataset: ReactAirgapScriptProps['dataset']): string {
+  return JSON.stringify(
+    Object.entries(dataset ?? {}).sort(([left], [right]) => left.localeCompare(right)),
+  );
+}
+
 /**
  * Client component that injects a script element only after `loadAfter` resolves.
  *
@@ -41,10 +47,19 @@ export interface TrackingScriptProps extends ReactAirgapScriptProps {
  */
 export function TrackingScript({
   loadAfter,
+  async,
   children,
+  crossOrigin,
+  dataset,
+  defer,
+  id,
+  integrity,
+  nonce,
+  referrerPolicy,
   src,
-  ...scriptProps
 }: TrackingScriptProps): null {
+  const datasetDependencyKey = getDatasetDependencyKey(dataset);
+
   useEffect(() => {
     let cancelled = false;
     let cleanup: (() => void) | undefined;
@@ -53,7 +68,16 @@ export function TrackingScript({
         if (cancelled || typeof document === 'undefined') return;
 
         cleanup = appendScriptElement({
-          scriptProps,
+          scriptProps: {
+            async,
+            crossOrigin,
+            dataset,
+            defer,
+            id,
+            integrity,
+            nonce,
+            referrerPolicy,
+          },
           src,
           text: children,
         });
@@ -64,7 +88,19 @@ export function TrackingScript({
       cancelled = true;
       cleanup?.();
     };
-  }, [children, loadAfter, scriptProps, src]);
+  }, [
+    async,
+    children,
+    crossOrigin,
+    datasetDependencyKey,
+    defer,
+    id,
+    integrity,
+    loadAfter,
+    nonce,
+    referrerPolicy,
+    src,
+  ]);
 
   return null;
 }

From caa4dcdd13ecaae75a3de80d2233d2f5deed9970 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 09:35:29 -0400
Subject: [PATCH 10/17] fix preview package packing

---
 .github/workflows/preview.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
index 08f9d983..acaa7f5c 100644
--- a/.github/workflows/preview.yml
+++ b/.github/workflows/preview.yml
@@ -41,7 +41,7 @@ jobs:
           while IFS= read -r line; do
             PACKAGE_PATHS+=("$line")
           done < <(mise exec -- pnpm list -r --depth -1 --json | jq -r '.[] | select(.private != true) | .path')
-          output="$(mise exec -- pnpx pkg-pr-new publish --packageManager=pnpm,yarn "${PACKAGE_PATHS[@]}" 2>&1)"
+          output="$(mise exec -- pnpx pkg-pr-new publish --pnpm --packageManager=pnpm,yarn "${PACKAGE_PATHS[@]}" 2>&1)"
           status=$?
           set -e
 

From 3745d33497a629d25d98cd8015ee2734a3b49161 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 10:10:28 -0400
Subject: [PATCH 11/17] clarify airgap package docs

---
 packages/airgap-react/airgap-nextjs/README.md | 194 ++++++++++------
 packages/airgap-react/airgap-react/README.md  | 211 ++++++++++--------
 2 files changed, 250 insertions(+), 155 deletions(-)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index a0ac1f66..21eec9c4 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -4,57 +4,73 @@ Next.js helpers for loading Airgap and gating trackers. This package has the
 same public features as `@transcend-io/airgap-react`, but uses `next/script`
 for script rendering.
 
-## TrackingScript
+Not using Next.js? Use
+[`@transcend-io/airgap-react`](https://www.npmjs.com/package/@transcend-io/airgap-react)
+instead. It provides the same public APIs without depending on `next/script`.
+
+> [!WARNING]
+> If you load airgap.js asynchronously, Airgap can only regulate network traffic
+> after it has loaded. Make sure no trackers load before airgap.js is ready. See
+> Transcend's guide to
+> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
+
+## API Overview
+
+1. `useConsentManager()` hook: access the loaded Airgap APIs and re-render when
+   airgap.js is ready.
+
+   ```tsx
+   const { airgap, transcend } = useConsentManager();
+   ```
+
+2. `<TrackingScript>` component: a `next/script` wrapper that waits for airgap.js
+   or any other promise before loading.
+
+   ```tsx
+   <TrackingScript
+     src="https://cdn.example.com/analytics.js"
+     strategy="afterInteractive"
+     loadAfter={loadAfter}
+   />
+   ```
+
+3. `<ConsentBoundary>` component: like a
+   [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary, but it
+   waits until consent is granted before mounting children. See the
+   [ConsentBoundary demo](https://docs.transcend.io/docs/articles/consent-management/reference/react-snippets#add-a-consentboundary-react-component).
+
+   ```tsx
+   <ConsentBoundary urlsRequiredForRender={[videoUrl]} fallback={ConsentFallback}>
+     <VideoPlayer src={videoUrl} />
+   </ConsentBoundary>
+   ```
 
-`TrackingScript` is a small client component around `next/script`. It renders
-nothing until its `loadAfter` promise resolves, then renders the underlying
-`<Script>`.
+## useConsentManager
+
+`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook
+re-renders when either API becomes ready.
+
+If your app already loads airgap.js, call the hook directly and it will observe
+the existing `self.airgap` and `self.transcend` globals:
 
 ```tsx
-import { airgapReady, TrackingScript } from '@transcend-io/airgap-nextjs';
+import { useConsentManager } from '@transcend-io/airgap-nextjs';
 
-const loadAfter = airgapReady();
+export function PrivacyChoicesButton() {
+  const { transcend } = useConsentManager();
 
-export function AnalyticsScript() {
   return (
-    <TrackingScript
-      src="https://cdn.example.com/analytics.js"
-      strategy="afterInteractive"
-      loadAfter={loadAfter}
-    />
+    <button
+      type="button"
+      disabled={!transcend}
+      onClick={() => void transcend?.showConsentManager()}
+    >
+      Privacy choices
+    </button>
   );
 }
 ```
 
-`strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
-script injection after hydration.
-
-## airgapReady
-
-`airgapReady()` resolves with the typed `AirgapAPI` when
-`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
-documented ready-queue stub so the callback is drained when airgap.js
-initializes.
-
-```tsx
-const airgapSyncPromise = airgapReady().then((airgap) => {
-  return new Promise<void>((resolve) => {
-    airgap.addEventListener('sync', () => resolve(), { once: true });
-  });
-});
-```
-
-When loading airgap.js asynchronously, make sure no trackers load before
-airgap.js is ready. Async loading cannot regulate trackers that initialize
-before Airgap has initialized. See Transcend's guide to
-[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
-
-## useConsentManager
-
-`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. If your
-app already loads airgap.js, the hook observes the existing `self.airgap` and
-`self.transcend` globals without a provider.
-
 Use `ConsentProvider` when you want this package to load airgap.js through
 `next/script`:
 
@@ -87,48 +103,92 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-If Airgap is loaded elsewhere, call the hook directly:
+## TrackingScript
+
+`TrackingScript` is a small client component around `next/script`. It renders
+nothing until its `loadAfter` promise resolves, then renders the underlying
+`<Script>`.
+
+Create the promise outside render so React does not restart the gate effect on
+every render.
 
 ```tsx
-import { useConsentManager } from '@transcend-io/airgap-nextjs';
+import { airgapReady, TrackingScript } from '@transcend-io/airgap-nextjs';
 
-export function PrivacyChoicesButton() {
-  const { transcend } = useConsentManager();
+const loadAfter = airgapReady();
 
+export function AnalyticsScript() {
   return (
-    <button
-      type="button"
-      disabled={!transcend}
-      onClick={() => void transcend?.showConsentManager()}
-    >
-      Privacy choices
-    </button>
+    <TrackingScript
+      src="https://cdn.example.com/analytics.js"
+      strategy="afterInteractive"
+      loadAfter={loadAfter}
+    />
   );
 }
 ```
 
+`strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
+script injection after hydration.
+
 ## ConsentBoundary
 
 `ConsentBoundary` is re-exported from `@transcend-io/airgap-react` so it shares
-the same behavior in both packages. It uses `useConsentManager()`, so it works
-with `ConsentProvider` or with Airgap globals loaded separately.
+the same behavior in both packages. It is similar to
+[`<Suspense>`](https://react.dev/reference/react/Suspense): it displays a
+fallback while work is pending, then reveals its children when they are ready.
+Instead of waiting for code or data, it waits until Airgap allows the URLs needed
+by the subtree.
 
-```tsx
-import { ConsentBoundary, type ConsentBoundaryFallbackProps } from '@transcend-io/airgap-nextjs';
+This is a good fit for embeds, videos, analytics widgets, and other components
+that connect to services requiring consent.
+
+<video controls src="https://cdn.sanity.io/files/1ievmmav/production/40de95dcbe5e1c0406493c96b708590f505d5db8.webm"></video>
 
-function ConsentFallback({
-  missingConsentPurposes,
-  onConsentGiven,
-  status,
-}: ConsentBoundaryFallbackProps) {
-  if (status === 'pending') {
-    return <p>Checking consent...</p>;
-  }
+It uses `useConsentManager()`, so it works with `ConsentProvider` or with Airgap
+globals loaded separately. The fallback receives the missing consent purposes
+and an `onConsentGiven` handler that opts into those purposes.
 
+```tsx
+import { ConsentBoundary } from '@transcend-io/airgap-nextjs';
+
+export function VideoBoundary({ videoUrl }: { videoUrl: string }) {
   return (
-    <button type="button" onClick={onConsentGiven}>
-      Allow {Array.from(missingConsentPurposes).join(', ')} trackers
-    </button>
+    <ConsentBoundary
+      urlsRequiredForRender={[videoUrl]}
+      fallback={({ missingConsentPurposes, onConsentGiven, status }) => {
+        if (status === 'pending') {
+          return <p>Checking consent...</p>;
+        }
+
+        return (
+          <button type="button" onClick={onConsentGiven}>
+            Allow {Array.from(missingConsentPurposes).join(', ')} trackers
+          </button>
+        );
+      }}
+    >
+      <VideoPlayer src={videoUrl} />
+    </ConsentBoundary>
   );
 }
 ```
+
+## Helpers
+
+### airgapReady
+
+`airgapReady()` resolves with the typed `AirgapAPI` when
+`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
+documented ready-queue stub so the callback is drained when airgap.js
+initializes.
+
+```tsx
+import { airgapReady } from '@transcend-io/airgap-nextjs';
+
+const airgapSyncPromise = airgapReady().then((airgap) => {
+  return new Promise<void>((resolve) => {
+    airgap.addEventListener('sync', () => resolve(), { once: true });
+  });
+});
+```
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index a83ad955..f994f1fa 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -1,71 +1,70 @@
 # @transcend-io/airgap-react
 
-React helpers for loading Airgap and gating trackers without depending on
-Next.js.
+React helpers for loading airgap.js asynchronously and gating trackers.
 
-## TrackingScript
+Using Next.js? Use
+[`@transcend-io/airgap-nextjs`](https://www.npmjs.com/package/@transcend-io/airgap-nextjs)
+instead. It provides the same public APIs, but renders scripts with
+`next/script`.
 
-`TrackingScript` injects a script element after its `loadAfter` promise
-resolves.
+> [!WARNING]
+> If you load airgap.js asynchronously, Airgap can only regulate network traffic
+> after it has loaded. Make sure no trackers load before airgap.js is ready. See
+> Transcend's guide to
+> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
 
-```tsx
-import { airgapReady, TrackingScript } from '@transcend-io/airgap-react';
+## API Overview
 
-const loadAfter = airgapReady();
+1. `useConsentManager()` hook: access the loaded Airgap APIs and re-render when
+   airgap.js is ready.
 
-export function AnalyticsScript() {
-  return <TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
-}
-```
+   ```tsx
+   const { airgap, transcend } = useConsentManager();
+   ```
 
-The resolved value is ignored, so any `PromiseLike<unknown>` can open the gate.
-Create the promise outside render so React does not restart the gate effect on
-every render.
+2. `<TrackingScript>` component: a `<script>` tag that waits for airgap.js or
+   any other promise before loading.
 
-```tsx
-const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
+   ```tsx
+   <TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />
+   ```
 
-<TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
-```
-
-You can also gate inline scripts:
+3. `<ConsentBoundary>` component: like a
+   [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary, but it
+   waits until consent is granted before mounting children. See the
+   [ConsentBoundary demo](https://docs.transcend.io/docs/articles/consent-management/reference/react-snippets#add-a-consentboundary-react-component).
 
-```tsx
-const gtmReadyPromise = airgapReady();
+   ```tsx
+   <ConsentBoundary urlsRequiredForRender={[videoUrl]} fallback={ConsentFallback}>
+     <VideoPlayer src={videoUrl} />
+   </ConsentBoundary>
+   ```
 
-<TrackingScript id="gtm-init" loadAfter={gtmReadyPromise}>{`
-  window.dataLayer = window.dataLayer || [];
-  window.dataLayer.push({ event: 'gtm.js' });
-`}</TrackingScript>;
-```
+## useConsentManager
 
-## airgapReady
+`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook
+re-renders when either API becomes ready.
 
-`airgapReady()` resolves with the typed `AirgapAPI` when
-`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
-documented ready-queue stub so the callback is drained when airgap.js
-initializes.
+If your app already loads airgap.js, call the hook directly and it will observe
+the existing `self.airgap` and `self.transcend` globals:
 
 ```tsx
-import { airgapReady } from '@transcend-io/airgap-react';
-
-const airgapSyncPromise = airgapReady().then((airgap) => {
-  return new Promise<void>((resolve) => {
-    airgap.addEventListener('sync', () => resolve(), { once: true });
-  });
-});
-```
-
-When loading airgap.js asynchronously, make sure no trackers load before
-airgap.js is ready. Async loading cannot regulate trackers that initialize
-before Airgap has initialized. See Transcend's guide to
-[loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
+import { useConsentManager } from '@transcend-io/airgap-react';
 
-## useConsentManager
+export function PrivacyChoicesButton() {
+  const { transcend } = useConsentManager();
 
-`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. If your
-app already loads airgap.js, the hook observes the existing `self.airgap` and
-`self.transcend` globals without a provider.
+  return (
+    <button
+      type="button"
+      disabled={!transcend}
+      onClick={() => void transcend?.showConsentManager()}
+    >
+      Privacy choices
+    </button>
+  );
+}
+```
 
 Use `ConsentProvider` when you want this package to inject airgap.js for you:
 
@@ -95,61 +94,97 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-If Airgap is loaded elsewhere, call the hook directly:
+## TrackingScript
+
+`TrackingScript` injects a script element after its `loadAfter` promise
+resolves. The resolved value is ignored, so any `PromiseLike<unknown>` can open
+the gate.
+
+Create the promise outside render so React does not restart the gate effect on
+every render.
 
 ```tsx
-import { useConsentManager } from '@transcend-io/airgap-react';
+import { airgapReady, TrackingScript } from '@transcend-io/airgap-react';
 
-export function PrivacyChoicesButton() {
-  const { transcend } = useConsentManager();
+const loadAfter = airgapReady();
 
-  return (
-    <button
-      type="button"
-      disabled={!transcend}
-      onClick={() => void transcend?.showConsentManager()}
-    >
-      Privacy choices
-    </button>
-  );
+export function AnalyticsScript() {
+  return <TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
 }
 ```
 
+You can also compose multiple gates or gate inline scripts:
+
+```tsx
+const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
+
+<TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={loadAfter} />;
+
+<TrackingScript id="gtm-init" loadAfter={airgapReady()}>{`
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({ event: 'gtm.js' });
+`}</TrackingScript>;
+```
+
 ## ConsentBoundary
 
-`ConsentBoundary` checks the URLs needed by a subtree before mounting its
-children. While the check is pending, or when consent is missing, only the
-fallback renders so gated children cannot start loading network resources. It
-uses `useConsentManager()`, so it works with `ConsentProvider` or with Airgap
-globals loaded separately.
+`ConsentBoundary` is similar to
+[`<Suspense>`](https://react.dev/reference/react/Suspense): it displays a
+fallback while work is pending, then reveals its children when they are ready.
+Instead of waiting for code or data, it waits until Airgap allows the URLs needed
+by the subtree.
 
-```tsx
-import { ConsentBoundary, type ConsentBoundaryFallbackProps } from '@transcend-io/airgap-react';
+This is a good fit for embeds, videos, analytics widgets, and other components
+that connect to services requiring consent.
 
-function ConsentFallback({
-  missingConsentPurposes,
-  onConsentGiven,
-  status,
-}: ConsentBoundaryFallbackProps) {
-  if (status === 'pending') {
-    return <p>Checking consent...</p>;
-  }
+<video controls src="https://cdn.sanity.io/files/1ievmmav/production/40de95dcbe5e1c0406493c96b708590f505d5db8.webm"></video>
 
-  return (
-    <button type="button" onClick={onConsentGiven}>
-      Allow {Array.from(missingConsentPurposes).join(', ')} trackers
-    </button>
-  );
-}
+While the check is pending, or when consent is missing, only the fallback renders
+so gated children cannot start loading network resources. It uses
+`useConsentManager()`, so it works with `ConsentProvider` or with Airgap globals
+loaded separately. The fallback receives the missing consent purposes and an
+`onConsentGiven` handler that opts into those purposes.
 
-export function AnalyticsWidgetBoundary() {
+```tsx
+import { ConsentBoundary } from '@transcend-io/airgap-react';
+
+export function VideoBoundary({ videoUrl }: { videoUrl: string }) {
   return (
     <ConsentBoundary
-      urlsRequiredForRender={['https://www.googletagmanager.com/gtm.js?id=GTM-XXXX']}
-      fallback={ConsentFallback}
+      urlsRequiredForRender={[videoUrl]}
+      fallback={({ missingConsentPurposes, onConsentGiven, status }) => {
+        if (status === 'pending') {
+          return <p>Checking consent...</p>;
+        }
+
+        return (
+          <button type="button" onClick={onConsentGiven}>
+            Allow {Array.from(missingConsentPurposes).join(', ')} trackers
+          </button>
+        );
+      }}
     >
-      <AnalyticsWidget />
+      <VideoPlayer src={videoUrl} />
     </ConsentBoundary>
   );
 }
 ```
+
+## Helpers
+
+### airgapReady
+
+`airgapReady()` resolves with the typed `AirgapAPI` when
+`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
+documented ready-queue stub so the callback is drained when airgap.js
+initializes.
+
+```tsx
+import { airgapReady } from '@transcend-io/airgap-react';
+
+const airgapSyncPromise = airgapReady().then((airgap) => {
+  return new Promise<void>((resolve) => {
+    airgap.addEventListener('sync', () => resolve(), { once: true });
+  });
+});
+```

From 0a87b83fcf8c55d13f24fcaa2fe74d8c4e9c8a9a Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 10:19:15 -0400
Subject: [PATCH 12/17] exclude generated folders from search

---
 .vscode/settings.json | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 5f363377..661504ed 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -17,5 +17,10 @@
    */
   "prettier.enable": false,
   "eslint.enable": false,
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/dist": true,
+    "**/.turbo": true
+  }
 }

From 30381ab81e81fe6ad01b5eda64e589866b6da5d3 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 12:25:31 -0400
Subject: [PATCH 13/17] specify async on consentprovider

---
 packages/airgap-react/airgap-nextjs/README.md | 4 ++--
 packages/airgap-react/airgap-react/README.md  | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index 21eec9c4..5929b7b7 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -71,7 +71,7 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-Use `ConsentProvider` when you want this package to load airgap.js through
+Use `ConsentProvider` when you want this package to load airgap.js **asynchronously**, using
 `next/script`:
 
 ```tsx
@@ -105,7 +105,7 @@ export function PrivacyChoicesButton() {
 
 ## TrackingScript
 
-`TrackingScript` is a small client component around `next/script`. It renders
+`TrackingScript` is a small client component around [`next/script`](https://nextjs.org/docs/pages/api-reference/components/script). It renders
 nothing until its `loadAfter` promise resolves, then renders the underlying
 `<Script>`.
 
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index f994f1fa..72839607 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -66,7 +66,7 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-Use `ConsentProvider` when you want this package to inject airgap.js for you:
+Use `ConsentProvider` when you want this package to inject airgap.js for you **asynchronously**:
 
 ```tsx
 import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-react';

From 89930bb9d200f7051540a13dcd4621b343b43284 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 12:26:11 -0400
Subject: [PATCH 14/17] move warning block

---
 packages/airgap-react/airgap-nextjs/README.md | 12 ++++++------
 packages/airgap-react/airgap-react/README.md  | 12 ++++++------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index 5929b7b7..d58c231b 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -8,12 +8,6 @@ Not using Next.js? Use
 [`@transcend-io/airgap-react`](https://www.npmjs.com/package/@transcend-io/airgap-react)
 instead. It provides the same public APIs without depending on `next/script`.
 
-> [!WARNING]
-> If you load airgap.js asynchronously, Airgap can only regulate network traffic
-> after it has loaded. Make sure no trackers load before airgap.js is ready. See
-> Transcend's guide to
-> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
-
 ## API Overview
 
 1. `useConsentManager()` hook: access the loaded Airgap APIs and re-render when
@@ -45,6 +39,12 @@ instead. It provides the same public APIs without depending on `next/script`.
    </ConsentBoundary>
    ```
 
+> [!WARNING]
+> If you load airgap.js asynchronously, Airgap can only regulate network traffic
+> after it has loaded. Make sure no trackers load before airgap.js is ready. See
+> Transcend's guide to
+> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
+
 ## useConsentManager
 
 `useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index 72839607..4bab9b14 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -7,12 +7,6 @@ Using Next.js? Use
 instead. It provides the same public APIs, but renders scripts with
 `next/script`.
 
-> [!WARNING]
-> If you load airgap.js asynchronously, Airgap can only regulate network traffic
-> after it has loaded. Make sure no trackers load before airgap.js is ready. See
-> Transcend's guide to
-> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
-
 ## API Overview
 
 1. `useConsentManager()` hook: access the loaded Airgap APIs and re-render when
@@ -40,6 +34,12 @@ instead. It provides the same public APIs, but renders scripts with
    </ConsentBoundary>
    ```
 
+> [!WARNING]
+> If you load airgap.js asynchronously, Airgap can only regulate network traffic
+> after it has loaded. Make sure no trackers load before airgap.js is ready. See
+> Transcend's guide to
+> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
+
 ## useConsentManager
 
 `useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook

From 230d8f57e626eb910fb02f32c12af223cf4ad56b Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 12:34:16 -0400
Subject: [PATCH 15/17] clarify async tracker loading docs

---
 packages/airgap-react/airgap-nextjs/README.md | 20 ++++++++++++++++---
 packages/airgap-react/airgap-react/README.md  | 20 ++++++++++++++++---
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index d58c231b..b1932bc3 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -41,9 +41,23 @@ instead. It provides the same public APIs without depending on `next/script`.
 
 > [!WARNING]
 > If you load airgap.js asynchronously, Airgap can only regulate network traffic
-> after it has loaded. Make sure no trackers load before airgap.js is ready. See
-> Transcend's guide to
-> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
+> after it has loaded. Make sure no trackers load before airgap.js is ready.
+> Replace tracking script elements with [`<TrackingScript>`](#trackingscript), or
+> condition script loads on the hook:
+>
+> ```tsx
+> function TrackerLoader() {
+>   const { airgap } = useConsentManager();
+>
+>   useEffect(() => {
+>     if (!airgap) return;
+>
+>     loadTrackers();
+>   }, [airgap]);
+>
+>   return null;
+> }
+> ```
 
 ## useConsentManager
 
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index 4bab9b14..27b73456 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -36,9 +36,23 @@ instead. It provides the same public APIs, but renders scripts with
 
 > [!WARNING]
 > If you load airgap.js asynchronously, Airgap can only regulate network traffic
-> after it has loaded. Make sure no trackers load before airgap.js is ready. See
-> Transcend's guide to
-> [loading airgap.js asynchronously](https://docs.transcend.io/docs/articles/consent-management/configuration/loading-asynchronously).
+> after it has loaded. Make sure no trackers load before airgap.js is ready.
+> Replace tracking script elements with [`<TrackingScript>`](#trackingscript), or
+> condition script loads on the hook:
+>
+> ```tsx
+> function TrackerLoader() {
+>   const { airgap } = useConsentManager();
+>
+>   useEffect(() => {
+>     if (!airgap) return;
+>
+>     loadTrackers();
+>   }, [airgap]);
+>
+>   return null;
+> }
+> ```
 
 ## useConsentManager
 

From d78dd559a2910b285823343df0112e409bad8394 Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 12:53:27 -0400
Subject: [PATCH 16/17] clarify airgap readiness docs

---
 packages/airgap-react/airgap-nextjs/README.md | 79 +++++++++++++------
 packages/airgap-react/airgap-react/README.md  | 79 +++++++++++++------
 2 files changed, 109 insertions(+), 49 deletions(-)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index b1932bc3..66521ec7 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -39,11 +39,13 @@ instead. It provides the same public APIs without depending on `next/script`.
    </ConsentBoundary>
    ```
 
+## Asynchronously loading airgap.js
+
 > [!WARNING]
 > If you load airgap.js asynchronously, Airgap can only regulate network traffic
-> after it has loaded. Make sure no trackers load before airgap.js is ready.
-> Replace tracking script elements with [`<TrackingScript>`](#trackingscript), or
-> condition script loads on the hook:
+> after it has loaded and is ready. Make sure no trackers load before airgap.js
+> is ready. Replace tracking script elements with
+> [`<TrackingScript>`](#trackingscript), or condition script loads on the hook:
 >
 > ```tsx
 > function TrackerLoader() {
@@ -62,7 +64,28 @@ instead. It provides the same public APIs without depending on `next/script`.
 ## useConsentManager
 
 `useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook
-re-renders when either API becomes ready.
+re-renders when either API becomes ready. `airgap` and `transcend` are
+`undefined` until each API is loaded and ready.
+
+Use the hook for component-level conditions, like enabling UI or loading trackers
+from an effect once `airgap` is loaded and ready to regulate network traffic:
+
+```tsx
+import { useEffect } from 'react';
+import { useConsentManager } from '@transcend-io/airgap-nextjs';
+
+function TrackerLoader() {
+  const { airgap } = useConsentManager();
+
+  useEffect(() => {
+    if (!airgap) return;
+
+    loadTrackers();
+  }, [airgap]);
+
+  return null;
+}
+```
 
 If your app already loads airgap.js, call the hook directly and it will observe
 the existing `self.airgap` and `self.transcend` globals:
@@ -85,7 +108,8 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-Use `ConsentProvider` when you want this package to load airgap.js **asynchronously**, using
+Use `ConsentProvider` when you want this package to load
+[airgap.js **asynchronously**](#asynchronously-loading-airgapjs), using
 `next/script`:
 
 ```tsx
@@ -145,6 +169,32 @@ export function AnalyticsScript() {
 `strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
 script injection after hydration.
 
+### airgapReady
+
+`airgapReady()` returns a `Promise<AirgapAPI>` that resolves when
+`self.airgap.ready(...)` fires. It is primarily intended for the `loadAfter` prop
+on `TrackingScript`.
+
+If airgap.js has not loaded yet, `airgapReady()` creates a ready-queue stub so
+the callback is drained when airgap.js initializes. For component logic, prefer
+`useConsentManager()` so React re-renders when `airgap` becomes available.
+
+```tsx
+import { airgapReady, TrackingScript } from '@transcend-io/airgap-nextjs';
+
+const airgapSyncPromise = airgapReady().then((airgap) => {
+  return new Promise<void>((resolve) => {
+    airgap.addEventListener('sync', () => resolve(), { once: true });
+  });
+});
+
+<TrackingScript
+  src="https://cdn.example.com/analytics.js"
+  strategy="afterInteractive"
+  loadAfter={airgapSyncPromise}
+/>;
+```
+
 ## ConsentBoundary
 
 `ConsentBoundary` is re-exported from `@transcend-io/airgap-react` so it shares
@@ -187,22 +237,3 @@ export function VideoBoundary({ videoUrl }: { videoUrl: string }) {
   );
 }
 ```
-
-## Helpers
-
-### airgapReady
-
-`airgapReady()` resolves with the typed `AirgapAPI` when
-`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
-documented ready-queue stub so the callback is drained when airgap.js
-initializes.
-
-```tsx
-import { airgapReady } from '@transcend-io/airgap-nextjs';
-
-const airgapSyncPromise = airgapReady().then((airgap) => {
-  return new Promise<void>((resolve) => {
-    airgap.addEventListener('sync', () => resolve(), { once: true });
-  });
-});
-```
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index 27b73456..b7dc3eed 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -1,6 +1,8 @@
 # @transcend-io/airgap-react
 
-React helpers for loading airgap.js asynchronously and gating trackers.
+React helpers for loading
+[airgap.js asynchronously](#asynchronously-loading-airgapjs) and gating
+trackers.
 
 Using Next.js? Use
 [`@transcend-io/airgap-nextjs`](https://www.npmjs.com/package/@transcend-io/airgap-nextjs)
@@ -34,11 +36,13 @@ instead. It provides the same public APIs, but renders scripts with
    </ConsentBoundary>
    ```
 
+## Asynchronously loading airgap.js
+
 > [!WARNING]
 > If you load airgap.js asynchronously, Airgap can only regulate network traffic
-> after it has loaded. Make sure no trackers load before airgap.js is ready.
-> Replace tracking script elements with [`<TrackingScript>`](#trackingscript), or
-> condition script loads on the hook:
+> after it has loaded and is ready. Make sure no trackers load before airgap.js
+> is ready. Replace tracking script elements with
+> [`<TrackingScript>`](#trackingscript), or condition script loads on the hook:
 >
 > ```tsx
 > function TrackerLoader() {
@@ -57,7 +61,28 @@ instead. It provides the same public APIs, but renders scripts with
 ## useConsentManager
 
 `useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook
-re-renders when either API becomes ready.
+re-renders when either API becomes ready. `airgap` and `transcend` are
+`undefined` until each API is loaded and ready.
+
+Use the hook for component-level conditions, like enabling UI or loading trackers
+from an effect once `airgap` is loaded and ready to regulate network traffic:
+
+```tsx
+import { useEffect } from 'react';
+import { useConsentManager } from '@transcend-io/airgap-react';
+
+function TrackerLoader() {
+  const { airgap } = useConsentManager();
+
+  useEffect(() => {
+    if (!airgap) return;
+
+    loadTrackers();
+  }, [airgap]);
+
+  return null;
+}
+```
 
 If your app already loads airgap.js, call the hook directly and it will observe
 the existing `self.airgap` and `self.transcend` globals:
@@ -80,7 +105,8 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-Use `ConsentProvider` when you want this package to inject airgap.js for you **asynchronously**:
+Use `ConsentProvider` when you want this package to inject
+[airgap.js **asynchronously**](#asynchronously-loading-airgapjs):
 
 ```tsx
 import { ConsentProvider, useConsentManager } from '@transcend-io/airgap-react';
@@ -140,6 +166,28 @@ const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
 `}</TrackingScript>;
 ```
 
+### airgapReady
+
+`airgapReady()` returns a `Promise<AirgapAPI>` that resolves when
+`self.airgap.ready(...)` fires. It is primarily intended for the `loadAfter` prop
+on `TrackingScript`.
+
+If airgap.js has not loaded yet, `airgapReady()` creates a ready-queue stub so
+the callback is drained when airgap.js initializes. For component logic, prefer
+`useConsentManager()` so React re-renders when `airgap` becomes available.
+
+```tsx
+import { airgapReady, TrackingScript } from '@transcend-io/airgap-react';
+
+const airgapSyncPromise = airgapReady().then((airgap) => {
+  return new Promise<void>((resolve) => {
+    airgap.addEventListener('sync', () => resolve(), { once: true });
+  });
+});
+
+<TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={airgapSyncPromise} />;
+```
+
 ## ConsentBoundary
 
 `ConsentBoundary` is similar to
@@ -183,22 +231,3 @@ export function VideoBoundary({ videoUrl }: { videoUrl: string }) {
   );
 }
 ```
-
-## Helpers
-
-### airgapReady
-
-`airgapReady()` resolves with the typed `AirgapAPI` when
-`self.airgap.ready(...)` fires. If airgap.js has not loaded yet, it creates the
-documented ready-queue stub so the callback is drained when airgap.js
-initializes.
-
-```tsx
-import { airgapReady } from '@transcend-io/airgap-react';
-
-const airgapSyncPromise = airgapReady().then((airgap) => {
-  return new Promise<void>((resolve) => {
-    airgap.addEventListener('sync', () => resolve(), { once: true });
-  });
-});
-```

From 82d190cc82e136ee2613ef2d10df5052601ae49d Mon Sep 17 00:00:00 2001
From: bencmbrook <7354176+bencmbrook@users.noreply.github.com>
Date: Thu, 28 May 2026 16:10:18 -0400
Subject: [PATCH 17/17] standardize airgap README API headings

---
 packages/airgap-react/airgap-nextjs/README.md | 32 ++++++++++---------
 packages/airgap-react/airgap-react/README.md  | 28 ++++++++--------
 2 files changed, 31 insertions(+), 29 deletions(-)

diff --git a/packages/airgap-react/airgap-nextjs/README.md b/packages/airgap-react/airgap-nextjs/README.md
index 66521ec7..3654a585 100644
--- a/packages/airgap-react/airgap-nextjs/README.md
+++ b/packages/airgap-react/airgap-nextjs/README.md
@@ -61,11 +61,11 @@ instead. It provides the same public APIs without depending on `next/script`.
 > }
 > ```
 
-## useConsentManager
+## `useConsentManager()` hook
 
-`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook
-re-renders when either API becomes ready. `airgap` and `transcend` are
-`undefined` until each API is loaded and ready.
+`useConsentManager()` is a React hook that returns the loaded `airgap` and
+`transcend` APIs. The hook re-renders when either API becomes ready. `airgap` and
+`transcend` are `undefined` until each API is loaded and ready.
 
 Use the hook for component-level conditions, like enabling UI or loading trackers
 from an effect once `airgap` is loaded and ready to regulate network traffic:
@@ -141,11 +141,12 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-## TrackingScript
+## `<TrackingScript>` component
 
-`TrackingScript` is a small client component around [`next/script`](https://nextjs.org/docs/pages/api-reference/components/script). It renders
-nothing until its `loadAfter` promise resolves, then renders the underlying
-`<Script>`.
+`<TrackingScript>` is a React component around
+[`next/script`](https://nextjs.org/docs/pages/api-reference/components/script).
+It renders nothing until its `loadAfter` promise resolves, then renders the
+underlying `<Script>`.
 
 Create the promise outside render so React does not restart the gate effect on
 every render.
@@ -169,11 +170,11 @@ export function AnalyticsScript() {
 `strategy="beforeInteractive"` is unsupported because `TrackingScript` gates
 script injection after hydration.
 
-### airgapReady
+### `airgapReady()` helper
 
-`airgapReady()` returns a `Promise<AirgapAPI>` that resolves when
-`self.airgap.ready(...)` fires. It is primarily intended for the `loadAfter` prop
-on `TrackingScript`.
+`airgapReady()` is a helper function that returns a `Promise<AirgapAPI>` that
+resolves when `self.airgap.ready(...)` fires. It is primarily intended for the
+`loadAfter` prop on `<TrackingScript>`.
 
 If airgap.js has not loaded yet, `airgapReady()` creates a ready-queue stub so
 the callback is drained when airgap.js initializes. For component logic, prefer
@@ -195,10 +196,11 @@ const airgapSyncPromise = airgapReady().then((airgap) => {
 />;
 ```
 
-## ConsentBoundary
+## `<ConsentBoundary>` component
 
-`ConsentBoundary` is re-exported from `@transcend-io/airgap-react` so it shares
-the same behavior in both packages. It is similar to
+`<ConsentBoundary>` is a React component re-exported from
+`@transcend-io/airgap-react` so it shares the same behavior in both packages. It
+is similar to
 [`<Suspense>`](https://react.dev/reference/react/Suspense): it displays a
 fallback while work is pending, then reveals its children when they are ready.
 Instead of waiting for code or data, it waits until Airgap allows the URLs needed
diff --git a/packages/airgap-react/airgap-react/README.md b/packages/airgap-react/airgap-react/README.md
index b7dc3eed..bb5b5d6a 100644
--- a/packages/airgap-react/airgap-react/README.md
+++ b/packages/airgap-react/airgap-react/README.md
@@ -58,11 +58,11 @@ instead. It provides the same public APIs, but renders scripts with
 > }
 > ```
 
-## useConsentManager
+## `useConsentManager()` hook
 
-`useConsentManager()` returns the loaded `airgap` and `transcend` APIs. The hook
-re-renders when either API becomes ready. `airgap` and `transcend` are
-`undefined` until each API is loaded and ready.
+`useConsentManager()` is a React hook that returns the loaded `airgap` and
+`transcend` APIs. The hook re-renders when either API becomes ready. `airgap` and
+`transcend` are `undefined` until each API is loaded and ready.
 
 Use the hook for component-level conditions, like enabling UI or loading trackers
 from an effect once `airgap` is loaded and ready to regulate network traffic:
@@ -134,11 +134,11 @@ export function PrivacyChoicesButton() {
 }
 ```
 
-## TrackingScript
+## `<TrackingScript>` component
 
-`TrackingScript` injects a script element after its `loadAfter` promise
-resolves. The resolved value is ignored, so any `PromiseLike<unknown>` can open
-the gate.
+`<TrackingScript>` is a React component that injects a script element after its
+`loadAfter` promise resolves. The resolved value is ignored, so any
+`PromiseLike<unknown>` can open the gate.
 
 Create the promise outside render so React does not restart the gate effect on
 every render.
@@ -166,11 +166,11 @@ const loadAfter = Promise.all([airgapReady(), analyticsConsentPromise]);
 `}</TrackingScript>;
 ```
 
-### airgapReady
+### `airgapReady()` helper
 
-`airgapReady()` returns a `Promise<AirgapAPI>` that resolves when
-`self.airgap.ready(...)` fires. It is primarily intended for the `loadAfter` prop
-on `TrackingScript`.
+`airgapReady()` is a helper function that returns a `Promise<AirgapAPI>` that
+resolves when `self.airgap.ready(...)` fires. It is primarily intended for the
+`loadAfter` prop on `<TrackingScript>`.
 
 If airgap.js has not loaded yet, `airgapReady()` creates a ready-queue stub so
 the callback is drained when airgap.js initializes. For component logic, prefer
@@ -188,9 +188,9 @@ const airgapSyncPromise = airgapReady().then((airgap) => {
 <TrackingScript src="https://cdn.example.com/analytics.js" loadAfter={airgapSyncPromise} />;
 ```
 
-## ConsentBoundary
+## `<ConsentBoundary>` component
 
-`ConsentBoundary` is similar to
+`<ConsentBoundary>` is a React component similar to
 [`<Suspense>`](https://react.dev/reference/react/Suspense): it displays a
 fallback while work is pending, then reveals its children when they are ready.
 Instead of waiting for code or data, it waits until Airgap allows the URLs needed