@c15t/react 3.0.0-alpha.2 → 3.0.0-alpha.4

package/dist-types/hooks/use-committed-ref.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A ref that holds `value` from the render React most recently committed.
+ *
+ * Consent guards use it to answer "is this still the kernel, draft or IAB
+ * selection this component renders?" when a kept callback runs, including
+ * from a descendant's layout effect in the very commit that switched
+ * runtimes.
+ *
+ * Why an insertion effect: React runs insertion effects while it applies a
+ * commit, before any layout effect of that commit, and never for a render it
+ * discards. Assigning the ref during render would publish values from
+ * renders React throws away (an interrupted concurrent render, StrictMode's
+ * second render). A layout effect is too late, because descendants' layout
+ * effects run before their ancestors'. A passive effect is later still.
+ * Assigning the committed value is idempotent, so StrictMode's replayed
+ * effects cannot leave a stale value behind.
+ *
+ * @param value - The value this render uses.
+ * @returns A ref whose `current` is the last committed `value`.
+ * @internal
+ */
+export declare const useCommittedRef: <Value>(value: Value) => {
+    readonly current: Value;
+};

package/dist-types/hooks/use-focus-trap.d.ts

@@ -1,3 +1,4 @@
+import type { FocusTrapOptions } from '@c15t/ui/utils/dom';
 import type { RefObject } from 'react';
 /**
  * Hook that manages focus trapping within a container.
@@ -8,7 +9,8 @@ import type { RefObject } from 'react';
  *
  * @param shouldTrap - Boolean indicating whether focus should be trapped
  * @param containerRef - Reference to the container element
+ * @param options - Where the trap puts focus when it starts
  *
  * @public
  */
-export declare const useFocusTrap: (shouldTrap: boolean, containerRef: RefObject<HTMLElement | null> | null) => void;
+export declare const useFocusTrap: (shouldTrap: boolean, containerRef: RefObject<HTMLElement | null> | null, options?: FocusTrapOptions) => void;

package/dist-types/hooks.d.ts

@@ -17,7 +17,8 @@
  * observed through the selector hooks, whose subscription model handles
  * invalidation correctly.
  */
-import type { AllConsentNames, ConsentKernel, PromptPresentation, PreferencesPresentation, ConsentSnapshot, ConsentState, KernelActiveUI, KernelBranding, KernelIABState, KernelModel, KernelOverrides, KernelTranslations, KernelUser, LocationResponse, PolicyScopeMode, ResolvedVendor, VendorChoice } from '@c15t/core';
+import type { AllConsentNames, ConsentKernel, ConsentPresentation, ExperimentAssignment, PromptPresentation, PreferencesPresentation, ConsentSnapshot, ConsentState, KernelActiveUI, KernelBranding, KernelIABState, KernelModel, KernelOverrides, KernelTranslations, KernelUser, LocationResponse, PolicyScopeMode, ResolvedVendor, VendorChoice } from '@c15t/core';
+import type { Theme } from './types/theme/index.js';
 /**
  * Full snapshot accessor. Escape hatch for consumers that genuinely need
  * multiple slices. Prefer narrow hooks for re-render isolation.
@@ -65,6 +66,8 @@ export declare const useHasConsentPolicy: () => boolean;
  * {@link useHasConsentPolicy}.
  */
 export declare const useHasConsentUI: () => boolean;
+/** Whether c15t or an external CMP offers a preferences control. */
+export declare const useHasConsentPreferences: () => boolean;
 /**
  * Derived consent model (opt-in / opt-out / iab), or `null` while no policy
  * rule is resolved. The kernel keeps a safe fallback rule internally; this
@@ -106,14 +109,13 @@ export declare const useDeclaredVendors: () => readonly ResolvedVendor[];
  */
 export declare const useVendorChoice: () => Readonly<VendorChoice> | null;
 /**
- * Whether one vendor is allowed: its category condition passes and the
- * visitor has not turned it off.
+ * Whether one vendor may load: it is declared, its category condition
+ * passes, and outside IAB the visitor has not turned it off.
  *
- * @param vendorId - Vendor slug as declared in `vendors` or on a script.
- * @returns `false` while the vendor is denied outside `iab`, otherwise the
- * result of its declared category condition. An undeclared id is `true`:
- * nothing is known about its category, and a denial only exists for a vendor
- * the visitor saw.
+ * @param vendorId - Vendor id as declared in `vendors`, on a script or by
+ * the backend.
+ * @returns `true` while the vendor may load. An id nothing declares, such
+ * as a typo, returns `false` and logs a development warning.
  */
 export declare const useVendorAllowed: (vendorId: string) => boolean;
 /** Register categories used by scripts, frames, or other integrations. */
@@ -123,7 +125,21 @@ export declare const useRegisterConsentCategories: () => (categories: readonly A
  */
 export declare const useSetOverrides: () => (input: KernelOverrides) => void;
 /**
- * Sync mutation: switch active language.
+ * Switch the consent language and load its copy.
+ *
+ * Stores the language override and runs init again, so the banner and
+ * dialog show copy in that language: a hosted backend returns it, and
+ * offline mode takes it from the bundled translations and `i18n.messages`.
+ * Setting the current language does nothing. A disabled provider stores
+ * the language without running init.
+ *
+ * @returns A setter that takes a language code such as `'de'`.
+ *
+ * @example
+ * ```tsx
+ * const setLanguage = useSetLanguage();
+ * <button onClick={() => setLanguage('de')}>Deutsch</button>
+ * ```
  */
 export declare const useSetLanguage: () => (code: string) => void;
 /**
@@ -159,8 +175,6 @@ export declare const usePromptRequirement: () => ConsentSnapshot['promptRequirem
 export declare const useNoticeDismissal: () => ConsentSnapshot['noticeDismissal'];
 /** Read privacySignals from the kernel without a competing projection. */
 export declare const usePrivacySignals: () => ConsentSnapshot['privacySignals'];
-/** Read optOutDirectives from the kernel without a competing projection. */
-export declare const useOptOutDirectives: () => ConsentSnapshot['optOutDirectives'];
 /** Read resolution from the kernel without a competing projection. */
 export declare const usePolicyResolution: () => ConsentSnapshot['resolution'];
 /** Read policyRule from the kernel without a competing projection. */
@@ -169,7 +183,36 @@ export declare const usePolicyRule: () => ConsentSnapshot['policyRule'];
 export declare const useRestrictions: () => ConsentSnapshot['restrictions'];
 /** Dismiss the current local notice without recording a category choice. */
 export declare const useDismissNotice: () => ConsentKernel['commands']['dismissNotice'];
-/** Host first-layer presentation. */
+/**
+ * The presentation experiment arm this visitor runs. Built-in assignment
+ * lands after mount; a host-resolved `variant` is known at once.
+ *
+ * @returns The assignment, or `null` while no experiment is configured, the
+ * arm is not assigned yet, or the visitor's policy rejects it.
+ *
+ * @example
+ * ```tsx
+ * const arm = useExperiment();
+ * return arm ? <p>{arm.id}: {arm.variant}</p> : null;
+ * ```
+ */
+export declare const useExperiment: () => Readonly<ExperimentAssignment> | null;
+/**
+ * The host presentation with the assigned experiment arm merged over it.
+ *
+ * @returns The presentation to render: `options.presentation` itself while
+ * no arm is assigned.
+ */
+export declare const useResolvedPresentation: () => ConsentPresentation | undefined;
+/**
+ * The host theme with the assigned experiment arm's `theme` merged over it.
+ * Render its tokens with `<ConsentTheme theme={useResolvedTheme()} />`.
+ *
+ * @returns The theme to render: `options.theme` itself while no arm is
+ * assigned or the arm has no theme.
+ */
+export declare const useResolvedTheme: () => Theme | undefined;
+/** Host first-layer presentation, with the experiment arm applied. */
 export declare const usePromptPresentation: () => PromptPresentation;
-/** Host persistent preferences presentation. */
+/** Host persistent preferences presentation, with the experiment arm applied. */
 export declare const usePreferencesPresentation: () => PreferencesPresentation;

package/dist-types/iab.d.ts

@@ -1,5 +1,5 @@
 /**
- * IAB TCF 2.3 React components and hooks.
+ * IAB TCF 2.4 React components and hooks.
  *
  * This subpath export contains all IAB-specific React UI. It is only
  * loaded when explicitly imported from '@c15t/react/iab'.

package/dist-types/index.d.ts

@@ -48,14 +48,15 @@ export type { ConsentGateProps, FrameProps } from './components/consent-gate/ind
 export { ConsentGate, Frame } from './components/consent-gate/index.js';
 export type { ConsentDraftHandle, ConsentDraftProviderProps, VendorDraftHandle, } from './draft.js';
 export { ConsentDraftProvider, useConsentDraft, useVendorDraft } from './draft.js';
-export { useConsentManager } from './component-hooks/use-manager.js';
 export { useTranslations } from './component-hooks/use-translations.js';
-export { useActiveUI, useBranding, useConsent, useConsents, useHasConsentPolicy, useHasConsentUI, useIABEnabled, useIABSnapshot, useIdentify, useInit, useLocation, useModel, useOverrides, usePromptPresentation, usePolicyCategories, usePreferencesPresentation, usePolicyScopeMode, usePurposeConsent, useSaveConsents, useSetActiveUI, useSetLanguage, useSetOverrides, useSnapshot, useSpecialFeatureOptIn, useTCString, useUser, useDeclaredVendors, useVendorAllowed, useVendorChoice, useVendorConsent, } from './hooks.js';
+export { useActiveUI, useBranding, useConsent, useConsents, useExperiment, useHasConsentPolicy, useHasConsentPreferences, useHasConsentUI, useIABEnabled, useIABSnapshot, useIdentify, useInit, useLocation, useModel, useOverrides, usePromptPresentation, usePolicyCategories, usePreferencesPresentation, useResolvedPresentation, useResolvedTheme, usePolicyScopeMode, usePurposeConsent, useRegisterConsentCategories, useSaveConsents, useSetActiveUI, useSetLanguage, useSetOverrides, useSnapshot, useSpecialFeatureOptIn, useSubscribeToConsentChanges, useTCString, useUser, useDeclaredVendors, useVendorAllowed, useVendorChoice, useVendorConsent, } from './hooks.js';
 export type { UseIframeBlockerOptions, UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions, } from './module-hooks.js';
 export { useIframeBlocker, useNetworkBlocker, usePersistence, useScriptLoader, } from './module-hooks.js';
 export type { ConsentProviderOptions, ConsentProviderCallbacks, ConsentProviderPrefetch, ConsentProviderProps, ExternalRuntimeProviderOptions, ExternalRuntimeProviderProps, OwnedRuntimeProviderProps, } from './provider.js';
 export { ConsentProvider } from './provider.js';
+export { ConsentTheme } from './consent-theme.js';
+export type { ConsentThemeProps } from './consent-theme.js';
 export type { ReactUIOptions } from './types/manager.js';
 export { defineTheme, type Theme } from './types/theme/index.js';
-export { useExplicitChoice, useEffectivePermissions, usePromptRequirement, useNoticeDismissal, usePrivacySignals, useOptOutDirectives, usePolicyResolution, usePolicyRule, useRestrictions, useDismissNotice, } from './hooks.js';
+export { useExplicitChoice, useEffectivePermissions, usePromptRequirement, useNoticeDismissal, usePrivacySignals, usePolicyResolution, usePolicyRule, useRestrictions, useDismissNotice, } from './hooks.js';
 export type { ConsentPresentation, PromptPresentation, PreferencesPresentation, PresentationAction, PromptPosition, PromptVariant, ResolvedConsentPresentation, } from '@c15t/core';

package/dist-types/kernel-selector.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Kernel access for the hooks and the stock components. The component
+ * selectors below each read a single derived value, so a component
+ * re-renders only when that value changes. Not exported from any package
+ * entry.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+import type { AllConsentNames, ConsentKernel, ConsentSnapshot } from '@c15t/core';
+/**
+ * Reads the kernel from the nearest provider.
+ *
+ * @returns The provider's kernel.
+ * @throws {Error} When called outside a `ConsentProvider`.
+ * @internal
+ */
+export declare const useKernel: () => ConsentKernel;
+/**
+ * Subscribes to one slice of the kernel snapshot. React re-renders the
+ * caller only when the selected value `Object.is`-differs, so a selector
+ * must return a primitive or a reference the snapshot already holds.
+ *
+ * @param selector - Picks the slice from a snapshot.
+ * @returns The selected slice.
+ * @internal
+ */
+export declare const useKernelSelector: <SliceType>(selector: (snap: ConsentSnapshot) => SliceType) => SliceType;
+/**
+ * Like `useKernelSelector`, for selectors that evaluate a gate at a point in
+ * time. The server render and hydration evaluate at the snapshot's own
+ * `evaluatedAt`, so they never read the clock: a Next.js `cacheComponents`
+ * prerender rejects `Date.now()` in a Client Component. In the browser the
+ * gate is evaluated at `Date.now()`, so an expiry the kernel's deadline
+ * timer has not processed yet still denies.
+ *
+ * @param selector - Picks the slice from a snapshot at the given time.
+ * @returns The selected slice.
+ * @internal
+ */
+export declare const useGateSelector: <SliceType>(selector: (snap: ConsentSnapshot, now: number) => SliceType) => SliceType;
+/**
+ * Whether content gated on one category may render, with the kernel's gate
+ * semantics. Server rendering and hydration read no clock; see
+ * `useGateSelector`.
+ *
+ * @param category - Category the content needs.
+ * @returns `true` while the category is permitted.
+ * @internal
+ */
+export declare const useCategoryAllowed: (category: AllConsentNames) => boolean;
+/**
+ * Language of the active translation bundle.
+ *
+ * @returns The bundle's language, or the default language before one loads.
+ * @internal
+ */
+export declare const useTranslationLanguage: () => string;
+/**
+ * Categories the preference surface lists: `necessary` plus the recorded
+ * choice scope, or the policy scope when no choice scope applies.
+ *
+ * @returns A list whose identity changes only when the scope does.
+ * @internal
+ */
+export declare const useDisplayedCategories: () => readonly AllConsentNames[];

package/dist-types/module-hooks/iframe-blocker.d.ts

@@ -1,6 +1,33 @@
+import type { ConsentKernel } from '@c15t/core';
 import type { IframeBlockerHandle } from '@c15t/core/modules/iframe-blocker';
 export interface UseIframeBlockerOptions {
     disableAutomaticBlocking?: boolean;
 }
 export declare const useIframeBlocker: (options?: UseIframeBlockerOptions) => IframeBlockerHandle;
+/**
+ * Call `onFound` when a gated iframe is on the page: at once when one is
+ * there already, and again for each batch of gated frames that arrives.
+ *
+ * Until the returned stop function runs, a gated frame that arrives with a
+ * `src` the snapshot does not clearly allow is paused (`src` moved to
+ * `data-src`), as the loaded blocker would pause it. Frames on the page at
+ * the first call are left to the blocker, which is what happens when it
+ * loads with the provider.
+ *
+ * @param kernel - The kernel whose snapshot decides what is clearly allowed.
+ * @param onFound - Called for every sighting; the caller dedupes.
+ * @returns Stops watching.
+ * @internal
+ */
+export declare const watchGatedIframes: (kernel: ConsentKernel, onFound: () => void) => () => void;
+/**
+ * The provider's default iframe blocker. Loads the blocker module when the
+ * first gated iframe (`data-category` or `data-vendor`) is on the page
+ * instead of on every mount, so pages without one never download it.
+ *
+ * @param options - Blocker options. With `disableAutomaticBlocking` the
+ * module loads at once, as it did before.
+ * @internal
+ */
+export declare const useIframeBlockerOnDemand: (options?: UseIframeBlockerOptions) => void;
 export type { IframeBlockerHandle };

package/dist-types/module-hooks/network-blocker.d.ts

@@ -5,5 +5,28 @@ export interface UseNetworkBlockerOptions {
     logBlockedRequests?: boolean;
     onRequestBlocked?: (info: BlockedRequestInfo) => void;
 }
+/**
+ * Block `fetch` and XHR requests that match `rules` until the visitor's
+ * consent allows them.
+ *
+ * Blocking starts during the first render in the browser: matching requests
+ * wait from then on, including ones sent from this component's children's
+ * mount effects and from effects that run before this component's. The
+ * blocker loads after mount and decides each waiting request. On the
+ * server the hook does nothing.
+ *
+ * Rendering has a side effect: the first render patches `fetch` and
+ * `XMLHttpRequest` to hold matching requests. If React discards that
+ * render and never commits it, the hold ends after 10 seconds. Nothing
+ * checked consent for the requests it held, so they fail as blocked: a 451
+ * response for `fetch`, a failed XHR.
+ *
+ * Prefer the provider's `networkBlocker` option. It starts blocking when
+ * the provider renders, so it also covers components rendered before this
+ * one.
+ *
+ * @param options - Rules and logging options.
+ * @returns A handle to update rules or toggle blocking.
+ */
 export declare const useNetworkBlocker: (options: UseNetworkBlockerOptions) => NetworkBlockerHandle;
 export type { BlockedRequestInfo, NetworkBlockerHandle, NetworkBlockerRule };

package/dist-types/module-hooks/network-hold.d.ts

@@ -0,0 +1,47 @@
+import type { NetworkBlockerRule } from '@c15t/core/modules/network-blocker';
+import type { NetworkHold } from '@c15t/core/modules/network-hold';
+/**
+ * How long a hold started during render waits for its component to commit.
+ * A render React throws away never commits, so nothing else would end its
+ * hold. When this runs out the hold ends, and since nothing checked consent
+ * for the requests it held, they get the blocker's answer for a blocked
+ * request instead of being sent.
+ * @internal
+ */
+export declare const UNCOMMITTED_HOLD_MS = 10000;
+/**
+ * The render-time hold behind one network blocker mount.
+ * @internal
+ */
+export interface EarlyNetworkHold {
+    /**
+     * Call from the mount effect, before loading the blocker. Keeps the hold
+     * from expiring, starts a new one if it already ended (a StrictMode or
+     * kernel re-run after the blocker took over, or a commit that came after
+     * the expiry), and returns it for `createNetworkBlocker({ hold })`. A
+     * disabled blocker gets a hold that holds nothing, so it cannot end
+     * another caller's hold.
+     */
+    claim: (rules: readonly NetworkBlockerRule[], enabled: boolean | undefined) => NetworkHold;
+    /**
+     * Call from the mount effect's cleanup. Ends a hold no blocker took
+     * over, unless the effect runs again first (StrictMode, a kernel change).
+     * Nothing checked consent for what that hold held, so those requests get
+     * the blocker's answer for a blocked request instead of being sent.
+     */
+    unmount: () => void;
+}
+/**
+ * Hold requests matching `rules` from this component's first render in the
+ * browser, before any child renders or runs an effect. The network blocker
+ * loads after mount and takes the hold over.
+ *
+ * Rendering is not side-effect free: the first render patches `fetch` and
+ * `XMLHttpRequest`. That is safe because the hold only delays matching
+ * requests, a render React discards ends its hold after
+ * {@link UNCOMMITTED_HOLD_MS} (failing what it held as blocked), and on the
+ * server it does nothing.
+ *
+ * @internal
+ */
+export declare const useEarlyNetworkHold: (rules: readonly NetworkBlockerRule[], enabled: boolean | undefined) => EarlyNetworkHold;

package/dist-types/panel.d.ts

@@ -1 +1,13 @@
-export * from './components/panel/index.js';
+/**
+ * `@c15t/react/consent-dialog`: the deferred `ConsentDialog`, the same
+ * component the `@c15t/react` entry exports. Its implementation and styles
+ * load when the dialog first opens, or earlier when something preloads it,
+ * so importing this entry adds nothing heavy to the first load.
+ *
+ * The eager dialog and its individual parts (`Card`, `Header`, `Overlay`,
+ * ...) are in `@c15t/react/components/consent-dialog`.
+ *
+ * @packageDocumentation
+ */
+export { ConsentDialog } from './aggregate-components.js';
+export type { ConsentDialogCompoundComponent, ConsentDialogProps, } from './components/panel/index.js';

package/dist-types/postcss-tailwind3.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tailwind 3 PostCSS plugin for c15t stylesheets, re-exported from
+ * `@c15t/ui/postcss-tailwind3` so an app that installs `@c15t/react` can list
+ * `@c15t/react/postcss-tailwind3` without installing `@c15t/ui`.
+ * See `@c15t/ui/postcss-tailwind3` for what the plugin does. It must come
+ * before `tailwindcss`.
+ *
+ * @example
+ * ```js
+ * // postcss.config.mjs
+ * export default {
+ * 	plugins: {
+ * 		'@c15t/react/postcss-tailwind3': {},
+ * 		tailwindcss: {},
+ * 		autoprefixer: {},
+ * 	},
+ * };
+ * ```
+ */
+export * from '@c15t/ui/postcss-tailwind3';
+export { default } from '@c15t/ui/postcss-tailwind3';

package/dist-types/preferences.d.ts

@@ -1 +1,12 @@
-export * from './components/preferences/index.js';
+/**
+ * `@c15t/react/consent-widget`: the deferred `ConsentWidget`, the same
+ * component the `@c15t/react` entry exports. Its implementation and styles
+ * load when the widget first renders.
+ *
+ * The eager widget and its individual parts (`Accordion`, `Switch`, `Footer`,
+ * ...) are in `@c15t/react/components/consent-widget`.
+ *
+ * @packageDocumentation
+ */
+export { ConsentWidget } from './aggregate-components.js';
+export type { ConsentWidgetCompoundComponent, ConsentWidgetProps, } from './components/preferences/index.js';

package/dist-types/provider.d.ts

@@ -1,26 +1,39 @@
-import type { AllConsentNames, ClearOnRevocationConfig, ConsentPresentation, Callbacks, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
+import type { AllConsentNames, ClearOnRevocationConfig, ConsentExperiment, ExperimentState, ConsentPresentation, Callbacks, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } from '@c15t/core';
 import type { Script } from '@c15t/core/modules/script-loader';
-import type { ConsentRuntime } from '@c15t/core/runtime';
+import type { ConsentControlOptions, ConsentRuntime } from '@c15t/core/runtime';
 import type { ReactNode } from 'react';
+import type { DialogPreload } from './chunk-warming.js';
 import type { UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions } from './module-hooks.js';
 import type { UseIframeBlockerOptions } from './module-hooks/iframe-blocker.js';
 import type { ReactUIOptions } from './types/manager.js';
 import type { ReactComponentSlots } from './types/slots.js';
 /** Events emitted by the mounted provider without snapshot-derived consent aliases. */
-export type ConsentProviderCallbacks = Pick<Callbacks, 'onChoiceRecorded' | 'onPermissionsChanged' | 'onError'>;
-/** Prepared policy and records; legacy consent projections are not provider inputs. */
-export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'>;
-export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorScheme' | 'disableAnimation' | 'noStyle' | 'scrollLock' | 'theme' | 'trapFocus'> {
+export type ConsentProviderCallbacks = Pick<Callbacks, 'onChoiceRecorded' | 'onPermissionsChanged' | 'onSurfaceShown' | 'onError' | 'onBeforeConsentRevocationReload'>;
+/**
+ * Prepared policy and records; legacy consent projections are not provider
+ * inputs. An `experiment` a server helper resolved runs instead of
+ * `options.experiment`.
+ */
+export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'> & ExperimentState;
+export interface ConsentProviderOptions extends ConsentControlOptions, Pick<ReactUIOptions, 'colorScheme' | 'disableAnimation' | 'noStyle' | 'scrollLock' | 'theme' | 'trapFocus'> {
     enabled?: boolean;
     presentation?: ConsentPresentation;
+    /**
+     * A/B experiment on prompt/preferences presentation. The assigned arm is
+     * merged over `presentation`, exposed through `useExperiment()`, and
+     * recorded with every impression and choice. Initial-only: remount the
+     * provider to change the experiment.
+     */
+    experiment?: ConsentExperiment;
     /**
      * Content Security Policy nonce applied to DOM nodes c15t injects.
      *
      * @remarks
      * Set this when your CSP uses a nonce-based policy instead of
-     * `'unsafe-inline'`. The provider forwards it to the injected theme
-     * `<style>` element and to every `<script>` element created by the
-     * script loader. A per-script `nonce` still takes precedence.
+     * `'unsafe-inline'`. The provider forwards it to every `<script>`
+     * element created by the script loader. A per-script `nonce` still takes
+     * precedence. Pass the same nonce to `ConsentTheme`, which renders the
+     * theme `<style>` element.
      */
     nonce?: string;
     /**
@@ -83,6 +96,15 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
      * Initial-only: remount the provider to replace its cleanup configuration.
      */
     clearOnRevocation?: ClearOnRevocationConfig;
+    /**
+     * Reload the page after an accept, reject or save turns off a category or
+     * vendor that was granted, or after a `consentSource` withdraws one.
+     * Removing a script cannot stop code that already ran, so the reload
+     * starts a document with only permitted code. Waits for the save request.
+     * Set `false` to handle revocation yourself.
+     * @default true
+     */
+    reloadOnConsentRevoked?: boolean;
     scripts?: Script[];
     /**
      * Vendors offered for vendor-level consent outside IAB. Each sits inside a
@@ -94,7 +116,12 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
     vendors?: Vendor[];
     scriptLoader?: UseScriptLoaderOptions;
     networkBlocker?: UseNetworkBlockerOptions | false;
-    /** Discover and gate DOM iframes with data-category. Enabled by default. */
+    /**
+     * Discover and gate DOM iframes with data-category. Enabled by default.
+     * The blocker loads when the first gated iframe is on the page; until it
+     * runs, a gated iframe that arrives with a `src` consent does not allow
+     * is paused.
+     */
     iframeBlocker?: UseIframeBlockerOptions | false;
     persistence?: boolean | UsePersistenceOptions;
     i18n?: Partial<I18nConfig>;
@@ -103,6 +130,21 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
     /** Per-component slot attribute overrides (shared contract with @c15t/vue). */
     components?: ReactComponentSlots;
     legalLinks?: LegalLinks;
+    /**
+     * When the deferred `<ConsentDialog />` starts loading before it opens.
+     *
+     * - `'idle'` (default): after the page's load event, in browser idle time,
+     *   while the banner is shown or a button that opens the dialog is
+     *   mounted, and on hover or focus of such a button. Skipped when the
+     *   visitor has Save-Data on or a 2G-class connection.
+     * - `'intent'`: only on hover or focus of a button that opens the dialog.
+     *
+     * Neither loads the dialog on a visit that shows no banner and has no
+     * dialog trigger.
+     *
+     * @default 'idle'
+     */
+    preloadDialog?: DialogPreload;
     /**
      * Adapter package name reported by `window.c15t`.
      * @internal
@@ -116,13 +158,19 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
  * Everything the component tree still owns — theme, slots, legal links —
  * is unchanged.
  */
-export type ExternalRuntimeProviderOptions = Omit<ConsentProviderOptions, 'mode' | 'vendors'> & {
+export type ExternalRuntimeProviderOptions = Omit<ConsentProviderOptions, 'callbacks' | 'mode' | 'vendors'> & {
     mode?: ConsentProviderOptions['mode'];
     /**
      * Not accepted here: the runtime owner declares vendors through
      * `createConsentRuntime({ vendors })`, and the kernel carries them.
      */
     vendors?: never;
+    /**
+     * Not accepted here: the runtime owner passes callbacks to
+     * `createConsentRuntime({ callbacks })`, and the runtime runs them.
+     * Passing them anyway logs a warning in development.
+     */
+    callbacks?: never;
 };
 /** The provider builds and owns its own kernel. */
 export interface OwnedRuntimeProviderProps {
@@ -149,7 +197,9 @@ export type ConsentProviderProps = OwnedRuntimeProviderProps | ExternalRuntimePr
  * Pass `runtime` to render a runtime someone else created. The provider
  * then borrows its kernel and mounts none of the side-effecting modules —
  * no second `init()`, no second persistence handle, no second `window.c15t`
- * — and does not dispose it on unmount.
+ * — and does not dispose it on unmount. Handing it a different runtime
+ * switches the tree to that runtime's kernel; switching between a borrowed
+ * runtime and a provider-built kernel still needs a remount.
  *
  * @example
  * ```tsx

package/dist-types/server/headers.d.ts

@@ -1,5 +1,10 @@
-declare const FORWARDED_HEADERS: readonly ["x-c15t-country", "cf-ipcountry", "x-vercel-ip-country", "x-amz-cf-ipcountry", "x-country-code", "x-country", "x-c15t-region", "cf-region-code", "x-vercel-ip-country-region", "x-region-code", "accept-language", "x-c15t-gpc", "sec-gpc", "x-c15t-version", "user-agent", "x-forwarded-host", "x-forwarded-for", "purpose", "sec-purpose", "next-router-prefetch", "x-middleware-prefetch"];
-type ForwardedHeader = (typeof FORWARDED_HEADERS)[number];
+declare const FORWARDED_HEADERS: readonly ["x-c15t-country", "cf-ipcountry", "x-vercel-ip-country", "x-amz-cf-ipcountry", "x-country-code", "x-country", "x-c15t-region", "cf-region-code", "x-vercel-ip-country-region", "x-region-code", "accept-language", "x-c15t-gpc", "sec-gpc", "x-c15t-version", "user-agent", "x-forwarded-for", "purpose", "sec-purpose", "next-router-prefetch", "x-middleware-prefetch"];
+/**
+ * Forwarding headers a client can set to name a host or scheme. Passed to
+ * the backend only when the app trusts them.
+ */
+export declare const CLIENT_FORWARDING_HEADERS: readonly ['forwarded', 'x-forwarded-host', 'x-forwarded-proto'];
+type ForwardedHeader = (typeof FORWARDED_HEADERS)[number] | (typeof CLIENT_FORWARDING_HEADERS)[number];
 type RelevantHeaders = Partial<Record<ForwardedHeader, string>>;
 /**
  * Extracts relevant headers for consent management from the request headers.
@@ -12,10 +17,13 @@ type RelevantHeaders = Partial<Record<ForwardedHeader, string>>;
  * The extracted headers include:
  * - Country headers (cf-ipcountry, x-vercel-ip-country, etc.)
  * - Region headers (x-vercel-ip-country-region, x-region-code)
- * - Standard headers (accept-language, user-agent, x-forwarded-*)
+ * - Standard headers (accept-language, user-agent, x-forwarded-for)
  * - Prefetch headers (purpose, sec-purpose, next-router-prefetch, x-middleware-prefetch)
  *
  * @param headersList - The Headers object from the incoming request
+ * @param options - `trustForwardedHeaders` also copies `forwarded`,
+ * `x-forwarded-host` and `x-forwarded-proto`, which any client can send.
+ * Leave it off unless a proxy you control sets them and drops incoming ones.
  * @returns An object containing the relevant headers for consent management
  *
  * @example
@@ -28,5 +36,7 @@ type RelevantHeaders = Partial<Record<ForwardedHeader, string>>;
  *
  * @public
  */
-export declare const extractRelevantHeaders: (headersList: Headers) => RelevantHeaders;
+export declare const extractRelevantHeaders: (headersList: Headers, options?: {
+    trustForwardedHeaders?: boolean;
+}) => RelevantHeaders;
 export {};

package/dist-types/server/normalize-url.d.ts

@@ -21,16 +21,21 @@ export declare const validateBackendURL: (backendURL: string) => {
     normalizedURL: string;
 };
 /**
- * Normalizes a backend URL, resolving relative URLs using request headers.
+ * Normalizes a backend URL, resolving relative URLs against the request.
  *
  * @remarks
  * For absolute URLs, returns the URL as-is (with trailing slash trimmed).
- * For relative URLs, attempts to construct the full URL using:
- * 1. x-forwarded-proto + x-forwarded-host/host headers
- * 2. Referer header as fallback
+ * A relative URL resolves against the `host` header: over `https` for a
+ * domain name, and over `http` for `localhost`, an IP address or a
+ * single-label host. `x-forwarded-host`, `x-forwarded-proto` and `forwarded`
+ * are read only when `trustForwardedHeaders` is set, because any client can
+ * send them; the `referer` header is never used.
  *
  * @param backendURL - The backend URL (absolute or relative)
  * @param headersList - The Headers object from the incoming request
+ * @param options - `trustForwardedHeaders`: resolve against the request's
+ * forwarding headers. Set it only behind a proxy that sets them and drops
+ * incoming ones.
  * @returns The normalized absolute URL, or null if it cannot be determined
  *
  * @example
@@ -41,11 +46,13 @@ export declare const validateBackendURL: (backendURL: string) => {
  * normalizeBackendURL('https://api.example.com/', headers);
  * // Returns: 'https://api.example.com'
  *
- * // Relative URL - resolved from headers
+ * // Relative URL - resolved from the host header
  * normalizeBackendURL('/api/consent', headers);
- * // Returns: 'https://example.com/api/consent' (based on headers)
+ * // Returns: 'https://example.com/api/consent' (for `host: example.com`)
  * ```
  *
  * @public
  */
-export declare const normalizeBackendURL: (backendURL: string, headersList: Headers) => string | null;
+export declare const normalizeBackendURL: (backendURL: string, headersList: Headers, options?: {
+    trustForwardedHeaders?: boolean;
+}) => string | null;