@c15t/react 3.0.0-alpha.5 → 3.0.0-alpha.7

package/dist-types/hooks/use-iab-manager.d.ts

@@ -11,8 +11,8 @@ export declare const useIABConsentManager: (overrides?: ConsentPresentation) =>
         actionGroups: import("@c15t/core").PresentationAction[][];
         primaryActions: import("@c15t/core").PresentationAction[];
         diagnostics: import("@c15t/core").PresentationDiagnostic[];
-        rights: readonly import("@c15t/schema/types").PolicyRight[];
-        preferenceControls: Exclude<import("@c15t/schema/types").PolicyRight, 'disclosure'>[];
+        rights: readonly import("@c15t/schema").PolicyRight[];
+        preferenceControls: Exclude<import("@c15t/schema").PolicyRight, 'disclosure'>[];
         direction: 'row' | 'column';
         uiProfile: 'balanced' | 'compact' | 'strict';
         scrollLock: boolean;
@@ -32,8 +32,8 @@ export declare const useIABConsentManager: (overrides?: ConsentPresentation) =>
         actionGroups: import("@c15t/core").PresentationAction[][];
         primaryActions: import("@c15t/core").PresentationAction[];
         diagnostics: import("@c15t/core").PresentationDiagnostic[];
-        rights: readonly import("@c15t/schema/types").PolicyRight[];
-        preferenceControls: Exclude<import("@c15t/schema/types").PolicyRight, 'disclosure'>[];
+        rights: readonly import("@c15t/schema").PolicyRight[];
+        preferenceControls: Exclude<import("@c15t/schema").PolicyRight, 'disclosure'>[];
         direction: 'row' | 'column';
         uiProfile: 'balanced' | 'compact' | 'strict';
         scrollLock: boolean;

package/dist-types/hooks/use-late-entry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether a banner that shows now arrives after the page has painted.
+ *
+ * Decided once each time `shown` turns on, and held while it stays on, so a
+ * re-render never restarts the entry. A banner hydrated from server HTML is
+ * part of the first paint: the hook answers `false` while hydrating, which
+ * also keeps the markup matching the server's.
+ *
+ * @param shown - Whether the banner is rendered.
+ * @returns Whether to mark the mount `data-entry="late"`.
+ *
+ * @internal
+ */
+export declare const useLateEntry: (shown: boolean) => boolean;

package/dist-types/hooks.d.ts

@@ -84,13 +84,35 @@ export declare const usePolicyScopeMode: () => PolicyScopeMode;
 export declare const useIABSnapshot: () => Readonly<KernelIABState> | null;
 /** Is IAB active? */
 export declare const useIABEnabled: () => boolean;
-/** Consent for a specific IAB vendor. Accepts numeric or string IDs; IAB
- * vendors are numeric but the kernel stores them as strings for
- * uniformity with custom vendors. */
+/**
+ * The preference centre's consent selection for one IAB vendor, including
+ * changes the visitor has not saved yet. Use it to render a control, not to
+ * gate a vendor: the saved choice is the TC string that `__tcfapi` serves,
+ * and `useIABSnapshot()?.authority` holds its decoded signals.
+ *
+ * @param vendorId - Numeric or string ID. IAB vendors are numeric; the
+ * kernel stores IDs as strings so custom vendors fit the same map.
+ * @returns Whether the vendor is selected.
+ */
 export declare const useVendorConsent: (vendorId: string | number) => boolean;
-/** Consent for a specific IAB purpose (1–11). */
+/**
+ * The preference centre's consent selection for one IAB purpose (1-11),
+ * including changes the visitor has not saved yet. Use it to render a
+ * control, not to gate a vendor: see {@link useVendorConsent}.
+ *
+ * @param purposeId - IAB purpose ID.
+ * @returns Whether the purpose is selected.
+ */
 export declare const usePurposeConsent: (purposeId: number) => boolean;
-/** Opt-in for a special feature (1 = geolocation, 2 = device ID). */
+/**
+ * The preference centre's opt-in selection for one special feature
+ * (1 = geolocation, 2 = device ID), including changes the visitor has not
+ * saved yet. Use it to render a control, not to gate a vendor: see
+ * {@link useVendorConsent}.
+ *
+ * @param featureId - IAB special feature ID.
+ * @returns Whether the special feature is selected.
+ */
 export declare const useSpecialFeatureOptIn: (featureId: number) => boolean;
 /** Latest TCF string. `null` until the IAB module encodes one. */
 export declare const useTCString: () => string | null;

package/dist-types/index-parts/core.d.ts

@@ -4,5 +4,5 @@
  * (esbuild) does not treat every module the index names as part of an app
  * that imports one hook: only the groups it uses are live.
  */
-export { createConsentKernel, custom, hosted } from '@c15t/core';
+export { createConsentKernel, custom, hosted, policyRulePresets, } from '@c15t/core';
 export { offline } from '../transports/offline.js';

package/dist-types/index.d.ts

@@ -31,7 +31,7 @@
  *   cache patching. No method rewriting. Provider boot work is explicit
  *   module wiring around a single per-mount kernel.
  */
-export type { ConsentKernel, ConsentSnapshot, ConsentState, HostedTransportOptions, InitContext, InitResponse, InitResult, KernelConfig, KernelEvent, KernelOverrides, KernelTransport, KernelUser, Listener, HostedModeOptions, ProviderTransportContext, ProviderTransportFactory, ProviderTransportKind, SavePayload, SaveResult, Unsubscribe, } from '@c15t/core';
+export type { AllConsentNames, ClearOnRevocationConfig, ConsentKernel, ConsentSnapshot, ConsentState, HostedTransportOptions, InitContext, InitResponse, InitResult, KernelConfig, KernelEvent, KernelOverrides, KernelTransport, KernelUser, Listener, HostedModeOptions, PolicyRule, ProviderTransportContext, ProviderTransportFactory, ProviderTransportKind, SavePayload, SaveResult, Unsubscribe, } from '@c15t/core';
 export type { OfflineModeOptions } from './transports/offline.js';
 export type { ConsentBannerButton, ConsentBannerLayout, ConsentBannerProps, ConsentBannerRight, ConsentBannerRightLinkProps, ConsentBannerRightsProps, ConsentBannerSurface, } from './components/prompt/index.js';
 export type { ConsentDialogCompoundComponent, ConsentDialogProps, } from './components/panel/index.js';

package/dist-types/provider.d.ts

@@ -1,7 +1,7 @@
-import type { AllConsentNames, Callbacks, ClearOnRevocationConfig, ConsentExperiment, ConsentPresentation, ExperimentState, I18nConfig, KernelConfig, KernelOverrides, KernelUser, LegalLinks, ProviderTransportFactory, StorageConfig, User, Vendor } 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 { ConsentControlOptions } from '@c15t/core/runtime';
-import type { ConsentRuntime, ResolveStreamedInit } from '@c15t/core/runtime/provider';
+import type { ConsentRuntime, ConsentRuntimeModules, ResolveStreamedInit } from '@c15t/core/runtime/provider';
 import type { ReactNode } from 'react';
 import type { DialogPreload } from './chunk-warming.js';
 import type { UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions } from './module-hooks.js';
@@ -13,9 +13,10 @@ export type ConsentProviderCallbacks = Pick<Callbacks, 'onChoiceRecorded' | 'onP
 /**
  * Prepared policy and records; legacy consent projections are not provider
  * inputs. An `experiment` a server helper resolved runs instead of
- * `options.experiment`.
+ * `options.experiment`, and a `journey` it started is the one the provider
+ * continues.
  */
-export type ConsentProviderPrefetch = Omit<KernelConfig, 'initialDraft' | 'transport'> & ExperimentState;
+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;
@@ -26,6 +27,13 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * 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.
      *
@@ -171,6 +179,17 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * @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.

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.5";
+export declare const version = "3.0.0-alpha.7";

package/docs/README.md

@@ -15,7 +15,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [How consent works](./concepts/how-consent-works.md): What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.
 - [Customize the interface](./customization/overview.md): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
 - [Verify consent](./guides/verify-consent.md): Check in a production build that vendor requests wait for consent, rejection survives a reload, preferences reopen and privacy signals apply.
-- [Migrate to v3](./upgrade-v3.md): Upgrade a c15t v2 app to v3. Covers packages, the Next.js and React providers, the JavaScript runtime, custom UI built on useConsentManager, callbacks, policies, stored consent and a self-hosted backend.
+- [Migrate to v3](./upgrade-v3.md): Upgrade from c15t v2 to v3. Pick the guide for the v2 package you use (@c15t/nextjs, @c15t/react or the c15t store), rename @c15t/scripts, keep visitors' choices, and upgrade a self-hosted backend and the Node.js SDK.
 
 ## More documentation
 
@@ -48,6 +48,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Scripts](./frameworks/react/scripts.md): Load vendor scripts by consent category in a React app with ConsentProvider, and clear stored data or reload the page when a visitor withdraws consent.
 - [Translations](./frameworks/react/translations.md): Where c15t banner and dialog copy comes from in a React app, how the browser picks the visitor's language, and how to override copy and switch languages with the provider's i18n option and hooks.
 - [Troubleshooting](./frameworks/react/troubleshooting.md): Fix a missing banner, early vendor requests, unstyled components and theme warnings in a React app that uses c15t/react.
+- [Upgrade from v2](./frameworks/react/upgrade-v3.md): Upgrade a React app from c15t v2 (@c15t/react) to v3. Covers packages, ConsentProvider and transports, the useConsentManager codemod, callbacks, policies, styles, IAB and stored consent.
 - [Vendor consent](./frameworks/react/vendor-consent.md): Let visitors allow a category such as marketing in a React app and still turn off one vendor in it, with the vendors option on ConsentProvider and useVendorAllowed.
 
 ## Concepts
@@ -55,7 +56,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Choose your setup](./concepts/choose-your-setup.md): Pick the c15t setup for your framework, rendering mode and hosting, and decide who runs the consent backend.
 - [Consent categories](./concepts/consent-categories.md): Assign scripts, embeds and features to c15t consent categories, and understand which categories the preference dialog shows.
 - [Consent state reference](./concepts/consent-state.md): How c15t saves choices, gates IAB vendors, hydrates server records and keeps browser tabs and storage in step.
-- [Data fetching](./concepts/data-fetching.md): How c15t gets policy data through a cached manifest, backend /init, the browser or offline rules, and where consent choices are saved.
+- [Data fetching](./concepts/data-fetching.md): Choose the recommended build-time policy snapshot or runtime manifest fetching, backend /init, browser resolution or offline rules, and understand where consent choices are saved.
 - [How consent works](./concepts/how-consent-works.md): What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.
 - [Policies](./concepts/policies.md): How policy models, prompts and scope decide what c15t asks visitors, where to change the rules, and why a banner may not appear.
 
@@ -73,7 +74,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Customize the interface](./customization/overview.md): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
 - [Banner designs](./customization/recipes.md): Five consent banner designs built with c15t, from one prop to your own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.
 - [Component parts](./customization/slots.md): Find every part of c15t's banner, dialog, widget, trigger and ConsentGate placeholder, its key in your framework's part API, and the data attributes to select on.
-- [Stylesheets and CSS layers](./customization/stylesheets.md): Load the right c15t stylesheet for your framework, see when the dialog's CSS loads, order c15t's cascade layer against your own, and run c15t without its styles.
+- [Stylesheets and CSS layers](./customization/stylesheets.md): Load the right c15t stylesheet for your framework, see which file holds the dialog's rules, order c15t's cascade layer against your own, and run c15t without its styles.
 - [Tailwind CSS](./customization/tailwind.md): Load c15t's styles next to Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
 - [Theme tokens](./customization/tokens.md): Change c15t's colors, type, radius, spacing, shadows and motion with theme tokens, and see every --c15t-* variable with its default.
 - [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
@@ -118,6 +119,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [RudderStack](./integrations/rudderstack.md): Load the RudderStack JavaScript SDK after measurement consent with the c15t rudderstack helper, or map c15t categories to destination consent IDs, and check each mode.
 - [Rybbit Analytics](./integrations/rybbit-analytics.md): Load Rybbit Analytics only after measurement consent with the c15t rybbitAnalytics helper, map its tracking options to data attributes, and check it in DevTools.
 - [Segment](./integrations/segment.md): Load Segment Analytics.js only after measurement consent with the c15t segment helper, guard your own track and identify calls, and check it in DevTools.
+- [Sentry](./integrations/sentry.md): Configure Sentry's CDN or your own SDK with consent for error monitoring, Session Replay and user data.
 - [Snapchat Pixel](./integrations/snapchat-pixel.md): Load the Snapchat Pixel only after marketing consent with the c15t snapchatPixel helper, guard snaptr event calls, and check it in DevTools.
 - [TikTok Pixel](./integrations/tiktok-pixel.md): Load the TikTok Pixel only after marketing consent with the c15t tiktokPixel helper, guard ttq event calls, and check it in DevTools.
 - [Umami Analytics](./integrations/umami-analytics.md): Load the Umami Analytics tracker only after measurement consent with the c15t umamiAnalytics helper, point it at a self-hosted instance, and check it in DevTools.
@@ -127,4 +129,4 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 
 ## Reference
 
-- [Migrate to v3](./upgrade-v3.md): Upgrade a c15t v2 app to v3. Covers packages, the Next.js and React providers, the JavaScript runtime, custom UI built on useConsentManager, callbacks, policies, stored consent and a self-hosted backend.
+- [Migrate to v3](./upgrade-v3.md): Upgrade from c15t v2 to v3. Pick the guide for the v2 package you use (@c15t/nextjs, @c15t/react or the c15t store), rename @c15t/scripts, keep visitors' choices, and upgrade a self-hosted backend and the Node.js SDK.

package/docs/concepts/choose-your-setup.md

@@ -12,9 +12,9 @@ to the alternatives it rules out.
 
 | Your app                                                                               | Setup                                                                                  | Guide                                                                                                                             |
 | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js App Router with a Next.js server                                               | Server resolves consent from a cached manifest and streams it to the page              | [App Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                            |
+| Next.js App Router with a Next.js server                                               | Server resolves consent from a build-time manifest and streams it to the page          | [App Router](https://c15t.com/docs/frameworks/next/quickstart)                                                                    |
 | Next.js App Router, banner must be in the first HTML                                   | Await consent inside `Suspense`                                                        | [Stream or await](https://c15t.com/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)                      |
-| Next.js with static, ISR or `'use cache'` pages                                        | Browser resolves consent on those pages                                                | [Static, ISR and cached pages](https://c15t.com/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)                |
+| Next.js with static, ISR, `'use cache'` or `ensureStatic = 'navigation'` pages         | Browser resolves consent on those pages                                                | [Static, ISR and cached pages](https://c15t.com/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)                |
 | Next.js Pages Router                                                                   | Resolve consent in `getServerSideProps`                                                | [Pages Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                          |
 | Next.js with `output: 'export'`                                                        | Browser resolves consent                                                               | [Static export](https://c15t.com/docs/frameworks/next/static-export)                                                              |
 | TanStack Start with a server                                                           | Root loader resolves consent on the server                                             | [TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart)                                                      |
@@ -22,14 +22,14 @@ to the alternatives it rules out.
 | TanStack Start in SPA mode or prerendered                                              | Browser resolves consent                                                               | [TanStack Start rendering](https://c15t.com/docs/frameworks/tanstack-start/rendering#spa-mode-prerendered-pages-and-static-hosts) |
 | React with Vite, or another single-page app                                            | Browser resolves consent                                                               | [React](../frameworks/react/quickstart.md)                                                                                        |
 | React Router framework mode, Remix, or another server-rendered React app               | Browser resolves consent after hydration                                               | [React rendering](../frameworks/react/rendering.md#react-router-remix-and-other-server-rendered-apps)                             |
-| Nuxt with a Nuxt server                                                                | Nuxt module resolves consent on the server from a cached manifest                      | [Nuxt](https://c15t.com/docs/frameworks/nuxt/quickstart)                                                                          |
+| Nuxt with a Nuxt server                                                                | Nuxt module resolves consent on the server from a build-time manifest                  | [Nuxt](https://c15t.com/docs/frameworks/nuxt/quickstart)                                                                          |
 | Nuxt with prerendered or cached routes                                                 | Nuxt server for most pages, the browser on prerendered and cached routes               | [Nuxt prerendered and cached routes](https://c15t.com/docs/frameworks/nuxt/rendering#prerendered-and-cached-routes)               |
 | Nuxt with `nuxt generate` on static hosting                                            | Nuxt module, browser resolves consent from the manifest or `/init`                     | [Nuxt static hosting](https://c15t.com/docs/frameworks/nuxt/rendering#deploy-to-static-hosting)                                   |
 | Nuxt with `ssr: false`                                                                 | Nuxt module, browser resolves consent from the manifest                                | [Nuxt single-page app](https://c15t.com/docs/frameworks/nuxt/rendering#build-a-single-page-app-with-ssr-false)                    |
 | Vue with Vite                                                                          | Vue plugin, browser resolves consent                                                   | [Vue](https://c15t.com/docs/frameworks/vue/quickstart)                                                                            |
 | Vue rendered on the server without Nuxt                                                | Vue plugin; the banner mounts after hydration. Use Nuxt for the banner in server HTML. | [Vue rendering](https://c15t.com/docs/frameworks/vue/rendering#server-rendering-without-nuxt)                                     |
 | Astro with static output                                                               | Browser resolves consent through the hosted backend                                    | [Astro static output](https://c15t.com/docs/frameworks/astro/rendering#static-output-with-hosted)                                 |
-| Astro with server output and an adapter                                                | Middleware resolves consent from a cached manifest                                     | [Astro server output](https://c15t.com/docs/frameworks/astro/rendering#server-output-with-manifest)                               |
+| Astro with server output and an adapter                                                | Middleware resolves consent from a build-time manifest                                 | [Astro server output](https://c15t.com/docs/frameworks/astro/rendering#server-output-with-manifest)                               |
 | Svelte with Vite                                                                       | Svelte provider, browser resolves consent                                              | [Svelte](https://c15t.com/docs/frameworks/svelte/quickstart)                                                                      |
 | SvelteKit with a server                                                                | Root layout load resolves consent on the server                                        | [SvelteKit](https://c15t.com/docs/frameworks/sveltekit/quickstart)                                                                |
 | SvelteKit with `adapter-static`, prerendered pages or SPA mode                         | Browser resolves consent                                                               | [SvelteKit rendering](https://c15t.com/docs/frameworks/sveltekit/rendering#build-a-static-site)                                   |
@@ -75,9 +75,26 @@ public policy manifest, never a response that contains a visitor's consent.
 
 ## How the server gets the policy
 
-Server setups fetch policy one of two ways:
+Use a build-time manifest as the default for supported production builds.
+Next.js, TanStack Start, Nuxt server output, Astro server output and SvelteKit
+can resolve requests from the deployment's snapshot. Vite apps can bundle it
+for browser resolution too; location-based policies may still need a location
+request. The framework quickstarts show the build hook and snapshot wiring.
 
-* **Manifest**, used by the Next.js, Nuxt and Astro server guides.
+The build fetches your public policy once and bundles it, so the server never
+fetches it at runtime.
+
+The snapshot is fixed at build time:
+
+* Rebuild after changing policies, translations or vendors. If your CI caches
+  build output, force a fresh build.
+* The build must reach the backend. A failed fetch fails the build.
+* Consent choices still go to the backend.
+
+For deployments that need policy updates without a rebuild, choose a runtime
+path:
+
+* **Cached manifest**.
   Your server downloads the project's public policy file, caches it, and
   resolves each visitor locally. Consent saves still go to the backend.
 * **`/init`**. Each visit asks the backend to resolve the visitor. Simpler, but

package/docs/concepts/consent-state.md

@@ -27,6 +27,42 @@ itself stays refused: its `effectivePermissions` entry is `false`, and targets
 that name only the category, or that also declare a consent purpose or special
 feature, stay blocked.
 
+## Categories under an IAB policy
+
+Under an IAB policy the visitor chooses TCF purposes, and c15t derives each
+category from them when the choice is saved. A category is granted when the
+visitor consented to every purpose in it that a listed vendor processes on
+consent:
+
+| Category        | TCF purposes |
+| --------------- | ------------ |
+| `marketing`     | 2, 3, 4      |
+| `measurement`   | 7, 8, 9      |
+| `experience`    | 5, 6         |
+| `functionality` | 10, 11       |
+
+`necessary` is always granted. Purpose 1, device storage, decides no category.
+
+Accept All consents only to the purposes and special features that the vendors
+in your list declare, because the TCF Policies allow no consent signal for a
+purpose the visitor was not shown. A category whose purposes no listed vendor
+processes on consent therefore stays denied after Accept All, and so does every
+script, iframe or network rule gated on it. With a vendor list whose vendors
+declare only purposes 1 to 4 and 7, for example, `experience` and
+`functionality` stay denied.
+
+If your own scripts depend on such a category, do one of these:
+
+* Declare the processing. Add a custom vendor for it, with the purposes it
+  uses, through the `customVendors` option of your IAB setup. The preference
+  centre then lists those purposes, and Accept All and the purpose switches
+  can grant the category.
+* Gate the script on a category that your listed vendors' purposes cover, or on
+  `necessary` if it needs no consent.
+
+Check `effectivePermissions` after Accept All on a fresh visit to see which
+categories your vendor list leaves denied.
+
 ## When a choice is saved
 
 A save records the choice in the browser first and sends it to the backend
@@ -63,6 +99,12 @@ backend that signs policy snapshot tokens rejects a replay made after the
 token expires, which is 30 minutes by default for the self-hosted backend. A
 save still queued by then is recorded only in the browser.
 
+A replay that fails and stays queued emits `save:replayed` with `ok: false` but
+not `command:error`, since the save already reported its first failure. A save
+that leaves the queue without the backend recording it, because it ran out of
+attempts, waited more than 7 days or was refused, emits `command:error` once.
+Development builds also log a `[c15t]` console warning for each of these.
+
 IAB surfaces close in the click task too, but an IAB choice is recorded only
 after its TC string is encoded, which can wait for the TCF library to load.
 If that local step records nothing, for example because the vendor list
@@ -76,6 +118,11 @@ unchanged selection, closes the surface when it resolves successfully. Opening
 or closing a surface, or starting another save, before then leaves the surface
 as the visitor set it.
 
+Closing the dialog without saving, with Escape or the adapter's close call,
+leaves the same surface a save would. A visitor who opens preferences from the
+banner and backs out still owes a choice, so the banner comes back. Once a
+choice is recorded, closing the dialog leaves nothing open.
+
 ## Preserve records during hydration
 
 Server helpers return records with policy information and evaluation time.

package/docs/concepts/data-fetching.md

@@ -1,7 +1,8 @@
 ---
 title: Data fetching
-description: How c15t gets policy data through a cached manifest, backend /init,
-  the browser or offline rules, and where consent choices are saved.
+description: Choose the recommended build-time policy snapshot or runtime
+  manifest fetching, backend /init, browser resolution or offline rules, and
+  understand where consent choices are saved.
 group: concepts
 ---
 
@@ -13,13 +14,14 @@ the same protocol, so every path below works with either. Only `offline()`
 removes backend requests. For a recommendation by framework, start with
 [choose your setup](./choose-your-setup.md).
 
-| Fetching path                  | Where policy resolves                                                                 | Where choices are submitted | Choose it when                                                                                         |
-| ------------------------------ | ------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Cached manifest on your server | Your application resolves public policy data with each request's location and signals | Inth or your c15t backend   | Your host has a runtime server and you want to reuse policy data across requests                       |
-| Regular backend `/init`        | The consent backend                                                                   | The same backend            | You want the fewest moving parts, need backend-owned request resolution, or have no application server |
-| Manifest in the browser        | The browser, using supplied or unknown location                                       | Inth or your c15t backend   | You deliberately want client resolution and have planned geography, bundle size and policy refresh     |
-| Offline                        | The browser or local runtime, using bundled rules                                     | No backend submission       | Local development and tests. Not recommended for production environments.                              |
-| Custom transport               | Your implementation                                                                   | Your implementation         | An existing service cannot use the c15t backend protocol                                               |
+| Fetching path                    | Where policy resolves                                                                 | Where choices are submitted | Choose it when                                                                                         |
+| -------------------------------- | ------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Build-time manifest, recommended | Your server or browser resolves a bundled policy snapshot with each visitor's inputs  | Inth or your c15t backend   | Your framework supports a build integration and policy changes can ship with a rebuild                 |
+| Cached manifest on your server   | Your application resolves public policy data with each request's location and signals | Inth or your c15t backend   | Policy changes must reach the app without rebuilding, or builds cannot access the backend              |
+| Regular backend `/init`          | The consent backend                                                                   | The same backend            | You want the fewest moving parts, need backend-owned request resolution, or have no application server |
+| Manifest in the browser          | The browser, using supplied or unknown location                                       | Inth or your c15t backend   | You deliberately want client resolution and have planned geography, bundle size and policy refresh     |
+| Offline                          | The browser or local runtime, using bundled rules                                     | No backend submission       | Local development and tests. Not recommended for production environments.                              |
+| Custom transport                 | Your implementation                                                                   | Your implementation         | An existing service cannot use the c15t backend protocol                                               |
 
 ## What is a consent manifest?
 
@@ -38,6 +40,24 @@ Do not put secrets, visitor identifiers or consent records into a manifest.
 Keep personalized init responses out of shared caches. Changing a policy also
 requires a refresh strategy for cached or build-time manifests.
 
+## Use a build-time manifest by default
+
+The build fetches your public policy once and bundles it, so the server never
+fetches it at runtime.
+
+The framework quickstarts include the build integration for supported
+deployments. Server resolution uses the snapshot without an upstream manifest
+request. Browser resolution includes the policy and resolver in the client
+bundle, and may still request location for regional policies. Static Nuxt and
+Astro sites and script-tag sites keep the runtime setup from their guides.
+
+The snapshot is fixed at build time:
+
+* Rebuild after changing policies, translations or vendors. If your CI caches
+  build output, force a fresh build.
+* The build must reach the backend. A failed fetch fails the build.
+* Consent choices still go to the backend.
+
 ## How manifest mode counts visitors
 
 The backend counts visitors from `/init` requests, and manifest resolution
@@ -48,6 +68,40 @@ no identity; the visitor's IP address and user agent are forwarded under the
 backend's usual IP handling. Static output resolves in the browser and sends
 no report. Set `reportSessions: false` on an adapter to turn it off.
 
+## Link an init to the save that follows
+
+Each page load gets a journey id, a random UUID sent on requests c15t already
+makes:
+
+| Request          | Query parameters                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| `GET /init`      | `c15tJourney`, `c15tJourneyScope`, `c15tStored` (`1` if a choice or notice dismissal was stored) |
+| `POST /subjects` | `c15tJourney`, `c15tJourneyScope`                                                                |
+
+Session reports carry it as `journey: { id, scope, storedChoice, prompt, domain }`.
+A report and a save with the same `id` belong to one page load. `prompt` is
+`due`, `stored` or `not-required`; a page that falls back to the default opt-in
+banner counts as `due` or `stored`. A stored answer counts as `stored` even if a
+policy change makes c15t ask again.
+
+The id is random, is never the subject id and is never written to a cookie.
+Every save that carries one follows an `/init` or report with the same id.
+Saves replayed after going offline carry none.
+
+| `journey`          | Behavior                                                                                                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'page'` (default) | One id per page load, in memory.                                                                                                                                                   |
+| `'tab'`            | Kept in `sessionStorage` while a prompt is due, and removed once the visitor chooses or no prompt is due. Only when the browser resolves init; server-rendered pages use `'page'`. |
+| `false`            | No journey.                                                                                                                                                                        |
+
+Set it on the runtime or provider. In Next.js use `defineConsentConfig({ journey })`;
+in TanStack Start pass the same value to `resolveConsent` and `ConsentRoot`; with
+the inline prefetch script, pass it to `buildPrefetchScript`. Vue, Svelte, Astro
+and the script tag use `'page'`. A manifest that resolves locally in the
+browser reports no init, so it sends no journey.
+
+If you pass `hosted()` a `fetch`, match on the path: URLs now carry a query string.
+
 ## What does regular `/init` do?
 
 `hosted({ url })` uses `${url}/init` for initialization and `${url}/subjects` for
@@ -156,10 +210,13 @@ the kernel contract. Prefer a built-in transport when your backend supports it.
 ## Verify the selected path
 
 Inspect browser and server requests separately. A server manifest fetch will
-not appear in the browser's Network panel. On a warm manifest path, check that
+not appear in the browser's Network panel. With a build-time snapshot, start a
+fresh production server and confirm it makes no upstream `/manifest` request.
+After a policy edit, rebuild and confirm the new policy appears. On a runtime
+manifest path, check that
 page requests do not call the backend `/init`, a visitor's choice still reaches
 the backend's `/subjects`, and policy changes become visible after the configured
-refresh. In the recommended Next.js setup, the browser should call only
+refresh. With a same-origin consent proxy, the browser should call only
 `/api/c15t` paths for consent HTTP traffic; inspect server logs to verify their
 upstream destinations.
 

package/docs/customization/motion.md

@@ -8,20 +8,21 @@ group: customization
 
 ## Change the speed with motion tokens
 
-c15t animates its surfaces with three durations and four easing curves. Set
+c15t animates its surfaces with three durations and five easing curves. Set
 them in the theme's `motion` object, or as CSS variables:
 
-| CSS variable             | Theme key                | Default                                | Used by                                         |
-| ------------------------ | ------------------------ | -------------------------------------- | ----------------------------------------------- |
-| `--c15t-duration-fast`   | `motion.duration.fast`   | `80ms`                                 | Banner, buttons, tabs                           |
-| `--c15t-duration-normal` | `motion.duration.normal` | `150ms`                                | Preference dialog, switches, accordions         |
-| `--c15t-duration-slow`   | `motion.duration.slow`   | `200ms`                                | Legal links, floating trigger                   |
-| `--c15t-easing`          | `motion.easing`          | `cubic-bezier(0.4, 0, 0.2, 1)`         | Banner fade, switches, accordions               |
-| `--c15t-easing-out`      | `motion.easingOut`       | `cubic-bezier(0.215, 0.61, 0.355, 1)`  | Preference dialog, floating trigger hover       |
-| `--c15t-easing-in-out`   | `motion.easingInOut`     | `cubic-bezier(0.645, 0.045, 0.355, 1)` | Floating trigger snapping to a corner           |
-| `--c15t-easing-spring`   | `motion.easingSpring`    | `cubic-bezier(0.34, 1.56, 0.64, 1)`    | The banner's slide in and the dialog's scale in |
+| CSS variable             | Theme key                | Default                                  | Used by                                                        |
+| ------------------------ | ------------------------ | ---------------------------------------- | -------------------------------------------------------------- |
+| `--c15t-duration-fast`   | `motion.duration.fast`   | `80ms`                                   | Banner fade out, buttons, tabs                                 |
+| `--c15t-duration-normal` | `motion.duration.normal` | `150ms`                                  | Preference dialog, late banner fade in, switches, accordions   |
+| `--c15t-duration-slow`   | `motion.duration.slow`   | `200ms`                                  | Legal links, floating trigger                                  |
+| `--c15t-easing`          | `motion.easing`          | `cubic-bezier(0.4, 0, 0.2, 1)`           | Switches, accordions                                           |
+| `--c15t-easing-out`      | `motion.easingOut`       | `cubic-bezier(0.215, 0.61, 0.355, 1)`    | Preference dialog, late banner fade in, floating trigger hover |
+| `--c15t-easing-in`       | `motion.easingIn`        | `cubic-bezier(0.55, 0.055, 0.675, 0.19)` | Banner fade out                                                |
+| `--c15t-easing-in-out`   | `motion.easingInOut`     | `cubic-bezier(0.645, 0.045, 0.355, 1)`   | Floating trigger snapping to a corner                          |
+| `--c15t-easing-spring`   | `motion.easingSpring`    | `cubic-bezier(0.34, 1.56, 0.64, 1)`      | The dialog's scale in                                          |
 
-This theme slows the dialog down and removes the banner's overshoot:
+This theme slows the dialog down and removes its overshoot:
 
 ```ts title="consent-theme.ts"
 export const theme = {
@@ -32,6 +33,14 @@ export const theme = {
 };
 ```
 
+The banner never slides in. When it shows with the page, it is part of the
+first paint and appears on its first frame. When it arrives more than 100ms
+after the page first painted, such as after a slow script or a client-side
+init, it fades in over `--c15t-duration-normal` instead, and its root and
+backdrop carry `data-entry="late"`. A banner rendered on the server always
+shows at once. When it hides, Vue, Svelte and the script tag fade it out over
+`--c15t-duration-fast`.
+
 The theme goes where your framework's other tokens go. See
 [theme tokens](./tokens.md) and your framework's customize page.
 In Vue and Nuxt, set `tokens` with the variable name without the leading
@@ -39,8 +48,8 @@ In Vue and Nuxt, set `tokens` with the variable name without the leading
 
 ## Turn animations off
 
-`disableAnimation` removes the enter and exit transitions of the banner and
-dialogs, and the hover and snap transitions of the floating
+`disableAnimation` removes the banner's fades, the enter and exit
+transitions of the dialogs, and the hover and snap transitions of the floating
 `ConsentDialogTrigger`. Set it once for every surface, then override it for one
 surface where your framework allows:
 

package/docs/customization/recipes.md

@@ -517,8 +517,7 @@ from your Inth project, and put the block before `</body>`.
 
 ```html title="index.html"
 <script
-	src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.headless.js"
-	data-backend-url="https://your-project.inth.app"
+	src="https://your-project.inth.app/c15t.headless.js"
 	defer
 ></script>
 
@@ -622,8 +621,8 @@ from your Inth project, and put the block before `</body>`.
 	hidden
 >
 	<p class="cookie-bar__text">
-		We use cookies to measure traffic and improve this site. Choose which ones
-		can run.
+		We use cookies to measure traffic and improve this site. Choose which
+		ones can run.
 	</p>
 	<fieldset
 		class="cookie-bar__prefs"
@@ -867,5 +866,5 @@ The source repository renders each design in its Storybook under
 `Docs / Banner designs`: `apps/storybook-react`, `apps/storybook-vue`,
 `apps/storybook-svelte` and `apps/storybook-astro`. Each story uses an
 in-memory policy and loads no analytics. The HTML headless bar runs at
-`/consent-example/headless` in `examples/script-tag`, which the example
+`/consent-example/headless` in `internals/fixtures/script-tag`, which the example
 acceptance tests cover.

package/docs/customization/slots.md

@@ -129,8 +129,9 @@ The widget is the list of categories inside the dialog. React and Vue call it
 | Label                        | `trigger.text`                                                  | None                                                                                                |
 | Toolbar, its items and icons | `trigger.toolbar`, `trigger.toolbarItem`, `trigger.toolbarIcon` | `consentDialogTriggerToolbar`, `consentDialogTriggerToolbarItem`, `consentDialogTriggerToolbarIcon` |
 
-Only React renders the toolbar. Vue has no toolbar, and the toolbar slots only
-reach Astro's React dialog.
+React renders the toolbar from `ConsentDialogTriggerToolbar`, and while
+`ConsentDevTools` is mounted. Vue renders it only while `ConsentDevTools` is
+mounted. In Astro, the toolbar slots reach the React dialog.
 
 ## Legal links and IAB TCF parts