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

package/dist-types/components/iab-panel/index.d.ts

@@ -10,6 +10,7 @@ import '@c15t/ui/styles/dialog';
 import type { FC } from 'react';
 import { IABConsentDialogCard } from './atoms/card.js';
 import { IABConsentDialogContent } from './atoms/content.js';
+import { FeatureItem } from './atoms/feature-item.js';
 import { IABConsentDialogFooter } from './atoms/footer.js';
 import { IABConsentDialogHeader } from './atoms/header.js';
 import { IABConsentDialogOverlay } from './atoms/overlay.js';
@@ -32,19 +33,20 @@ export interface IABConsentDialogCompoundComponent extends FC<IABConsentDialogPr
     Content: typeof IABConsentDialogContent;
     Footer: typeof IABConsentDialogFooter;
     Overlay: typeof IABConsentDialogOverlay;
+    FeatureItem: typeof FeatureItem;
     PurposeItem: typeof PurposeItem;
     StackItem: typeof StackItem;
     VendorList: typeof VendorList;
 }
 /**
- * IAB TCF 2.3 compliant consent dialog dialog component.
+ * IAB TCF 2.4 compliant consent dialog dialog component.
  *
  * @remarks
  * This component serves as the main entry point for rendering an IAB-compliant consent dialog.
  * It provides a structured layout with required IAB TCF elements.
  *
  * Key features:
- * - IAB TCF 2.3 compliant
+ * - IAB TCF 2.4 compliant
  * - Fully accessible by default
  * - Customizable appearance
  * - Compound component pattern support
@@ -79,6 +81,7 @@ declare const IABConsentDialog: IABConsentDialogCompoundComponent;
 export default IABConsentDialog;
 export { IABConsentDialogCard } from './atoms/card.js';
 export { IABConsentDialogContent } from './atoms/content.js';
+export { FeatureItem, type FeatureItemProps } from './atoms/feature-item.js';
 export { IABConsentDialogFooter } from './atoms/footer.js';
 export { IABConsentDialogHeader } from './atoms/header.js';
 export { IABConsentDialogOverlay } from './atoms/overlay.js';

package/dist-types/components/iab-panel/use-iab-translations.d.ts

@@ -45,6 +45,10 @@ interface IABTranslations {
             title: string;
             tooltip: string;
         };
+        features: {
+            title: string;
+            description: string;
+        };
         vendorList: {
             search: string;
             showingCount: string;

package/dist-types/components/iab-prompt/iab-prompt.d.ts

@@ -42,10 +42,10 @@ export interface IABConsentBannerProps {
     uiSource?: string;
 }
 /**
- * IAB TCF 2.3 compliant cookie consent banner.
+ * IAB TCF 2.4 compliant cookie consent banner.
  *
  * @remarks
- * This component implements the required IAB TCF 2.3 UI elements:
+ * This component implements the required IAB TCF 2.4 UI elements:
  * - Partner count disclosure
  * - Purpose summary
  * - Legitimate interest notice

package/dist-types/components/iab-prompt/index.d.ts

@@ -32,14 +32,14 @@ export interface IABConsentBannerCompoundComponent extends FC<IABConsentBannerPr
     Overlay: typeof IABConsentBannerOverlay;
 }
 /**
- * IAB TCF 2.3 compliant cookie consent banner component.
+ * IAB TCF 2.4 compliant cookie consent banner component.
  *
  * @remarks
  * This component serves as the main entry point for rendering an IAB-compliant consent banner.
  * It provides a structured layout with required IAB TCF elements.
  *
  * Key features:
- * - IAB TCF 2.3 compliant
+ * - IAB TCF 2.4 compliant
  * - Fully accessible by default
  * - Customizable appearance
  * - Compound component pattern support

package/dist-types/components/panel/atoms/card.d.ts

@@ -25,6 +25,7 @@ declare const ConsentDialogHeader: import("react").ForwardRefExoticComponent<Omi
  * - Uses proper heading semantics for accessibility
  * - Should be used within ConsentDialogHeader
  * - Supports theme customization
+ * - Renders an `h2`; with `asChild` the child element takes its place
  */
 declare const ConsentDialogHeaderTitle: import("react").ForwardRefExoticComponent<Omit<BoxProps, "slotKey"> & import("react").RefAttributes<HTMLDivElement>>;
 /**

package/dist-types/components/prompt/components.d.ts

@@ -16,12 +16,18 @@ export type ConsentBannerRight = Exclude<PolicyRight, 'disclosure'>;
  * @remarks
  * Provides the main heading for the consent notice.
  * Implements proper heading semantics and supports theming.
+ * Renders an `h2`. With `asChild`, the child element, such as an `h1`,
+ * takes its place and receives the title's class and attributes.
  *
  * @example
  * ```tsx
  * <ConsentBannerTitle>
  *   Cookie Preferences
  * </ConsentBannerTitle>
+ *
+ * <ConsentBannerTitle asChild>
+ *   <h1>Cookie Preferences</h1>
+ * </ConsentBannerTitle>
  * ```
  */
 declare const ConsentBannerTitle: import("react").ForwardRefExoticComponent<Omit<BoxProps, "slotKey"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist-types/components/shared/libs/compose-refs.d.ts

@@ -0,0 +1,20 @@
+import type { Ref, RefCallback } from 'react';
+/**
+ * Combine refs so one element fills all of them.
+ *
+ * @param refs - Callback refs, object refs, or `undefined`.
+ * @returns A callback ref that calls or assigns each ref in order.
+ * @internal
+ */
+export declare const composeRefs: <ElementType>(...refs: (Ref<ElementType> | undefined)[]) => RefCallback<ElementType>;
+/**
+ * {@link composeRefs} for two refs, with a stable identity while they stay
+ * the same, so React does not detach and reattach the element on every
+ * render.
+ *
+ * @param first - A callback ref, object ref, or `undefined`.
+ * @param second - A callback ref, object ref, or `undefined`.
+ * @returns A memoized callback ref.
+ * @internal
+ */
+export declare const useComposedRefs: <ElementType>(first: Ref<ElementType> | undefined, second: Ref<ElementType> | undefined) => RefCallback<ElementType>;

package/dist-types/components/shared/ui/icon.d.ts

@@ -1,6 +1,7 @@
 import type { ElementType, JSX, SVGProps } from 'react';
 type LucideIconProps = SVGProps<SVGSVGElement> & {
-    title: string;
+    /** Omit for a decorative icon that must add nothing to an accessible name. */
+    title?: string;
     iconPath: JSX.Element;
 };
 export declare const LucideIcon: ({ title, iconPath }: LucideIconProps) => ElementType;

package/dist-types/context/consent-tracking-context.d.ts

@@ -1,3 +1,4 @@
+import type { SaveUISource } from '@c15t/core';
 /**
  * Value provided by the ConsentTrackingContext.
  *
@@ -30,3 +31,12 @@ export declare const ConsentTrackingContext: import("react").Context<ConsentTrac
  * @public
  */
 export declare const useConsentTracking: () => ConsentTrackingValue;
+/**
+ * Narrow a tracking `uiSource` to a value the kernel records. Custom labels
+ * fall back to the kernel's `activeUI` attribution.
+ *
+ * @param value - The `uiSource` from props or context.
+ * @returns A kernel save source, or `undefined` to keep the default.
+ * @public
+ */
+export declare const toSaveUISource: (value: string | undefined) => SaveUISource | undefined;

package/dist-types/context/theme-context.d.ts

@@ -41,10 +41,10 @@ export interface ThemeContextValue {
      */
     trapFocus?: boolean;
     /**
-     * Color scheme preference.
+     * Color scheme preference. `null` when the provider leaves the class alone.
      * @default 'system'
      */
-    colorScheme?: 'light' | 'dark' | 'system';
+    colorScheme?: 'light' | 'dark' | 'system' | null;
 }
 /**
  * Context for providing theme values to components.

package/dist-types/context.d.ts

@@ -13,5 +13,11 @@ export interface ProviderServices {
     clearRecords: () => void;
     getPresentation: () => ConsentPresentation | undefined;
     getConsentCategories: () => readonly AllConsentNames[];
+    /**
+     * Store a language override and load its copy: init runs again on the
+     * provider's own kernel while it is enabled, and a borrowed runtime
+     * reinitializes itself.
+     */
+    setLanguage: (code: string) => void;
 }
 export declare const ProviderServicesContext: import("react").Context<ProviderServices | null>;

package/dist-types/devtools.d.ts

@@ -15,7 +15,7 @@ export type DevToolsProps = ConsentDevToolsProps;
  * @param props - Presentation options passed to the DevTools engine.
  * @returns `null`; the engine mounts its interface into `document.body`.
  */
-export declare const ConsentDevTools: ({ disabled, clearRecords, getPresentation, defaultOpen, defaultTab, getConsentCategories, maxEvents, position, }: ConsentDevToolsProps) => null;
+export declare const ConsentDevTools: ({ disabled, clearRecords, getPresentation, defaultOpen, defaultTab, getConsentCategories, maxEvents, position, shadow, }: ConsentDevToolsProps) => null;
 /** Compatible short name for {@link ConsentDevTools}. */
 export declare const DevTools: typeof ConsentDevTools;
 /** Backward-compatible name for {@link ConsentDevTools}. */
@@ -24,13 +24,24 @@ export declare const C15TDevTools: typeof ConsentDevTools;
 export interface C15tTanStackDevtoolsPanelProps extends HTMLAttributes<HTMLDivElement>, Pick<DevToolsOptions, 'defaultTab' | 'maxEvents' | 'getConsentCategories' | 'getPresentation' | 'clearRecords'> {
     /** Prevents the embedded DevTools engine from mounting. @default false */
     disabled?: boolean;
+    /**
+     * Color scheme of the surrounding devtools shell. Omit to follow the
+     * operating system. {@link c15tDevtools} passes TanStack's theme.
+     */
+    theme?: TanStackDevtoolsTheme;
+}
+/** Color scheme TanStack Devtools passes to plugin panels. */
+export type TanStackDevtoolsTheme = 'light' | 'dark';
+/** Props React TanStack Devtools passes to a plugin's render function. */
+export interface TanStackDevtoolsPluginProps {
+    theme?: TanStackDevtoolsTheme;
 }
 /** Plugin configuration accepted by React TanStack Devtools. */
 export interface TanStackDevtoolsPlugin {
     id?: string;
     name: string;
     defaultOpen?: boolean;
-    render: ReactElement;
+    render: (element: HTMLElement, props?: TanStackDevtoolsPluginProps | TanStackDevtoolsTheme) => ReactElement;
 }
 /** Options for {@link c15tDevtools}. */
 export interface C15tDevtoolsPluginOptions extends C15tTanStackDevtoolsPanelProps {

package/dist-types/draft.d.ts

@@ -1,4 +1,4 @@
-import type { AllConsentNames, ConsentKernel, ConsentState, SaveResult, SaveInput } from '@c15t/core';
+import type { AllConsentNames, ConsentKernel, ConsentState, SaveResult, SaveInput, SaveUISource } from '@c15t/core';
 import type { ReactNode } from 'react';
 /** A local, unmasked selection, committed only by an explicit save. */
 export interface ConsentDraftHandle {
@@ -34,7 +34,7 @@ interface DraftSnapshot {
     isDirty: boolean;
     isStale: boolean;
 }
-declare const createDraftStore: (kernel: ConsentKernel, defaults?: Partial<ConsentState>) => {
+declare const createDraftStore: (kernel: ConsentKernel, initialDefaults?: Partial<ConsentState>) => {
     acceptAll(): void;
     connect(): import("@c15t/core").Unsubscribe;
     getSnapshot: () => DraftSnapshot;
@@ -42,8 +42,14 @@ declare const createDraftStore: (kernel: ConsentKernel, defaults?: Partial<Conse
     kernel: ConsentKernel;
     rejectAll(): void;
     reset: () => void;
-    save(input?: SaveInput, categories?: readonly AllConsentNames[], onSuccess?: () => void): Promise<SaveResult>;
+    save(input?: SaveInput, categories?: readonly AllConsentNames[], onSuccess?: () => void, uiSource?: SaveUISource): Promise<SaveResult>;
     set(category: AllConsentNames, value: boolean): void;
+    /**
+     * Replace the defaults a category without a receipt seeds from. A
+     * clean draft reseeds at once, so an experiment arm assigned after
+     * mount shows its own defaults; edits the visitor already made stay.
+     */
+    setDefaults(next: Partial<ConsentState> | undefined): void;
     setVendor(vendorId: string, granted: boolean): void;
     subscribe(listener: () => void): () => void;
     update: (patch: Partial<ConsentState>) => void;
@@ -56,7 +62,7 @@ export interface ConsentDraftProviderProps {
 }
 export declare const ConsentDraftProvider: ({ children, initial, }: ConsentDraftProviderProps) => import("react").JSX.Element;
 /** Internal UI save path shared by stock controls and headless actions. */
-export declare const useConsentSaveAction: () => (input?: SaveInput) => Promise<SaveResult>;
+export declare const useConsentSaveAction: () => (input?: SaveInput, uiSource?: SaveUISource) => Promise<SaveResult>;
 /**
  * The nearest consent draft store, for the stock preference rows. Pair with
  * {@link useConsentDraftSlice} so a row re-renders only when its own slice

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.
@@ -108,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. */
@@ -125,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;
 /**
@@ -161,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. */
@@ -171,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

@@ -49,7 +49,7 @@ 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 { useTranslations } from './component-hooks/use-translations.js';
-export { useActiveUI, useBranding, useConsent, useConsents, useHasConsentPolicy, useHasConsentPreferences, useHasConsentUI, useIABEnabled, useIABSnapshot, useIdentify, useInit, useLocation, useModel, useOverrides, usePromptPresentation, usePolicyCategories, usePreferencesPresentation, usePolicyScopeMode, usePurposeConsent, useRegisterConsentCategories, useSaveConsents, useSetActiveUI, useSetLanguage, useSetOverrides, useSnapshot, useSpecialFeatureOptIn, useSubscribeToConsentChanges, 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';
@@ -58,5 +58,5 @@ 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/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/provider.d.ts

@@ -1,4 +1,4 @@
-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 { ConsentControlOptions, ConsentRuntime } from '@c15t/core/runtime';
 import type { ReactNode } from 'react';
@@ -8,12 +8,23 @@ 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' | 'onBeforeConsentRevocationReload'>;
-/** Prepared policy and records; legacy consent projections are not provider inputs. */
-export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'>;
+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.
      *
@@ -147,13 +158,19 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
  * 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 {

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;

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

@@ -12,9 +12,20 @@ import type { Overrides, SSRInitialData } from '@c15t/core';
 export interface FetchSSRDataOptionsBase {
     /**
      * The backend URL to fetch consent data from.
-     * Can be absolute (https://...) or relative (/api/consent).
+     * Can be absolute (https://...) or relative (/api/consent). A relative
+     * URL resolves against the request's `host` header.
      */
     backendURL: string;
+    /**
+     * Resolve a relative `backendURL` against the request's `forwarded`,
+     * `x-forwarded-host` and `x-forwarded-proto` headers instead of `host`.
+     * Any client can send those headers, so set this only behind a proxy
+     * that sets them and drops incoming ones. Also forwards those three
+     * headers to the backend, which is skipped otherwise.
+     *
+     * @default false
+     */
+    trustForwardedHeaders?: boolean;
     /**
      * Optional overrides for geo-location.
      */

package/dist-types/transports/offline.d.ts

@@ -1,18 +1,9 @@
-import type { ProviderTransportFactory } from '@c15t/core';
-import type { PolicyRule } from '@c15t/schema/types';
-/** Policy rules evaluated locally when initialization runs. */
-export interface OfflineModeOptions {
-    /**
-     * Rules to resolve locally. Omit them to use `recommendedPolicyRules()`:
-     * strict opt-in for Europe, the UK, Quebec and unknown locations, opt-out
-     * for the US states with a privacy law, and `none` everywhere else.
-     * Passing rules replaces that pack entirely.
-     */
-    policyRules?: PolicyRule[];
-}
 /**
- * Resolve local rules outside render and hydration.
- * @param options - Explicit policy rules; absence resolves the recommended pack.
- * @returns A provider transport with no network requests.
+ * Offline mode for the React provider: core's `offline()`, which resolves
+ * policy rules locally and switches copy when `overrides.language` or
+ * `useSetLanguage()` names a language the bundle or `i18n.messages` has.
+ * The language a server prefetch detected from `Accept-Language` keeps the
+ * startup copy.
  */
-export declare const offline: (options?: OfflineModeOptions) => ProviderTransportFactory;
+export { offline } from '@c15t/core';
+export type { OfflineModeOptions } from '@c15t/core';

package/dist-types/ui-config-context.d.ts

@@ -1,9 +1,15 @@
-import type { LegalLinks, ConsentPresentation } from '@c15t/core';
+import type { ConsentExperiment, ConsentPresentation, LegalLinks } from '@c15t/core';
 import type { DialogPreload } from './chunk-warming.js';
 import type { ReactComponentSlots } from './types/slots.js';
+import type { Theme } from './types/theme/index.js';
 export interface V3UIConfigValue {
     components?: ReactComponentSlots;
+    /** The host's base presentation, before any experiment arm is applied. */
     presentation?: ConsentPresentation;
+    /** The configured experiment; the assigned arm lives on the snapshot. */
+    experiment?: ConsentExperiment;
+    /** The host's base theme, before any experiment arm is applied. */
+    theme?: Theme;
     legalLinks?: LegalLinks;
     preloadDialog?: DialogPreload;
 }