@c15t/react 3.0.0-alpha.0 → 3.0.0-alpha.10

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, 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,28 +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.
@@ -99,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 {
@@ -117,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;

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

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
-import type { ThemeContextValue } from './context/theme-context';
-import type { V3UIConfigValue } from './ui-config-context';
+import type { ThemeContextValue } from './context/theme-context.js';
+import type { V3UIConfigValue } from './ui-config-context.js';
 interface V3ThemeProviderProps {
     themeConfig: ThemeContextValue;
     uiConfig: V3UIConfigValue;

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

@@ -0,0 +1,36 @@
+import type { HostedModeFactory, HostedModeOptions } from '@c15t/core';
+/** Options for {@link hosted}. `backendURL` defaults to the build's. */
+export type HostedOptions = Omit<HostedModeOptions, 'backendURL'> & {
+    /**
+     * Backend URL, relative (`/api/c15t`) or absolute. Defaults to the URL
+     * `consentManifest()` from `c15t/build` read from
+     * `VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`.
+     */
+    backendURL?: string;
+};
+/**
+ * Build a hosted factory, taking the backend URL from the build when the
+ * options name none.
+ *
+ * @param options - The page's options.
+ * @param buildBackendURL - The backend URL the build read, if any.
+ * @returns A hosted transport factory.
+ * @throws {Error} When neither names a backend URL.
+ * @internal
+ */
+export declare const hostedWithBuild: (options: HostedOptions, buildBackendURL: string | undefined) => HostedModeFactory;
+/**
+ * Ask the backend's `/init` for every visitor's policy.
+ *
+ * @param options - Backend URL, init headers and request overrides.
+ * @returns A transport factory for the provider's `mode`, carrying its
+ * options.
+ * @throws {Error} When no backend URL is passed and the build set none.
+ * @example
+ * ```tsx
+ * import { ConsentProvider, hosted } from 'c15t/react';
+ *
+ * <ConsentProvider options={{ mode: hosted() }}>{children}</ConsentProvider>;
+ * ```
+ */
+export declare const hosted: (options?: HostedOptions) => HostedModeFactory;

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

@@ -0,0 +1,48 @@
+import type { BrowserManifestModeFactory, BrowserManifestOptions } from '@c15t/core/transports/manifest-browser';
+/**
+ * Manifest mode for the React provider: core's browser resolver, with the
+ * policy and backend URL the build integration downloaded as defaults.
+ */
+import type { ConsentManifest } from '@c15t/schema/types';
+/** What a build integration downloaded, as `@c15t/core/generated` exports it. */
+export interface BuildOutput {
+    backendURL?: string;
+    snapshot?: ConsentManifest;
+}
+/**
+ * Fill the options the page left out from the build: the backend URL that
+ * saves go to, and the snapshot unless the page passed one, a
+ * `manifestURL`, or `source: 'runtime'`.
+ *
+ * @param options - The page's options.
+ * @param build - What the build downloaded.
+ * @returns The options `manifest()` resolves with.
+ * @internal
+ */
+export declare const withBuildDefaults: (options: BrowserManifestOptions, build: BuildOutput) => BrowserManifestOptions;
+/**
+ * Resolve the policy in the browser from the backend's consent manifest.
+ *
+ * Without options it uses what `consentManifest()` from `c15t/build`
+ * downloaded: the snapshot and the backend URL from
+ * `VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`, both served as
+ * `c15t/generated`. Without a
+ * snapshot, such as in dev after a failed fetch, it fetches
+ * `${backendURL}/manifest` at runtime. Saves go to the backend either way.
+ * With `manifestURL` or `source: 'runtime'`, also pass `source: 'runtime'`
+ * to `consentManifest()`, so the build downloads no snapshot.
+ *
+ * @param options - Overrides: your own `snapshot`, `source: 'runtime'`, a
+ * `manifestURL`, a `backendURL`, or the visitor's location as `inputs`.
+ * @returns A transport factory for the provider's `mode`, carrying its
+ * options.
+ * @throws {Error} When no snapshot, manifest URL or backend URL is known.
+ * @example
+ * ```tsx
+ * import { ConsentProvider, manifest } from 'c15t/react';
+ *
+ * <ConsentProvider options={{ mode: manifest() }}>{children}</ConsentProvider>;
+ * ```
+ */
+export declare const manifest: (options?: BrowserManifestOptions) => BrowserManifestModeFactory;
+export type { BrowserManifestModeFactory, BrowserManifestOptions as ManifestModeOptions, } from '@c15t/core/transports/manifest-browser';