@c15t/react 2.0.4 → 2.2.0-canary-20260727202135

package/docs/shared/react/components/consent-dialog.md

@@ -0,0 +1,119 @@
+---
+title: Consent Dialog
+description: Reference page for consent dialog.
+group: reference
+---
+`ConsentDialog` is a modal that shows toggles for each consent category. In **opt-in jurisdictions**, it typically opens when users click "Customize" on `ConsentBanner`. It can also be controlled programmatically for use on settings pages regardless of jurisdiction.
+
+## Floating Trigger
+
+Add a floating button that lets users re-open the dialog after dismissing the banner:
+
+```tsx
+{/* Default trigger */}
+<ConsentDialog showTrigger />
+
+{/* Custom trigger */}
+<ConsentDialog
+  showTrigger={{
+    icon: 'settings',
+    defaultPosition: 'bottom-left',
+    showWhen: 'after-consent',
+    size: 'sm',
+  }}
+/>
+```
+
+## Branding
+
+Hide the c15t branding tag:
+
+```tsx
+<ConsentDialog hideBranding />
+```
+
+## Styling First
+
+> ℹ️ **Info:**
+> If you are only changing visuals, stay with the stock dialog and use the theme system first. Start with tokens and slots such as consentDialogCard, consentWidgetFooter, and consentDialogTag. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentDialogCard: 'rounded-[32px] shadow-xl',
+        consentDialogHeader: 'gap-3',
+        consentWidgetFooter: 'gap-3 pt-6',
+        consentDialogTag: 'shadow-none',
+      },
+    },
+  }}
+>
+  <ConsentDialog />
+</ConsentManagerProvider>
+```
+
+Dialog copy should be changed through `ConsentManagerProvider.options.i18n`, not by rebuilding the dialog structure.
+
+## Advanced: Compound Components
+
+Use compound components only when you need custom dialog markup while still keeping c15t primitives and policy-aware footer actions:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.Overlay />
+  <ConsentDialog.Card>
+    <ConsentDialog.Header>
+      <ConsentDialog.HeaderTitle />
+      <ConsentDialog.HeaderDescription />
+    </ConsentDialog.Header>
+    <ConsentDialog.Content>
+      <ConsentWidget.Root>
+        <ConsentWidget.Accordion type="single">
+          <ConsentWidget.AccordionItems />
+        </ConsentWidget.Accordion>
+        <ConsentWidget.PolicyActions />
+      </ConsentWidget.Root>
+    </ConsentDialog.Content>
+    <ConsentDialog.Footer />
+  </ConsentDialog.Card>
+</ConsentDialog.Root>
+```
+
+* `ConsentDialog.Root` — Portal container with focus trap, scroll lock, and animation
+* `ConsentDialog.Card` — Main dialog card
+* `ConsentDialog.Header` — Contains title and description
+* `ConsentDialog.HeaderTitle` — Dialog title
+* `ConsentDialog.HeaderDescription` — Description with optional `legalLinks`
+* `ConsentDialog.Content` — Main content area (typically contains `ConsentWidget`)
+* `ConsentDialog.Footer` — Footer with optional branding (`hideBranding` prop)
+* `ConsentDialog.Overlay` — Backdrop overlay
+* `ConsentWidget.PolicyActions` — Renders policy-aware grouped dialog actions
+
+For a quick pre-composed layout, use the shorthand card:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.ConsentCustomizationCard />
+</ConsentDialog.Root>
+```
+
+`ConsentWidget.PolicyActions` uses stock c15t widget buttons and translations by default. Pass `renderAction` only when you need to customize the action mapping, and return stock widget button compounds if you want to preserve built-in behavior and copy.
+
+For fully manual control over dialog action rendering, use `useHeadlessConsentUI()` and map `dialog.actionGroups` yourself.
+
+If the stock dialog structure still works, prefer tokens, slots, and provider configuration instead.
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentDialogProps\`|
+|Source Path|\`./packages/react/src/components/consent-dialog/consent-dialog.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentDialogProps" from "./packages/react/src/components/consent-dialog/consent-dialog.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/react/components/consent-manager-provider.md

@@ -0,0 +1,183 @@
+---
+title: Consent Manager Provider
+description: Reference page for consent manager provider.
+group: reference
+---
+`ConsentManagerProvider` is the root component for the c15t consent system. It initializes the consent store, detects the user's jurisdiction, resolves translations, and provides consent state to all child components via React context.
+
+Every other c15t component and hook must be rendered inside this provider.
+
+## Options Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`CommonInlineStoreOptions\`|
+|Source Path|\`./packages/ui/src/theme/options.ts\`|
+
+\*ExtractedTypeTable: Could not extract "CommonInlineStoreOptions" from "./packages/ui/src/theme/options.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentManagerContentOptions\`|
+|Source Path|\`./packages/ui/src/theme/options.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentManagerContentOptions" from "./packages/ui/src/theme/options.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`UIOptions\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "UIOptions" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Legal Links
+
+`legalLinks` defines the URLs shown in consent UI text (banner, dialog, and widget where applicable).
+Configure only the links you want to expose.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    legalLinks: {
+      privacyPolicy: {
+        href: '/privacy',
+        target: '_self',
+      },
+      cookiePolicy: {
+        href: '/cookies',
+        target: '_self',
+      },
+      termsOfService: {
+        href: 'https://example.com/terms',
+        target: '_blank',
+        rel: 'noopener noreferrer',
+        label: 'Terms of Service',
+      },
+    },
+  }}
+>
+```
+
+Notes:
+
+* Omitting a key (for example `termsOfService`) hides that link.
+* `label` overrides the translated text for that single link.
+* Use `_self` for internal pages and `_blank` + `rel="noopener noreferrer"` for external pages.
+* Control which of the configured links render in each component via the component's `legalLinks` prop.
+
+## Overrides
+
+`overrides` lets you force location/language signals instead of browser or network detection.
+This is useful for QA, local development, and preview environments.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    overrides: {
+      country: 'DE',
+      region: 'BY',
+      language: 'de-DE',
+    },
+  }}
+>
+```
+
+You can also override Global Privacy Control (GPC) behavior during testing:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    overrides: {
+      gpc: true,
+    },
+  }}
+>
+```
+
+> ⚠️ **Warning:**
+> Treat overrides as an environment/testing tool. Avoid hard-coding production overrides unless that behavior is intentional for your deployment.
+
+## Policy Packs
+
+In hosted mode (recommended), the backend resolves the correct policy automatically — no frontend policy config needed:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+  }}
+>
+```
+
+### Fallback: Offline Policies
+
+When no backend is available, `ConsentManagerProvider` accepts `offlinePolicy.policyPacks` for local policy resolution during development, testing, previews, or temporary backend outages:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    mode: 'offline',
+    offlinePolicy: {
+      i18n: {
+        defaultProfile: 'default',
+        messages: {
+          default: {
+            translations: {
+              en: { cookieBanner: { title: 'Privacy choices' } },
+            },
+          },
+          qc: {
+            fallbackLanguage: 'fr',
+            translations: {
+              en: { cookieBanner: { title: 'Quebec Privacy Settings' } },
+              fr: { cookieBanner: { title: 'Paramètres de confidentialité du Québec' } },
+            },
+          },
+        },
+      },
+      policyPacks: [
+        {
+          id: 'qc_opt_in',
+          match: { regions: [{ country: 'CA', region: 'QC' }] },
+          i18n: { messageProfile: 'qc' },
+          consent: { model: 'opt-in', expiryDays: 365 },
+          ui: { mode: 'banner' },
+        },
+        {
+          id: 'default_world',
+          match: { isDefault: true },
+          consent: { model: 'none' },
+          ui: { mode: 'none' },
+        },
+      ],
+    },
+    overrides: {
+      country: 'CA',
+      region: 'QC',
+    },
+  }}
+>
+```
+
+Notes:
+
+* `offlinePolicy` is only used in `offline` mode.
+* Treat offline policies as a development/testing tool or resilience fallback, not the primary production source of truth.
+* `offlinePolicy.i18n` lets offline mode mirror hosted `messageProfile` and profile-local `fallbackLanguage` behavior.
+* Omitting `offlinePolicy.policyPacks` uses the built-in synthetic opt-in fallback banner. Hosted network fallback uses the same opt-in banner.
+* `offlinePolicy: { policyPacks: [] }` is explicit no-banner mode.
+* In hosted mode, backend `policyPacks` remain the source of truth — frontend offline policies never override a live backend decision.
+
+Read the full guide at [Policy Packs](/docs/frameworks/react/policy-packs) and the conceptual model at [Policy Packs Concept](/docs/frameworks/react/concepts/policy-packs).
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentManagerProviderProps\`|
+|Source Path|\`./packages/react/src/types/consent-manager.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentManagerProviderProps" from "./packages/react/src/types/consent-manager.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/react/components/consent-widget.md

@@ -0,0 +1,121 @@
+---
+title: Consent Widget
+description: Reference page for consent widget.
+group: reference
+---
+`ConsentWidget` is a standalone, inline consent management widget. Unlike `ConsentDialog` (which is a modal), the widget embeds directly in your page layout - ideal for privacy settings pages, account preferences, or any page where users should be able to manage consent without a modal overlay.
+
+## Configuration
+
+```tsx
+<ConsentWidget
+  hideBranding
+  legalLinks={['privacyPolicy', 'cookiePolicy']}
+  noStyle={false}
+  disableAnimation={false}
+/>
+```
+
+## Accordion Behavior
+
+Each consent category is rendered as an expandable accordion item. Clicking the category header expands it to show a description and any associated services. Users can toggle individual categories on or off using the switch control. The `necessary` category is always enabled and cannot be toggled.
+
+## Styling First
+
+> ℹ️ **Info:**
+> Most widget customization should stay in the stock component. Use theme tokens and slots such as consentWidgetAccordion, consentWidgetFooter, consentWidgetFooterSubGroup, and toggle before reaching for compound components. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentWidgetAccordion: 'rounded-3xl border border-black/10',
+        consentWidgetFooter: 'border-t border-black/10 px-6',
+        consentWidgetFooterSubGroup: 'gap-3',
+        toggle: 'shadow-sm',
+      },
+    },
+  }}
+>
+  <ConsentWidget />
+</ConsentManagerProvider>
+```
+
+Use `consentWidgetFooter` for styling the whole action area, such as border and padding. Use `consentWidgetFooterSubGroup` for spacing or alignment inside nested button groups.
+
+Widget copy should be changed through `ConsentManagerProvider.options.i18n` so the inline UI stays aligned with the rest of the consent experience.
+
+## Advanced: Compound Components
+
+Use compound components only when you need to rearrange the widget's existing primitives while keeping policy-aware action grouping:
+
+```tsx
+<ConsentWidget.Root>
+  <ConsentWidget.Accordion type="multiple">
+    <ConsentWidget.AccordionItems />
+  </ConsentWidget.Accordion>
+  <ConsentWidget.PolicyActions />
+</ConsentWidget.Root>
+```
+
+* `ConsentWidget.Root` — Theme context provider
+* `ConsentWidget.Accordion` — Radix-based accordion root
+* `ConsentWidget.AccordionItems` — Auto-generates toggle items from consent config
+* `ConsentWidget.AccordionItem` — Individual category item
+* `ConsentWidget.AccordionTrigger` — Clickable header for each item
+* `ConsentWidget.AccordionContent` — Collapsible content area
+* `ConsentWidget.AccordionArrow` — Expand/collapse indicator
+* `ConsentWidget.Switch` — Category toggle switch
+* `ConsentWidget.PolicyActions` — Renders grouped policy-aware actions
+* `ConsentWidget.Footer` — Footer container
+* `ConsentWidget.FooterSubGroup` — Groups related buttons
+* `ConsentWidget.AcceptAllButton` — Accepts all consent
+* `ConsentWidget.RejectButton` — Rejects all consent
+* `ConsentWidget.SaveButton` — Saves custom selections
+
+## Using `renderAction` with c15t Defaults
+
+`ConsentWidget.PolicyActions` renders stock c15t buttons and translations by default.
+
+```tsx
+<ConsentWidget.PolicyActions />
+```
+
+`renderAction` is optional. Return the stock button compounds when you want custom mapping while preserving built-in c15t behavior and copy:
+
+```tsx
+<ConsentWidget.PolicyActions
+renderAction={(action, props) => {
+  const { key, ...buttonProps } = props
+
+  switch (action) {
+    case 'accept':
+        return <ConsentWidget.AcceptAllButton key={key} {...buttonProps} />
+    case 'reject':
+        return <ConsentWidget.RejectButton key={key} {...buttonProps} />
+    case 'customize':
+        return <ConsentWidget.SaveButton key={key} {...buttonProps} />
+  }
+}}
+/>
+```
+
+`renderAction` is still meant for stock button compounds. If you want completely custom button elements and handlers, use `useHeadlessConsentUI()` and render `dialog.actionGroups` manually instead of `ConsentWidget.PolicyActions`.
+
+For a fixed footer layout, render `ConsentWidget.Footer` and `ConsentWidget.FooterSubGroup` manually instead of using `ConsentWidget.PolicyActions`.
+
+If the stock widget structure is already correct, stay with tokens and slots instead of rebuilding the layout.
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentWidgetProps\`|
+|Source Path|\`./packages/react/src/components/consent-widget/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentWidgetProps" from "./packages/react/src/components/consent-widget/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/react/components/dev-tools.md

@@ -0,0 +1,81 @@
+---
+title: Dev Tools
+description: Reference page for dev tools.
+group: reference
+---
+`DevTools` is a floating panel that shows the internal state of the consent manager. Use it during development to inspect consent values, geolocation results, loaded scripts, and debug consent flows. Also exported as `C15TDevTools` if you need to avoid naming conflicts with other devtools.
+
+> ⚠️ **Warning:**
+> DevTools should only be included in development builds. The component renders nothing to the React tree - it injects directly into document.body.
+
+## Installation
+
+DevTools lives in a separate package to keep it out of production bundles:
+
+```bash
+bun add -D @c15t/dev-tools
+```
+
+## Configuration
+
+```tsx
+<DevTools
+  position="bottom-right"  // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  defaultOpen={false}       // Start with panel open
+  namespace="c15tStore"     // Store namespace to connect to
+  disabled={false}          // Disable without removing from tree
+/>
+```
+
+## Panels
+
+|Panel|What it shows|
+|--|--|
+|**Consents**|Current consent state for all categories|
+|**Location**|Detected jurisdiction, country, region, and consent model|
+|**Scripts**|Configured scripts and their load status|
+|**IAB**|IAB TCF state (when enabled) - TC string, vendor consents, purposes|
+|**Events**|Timeline of consent events and state changes|
+|**Actions**|Buttons to trigger consent actions (accept all, reject all, reset)|
+
+## TanStack Devtools
+
+`@c15t/dev-tools/tanstack` exposes a panel component and plugin factory that match TanStack Devtools' plugin API, so c15t can sit beside Query and Router without a custom mount adapter:
+
+```tsx
+import * as React from 'react';
+import { useRouter } from '@tanstack/react-router';
+import { TanStackDevtools } from '@tanstack/react-devtools';
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
+import { c15tDevtools } from '@c15t/dev-tools/tanstack';
+
+export function AppDevtools() {
+  const router = useRouter();
+
+  return (
+    <TanStackDevtools
+      plugins={[
+        {
+          name: 'TanStack Query',
+          render: <ReactQueryDevtoolsPanel />,
+        },
+        {
+          name: 'TanStack Router',
+          render: <TanStackRouterDevtoolsPanel router={router} />,
+        },
+        c15tDevtools(),
+      ]}
+    />
+  );
+}
+```
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`C15TDevToolsProps\`|
+|Source Path|\`./packages/dev-tools/src/react.ts\`|
+
+\*ExtractedTypeTable: Could not extract "C15TDevToolsProps" from "./packages/dev-tools/src/react.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/react/components/frame.md

@@ -0,0 +1,52 @@
+---
+title: Frame
+description: Reference page for frame.
+group: reference
+---
+`Frame` conditionally renders its children based on consent state. When consent for the specified category is not granted, a placeholder is shown instead. Children are not mounted at all until consent is given, preventing any network requests or script execution.
+
+## Custom Placeholder
+
+Replace the default placeholder:
+
+```tsx
+<Frame
+  category="experience"
+  placeholder={
+    <div className="rounded-lg border p-8 text-center">
+      <p>This content requires experience cookies.</p>
+      <p>Please enable them in your privacy settings.</p>
+    </div>
+  }
+>
+  <InteractiveWidget />
+</Frame>
+```
+
+## Compound Components
+
+Build fully custom placeholder layouts:
+
+```tsx
+<Frame.Root category="marketing">
+  <Frame.Title category="marketing" />
+  <Frame.Button category="marketing" />
+</Frame.Root>
+```
+
+* `Frame.Root` - Container with default placeholder styling
+* `Frame.Title` - Displays a consent-request message with the category name
+* `Frame.Button` - Button that opens the consent dialog for the specified category
+
+## Automatic Category Registration
+
+When `Frame` mounts, it automatically adds its `category` to the active `consentCategories` list. This means you don't need to explicitly list the category in your provider's `consentCategories` option - if a `Frame` component uses it, it will be registered.
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`FrameProps\`|
+|Source Path|\`./packages/react/src/components/frame/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "FrameProps" from "./packages/react/src/components/frame/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/react/guides/building-headless-components.md

@@ -0,0 +1,110 @@
+---
+title: Building Headless Components
+description: Reference page for building headless components.
+group: reference
+---
+Building custom consent UI is easier now because c15t exposes multiple layers of policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
+
+Think of customization as a ladder:
+
+* stock component props for the shortest path
+* `ConsentBanner.PolicyActions` and `ConsentWidget.PolicyActions` when you want custom structure but still want c15t to resolve policy-aware actions
+* `useHeadlessConsentUI()` when you need fully manual action rendering, custom controls, or non-standard flow
+
+> ⚠️ **Warning:**
+> Headless is the last step in the customization ladder. Use this guide only when pre-built components, tokens, slots, compound components, and noStyle are no longer sufficient.
+
+The headless stack underneath that is:
+
+* `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary actions hints
+* `@c15t/ui/utils` for the pure policy-action helpers that framework packages build on
+* `useConsentManager()` for runtime state, categories, selected consent state, and policy metadata
+* `useTranslations()` for the resolved copy
+* `offlinePolicy.policyPacks` for offline previews that behave like backend policy resolution
+
+The split is intentional: `@c15t/ui` owns pure policy-action resolution, while the framework hooks own visibility, consent mutations, and reactive state.
+
+> ℹ️ **Info:**
+> This guide is about building your own components while still respecting resolved policy-pack behavior. For the general headless overview, see Headless Mode.
+
+## Choose the Smallest Layer That Solves the Job
+
+Start with the smallest API surface that still gives you the behavior you need:
+
+* Stay with stock components when you only need theming, spacing, copy, or legal-link changes
+* Use `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions` when you want a custom compound-component layout but still want grouped actions, ordering, and primary emphasis to come from policy
+* Add `renderAction` when the grouping is still correct but you want to remap actions to stock c15t button compounds
+* Reach for `useHeadlessConsentUI()` only when you need custom button elements, need to map `actionGroups` yourself, wire non-button controls, or coordinate the consent UI with a more custom state machine
+
+This order matters because every step down the ladder gives you more control, but also makes it easier for your UI to drift away from the resolved policy if you stop using the provided state.
+
+## Before You Build Headless UI
+
+Do not use headless mode for problems that are still inside the stock component model:
+
+* Use `layout`, `direction`, `primaryButton`, and `legalLinks` before you rebuild banner markup
+* Use `theme.consentActions` before you swap out stock actions
+* Use tokens such as `colors.surface` and `colors.surfaceHover` before raw CSS overrides
+* Use slots such as `consentBannerCard`, `consentBannerFooter`, and `consentDialogCard` before compound components
+* Use `ConsentManagerProvider.options.i18n` before rebuilding UI just to change text
+
+A good rule: if the stock banner or dialog structure is still correct, you probably do not need headless mode.
+
+## What the Headless Tooling Gives You
+
+The main win is that your custom UI can stay aligned with policy packs without duplicating policy logic in your components.
+
+`useHeadlessConsentUI()` already resolves:
+
+* which actions are allowed
+* the order those actions should render in
+* grouped actions from policy `layout`
+* layout `direction` (`row` or `column`)
+* the primary actions
+* UI profile and scroll-lock hints
+* whether the banner or dialog should currently be visible
+
+The hook also gives you the policy-aware action helpers you are expected to call:
+
+* `performBannerAction('accept' | 'reject')`
+* `performDialogAction('accept' | 'reject')`
+* `saveCustomPreferences()` for the dialog `customize` action
+* `openDialog()`, `openBanner()`, and `closeUI()` for surface visibility
+
+That means your component mostly focuses on markup and design-system concerns instead of re-implementing policy interpretation.
+
+For most compound-component layouts, start with `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions`. They render stock c15t buttons and translations by default, and `renderAction` is only needed when you want to override which stock compound renders for each action. Reach for manual `actionGroups` mapping when you need action rendering that no longer fits the stock button compounds.
+
+## What Headless Is Not For
+
+Headless mode is not the recommended path for:
+
+* changing the banner footer background
+* rounding the stock banner card
+* restyling stock banner or dialog buttons
+* changing consent copy
+
+Those should stay in the pre-built stack with tokens, slots, `theme.consentActions`, and provider `i18n`.
+
+## What a Policy-Aware Headless Component Should Respect
+
+When you build custom banner or dialog components, make sure they use:
+
+* `activeUI` or `banner.isVisible` / `dialog.isVisible` for visibility
+* `allowedActions`, `actionGroups`, and `primaryActions` instead of hard-coding buttons
+* `primaryActions` for visual emphasis
+* `consentCategories` when deciding which category toggles to render
+* `policyDecision` when you want to debug why a specific UI state was chosen
+
+If you ignore those values, your custom UI can drift away from the resolved policy pack even though the underlying consent engine is configured correctly.
+
+## Validation and Testing
+
+If you are building a reusable headless component library, validate your rendered UI against the resolved runtime policy in tests.
+
+The core package exposes:
+
+* `getEffectivePolicy(initData)` to read the resolved policy from `/init`
+* `validateUIAgainstPolicy({ policy, state })` to detect mismatches such as wrong actions, layout, or mode
+
+This is useful when your design system renders custom button arrangements and you want tests to catch policy drift early.