@c15t/react 3.0.0-alpha.1 → 3.0.0-alpha.11

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

@@ -1,6 +1,38 @@
-import type { IframeBlockerHandle } from '@c15t/core/modules/iframe-blocker';
+import type { ConsentKernel } from '@c15t/core';
+import type { IframeBlockerHandle, IframeBlockerOptions } 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 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. Until then it
+ * pauses gated frames that arrive with a `src` consent does not allow.
+ *
+ * Passed to the provider runtime as its `createIframeBlocker` module.
+ *
+ * @param options - The kernel and blocker options. With
+ * `disableAutomaticBlocking` the module loads at once.
+ * @returns A handle; `processAllIframes()` reaches the blocker once it has
+ * loaded.
+ * @internal
+ */
+export declare const createIframeBlockerOnDemand: ({ disableAutomaticBlocking, kernel, }: IframeBlockerOptions) => IframeBlockerHandle;
 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/module-hooks.d.ts

@@ -1,4 +1,4 @@
-export { type IframeBlockerHandle, type UseIframeBlockerOptions, useIframeBlocker, } from './module-hooks/iframe-blocker';
-export { type BlockedRequestInfo, type NetworkBlockerHandle, type NetworkBlockerRule, type UseNetworkBlockerOptions, useNetworkBlocker, } from './module-hooks/network-blocker';
-export { type PersistenceHandle, type PersistenceOptions, type UsePersistenceOptions, usePersistence, } from './module-hooks/persistence';
-export { type Script, type ScriptLoaderDebugEvent, type ScriptLoaderHandle, type UseScriptLoaderOptions, useScriptLoader, } from './module-hooks/script-loader';
+export { type IframeBlockerHandle, type UseIframeBlockerOptions, useIframeBlocker, } from './module-hooks/iframe-blocker.js';
+export { type BlockedRequestInfo, type NetworkBlockerHandle, type NetworkBlockerRule, type UseNetworkBlockerOptions, useNetworkBlocker, } from './module-hooks/network-blocker.js';
+export { type PersistenceHandle, type PersistenceOptions, type UsePersistenceOptions, usePersistence, } from './module-hooks/persistence.js';
+export { type Script, type ScriptLoaderDebugEvent, type ScriptLoaderHandle, type UseScriptLoaderOptions, useScriptLoader, } from './module-hooks/script-loader.js';

package/dist-types/panel-link.d.ts

@@ -1 +1 @@
-export * from './components/panel-link';
+export { ConsentDialogLink, type ConsentDialogLinkProps, } from './components/panel-link/index.js';

package/dist-types/panel-trigger.d.ts

@@ -1 +1 @@
-export * from './components/panel-trigger';
+export { ConsentDialogTrigger, type ConsentDialogTriggerCompound, type ConsentDialogTriggerProps, ConsentDialogTriggerToolbar, type ConsentDialogTriggerToolbarAction, type ConsentDialogTriggerToolbarPreferences, type ConsentDialogTriggerToolbarProps, type CornerPosition, TriggerButton, type TriggerButtonProps, TriggerIcon, type TriggerIconProps, type TriggerIconType, type TriggerOrientation, TriggerRoot, type TriggerRootProps, type TriggerSize, TriggerText, type TriggerTextProps, type TriggerVisibility, type UseDraggableOptions, type UseDraggableReturn, useDraggable, useTriggerContext, } from './components/panel-trigger/index.js';

package/dist-types/panel.d.ts

@@ -1 +1,13 @@
-export * from './components/panel';
+/**
+ * `@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';
+/**
+ * `@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/primitives/accordion.d.ts

@@ -1 +1 @@
-export * from '../components/shared/ui/accordion';
+export * from '../components/shared/ui/accordion/index.js';

package/dist-types/primitives/button.d.ts

@@ -1 +1 @@
-export * from '../components/shared/ui/button';
+export * from '../components/shared/ui/button/index.js';

package/dist-types/primitives/collapsible.d.ts

@@ -1 +1 @@
-export * from '../components/shared/ui/collapsible';
+export * from '../components/shared/ui/collapsible/index.js';

package/dist-types/primitives/dialog.d.ts

@@ -1 +1 @@
-export * from '../components/shared/ui/dialog';
+export * from '../components/shared/ui/dialog/index.js';

package/dist-types/primitives/preference-item.d.ts

@@ -1 +1 @@
-export * from '../components/shared/ui/preference-item';
+export * from '../components/shared/ui/preference-item/index.js';

package/dist-types/primitives/switch.d.ts

@@ -1 +1 @@
-export * from '../components/shared/ui/switch';
+export * from '../components/shared/ui/switch/index.js';

package/dist-types/primitives/tabs.d.ts

@@ -1 +1 @@
-export * from '../components/shared/ui/tabs';
+export * from '../components/shared/ui/tabs/index.js';

package/dist-types/primitives.d.ts

@@ -1,7 +1,7 @@
-export * as Accordion from './components/shared/ui/accordion';
-export * as Button from './components/shared/ui/button';
-export * as Collapsible from './components/shared/ui/collapsible';
-export * as Dialog from './components/shared/ui/dialog';
-export * as PreferenceItem from './components/shared/ui/preference-item';
-export * as Switch from './components/shared/ui/switch';
-export * as Tabs from './components/shared/ui/tabs';
+export * as Accordion from './components/shared/ui/accordion/index.js';
+export * as Button from './components/shared/ui/button/index.js';
+export * as Collapsible from './components/shared/ui/collapsible/index.js';
+export * as Dialog from './components/shared/ui/dialog/index.js';
+export * as PreferenceItem from './components/shared/ui/preference-item/index.js';
+export * as Switch from './components/shared/ui/switch/index.js';
+export * as Tabs from './components/shared/ui/tabs/index.js';

package/dist-types/prompt.d.ts

@@ -1 +1 @@
-export * from './components/prompt';
+export * from './components/prompt/index.js';

package/dist-types/provider.d.ts

@@ -1,27 +1,68 @@
-import type { AllConsentNames, ClearOnRevocationConfig, ConsentPresentation, Callbacks, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User } from '@c15t/core';
+import type { AllConsentNames, Callbacks, ClearOnRevocationConfig, ConsentExperiment, ConsentJourneyOption, ConsentPresentation, ExperimentState, JourneyState, 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 } from '@c15t/core/runtime';
+import type { ConsentRuntime, ConsentRuntimeModules, ResolveStreamedInit } from '@c15t/core/runtime/provider';
 import type { ReactNode } from 'react';
-import type { UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions } from './module-hooks';
-import type { ReactUIOptions } from './types/manager';
-import type { ReactComponentSlots } from './types/slots';
+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`, and a `journey` it started is the one the provider
+ * continues.
+ */
+export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'> & ExperimentState & JourneyState;
+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;
+    /**
+     * Random journey id that links each `/init` to the save that follows:
+     * `'page'`, `'tab'` or `false`. Initial-only.
+     *
+     * @default 'page'
+     */
+    journey?: ConsentJourneyOption;
     /**
      * 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, and to the `<style>` elements
+     * the stock surfaces render. A per-script `nonce` still takes
+     * precedence. Pass the same nonce to `ConsentTheme`, which renders the
+     * theme `<style>` element.
      */
     nonce?: string;
+    /**
+     * Whether the stock surfaces render their own stylesheets.
+     *
+     * @remarks
+     * The banner, dialog trigger, ConsentGate, dialog and preference widget
+     * each render the c15t rules they use as a `<style>` element: in the
+     * server-rendered HTML, or with the surface's own code in the browser.
+     * No c15t stylesheet `<link>` then holds back the page's first paint.
+     * React 19 moves them into `<head>` and renders each once. They carry
+     * {@link ConsentProviderOptions.nonce}.
+     *
+     * Set `false` when the app imports `styles.css` itself, for example to
+     * run it through Tailwind CSS 3 or to put it in a named cascade layer.
+     *
+     * @default true
+     */
+    styles?: boolean;
     /**
      * Transport factory the provider builds its kernel with. Required.
      *
@@ -34,7 +75,7 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
      * ```tsx
      * import { ConsentProvider, hosted, offline } from '@c15t/react';
      *
-     * <ConsentProvider options={{ mode: hosted({ url: '/api/c15t' }) }}>
+     * <ConsentProvider options={{ mode: hosted({ backendURL: '/api/c15t' }) }}>
      *   {children}
      * </ConsentProvider>
      *
@@ -42,6 +83,12 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
      * ```
      */
     mode: ProviderTransportFactory;
+    /**
+     * Where the visitor's choice is stored. Read once, like `persistence`:
+     * the stored records and the data clearing that protects them stay at
+     * the location the provider mounted with. Outside production, a change
+     * logs a warning; remount the provider to move storage.
+     */
     storageConfig?: StorageConfig;
     user?: User | KernelUser;
     overrides?: KernelOverrides;
@@ -56,9 +103,12 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
      * Pass the pending `Promise<KernelConfig>` instead and the provider
      * mounts at once with a provisional policy, so `children` render (and
      * the static shell can prerender) while the consent data streams in.
-     * Consent surfaces stay hidden until the promise resolves; its first
-     * `init()` then applies the resolved config in place of the transport's
-     * network init. A config that resolves without a policy (persisted
+     * Consent surfaces stay hidden until the promise resolves. On the
+     * server, `ConsentBanner` waits for it in its own Suspense boundary and
+     * follows the page in a later chunk of the same response, before
+     * hydration, when the resolved policy shows a banner; see
+     * `streamBanner`. The resolved config then answers the first `init()`
+     * in place of the transport's network init. A config that resolves without a policy (persisted
      * consents, geo, language only) is applied to the kernel and the
      * transport init runs as usual; a rejected promise is logged outside
      * production and falls through to the transport init. Initial-only:
@@ -69,33 +119,109 @@ export interface ConsentProviderOptions extends Pick<ReactUIOptions, 'colorSchem
      * // app/layout.tsx — stays synchronous, so the shell prerenders.
      * const config = resolveConsent({ backendURL });
      * return (
-     *   <ConsentProvider options={{ mode: hosted({ url }), prefetch: config }}>
+     *   <ConsentProvider options={{ mode: hosted({ backendURL }), prefetch: config }}>
      *     {children}
      *   </ConsentProvider>
      * );
      * ```
      */
     prefetch?: ConsentProviderPrefetch | Promise<ConsentProviderPrefetch>;
+    /**
+     * Whether `ConsentBanner` renders on the server once a `prefetch`
+     * promise resolves, so it arrives in the streamed response before the
+     * page hydrates. It shows only when the resolved policy shows a banner
+     * for this visitor. Set `false` to mount the banner after hydration
+     * instead, as with a client-only provider. No effect when `prefetch` is
+     * not a promise. Use the same value on the server and in the browser.
+     *
+     * @default true
+     */
+    streamBanner?: boolean;
     callbacks?: ConsentProviderCallbacks;
     /**
      * Remove configured browser data when its consent permission is revoked.
      * 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
+     * category; a visitor can grant the category and still turn one vendor
+     * off. Scripts, network rules and iframes name a vendor through `vendor`
+     * or `data-vendor`. Merged with vendors the backend returns and with slugs
+     * found on scripts and rules; presentation declared here wins.
+     */
+    vendors?: Vendor[];
     scriptLoader?: UseScriptLoaderOptions;
     networkBlocker?: UseNetworkBlockerOptions | false;
+    /**
+     * 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;
+    /**
+     * Store the visitor's choice in a cookie and localStorage. On by default.
+     * Read once, when the provider mounts; see `storageConfig`.
+     */
     persistence?: boolean | UsePersistenceOptions;
     i18n?: Partial<I18nConfig>;
+    /** Categories to offer alongside discovered integration categories, within policy scope. */
     consentCategories?: AllConsentNames[];
     /** 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
      */
     __debugPkg?: string;
+    /**
+     * The code that applies a `prefetch` promise, from
+     * `@c15t/core/runtime/streamed-init`. Without it the provider loads that
+     * code once `prefetch` is a promise, so an app that never streams one
+     * doesn't download it. A framework root whose state is usually streamed
+     * (`ConsentRoot`) passes it, so the state applies as soon as it arrives
+     * instead of after one more request. Read once, at mount.
+     * @internal
+     */
+    __resolveStreamedInit?: ResolveStreamedInit;
+    /**
+     * `preloadScriptLoaderWith` from
+     * `@c15t/core/runtime/script-loader-preload`. With it the runtime starts
+     * the script loader's download during the first render when consent
+     * already lets a script run, instead of from the mount effect. A
+     * framework root whose state usually holds a returning visitor's choice
+     * (`ConsentRoot`) passes it; without it the provider ships none of that
+     * decision. Read once, at mount.
+     * @internal
+     */
+    __preloadScriptLoader?: (load: () => Promise<unknown>) => ConsentRuntimeModules['preloadScriptLoader'];
 }
 /**
  * Options accepted when an external runtime supplies the kernel.
@@ -104,8 +230,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'> & {
+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 {
@@ -122,23 +259,27 @@ export type ConsentProviderProps = OwnedRuntimeProviderProps | ExternalRuntimePr
 /**
  * v3 ConsentProvider.
  *
- * Retains the enabled kernel while disabled mode uses a separate permissive
- * kernel, so toggling enabled preserves recorded choices. Provides the active
- * kernel via context and wires the curated v2-like options surface to v3
- * modules. It does not mirror the
- * snapshot into React state; selector hooks still subscribe directly to
- * the kernel through `useSyncExternalStore`.
+ * Builds one consent runtime (`createConsentProviderRuntime`) per mounted
+ * provider and renders its kernel: the kernel goes into context, and
+ * selector hooks subscribe to it through `useSyncExternalStore`. New
+ * options reach the runtime through `update()`, which applies only what
+ * changed; `mode`, `i18n`, `experiment`, `prefetch`, `persistence`,
+ * `storageConfig` and `clearOnRevocation` are read once. While `enabled` is
+ * `false` the runtime renders a separate permissive kernel, so toggling it
+ * keeps the visitor's records.
  *
  * 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.
+ * then borrows its kernel and starts nothing — no second `init()`, no
+ * second persistence handle, no second `window.c15t` — 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 one still needs a remount.
  *
  * @example
  * ```tsx
  * import { createConsentRuntime } from '@c15t/core/runtime';
  *
- * const runtime = createConsentRuntime({ mode: hosted({ url: '/api/c15t' }) });
+ * const runtime = createConsentRuntime({ mode: hosted({ backendURL: '/api/c15t' }) });
  * runtime.start();
  *
  * <ConsentProvider runtime={runtime} options={{ theme }}>

package/dist-types/server/fetch-ssr-data.d.ts

@@ -1,5 +1,5 @@
 import type { SSRInitialData } from '@c15t/core';
-import type { FetchSSRDataOptions } from './types';
+import type { FetchSSRDataOptions } from './types.js';
 /**
  * Fetches initial consent data on the server for SSR hydration.
  *

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/index.d.ts

@@ -24,8 +24,8 @@
  *
  * @packageDocumentation
  */
-export { fetchSSRData } from './fetch-ssr-data';
-export { extractRelevantHeaders } from './headers';
-export { createSSRInitCacheKey } from './init-cache-key';
-export { normalizeBackendURL, validateBackendURL } from './normalize-url';
-export type { FetchSSRDataOptions, FetchSSRDataOptionsBase, FetchSSRDataResult, } from './types';
+export { fetchSSRData } from './fetch-ssr-data.js';
+export { extractRelevantHeaders } from './headers.js';
+export { createSSRInitCacheKey } from './init-cache-key.js';
+export { normalizeBackendURL, validateBackendURL } from './normalize-url.js';
+export type { FetchSSRDataOptions, FetchSSRDataOptionsBase, FetchSSRDataResult, } from './types.js';

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;