@c15t/react 2.0.0-rc.7 → 2.0.0-rc.9

package/docs/building-headless-components.md

@@ -2,18 +2,27 @@
 title: Building Headless Components
 description: Build policy-aware custom consent components in React using the headless hooks and policy-pack tooling.
 ---
-Building headless components is easier now because c15t exposes policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
+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.
+
+The layering is:
+
+* stock component props for the shortest path
+* `ConsentBanner.PolicyActions` and `ConsentWidget.PolicyActions` for custom structure with policy-aware actions
+* `useHeadlessConsentUI()` for fully manual action rendering and non-standard controls
 
 > ⚠️ **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 is:
+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.
 
@@ -33,6 +42,11 @@ The main win is that your custom UI can stay aligned with policy packs without d
 
 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 the action mapping. Reach for manual `actionGroups` mapping when you need action rendering that no longer fits the stock button compounds.
+
+> ℹ️ **Info:**
+> For custom layouts built from c15t compound components, prefer ConsentBanner.PolicyActions and ConsentWidget.PolicyActions. The examples below intentionally use manual actionGroups mapping to show the fully headless escape hatch.
+
 ## Provider Setup for Local Policy Testing
 
 ```tsx
@@ -168,25 +182,29 @@ export function CustomConsentDialog() {
         ))}
       </div>
 
-      <div className="mt-4 flex gap-2">
-        {dialog.orderedActions.map((action) => (
-          <button
-            key={action}
-            type="button"
-            onClick={() => {
-              if (action === 'customize') {
-                void saveCustomPreferences();
-                return;
-              }
-              void performDialogAction(action);
-            }}
-          >
-            {action === 'accept'
-              ? translations.common.acceptAll
-              : action === 'reject'
-                ? translations.common.rejectAll
-                : translations.common.save}
-          </button>
+      <div className="mt-4 space-y-2">
+        {dialog.actionGroups.map((group, index) => (
+          <div key={`${group.join('-')}-${index}`} className="flex gap-2">
+            {group.map((action) => (
+              <button
+                key={action}
+                type="button"
+                onClick={() => {
+                  if (action === 'customize') {
+                    void saveCustomPreferences();
+                    return;
+                  }
+                  void performDialogAction(action);
+                }}
+              >
+                {action === 'accept'
+                  ? translations.common.acceptAll
+                  : action === 'reject'
+                    ? translations.common.rejectAll
+                    : translations.common.save}
+              </button>
+            ))}
+          </div>
         ))}
       </div>
     </section>
@@ -199,7 +217,7 @@ export function CustomConsentDialog() {
 When you build custom banner or dialog components, make sure they use:
 
 * `activeUI` or `banner.isVisible` / `dialog.isVisible` for visibility
-* `allowedActions`, `orderedActions`, or `actionGroups` instead of hard-coding buttons
+* `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

package/docs/callbacks.md

@@ -2,7 +2,12 @@
 title: Callbacks
 description: React to consent lifecycle events - initialization, consent changes, errors, and revocation reloads.
 ---
-Callbacks let you run custom code at key points in the consent lifecycle. Define them in the provider's `callbacks` option, or register them dynamically via `useConsentManager()`.
+Callbacks let you run custom code at key points in the consent lifecycle. Define them in the provider or runtime `callbacks` option, or register them dynamically after initialization.
+
+For analytics SDKs and other change-only integrations, prefer `subscribeToConsentChanges()` or `onConsentChanged`. Use `onConsentSet` when you want the broader lifecycle signal, including initialization, automatic defaults, and replay-aware registration.
+
+> ℹ️ **Info:**
+> subscribeToConsentChanges() is the recommended API for analytics SDKs and consent-mode integrations. It only emits future saves that actually changed persisted preferences.
 
 ## Configuration
 
@@ -23,8 +28,10 @@ export function ConsentManager({ children }: { children: ReactNode }) {
             console.log('Language:', translations.language);
           },
           onConsentSet: ({ preferences }) => {
-            // Fire analytics event
-            analytics.track('consent_updated', { preferences });
+            console.log('Consent lifecycle event:', preferences);
+          },
+          onConsentChanged: ({ allowedCategories, deniedCategories }) => {
+            analytics.syncConsent({ allowedCategories, deniedCategories });
           },
           onError: ({ error }) => {
             errorReporter.captureMessage(error);
@@ -42,6 +49,18 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 }
 ```
 
+## Choose the Right Surface
+
+|Surface|Replays when registered late?|Fires on init / hydration / auto-grants?|Best for|
+|--|--|--|--|
+|`onBannerFetched`|Yes, via `setCallback('onBannerFetched', ...)` after init|Yes|Logging resolved policy, location, and translations|
+|`onConsentSet`|Yes, via `setCallback('onConsentSet', ...)`|Yes|Broad lifecycle hooks, debugging, and integrations that want the latest full state regardless of how it was reached|
+|`onConsentChanged`|No|No|Declarative change-only integrations|
+|`subscribeToConsentChanges()`|No|No|Canonical change-only subscriptions after mount|
+
+> ℹ️ **Info:**
+> Script.onConsentChange is a script-scoped lifecycle hook. It is not the global consent change API for analytics SDKs or other app-wide integrations.
+
 ## Available Callbacks
 
 ### `onBannerFetched`
@@ -58,14 +77,34 @@ onBannerFetched: ({ jurisdiction, location, translations }) => {
 
 ### `onConsentSet`
 
-Called whenever consent preferences are saved - whether by user action (`saveConsents()`), automatic defaults, or on initialization when no jurisdiction is detected.
+Called whenever c15t broadly settles consent state: store initialization, automatic defaults during init, explicit saves, and replay via `setCallback('onConsentSet', ...)`.
 
 ```tsx
 onConsentSet: ({ preferences }) => {
   // preferences: { necessary: true, measurement: true, marketing: false, ... }
-  if (preferences.measurement) {
-    loadAnalytics();
-  }
+  console.log('Latest consent state:', preferences);
+}
+```
+
+### `onConsentChanged`
+
+Called only after an explicit `saveConsents()` or `setConsent()` that actually changes the saved consent state. It never fires on store creation, hydration, automatic grants, unchanged saves, or `setCallback('onConsentChanged', ...)`.
+
+```tsx
+onConsentChanged: ({
+  preferences,
+  previousPreferences,
+  allowedCategories,
+  deniedCategories,
+  previousAllowedCategories,
+  previousDeniedCategories,
+}) => {
+  analytics.syncConsent({
+    allowedCategories,
+    deniedCategories,
+    previousAllowedCategories,
+    previousDeniedCategories,
+  });
 }
 ```
 
@@ -91,7 +130,28 @@ onBeforeConsentRevocationReload: ({ preferences }) => {
 }
 ```
 
-## Dynamic Registration
+## Change-Only Subscriptions
+
+Use `subscribeToConsentChanges()` when you want a stable listener for real preference changes after mount:
+
+```tsx
+import { useEffect } from 'react';
+import { useConsentManager } from '@c15t/react';
+
+function ConsentAnalytics() {
+  const { subscribeToConsentChanges } = useConsentManager();
+
+  useEffect(() => {
+    return subscribeToConsentChanges(({ allowedCategories, deniedCategories }) => {
+      analytics.syncConsent({ allowedCategories, deniedCategories });
+    });
+  }, [subscribeToConsentChanges]);
+
+  return null;
+}
+```
+
+## Runtime Callback Registration
 
 Register or update callbacks at runtime using `setCallback()`:
 
@@ -103,11 +163,16 @@ function ConsentAnalytics() {
   const { setCallback } = useConsentManager();
 
   useEffect(() => {
+    setCallback('onBannerFetched', ({ jurisdiction, location }) => {
+      console.log('Resolved init data:', { jurisdiction, location });
+    });
+
     setCallback('onConsentSet', ({ preferences }) => {
-      analytics.track('consent_changed', preferences);
+      console.log('Broad consent lifecycle event:', preferences);
     });
 
     return () => {
+      setCallback('onBannerFetched', undefined);
       setCallback('onConsentSet', undefined);
     };
   }, [setCallback]);
@@ -115,3 +180,5 @@ function ConsentAnalytics() {
   return null;
 }
 ```
+
+`setCallback('onConsentSet', ...)` immediately replays the current consent state. For change-only logic, prefer `subscribeToConsentChanges()` or `onConsentChanged`.

package/docs/components/consent-banner.md

@@ -166,7 +166,7 @@ Direct text props such as `title`, `description`, and `acceptButtonText` are sti
 
 ## Advanced: Compound Components
 
-Use compound components only when the stock banner structure is no longer enough and you need to rearrange existing c15t primitives:
+Use compound components only when the stock banner structure is no longer enough and you need to rearrange existing c15t primitives while keeping policy-driven action grouping and emphasis:
 
 ```tsx
 <ConsentBanner.Root>
@@ -176,13 +176,7 @@ Use compound components only when the stock banner structure is no longer enough
       <ConsentBanner.Title />
       <ConsentBanner.Description />
     </ConsentBanner.Header>
-    <ConsentBanner.Footer>
-      <ConsentBanner.FooterSubGroup>
-        <ConsentBanner.RejectButton />
-        <ConsentBanner.AcceptButton />
-      </ConsentBanner.FooterSubGroup>
-      <ConsentBanner.CustomizeButton />
-    </ConsentBanner.Footer>
+    <ConsentBanner.PolicyActions />
   </ConsentBanner.Card>
 </ConsentBanner.Root>
 ```
@@ -190,8 +184,9 @@ Use compound components only when the stock banner structure is no longer enough
 * `ConsentBanner.Root` — Outermost container, provides theme context
 * `ConsentBanner.Card` — Main content card with optional focus trapping
 * `ConsentBanner.Header` — Contains title and description
-* `ConsentBanner.Title` — Heading, defaults to translation `cookieBanner.title`
+* `ConsentBanner.Title` — Heading, defaults to translation `consentBanner.title`
 * `ConsentBanner.Description` — Description text, supports `legalLinks` prop
+* `ConsentBanner.PolicyActions` — Renders policy-aware grouped actions inside the banner footer
 * `ConsentBanner.Footer` — Action buttons container
 * `ConsentBanner.FooterSubGroup` — Groups related buttons together
 * `ConsentBanner.RejectButton` — Rejects all consent
@@ -199,6 +194,84 @@ Use compound components only when the stock banner structure is no longer enough
 * `ConsentBanner.AcceptButton` — Accepts all consent
 * `ConsentBanner.Overlay` — Optional backdrop overlay
 
+For a fixed layout that intentionally ignores policy grouping, render the footer manually:
+
+```tsx
+<ConsentBanner.Root>
+  <ConsentBanner.Card>
+    <ConsentBanner.Header>
+      <ConsentBanner.Title />
+      <ConsentBanner.Description />
+    </ConsentBanner.Header>
+    <ConsentBanner.Footer>
+      <ConsentBanner.FooterSubGroup>
+        <ConsentBanner.RejectButton />
+        <ConsentBanner.AcceptButton />
+      </ConsentBanner.FooterSubGroup>
+      <ConsentBanner.CustomizeButton />
+    </ConsentBanner.Footer>
+  </ConsentBanner.Card>
+</ConsentBanner.Root>
+```
+
+## Using `renderAction` with c15t Defaults
+
+`ConsentBanner.PolicyActions` renders stock c15t buttons and translations by default.
+
+```tsx
+<ConsentBanner.PolicyActions />
+```
+
+`renderAction` is optional. When you want custom mapping but still want the built-in c15t button behavior and copy, return the stock button compounds:
+
+```tsx
+<ConsentBanner.PolicyActions
+renderAction={(action, props) => {
+  const { key, ...buttonProps } = props
+
+  switch (action) {
+    case 'accept':
+        return <ConsentBanner.AcceptButton key={key} {...buttonProps} />
+    case 'reject':
+        return <ConsentBanner.RejectButton key={key} {...buttonProps} />
+    case 'customize':
+        return <ConsentBanner.CustomizeButton key={key} {...buttonProps} />
+  }
+}}
+/>
+```
+
+Use `useTranslations()` only when you are replacing the button markup entirely:
+
+```tsx
+import { ConsentBanner, useTranslations } from '@c15t/react';
+
+export function CustomBannerActions() {
+  const { common } = useTranslations();
+
+  return (
+    <ConsentBanner.PolicyActions
+      renderAction={(action, props) => (
+        <button
+          key={props.key}
+          type="button"
+          className={props.isPrimary ? 'btn-primary' : 'btn-secondary'}
+          style={props.style}
+        >
+          {action === 'accept'
+            ? common.acceptAll
+            : action === 'reject'
+              ? common.rejectAll
+              : common.customize}
+        </button>
+      )}
+    />
+  );
+}
+```
+
+For maximum control, use `useHeadlessConsentUI()` and render `banner.actionGroups` manually.
+
 If you only need styling changes, stay with tokens and slots instead of rebuilding the banner layout.
 
 ## Props
@@ -217,6 +290,7 @@ If you only need styling changes, stay with tokens and slots instead of rebuildi
 |trapFocus|boolean \|undefined|When true, the consent banner will trap focus|true|Optional|
 |disableAnimation|boolean \|undefined|When true, disables the entrance/exit animations|false|Optional|
 |legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display. Options: \`undefined\` (default): Shows all available legal links; \`null\`: Explicitly hides all legal links; Array of keys: Shows only the specified legal links|-|Optional|
+|hideBranding|boolean \|undefined|When true, hides the branding tag on the banner.|false|Optional|
 |layout|ConsentBannerLayout \|undefined|Defines the layout of buttons in the footer. Allows reordering and grouping of buttons.|-|Optional|
 |direction|PolicyUiActionDirection \|undefined|Defines how footer button groups flow.|-|Optional|
 |primaryButton|ConsentBannerButton \|undefined|Specifies which button(s) should be highlighted as the primary action.|-|Optional|

package/docs/components/consent-dialog.md

@@ -110,7 +110,7 @@ Dialog copy should be changed through `ConsentManagerProvider.options.i18n`, not
 
 ## Advanced: Compound Components
 
-Use compound components only when you need custom dialog markup while still keeping c15t primitives:
+Use compound components only when you need custom dialog markup while still keeping c15t primitives and policy-aware footer actions:
 
 ```tsx
 <ConsentDialog.Root>
@@ -121,7 +121,12 @@ Use compound components only when you need custom dialog markup while still keep
       <ConsentDialog.HeaderDescription />
     </ConsentDialog.Header>
     <ConsentDialog.Content>
-      <ConsentWidget />
+      <ConsentWidget.Root>
+        <ConsentWidget.Accordion type="single">
+          <ConsentWidget.AccordionItems />
+        </ConsentWidget.Accordion>
+        <ConsentWidget.PolicyActions />
+      </ConsentWidget.Root>
     </ConsentDialog.Content>
     <ConsentDialog.Footer />
   </ConsentDialog.Card>
@@ -136,6 +141,7 @@ Use compound components only when you need custom dialog markup while still keep
 * `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:
 
@@ -145,6 +151,10 @@ For a quick pre-composed layout, use the shorthand card:
 </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

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

@@ -54,6 +54,7 @@ Event callbacks for consent actions.
 |:--|:--|:--|:--|:--:|
 |onBannerFetched|Callback\<OnBannerFetchedPayload> \|undefined|Called when the consent banner is fetched.|-|Optional|
 |onConsentSet|Callback\<OnConsentSetPayload> \|undefined|Called when the consent is set.|-|Optional|
+|onConsentChanged|Callback\<OnConsentChangedPayload> \|undefined|Called only when an explicit consent save changes the previously saved consent state.|-|Optional|
 |onError|Callback\<OnErrorPayload> \|undefined|Called when an error occurs.|-|Optional|
 |onBeforeConsentRevocationReload|Callback\<OnConsentSetPayload> \|undefined|Called before the page reloads when consent is revoked.|-|Optional|
 
@@ -325,7 +326,7 @@ In hosted mode (recommended), the backend resolves the correct policy automatica
 
 ### Fallback: Offline Policies
 
-When no backend is available, `ConsentManagerProvider` accepts `offlinePolicy.policyPacks` for local policy resolution:
+When no backend is available, `ConsentManagerProvider` accepts `offlinePolicy.policyPacks` for local policy resolution during development, testing, previews, or temporary backend outages:
 
 ```tsx
 <ConsentManagerProvider
@@ -376,6 +377,7 @@ When no backend is available, `ConsentManagerProvider` accepts `offlinePolicy.po
 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.

package/docs/components/consent-widget.md

@@ -64,20 +64,14 @@ Widget copy should be changed through `ConsentManagerProvider.options.i18n` so t
 
 ## Advanced: Compound Components
 
-Use compound components only when you need to rearrange the widget's existing primitives:
+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.Footer>
-    <ConsentWidget.FooterSubGroup>
-      <ConsentWidget.RejectButton />
-      <ConsentWidget.AcceptAllButton />
-    </ConsentWidget.FooterSubGroup>
-    <ConsentWidget.SaveButton />
-  </ConsentWidget.Footer>
+  <ConsentWidget.PolicyActions />
 </ConsentWidget.Root>
 ```
 
@@ -89,12 +83,71 @@ Use compound components only when you need to rearrange the widget's existing pr
 * `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} />
+  }
+}}
+/>
+```
+
+Use `useTranslations()` only when you are replacing the button markup entirely:
+
+```tsx
+import { ConsentWidget, useTranslations } from '@c15t/react';
+
+export function CustomWidgetActions() {
+  const { common } = useTranslations();
+
+  return (
+    <ConsentWidget.PolicyActions
+      renderAction={(action, props) => (
+        <button
+          key={props.key}
+          type="button"
+          className={props.isPrimary ? 'btn-primary' : 'btn-secondary'}
+          style={props.style}
+        >
+          {action === 'accept'
+            ? common.acceptAll
+            : action === 'reject'
+              ? common.rejectAll
+              : common.save}
+        </button>
+      )}
+    />
+  );
+}
+```
+
+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

package/docs/concepts/client-modes.md

@@ -4,12 +4,12 @@ description: Choose how c15t connects to its backend - full hosted integration,
 ---
 c15t supports three client modes that determine how consent data is stored and synchronized. Choose the mode that matches your infrastructure:
 
-* **Hosted mode** - Full backend integration with geolocation, API sync, and analytics
-* **Offline mode** - Local-only storage with no network requests
+* **Hosted mode** - Recommended for production. Backend-backed consent with geolocation, centralized policy resolution, audit history, and offline fallback.
+* **Offline mode** - Browser-only storage with no network requests. Best for local development, demos, static deployments, or controlled fallback scenarios.
 * **Custom mode** - Bring your own backend with custom endpoint handlers
 
 > ℹ️ **Info:**
-> Offline mode is browser-only storage. If browser storage is blocked or cleared, consent cannot be remembered and prior choices cannot be verified.
+> If you need durable consent records, server-side enforcement, or automatic jurisdiction detection, use hosted mode. Offline mode cannot provide those guarantees because consent lives only in the browser.
 
 <span id="c15t-mode" />
 
@@ -30,6 +30,13 @@ The default mode. Connects to a c15t backend for full consent lifecycle manageme
 
 * `backendURL` (required) - API endpoint path
 
+**Why it is the default for production:**
+
+* The backend stays the source of truth for policy, translations, and jurisdiction logic
+* Consent decisions can be stored beyond the current browser session for audit and support workflows
+* Server-side systems can preload consent-aware behavior instead of waiting for client-only storage
+* If the backend is temporarily unavailable, c15t can fall back locally and re-sync later
+
 **Best for:** Production apps that need geolocation-based jurisdiction detection, consent record storage, and compliance audit trails.
 
 ```tsx
@@ -78,10 +85,12 @@ If consent is not stored at all (for example, storage is blocked or frequently c
 
 * No automatic geolocation or jurisdiction detection
 * No consent audit trail
+* No centralized policy or translation updates without shipping frontend changes
 * No cross-device sync
+* No server-side visibility before client initialization
 * Works without any backend infrastructure
 
-**Best for:** Static sites, development/testing, or as a starting point before setting up a backend.
+**Best for:** Local development, Storybook/static demos, resilience fallback, or simpler sites that explicitly accept browser-only consent storage.
 
 ```tsx
 import { type ReactNode } from 'react';
@@ -156,7 +165,10 @@ export function ConsentManager({ children }: { children: ReactNode }) {
 |Feature|Hosted|Offline|Custom|
 |--|--|--|--|
 |Geolocation|Automatic|Manual via overrides|Your implementation|
+|Policy source of truth|Backend-managed|Bundled into the frontend|Your implementation|
 |Consent sync|API|Local only|Your implementation|
+|Audit trail|Backend records|Not available|Your implementation|
+|Server-side consent awareness|Supported|Not available|Your implementation|
 |SSR data|Supported|Not available|Your implementation|
 |Analytics|Built-in|Not available|Your implementation|
 |Infrastructure|c15t backend|None|Your backend|

package/docs/concepts/initialization-flow.md

@@ -88,7 +88,7 @@ If the resolved model is `none` or `opt-out` (and `ui.mode` is `none`), consents
 
 ## Debugging the Lifecycle
 
-Use the DevTools panel and callbacks to inspect each step of the initialization flow:
+Use the DevTools panel and callbacks to inspect each step of the initialization flow. `onConsentSet` is the broad lifecycle signal; `onConsentChanged` and `subscribeToConsentChanges()` are the change-only signals for explicit post-init saves.
 
 |Step|DevTools Panel|Callback|What to check|
 |--|--|--|--|
@@ -98,6 +98,7 @@ Use the DevTools panel and callbacks to inspect each step of the initialization
 |Banner visibility|Consents|—|`activeUI` in store state; does policy `ui.mode` require it?|
 |Re-prompting|Policy|—|Fingerprint mismatch between stored and resolved policy?|
 |Consent save|Consents + Events|`onConsentSet`|`preferences` object in callback payload|
+|Change-only integrations|Events|`onConsentChanged` or `subscribeToConsentChanges()`|`allowedCategories`, `deniedCategories`, and previous values only when a real save changed preferences|
 |Script loading|Scripts|`onConsentSet`|Script IDs and their load/blocked status|
 |Reload on revocation|Events|`onBeforeConsentRevocationReload`|Fires before reload; check localStorage for `c15t:pending-consent-sync`|
 |Deferred sync|Events|`onError` (if sync fails)|After reload, check Events panel for successful API call|
@@ -120,7 +121,13 @@ export default function ConsentManager({ children }: { children: ReactNode }) {
             console.log('Init complete:', { jurisdiction, location });
           },
           onConsentSet: ({ preferences }) => {
-            console.log('Consent saved:', preferences);
+            console.log('Broad consent lifecycle event:', preferences);
+          },
+          onConsentChanged: ({ allowedCategories, deniedCategories }) => {
+            console.log('Explicit consent change:', {
+              allowedCategories,
+              deniedCategories,
+            });
           },
           onBeforeConsentRevocationReload: ({ preferences }) => {
             console.log('Reloading due to revocation:', preferences);

package/docs/concepts/policy-packs.md

@@ -10,9 +10,9 @@ There are three ways to configure policy packs:
 
 1. **consent.io (recommended)** — use [consent.io](https://consent.io) as your hosted backend. Configure packs visually in the dashboard or via API — no code changes required. Works with any frontend, including static sites.
 2. **Self-hosted backend** — define packs in code via `policyPacks` and resolve them from real request geo data. Full control over policy logic and storage.
-3. **Offline fallback** — pass the same policy shapes to the frontend via `offlinePolicy.policyPacks`. Used as a resilience fallback when the backend is unreachable, or for quick local experimentation and demos. If you omit `offlinePolicy.policyPacks`, c15t falls back to a synthetic worldwide opt-in banner instead of no-banner mode.
+3. **Offline fallback** — pass the same policy shapes to the frontend via `offlinePolicy.policyPacks`. Use this mainly for local development, demos, deterministic testing, or resilience when the backend is temporarily unreachable. If you omit `offlinePolicy.policyPacks`, c15t falls back to a synthetic worldwide opt-in banner instead of no-banner mode.
 
-In both hosted and self-hosted modes, the **backend is always the source of truth**. Offline packs never override a live backend decision.
+In both hosted and self-hosted modes, the **backend is always the source of truth**. Offline packs are a preview or fallback layer and never override a live backend decision.
 
 ## Quickstart