@c15t/react 2.2.1 → 3.0.0-alpha.1

package/docs/README.md

@@ -1,155 +1,103 @@
 # @c15t/react
 
-> React consent management docs for c15t, including consent UI, hooks, styling, script loading, and integrations.
+> React v3 consent components, hooks, Inth setup and customization.
 
 These docs ship inside the package so coding agents can read them offline. Open the topic file you need from the list below — paths are relative to this file.
 
-## Frameworks
+## Using these docs
+
+These docs describe v3. Start with Inth hosted setup, identify the framework, router and deployment, then read its quickstart. Static sites can use Inth directly. Use page Markdown and package-bundled docs for targeted context. Verify scripts, rejection, reload and preferences; banner visibility alone is insufficient.
+
+## Start here
 
-Install and configure c15t in JavaScript, React, and Next.js applications.
+- [React quickstart](./frameworks/react/quickstart.md)
+- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
+- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.
 
-- [Building Headless Components](./frameworks/react/building-headless-components.md): Build policy-aware custom consent components in React using the headless hooks and policy-pack tooling.
-- [Callbacks](./frameworks/react/callbacks.md): React to consent lifecycle events - initialization, consent changes, errors, and revocation reloads.
-- [ConsentBanner](./frameworks/react/components/consent-banner.md): A pre-built consent banner that appears when user consent is needed. Supports policy-aware layout, theming, and advanced composition when markup must change.
-- [ConsentDialog](./frameworks/react/components/consent-dialog.md): A modal dialog where users can toggle individual consent categories.
-- [ConsentDialogLink](./frameworks/react/components/consent-dialog-link.md): An inline trigger for opening the consent dialog from footers, legal pages, and account settings.
-- [ConsentDialogTrigger](./frameworks/react/components/consent-dialog-trigger.md): A floating, draggable button that lets users re-open the consent dialog at any time.
-- [ConsentManagerProvider](./frameworks/react/components/consent-manager-provider.md): The root provider component that initializes the consent system and makes consent state available to all child components.
-- [ConsentWidget](./frameworks/react/components/consent-widget.md): An inline consent management widget for embedding in settings or privacy pages. Shows category toggles with accordion layout.
+## More documentation
+
+[Documentation index](https://c15t.com/docs/llms.txt) · [Full Markdown context](https://c15t.com/llms-full.txt). Prefer the index and individual pages for focused tasks.
+
+## Frameworks
+
+- [ConsentBanner](./frameworks/react/components/consent-banner.md): Pre-built consent banner shown when consent is required.
+- [ConsentDialog](./frameworks/react/components/consent-dialog.md): Open the c15t preference center as a modal ConsentDialog in a React app, wire its triggers and control blocking, focus and policy gating.
+- [ConsentDialogLink](./frameworks/react/components/consent-dialog-link.md): Add a ConsentDialogLink to a React footer so visitors reopen the c15t preference center from your own text link, with asChild and rights data.
+- [ConsentDialogTrigger](./frameworks/react/components/consent-dialog-trigger.md): Floating button and toolbar that reopen the preference center after the first prompt.
+- [ConsentProvider](./frameworks/react/components/consent-manager-provider.md): Configure the v3 consent runtime and share its state with child components.
+- [ConsentWidget](./frameworks/react/components/consent-widget.md): Embed the c15t preference center inline with ConsentWidget on a React privacy page, with draft toggles that record a choice only on Save.
 - [DevTools](./frameworks/react/components/dev-tools.md): A development tool for inspecting consent state, geolocation, loaded scripts, and consent events in real time.
-- [Frame](./frameworks/react/components/frame.md): A consent-gated content wrapper - children only mount when the required consent category is granted.
-- [Client Modes](./frameworks/react/concepts/client-modes.md): Choose how c15t connects to its backend - full hosted integration, offline-only, or bring your own backend.
-- [Consent Categories](./frameworks/react/concepts/consent-categories.md): How c15t organizes tracking technologies into five consent categories.
-- [Consent Models](./frameworks/react/concepts/consent-models.md): How c15t determines consent behavior based on legal jurisdiction.
-- [Cookie Management](./frameworks/react/concepts/cookie-management.md): How c15t manages cookies through script, iframe, and network gating
-- [Glossary](./frameworks/react/concepts/glossary.md): Key terms used throughout the c15t documentation.
-- [Initialization Flow](./frameworks/react/concepts/initialization-flow.md): What happens from provider mount to first render — the full consent lifecycle.
-- [Policy Packs](./frameworks/react/concepts/policy-packs.md): How c15t resolves regional consent policies and what a policy pack controls.
-- [Headless Mode](./frameworks/react/headless.md): Build fully custom consent UI using only hooks - no pre-built components required.
-- [useColorScheme](./frameworks/react/hooks/use-color-scheme.md): Manage light/dark mode preferences for consent components.
-- [Checking Consent](./frameworks/react/hooks/use-consent-manager/checking-consent.md): Use has() for flexible consent checks with AND, OR, and NOT logic. Check if any consent exists with hasConsented().
-- [Location Info](./frameworks/react/hooks/use-consent-manager/location-info.md): Access detected jurisdiction, country, and region. Override geolocation for testing.
-- [useConsentManager](./frameworks/react/hooks/use-consent-manager/overview.md): The primary hook for accessing consent state and actions. Returns the full consent store including all state properties and action methods.
-- [Setting Consent](./frameworks/react/hooks/use-consent-manager/setting-consent.md): Save, update, and reset consent preferences with setConsent(), setSelectedConsent(), and saveConsents().
-- [useDraggable](./frameworks/react/hooks/use-draggable.md): Make an element draggable between viewport corners with snapping, persistence, and animation support.
-- [useFocusTrap](./frameworks/react/hooks/use-focus-trap.md): Trap keyboard focus within a container for accessible modal dialogs.
-- [useReducedMotion](./frameworks/react/hooks/use-reduced-motion.md): Detect the user's prefers-reduced-motion OS setting and reactively disable animations.
-- [useSSRStatus](./frameworks/react/hooks/use-ssr-status.md): Check whether server-side rendered consent data was used during initialization.
-- [useTextDirection](./frameworks/react/hooks/use-text-direction.md): Manage RTL/LTR text direction based on the active language for consent UI.
-- [useTranslations](./frameworks/react/hooks/use-translations.md): Access the current language's translations for building custom consent UI.
-- [IABConsentBanner](./frameworks/react/iab/consent-banner.md): An IAB TCF 2.3 compliant consent banner that displays partner count, purpose summaries, and legitimate interest notices.
-- [IABConsentDialog](./frameworks/react/iab/consent-dialog.md): An IAB TCF 2.3 compliant preference center with tabbed purpose and vendor management.
-- [IAB TCF 2.3](./frameworks/react/iab/overview.md): Implement IAB Transparency & Consent Framework 2.3 compliance for programmatic advertising in EU/EEA jurisdictions.
-- [useGVLData (Internal)](./frameworks/react/iab/use-gvl-data.md): Status note for the internal GVL hook used by the built-in IAB dialog.
-- [Iframe Blocking](./frameworks/react/iframe-blocking.md): Block embedded content (YouTube, social widgets, maps) until users grant consent for the appropriate category.
-- [Internationalization](./frameworks/react/internationalization.md): Translate consent UI into 30+ languages with built-in translations, custom overrides, and automatic browser language detection.
-- [Network Blocker](./frameworks/react/network-blocker.md): Block outgoing network requests to third-party domains until the user grants consent for the appropriate category.
-- [Optimization](./frameworks/react/optimization.md): Improve c15t startup performance in React with prefetching, proxy rewrites, and rendering tradeoffs.
-- [Policy Packs](./frameworks/react/policy-packs.md): Configure regional consent policies in React — hosted mode, presets, and offline fallback.
-- [Quickstart](./frameworks/react/quickstart.md): Add consent management to your React app in under 5 minutes.
-- [Script Loader](./frameworks/react/script-loader.md): Gate third-party scripts behind consent in React — load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
-- [Server-Side Utilities](./frameworks/react/server-side.md): Fetch consent data on the server for SSR hydration — eliminate the loading flash and improve performance.
-- [Class Names](./frameworks/react/styling/classnames.md): Style consent components using className props and per-slot className targeting via the theme.
-- [Color Scheme](./frameworks/react/styling/color-scheme.md): Support light mode, dark mode, and system preference detection in consent components.
-- [CSS Variables](./frameworks/react/styling/css-variables.md): Reference for all --c15t-* CSS custom properties generated by the theme system.
-- [Styling Overview](./frameworks/react/styling/overview.md): Customize every aspect of c15t's consent components using design tokens, component slots, and CSS variables.
-- [Component Slots](./frameworks/react/styling/slots.md): Target individual component parts with styles using the slot system - className strings or inline style objects.
-- [Tailwind CSS](./frameworks/react/styling/tailwind.md): Use Tailwind CSS utility classes to style consent components via the slot system.
-- [Design Tokens](./frameworks/react/styling/tokens.md): The six base token categories that control colors, typography, spacing, radius, shadows, and motion, plus optional dark-mode overrides.
-- [Troubleshooting](./frameworks/react/troubleshooting.md): Solutions for common issues with @c15t/react — provider errors, missing banners, consent persistence, and more.
+- [Frame](./frameworks/react/components/frame.md): Gate a YouTube or map iframe behind consent with Frame in React, showing a placeholder that opens the preference center until the category is allowed.
+- [Consent categories](./frameworks/react/concepts/consent-categories.md): Assign optional features to categories and understand how policy scope affects permission.
+- [Policy presets](./frameworks/react/concepts/policy-presets.md): Understand how policy rules affect React prompts, permissions and persistent privacy controls.
+- [Headless](./frameworks/react/headless.md): Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.
+- [Hooks](./frameworks/react/hooks/use-consent-manager/overview.md): Gate features and save consent choices in React components with the focused hooks exported from c15t/react.
+- [IAB TCF](./frameworks/react/iab/overview.md): Mount the IAB TCF banner and dialog inside a React ConsentProvider and configure the CMP ID, policy and vendor data.
+- [Quickstart](./frameworks/react/quickstart.md): Connect a React application to Inth and add consent UI, persistence and a preferences link.
+- [Load scripts with consent](./frameworks/react/script-loader.md): Register vendor scripts once and let effective permissions control loading.
+- [Styling](./frameworks/react/styling/overview.md): Import the React stylesheet and theme c15t components with tokens, slots, and class names on ConsentProvider.
+- [Troubleshoot React consent](./frameworks/react/troubleshooting.md): Diagnose policy resolution, early scripts, storage and rendering problems.
+
+## Guides
+
+- [Understand consent state](./guides/consent-state.md): Distinguish policy resolution, effective permissions, explicit choices, notices and privacy signals.
+- [Data fetching and transports](./guides/data-fetching.md): Choose cached manifests, backend init or offline policy resolution, and understand where consent records are saved.
+- [Choose a deployment mode](./guides/deployment-modes.md): Choose who runs your consent backend, then select manifest, init or offline resolution for your deployment.
+- [Troubleshoot consent](./guides/troubleshooting.md): Diagnose missing banners, early vendor requests, lost choices and hydration differences.
+- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+
+## Customization
+
+- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
+- [Banner styling recipes](./customization/recipes.md): See real v3 components and reuse the exact theme configuration behind the examples.
+- [Style component slots](./customization/slots.md): Target a specific c15t component part without replacing its markup or behavior.
+- [Theme tokens and CSS](./customization/tokens.md): Style c15t with semantic tokens and use the stylesheet that matches your CSS tooling.
+- [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
 
 ## Integrations
 
-Connect analytics, advertising, maps, media, and other third-party tools behind consent.
-
-- [Adobe Analytics](./integrations/adobe-analytics.md): Adobe Analytics loaded through an Adobe Experience Platform Data Collection Tags embed URL.
-- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Cookieless web analytics from Ahrefs with a prebuilt helper that wires the project key into a c15t-managed script.
-- [Amplitude](./integrations/amplitude.md): Load Amplitude Browser SDK 2 with c15t and gate product analytics behind measurement consent.
-- [Build a Custom Script Integration](./integrations/building-integrations.md): Learn when to use a raw Script, when to build a reusable manifest-backed integration, and how to debug and test custom consent-aware scripts in c15t.
-- [Clearbit](./integrations/clearbit.md): Visitor and company enrichment loaded with Clearbit's account-keyed tags.js snippet.
-- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Cookieless analytics from Cloudflare with a prebuilt helper that serializes the beacon config into the `data-cf-beacon` attribute.
-- [Crisp](./integrations/crisp.md): Load Crisp live chat with website ID, runtime, cookie, and session options.
-- [Databuddy](./integrations/databuddy.md): Databuddy is a privacy-focused analytics platform that helps you understand user behavior and track events. It supports cookieless tracking and manages consent automatically through c15t's consent state synchronization.
-- [Fathom Analytics](./integrations/fathom-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that maps Fathom's data attributes into a c15t-managed script.
-- [Google Maps](./integrations/google-maps.md): Render Google Maps only after consent with one shared Maps JavaScript API loader and independently managed map instances.
-- [GA4 + Google Ads (gtag.js)](./integrations/google-tag.md): Send data to Google Analytics 4 and Google Ads with automatic Consent Mode v2 support.
-- [Google Tag Manager](./integrations/google-tag-manager.md): Deploy and manage marketing tags centrally with automatic consent state synchronization.
-- [Heap](./integrations/heap.md): Load Heap with c15t and gate autocapture product analytics behind measurement consent.
-- [Hightouch](./integrations/hightouch.md): Load Hightouch Events with c15t and gate the browser SDK behind measurement consent.
-- [Hotjar](./integrations/hotjar.md): Product analytics and behavior insights with a prebuilt helper that seeds Hotjar globals before loading the vendor bundle.
-- [Intercom](./integrations/intercom.md): Bootstrap Intercom settings and load the messenger widget bundle.
-- [LinkedIn Insights](./integrations/linkedin-insights.md): Track conversions and build matched audiences for LinkedIn advertising campaigns.
-- [LogRocket](./integrations/logrocket.md): Session replay and monitoring loaded after measurement consent with LogRocket's browser SDK.
-- [Matomo Analytics](./integrations/matomo-analytics.md): Load Matomo with c15t and keep Matomo's queue aligned with measurement consent.
-- [Meta Pixel](./integrations/meta-pixel.md): Track conversions and build audiences for Facebook and Instagram advertising campaigns.
-- [Microsoft Clarity](./integrations/microsoft-clarity.md): Session replay and behavior analytics with a prebuilt helper that keeps Clarity consent synchronized with c15t measurement state.
-- [Microsoft UET](./integrations/microsoft-uet.md): Track conversions and measure performance for Microsoft Advertising and Bing Ads.
-- [Mixpanel Analytics](./integrations/mixpanel-analytics.md): Load Mixpanel with c15t and let Mixpanel's own opt-in and opt-out APIs follow measurement consent.
-- [Integrations](./integrations/overview.md): Load analytics, pixels, tag managers, and widgets through c15t so consent state controls when they run, update, and appear in your consent UI.
-- [Pirsch](./integrations/pirsch.md): Privacy-friendly, cookieless analytics loaded with Pirsch's fixed script id and identification-code attributes.
-- [Plausible Analytics](./integrations/plausible-analytics.md): Privacy-friendly cookieless analytics with a prebuilt helper that preserves Plausible's queue bootstrap and loader attributes.
-- [PostHog](./integrations/posthog.md): PostHog is an open-source product analytics platform for tracking user behavior, session replays, feature flags, and A/B testing. It supports cookieless tracking, allowing analytics to continue even without cookie consent.
-- [Promptwatch](./integrations/promptwatch.md): Promptwatch analyzes traffic on your site for Artificial Intelligence (AI) traffic and usage insights. Data is stored in the EU without user-identifiable information.
-- [Reddit Pixel](./integrations/reddit-pixel.md): Track conversions and build retargeting audiences for Reddit advertising campaigns.
-- [RudderStack](./integrations/rudderstack.md): Load RudderStack's JavaScript SDK with c15t and gate the browser SDK behind measurement consent.
-- [Rybbit Analytics](./integrations/rybbit-analytics.md): Privacy-friendly analytics with script-tag configuration via Rybbit's data attributes.
-- [Segment](./integrations/segment.md): Load Segment Analytics.js with c15t and gate it behind measurement consent.
-- [Snapchat Pixel](./integrations/snapchat-pixel.md): Measure Snapchat ad performance and build remarketing audiences with a prebuilt pixel helper.
-- [TikTok Pixel](./integrations/tiktok-pixel.md): Measure ad performance and build audiences for TikTok advertising campaigns.
-- [Umami Analytics](./integrations/umami-analytics.md): Open-source, cookieless analytics with a prebuilt helper that maps Umami's data attributes into a c15t-managed script.
-- [Vercel Analytics](./integrations/vercel-analytics.md): Bootstrap Vercel Analytics with a declarative queue and script attributes.
-- [X Pixel (Twitter Pixel)](./integrations/x-pixel.md): Track conversions and build audiences for advertising campaigns on X (formerly Twitter).
-- [YouTube](./integrations/youtube.md): Keep YouTube iframes unmounted until consent with a privacy-enhanced, lazy-loaded React or Next.js embed.
+- [Adobe Analytics](./integrations/adobe-analytics.md): Configure Adobe Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Amplitude](./integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
+- [Custom integrations](./integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
+- [Clear on revocation](./integrations/clear-on-revocation.md): Remove configured first-party cookies and Web Storage keys when their consent category is denied.
+- [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
+- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
+- [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
+- [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
+- [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
+- [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
+- [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
+- [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.
+- [Intercom](./integrations/intercom.md): Load the Intercom messenger with functionality permission and configure its region.
+- [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Configure LinkedIn Insight Tag with c15t v3, understand marketing permission and verify loading and revocation.
+- [LogRocket](./integrations/logrocket.md): Configure LogRocket with c15t v3, understand measurement permission and verify loading and revocation.
+- [Matomo Analytics](./integrations/matomo-analytics.md): Choose gated loading or Matomo consent signaling and configure the correct tracker endpoints.
+- [Meta Pixel](./integrations/meta-pixel.md): Register the Meta Pixel under marketing permission and verify event calls after revocation.
+- [Microsoft Clarity](./integrations/microsoft-clarity.md): Configure Microsoft Clarity with c15t v3, understand measurement permission and verify loading and revocation.
+- [Microsoft UET](./integrations/microsoft-uet.md): Configure Microsoft UET with c15t v3, understand marketing permission and verify loading and revocation.
+- [Mixpanel](./integrations/mixpanel-analytics.md): Configure Mixpanel with c15t v3, understand measurement permission and verify loading and revocation.
+- [OpenAI Pixel](./integrations/openai-pixel.md): Configure the OpenAI Measurement Pixel for ChatGPT Ads with c15t v3, manage marketing permission and verify conversion delivery.
+- [Overview](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, chat and embedded content.
+- [Pirsch](./integrations/pirsch.md): Configure Pirsch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Plausible Analytics](./integrations/plausible-analytics.md): Configure Plausible Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [PostHog](./integrations/posthog.md): Choose PostHog loading and cookieless behavior, configure the region, and synchronize v3 permissions.
+- [Promptwatch](./integrations/promptwatch.md): Configure Promptwatch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Reddit Pixel](./integrations/reddit-pixel.md): Configure Reddit Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [RudderStack](./integrations/rudderstack.md): Gate the RudderStack browser SDK or map c15t categories to destination consent IDs.
+- [Rybbit Analytics](./integrations/rybbit-analytics.md): Configure Rybbit Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Segment](./integrations/segment.md): Configure Segment with c15t v3, understand measurement permission and verify loading and revocation.
+- [Snapchat Pixel](./integrations/snapchat-pixel.md): Configure Snapchat Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [TikTok Pixel](./integrations/tiktok-pixel.md): Configure TikTok Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [Umami Analytics](./integrations/umami-analytics.md): Configure Umami Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Vercel Analytics](./integrations/vercel-analytics.md): Configure Vercel Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [X Pixel](./integrations/x-pixel.md): Configure X Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [YouTube](./integrations/youtube.md): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
 
 ## Reference
 
-Concepts, legal templates, open-source policies, and contributor documentation.
-
-- [Client Modes](./shared/concepts/client-modes.md): Reference page for client modes.
-- [Consent Categories](./shared/concepts/consent-categories.md): Reference page for consent categories.
-- [Consent Models](./shared/concepts/consent-models.md): Reference page for consent models.
-- [Cookie Management](./shared/concepts/cookie-management.md): Reference page for cookie management.
-- [Glossary](./shared/concepts/glossary.md): Reference page for glossary.
-- [Initialization Flow](./shared/concepts/initialization-flow.md): Reference page for initialization flow.
-- [Policy Packs](./shared/concepts/policy-packs.md): Reference page for policy packs.
-- [Consent Banner](./shared/react/components/consent-banner.md): Reference page for consent banner.
-- [Consent Dialog](./shared/react/components/consent-dialog.md): Reference page for consent dialog.
-- [Consent Dialog Link](./shared/react/components/consent-dialog-link.md): Reference page for consent dialog link.
-- [Consent Dialog Trigger](./shared/react/components/consent-dialog-trigger.md): Reference page for consent dialog trigger.
-- [Consent Manager Provider](./shared/react/components/consent-manager-provider.md): Reference page for consent manager provider.
-- [Consent Widget](./shared/react/components/consent-widget.md): Reference page for consent widget.
-- [Dev Tools](./shared/react/components/dev-tools.md): Reference page for dev tools.
-- [Frame](./shared/react/components/frame.md): Reference page for frame.
-- [Building Headless Components](./shared/react/guides/building-headless-components.md): Reference page for building headless components.
-- [Callbacks](./shared/react/guides/callbacks.md): Reference page for callbacks.
-- [Headless](./shared/react/guides/headless.md): Reference page for headless.
-- [Iframe Blocking](./shared/react/guides/iframe-blocking.md): Reference page for iframe blocking.
-- [Internationalization](./shared/react/guides/internationalization.md): Reference page for internationalization.
-- [Network Blocker](./shared/react/guides/network-blocker.md): Reference page for network blocker.
-- [Optimization](./shared/react/guides/optimization.md): Reference page for optimization.
-- [Policy Packs](./shared/react/guides/policy-packs.md): Reference page for policy packs.
-- [Script Loader](./shared/react/guides/script-loader.md): Reference page for script loader.
-- [Use Color Scheme](./shared/react/hooks/use-color-scheme.md): Reference page for use color scheme.
-- [Checking Consent](./shared/react/hooks/use-consent-manager/checking-consent.md): Reference page for checking consent.
-- [Location Info](./shared/react/hooks/use-consent-manager/location-info.md): Reference page for location info.
-- [Overview](./shared/react/hooks/use-consent-manager/overview.md): Reference page for overview.
-- [Setting Consent](./shared/react/hooks/use-consent-manager/setting-consent.md): Reference page for setting consent.
-- [Use Draggable](./shared/react/hooks/use-draggable.md): Reference page for use draggable.
-- [Use Focus Trap](./shared/react/hooks/use-focus-trap.md): Reference page for use focus trap.
-- [Use Reduced Motion](./shared/react/hooks/use-reduced-motion.md): Reference page for use reduced motion.
-- [Use SSR Status](./shared/react/hooks/use-ssr-status.md): Reference page for use ssr status.
-- [Use Text Direction](./shared/react/hooks/use-text-direction.md): Reference page for use text direction.
-- [Use Translations](./shared/react/hooks/use-translations.md): Reference page for use translations.
-- [Consent Banner](./shared/react/iab/consent-banner.md): Reference page for consent banner.
-- [Consent Dialog](./shared/react/iab/consent-dialog.md): Reference page for consent dialog.
-- [Overview](./shared/react/iab/overview.md): Reference page for overview.
-- [Use GVL Data](./shared/react/iab/use-gvl-data.md): Reference page for use gvl data.
-- [Classnames](./shared/react/styling/classnames.md): Reference page for classnames.
-- [Color Scheme](./shared/react/styling/color-scheme.md): Reference page for color scheme.
-- [CSS Variables](./shared/react/styling/css-variables.md): Reference page for css variables.
-- [Overview](./shared/react/styling/overview.md): Reference page for overview.
-- [Slots](./shared/react/styling/slots.md): Reference page for slots.
-- [Stylesheet Entrypoint](./shared/react/styling/stylesheet-entrypoint.md): Reference page for stylesheet entrypoint.
-- [Tailwind](./shared/react/styling/tailwind.md): Reference page for tailwind.
-- [Tokens](./shared/react/styling/tokens.md): Reference page for tokens.
-- [Troubleshooting](./shared/troubleshooting.md): Reference page for troubleshooting.
+- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.

package/docs/customization/overview.md

@@ -0,0 +1,45 @@
+---
+title: Customize your consent interface
+description: Choose presentation, theme tokens, slots or custom markup for the
+  change you need.
+group: customization
+---
+
+## Start with the change you want
+
+| Change                                    | Use                                 | Why                                                          |
+| ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------ |
+| Banner shape or location                  | Presentation or banner props        | Keeps policy actions and built-in layout behavior            |
+| Brand colors, radius, typography, spacing | Theme tokens                        | Changes related component parts together                     |
+| One card, footer, title or button group   | Component slots                     | Targets existing markup                                      |
+| Labels, descriptions or language          | i18n configuration                  | Keeps banner and preferences copy consistent                 |
+| A different component structure           | Compound components where available | Retains the component behavior while changing markup         |
+| Your own interaction and markup           | Headless APIs                       | You own rendering, focus behavior and policy action coverage |
+
+Most brand changes need tokens and a few slots. Start there before opting out
+of the stock styles. The [recipes](./recipes.md) show how each
+choice affects a real banner.
+
+## Keep behavior and appearance separate
+
+Presentation controls the prompt's shape, position and blocking behavior.
+Policy controls which actions and rights are required. Changing colors or button
+order does not change a saved choice or policy scope.
+
+A choice wall always blocks. Notices never block and cannot become a wall merely
+because `variant: 'wall'` was requested. Preference dialogs remain centered;
+prompt positioning does not move them. Required actions omitted from a custom
+layout can be restored by the policy renderer.
+
+## Use the adapter's configuration shape
+
+React and Next.js accept provider `theme`, `presentation` and `components`
+options. Vue and Nuxt expose their own shared configuration, including CSS
+`tokens` and component slots. Svelte accepts its provider options and theme
+contract. Astro serializes integration options and uses the selected adapter for
+dialogs. Do not move a configuration object between frameworks without checking
+the target types.
+
+Read [tokens and CSS](./tokens.md),
+[slots](./slots.md) or
+[copy and translations](./translations.md) for the next step.

package/docs/customization/recipes.md

@@ -0,0 +1,79 @@
+---
+title: Banner styling recipes
+description: See real v3 components and reuse the exact theme configuration
+  behind the examples.
+group: customization
+---
+
+## A branded floating card
+
+This theme uses a green primary action and a four-pixel large radius. Accept and
+Reject keep matching treatment. The component's required action behavior stays
+intact.
+
+![A v3 floating consent card with green Customize action, matching Accept and Reject buttons, and compact corners](../assets/v3/brand-card.png)
+
+```ts
+import { defineTheme } from '@c15t/ui/theme';
+
+export const brandTheme = defineTheme({
+	colors: { primary: '#2f6f4e' },
+	consentActions: {
+		primary: { mode: 'filled', variant: 'primary' },
+	},
+	radius: { lg: '4px' },
+});
+
+```
+
+Install `@c15t/ui` to use `defineTheme` directly. Pass `brandTheme` as `theme` in
+your existing React or Next.js provider options. Keep your Inth mode and script
+configuration. The theme source above is also imported by the runnable example,
+so the rendered result and the documentation use the same values.
+
+## Change the shape without rebuilding the banner
+
+```tsx
+<ConsentBanner variant="bar" />
+```
+
+![The same green theme on a full-width v3 consent bar with the actions arranged across its footer](../assets/v3/brand-bar.png)
+
+A bar changes the prompt's footprint. It does not change policy, grant categories
+or require a headless implementation.
+
+```tsx
+<ConsentBanner variant="wall" />
+```
+
+![A centered v3 choice wall with a backdrop, using the same green action theme](../assets/v3/choice-wall.png)
+
+A choice wall blocks interaction with the page. A notice never blocks; requesting
+a wall for a notice falls back to a non-blocking presentation.
+
+## Carry the theme into preferences
+
+![The v3 preferences dialog with optional category toggles and a green Save Settings action](../assets/v3/preferences.png)
+
+Keep a preferences link after the banner closes. Test a reject action, reopen
+the dialog, change one category and save. A branded prompt is only part of the
+consent flow.
+
+## Check narrow screens
+
+![The branded v3 floating card at a 375-pixel viewport, with Accept and Reject sharing a row and Customize below](../assets/v3/mobile-card.png)
+
+This example fits a 375-pixel viewport without horizontal overflow. Test your
+own longest translations and font settings before adopting the same sizing.
+
+## Run the examples
+
+The source repository contains resettable Storybook examples under
+`Docs / Customization`: Brand Card, Brand Bar and Choice Wall. Each demo uses
+in-memory consent and no analytics; Reset example returns it to a fresh choice.
+The screenshots above come from these v3 examples.
+
+The stories are suitable for isolated iframe previews on a version-matched
+Storybook deployment. Keep source code and the explanation on this page when
+embedding them, so the recipe remains usable in Markdown and offline package
+docs. A live preview must use the same v3 revision as the documentation.

package/docs/customization/slots.md

@@ -0,0 +1,55 @@
+---
+title: Style component slots
+description: Target a specific c15t component part without replacing its markup or behavior.
+group: customization
+---
+
+## Use slots for local changes
+
+In React and Next.js, put per-part attributes in `options.components`. This
+fragment belongs in an existing provider's options:
+
+```tsx
+components: {
+  banner: {
+    card: { className: 'rounded-none shadow-none' },
+    title: { className: 'font-semibold' },
+    footer: { className: 'border-t' },
+  },
+}
+```
+
+The class names above assume Tailwind. A slot can also receive `style` and other
+supported element attributes. Keep shared colors and radius scales in tokens;
+use slots when only one component part should change.
+
+## Read attributes on the right element
+
+The banner root carries `data-prompt`, `data-model`, `data-variant`,
+`data-position` and `data-blocking`. Its child card does not inherit those HTML
+attributes. In Tailwind, give the root `className: 'group'` and use
+`group-data-[variant=bar]:...` on a child slot.
+
+| React banner slot                  | Use                                   |
+| ---------------------------------- | ------------------------------------- |
+| `root`                             | Position wrapper and state attributes |
+| `cardShell`                        | Card sizing and branding container    |
+| `card`                             | Visible card                          |
+| `header`, `title`, `description`   | Heading and explanatory copy          |
+| `footer`, `actions`, `actionGroup` | Action layout                         |
+| `rights`, `rightLink`              | Preferences access controls           |
+| `overlay`                          | Backdrop for blocking presentation    |
+
+Buttons expose `data-action` for action-specific CSS. Test notices as well as
+choice prompts; a notice uses acknowledgement rather than accept/reject.
+
+## When to remove styles
+
+`noStyle` removes the built-in component styling. It does not supply replacement
+layout, spacing, focus indicators or responsive behavior. Use it when you intend
+to own all of that work, not as the first response to a token that appears to do
+nothing.
+
+If the markup itself must change, use the adapter's compound components or
+headless API. The slot objects above are the React contract; check Vue and Svelte
+slot types before reusing them.

package/docs/customization/tokens.md

@@ -0,0 +1,76 @@
+---
+title: Theme tokens and CSS
+description: Style c15t with semantic tokens and use the stylesheet that matches
+  your CSS tooling.
+group: customization
+---
+
+## Load the stock stylesheet once
+
+React, Next.js and Svelte provide `styles.css`. Import the adapter's stylesheet
+at the app's global entry point. Vue includes styles in its components; Astro
+adds styles through its integration.
+
+```tsx
+import 'c15t/react/styles.css';
+```
+
+The standard stylesheet places rules in `@layer components`. For Tailwind 3,
+use the `styles.tw3.css` entry instead of the standard stylesheet, between the
+components and utilities directives in your Tailwind entry:
+
+```css
+@tailwind base;
+@tailwind components;
+@import 'c15t/react/styles.tw3.css';
+@tailwind utilities;
+```
+
+Do not load both c15t stylesheet variants. For Tailwind 4 or unlayered CSS,
+inspect layer order before reaching for `!important`.
+
+## Set semantic values together
+
+This React theme changes the brand color and large corner radius. Include
+hover and foreground colors when overriding raw variables so the button remains
+readable in each state.
+
+```ts
+import { defineTheme } from '@c15t/ui/theme';
+
+export const theme = defineTheme({
+  colors: { primary: '#2f6f4e' },
+  radius: { lg: '4px' },
+  consentActions: {
+    primary: { variant: 'primary', mode: 'filled' },
+    dismiss: { variant: 'neutral', mode: 'stroke' },
+  },
+});
+```
+
+Install `@c15t/ui` if importing its theme helper directly. Pass `theme` in your
+provider options. `consentActions` selects styling by action role. A per-action
+entry overrides `primary`, which overrides `default`.
+
+## Target a prompt with CSS
+
+```css
+[data-prompt][data-model='opt-in'] {
+  --c15t-primary: #2f6f4e;
+  --c15t-primary-hover: #24563c;
+  --c15t-text-on-primary: #fff;
+}
+```
+
+Use attributes exposed by the rendered component, not guessed class names.
+Test the prompt and the preferences dialog separately because tokens scoped to
+one prompt do not automatically reach a portaled dialog.
+
+| Size variable                       | Default | Target        |
+| ----------------------------------- | ------- | ------------- |
+| `--consent-banner-max-width`        | `440px` | Floating card |
+| `--consent-banner-widget-max-width` | `20rem` | Widget        |
+| `--consent-banner-wall-max-width`   | `30rem` | Choice wall   |
+
+Test long translations and small screens after changing width or typography.
+A compact banner must still fit the required actions.

package/docs/customization/translations.md

@@ -0,0 +1,49 @@
+---
+title: Copy and translations
+description: Change consent wording through i18n and test the complete prompt
+  and preferences flow.
+group: customization
+---
+
+## Configure shared messages
+
+Use provider `i18n` for wording that should stay consistent across components.
+For React, this fragment belongs in `ConsentProvider` options:
+
+```tsx
+i18n: {
+  messages: {
+    en: {
+      common: {
+        acceptAll: 'Accept all',
+        rejectAll: 'Reject optional',
+        customize: 'Choose cookies',
+        acknowledge: 'Got it',
+      },
+    },
+  },
+}
+```
+
+Supply the same message keys in each supported locale. A one-off component prop
+such as `dismissButtonText` is useful for one banner; use translations for a
+site-wide change. Astro's serializable integration options and Vue's module
+configuration have their own types, so verify those shapes before copying a
+React object.
+
+## Write labels that describe the action
+
+Accept and Reject record a choice. Customize opens preferences. Acknowledge
+dismisses a notice and does not record a grant. Do not label a notice dismissal
+"Accept all" or make a preferences link sound like it submits an opt-out.
+
+The notice acknowledgement uses `common.acknowledge`, with `common.dismiss` as
+a fallback for older translation bundles. Keep the displayed label and the
+command's effect aligned.
+
+## Test more than English
+
+Try the longest labels you support at a narrow width, with browser zoom and
+right-to-left text where relevant. Check banner actions, category descriptions,
+legal links and the preferences save action. Translate explanations as well as
+buttons so a visitor can make an informed choice.