@c15t/svelte 3.0.0-alpha.0

package/docs/frameworks/svelte/quickstart.md

@@ -0,0 +1,133 @@
+---
+title: Quickstart
+description: Mount c15t components and a persistent preferences link in a Svelte
+  5 application.
+group: frameworks
+---
+
+[Create an Inth project](https://inth.com) and use its backend endpoint in
+this guide. Configure the project's policy rules and allowed app origins first.
+
+## Install
+
+| Package manager | Command                                  |
+| :-------------- | :--------------------------------------- |
+| npm             | `npm install @c15t/svelte @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/svelte @c15t/scripts`    |
+| yarn            | `yarn add @c15t/svelte @c15t/scripts`    |
+| bun             | `bun add @c15t/svelte @c15t/scripts`     |
+
+## Register consent-gated scripts
+
+Include measurement and marketing categories in your policy for these vendors.
+Remove any existing loaders for them so each script loads once.
+
+This setup uses Vite's public environment variables. Set the Inth endpoint and
+add your PostHog project key, PostHog API host and X Pixel ID in `.env.local`:
+
+```dotenv title=".env.local"
+VITE_C15T_BACKEND_URL=
+VITE_POSTHOG_KEY=
+VITE_POSTHOG_HOST=
+VITE_X_PIXEL_ID=
+```
+
+Copy the exact backend endpoint from Inth. The vendor IDs are optional: leaving
+an ID empty disables that integration. When enabling PostHog, fill in both its project key and the API host
+shown in your PostHog project. Restart Vite after editing these values and
+rebuild for deployment. Other bundlers need their own configuration mechanism.
+
+Create `src/scripts.ts`. PostHog waits for measurement permission with
+`loadMode: 'after-consent'` and disables cookieless capture with
+`cookieless_mode: 'never'`. X Pixel waits for marketing permission.
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/scripts/posthog';
+import { xPixel } from '@c15t/scripts/x-pixel';
+
+const posthogKey = import.meta.env.VITE_POSTHOG_KEY;
+const xPixelId = import.meta.env.VITE_X_PIXEL_ID;
+
+export const scripts = [
+	...(posthogKey
+		? [
+				posthog({
+					apiHost: import.meta.env.VITE_POSTHOG_HOST,
+					id: posthogKey,
+					initOptions: { cookieless_mode: 'never' },
+					loadMode: 'after-consent',
+				}),
+			]
+		: []),
+	...(xPixelId ? [xPixel({ pixelId: xPixelId })] : []),
+];
+```
+
+## Mount the provider and UI
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import {
+    ConsentBanner,
+    ConsentDialog,
+    ConsentDialogLink,
+    ConsentManagerProvider,
+    hosted,
+  } from '@c15t/svelte';
+  import '@c15t/svelte/styles.css';
+  import { scripts } from './scripts';
+
+  const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+  const mode = hosted({ url: backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <main>Your application</main>
+  <ConsentBanner />
+  <ConsentDialog />
+  <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+</ConsentManagerProvider>
+```
+
+This example uses Svelte 5 and Vite. Set `VITE_C15T_BACKEND_URL` to your backend's
+absolute URL. Configure the backend's policy rules and allowed app origin.
+Svelte's provider is `ConsentManagerProvider` and accepts `mode` as a top-level
+prop. Do not copy React's `ConsentProvider` name into a Svelte component.
+
+The provider owns initialization and cleanup. Keep it mounted around the app
+rather than creating a new provider for each page. The stylesheet supplies the
+stock appearance. Use [customization](../../customization/overview.md) before
+rebuilding the UI with headless APIs.
+
+## Use local policies when no backend is needed
+
+Install `@c15t/schema` and replace the hosted mode in the example with this
+configuration:
+
+```ts
+import { offline } from '@c15t/svelte';
+import { policyRulePresets } from '@c15t/schema';
+
+const mode = offline({ policyRules: [policyRulePresets.europeOptIn()] });
+```
+
+Not recommended for production environments.
+
+This resolves policy locally and stores choices in the browser. It does not
+provide a backend audit history. Review the preset's scope and fallback rather
+than treating it as a complete compliance configuration.
+
+## Verify the lifecycle
+
+Under a choice policy, reject optional categories and reload. Reopen preferences
+and save a different choice. Check vendor requests using
+[verification](../../guides/verify-consent.md). A missing banner can also mean the
+resolved rule needs no prompt, so inspect policy resolution before changing CSS.
+
+For request-specific initial HTML, use the SvelteKit server integration.
+
+## Run the complete example
+
+Try the [runnable example](https://c15t.com/docs/examples) with PostHog, X Pixel, a consent-gated
+YouTube video and a persistent preferences control. Use it to test rejection, permission changes and reloads.

package/docs/frameworks/sveltekit/quickstart.md

@@ -0,0 +1,144 @@
+---
+title: Quickstart
+description: Resolve consent in a SvelteKit server load and hydrate the
+  provider, or initialize in the browser on static hosting.
+group: frameworks
+---
+
+[Create an Inth project](https://inth.com) and use its backend endpoint in
+this guide. Configure the project's policy rules and allowed app origins first.
+
+## Install
+
+| Package manager | Command                                  |
+| :-------------- | :--------------------------------------- |
+| npm             | `npm install @c15t/svelte @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/svelte @c15t/scripts`    |
+| yarn            | `yarn add @c15t/svelte @c15t/scripts`    |
+| bun             | `bun add @c15t/svelte @c15t/scripts`     |
+
+Set `PUBLIC_C15T_BACKEND_URL` to an absolute consent backend URL. Configure
+policy rules and the app origin on the backend. The URL is public because the
+browser also uses it to save choices.
+
+## Register consent-gated scripts
+
+Include measurement and marketing categories in your policy for these vendors.
+Remove any existing loaders for them so each script loads once.
+
+Add your PostHog project key and X Pixel ID to `.env`:
+
+```dotenv title=".env"
+PUBLIC_POSTHOG_KEY=
+PUBLIC_X_PIXEL_ID=
+```
+
+The layout reads these public values through SvelteKit's `$env/dynamic/public`.
+An empty ID disables that integration. Create `src/lib/example-scripts.ts`
+using the helper below. It selects PostHog's EU region; change `region` to `'us'`
+for a US project. PostHog waits for measurement permission and disables
+cookieless capture. X Pixel waits for marketing permission.
+
+```ts title="src/lib/example-scripts.ts"
+import { posthog } from '@c15t/scripts/posthog';
+import { xPixel } from '@c15t/scripts/x-pixel';
+
+export const createExampleScripts = (
+	posthogKey?: string,
+	xPixelId?: string
+) => [
+	...(posthogKey
+		? [
+				posthog({
+					id: posthogKey,
+					initOptions: { cookieless_mode: 'never' },
+					loadMode: 'after-consent',
+					region: 'eu',
+				}),
+			]
+		: []),
+	...(xPixelId ? [xPixel({ pixelId: xPixelId })] : []),
+];
+```
+
+## Resolve consent on each request
+
+```ts title="src/routes/+layout.server.ts"
+import { env } from '$env/dynamic/public';
+import { loadConsent } from '@c15t/svelte/kit';
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async (event) => {
+  const backendURL = env.PUBLIC_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set PUBLIC_C15T_BACKEND_URL');
+  return { prefetch: await loadConsent(event, { backendURL }), backendURL };
+};
+```
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { env } from '$env/dynamic/public';
+  import { createExampleScripts } from '$lib/example-scripts';
+  import {
+    ConsentBanner,
+    ConsentDialog,
+    ConsentDialogLink,
+    ConsentManagerProvider,
+    hosted,
+  } from '@c15t/svelte';
+  import '@c15t/svelte/styles.css';
+
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+  const scripts = createExampleScripts(env.PUBLIC_POSTHOG_KEY, env.PUBLIC_X_PIXEL_ID);
+</script>
+
+<ConsentManagerProvider {mode} prefetch={data.prefetch} {scripts}>
+  {@render children()}
+  <ConsentBanner />
+  <ConsentDialog />
+  <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+</ConsentManagerProvider>
+```
+
+`loadConsent` reads the request and returns serializable prefetch data. Pass
+that data through intact; reconstructing permissions as saved booleans loses
+receipt and policy information. The provider's `mode` and `prefetch` are
+top-level props.
+
+For manifest-backed resolution, the package also exports
+`createSvelteKitConsentRouteHandlers` from `@c15t/svelte/kit`. Once those routes
+are mounted, `loadConsent(event, { initRoute: '/api/c15t' })` uses the app's own
+init route through `event.fetch`. Merely changing the URL does not create it.
+
+Past the manifest's `s-maxage` those routes serve it stale and refresh it in
+the background. On adapters that expose `event.platform.context.waitUntil`
+(Cloudflare, Vercel edge) the handlers hand the refresh to it so it is not cut
+short when the response is sent; nothing is needed from you. For another
+lifetime API, pass `onBackgroundRevalidate(refresh, event)` to the handlers.
+
+## Use static hosting
+
+A prerendered page cannot resolve a visitor's cookies at build time. For static
+output, omit the request-specific server load and `prefetch`. Configure
+`hosted({ url })` in the layout with an absolute external backend URL, using a
+public build-time value from `$env/static/public`. Read vendor IDs from
+`$env/static/public` too for prerendering. Keep the provider and UI from
+the example. Do not point at a same-origin server route that the static host
+cannot run.
+
+The browser initializes consent after mount. Optional permissions remain denied
+while no policy has resolved. Follow your SvelteKit adapter's static deployment
+configuration independently of consent setup.
+
+## Verify hydration and navigation
+
+For SSR, a valid stored choice should survive the first client render without a
+new choice event. For static output, serve the actual generated site. On both,
+reject, navigate between routes, reload and reopen preferences. Check requests
+and failed initialization with [verification](../../guides/verify-consent.md).
+
+## Run the complete example
+
+Try the [runnable example](https://c15t.com/docs/examples) with PostHog, X Pixel, a consent-gated
+YouTube video and a persistent preferences control. Use it to test rejection, permission changes and reloads.

package/docs/guides/consent-state.md

@@ -0,0 +1,60 @@
+---
+title: Understand consent state
+description: Distinguish policy resolution, effective permissions, explicit
+  choices, notices and privacy signals.
+group: guides
+---
+
+## Use effective permissions to gate features
+
+`effectivePermissions` answers whether a category is allowed now. It combines
+the resolved policy, stored choices and privacy signals. Under an opt-out rule,
+permission can be true before the visitor acts. It is not evidence of a recorded
+grant.
+
+| Task                                        | State or API                                         |
+| ------------------------------------------- | ---------------------------------------------------- |
+| Load a script or render an optional feature | `effectivePermissions`, React `useConsent(category)` |
+| Inspect what the visitor confirmed          | `explicitChoice`                                     |
+| Decide whether to show a prompt             | `promptRequirement`                                  |
+| Explain regional behavior                   | `policyRule`                                         |
+| Diagnose initialization                     | `resolution`                                         |
+
+## Record only explicit visitor actions
+
+```ts
+// Run in the corresponding click or form-submit handler.
+await kernel.commands.save('all');
+await kernel.commands.save('none');
+await kernel.commands.save({ marketing: false });
+```
+
+These are three separate examples: accept, reject and a partial save. A partial
+save confirms only the supplied categories and keeps the other categories'
+confirmation times. Do not call all three in one handler.
+
+`onChoiceRecorded` reports an explicit choice. `onPermissionsChanged` reports
+changes in effective permissions, including changes caused by expiry or privacy
+signals. Hydration must not be counted as another visitor choice.
+
+## Treat notices and privacy signals separately
+
+`commands.dismissNotice()` acknowledges the current notice. It does not grant
+categories or overwrite existing denials. Global Privacy Control, or GPC, is a
+browser privacy signal. Its configured restrictions can change permissions
+without creating an explicit choice.
+
+A rule with `prompt: 'none'` can still require a persistent preferences entry
+point. Check the policy's rights instead of hiding preferences merely because
+the banner is absent. An unresolved rule is another distinct state; optional
+permissions stay denied until resolution succeeds.
+
+## Preserve records during hydration
+
+Server helpers return records with policy information and evaluation time.
+Forward that configuration intact. Copying an allowed category into a receipt
+would invent a grant and lose its original confirmation time.
+
+Valid v2 records can be read without a startup rewrite. The next explicit action
+writes the v3 format. See [migration](../upgrade-v3.md) for expiry, partial saves,
+custom transports and backend contract changes.

package/docs/guides/data-fetching.md

@@ -0,0 +1,163 @@
+---
+title: Data fetching and transports
+description: Choose cached manifests, backend init or offline policy resolution,
+  and understand where consent records are saved.
+group: guides
+---
+
+## Start with Inth and a cached manifest
+
+Use Inth for managed policy and consent records. For a Next.js application with
+a server, use a cached manifest to resolve policy in your application. Route
+browser consent traffic directly to Inth, or optionally use a Next.js rewrite
+to keep those requests on your app's origin. Follow the
+[Next.js manifest setup](https://c15t.com/docs/frameworks/next/data-fetching).
+
+Backend ownership and data fetching are separate decisions. Inth manages the
+backend for you. A [self-hosted backend](https://c15t.com/docs/self-host/quickstart) uses the same
+protocol while you operate its database, policies and availability. A static
+site can still call Inth. Only `offline()` deliberately removes consent backend
+requests and stores choices locally.
+
+| Fetching path                  | Where policy resolves                                                                 | Where choices are submitted | Choose it when                                                                                         |
+| ------------------------------ | ------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Cached manifest on your server | Your application resolves public policy data with each request's location and signals | Inth or your c15t backend   | Your host has a runtime server and you want to reuse policy data across requests                       |
+| Regular backend `/init`        | The consent backend                                                                   | The same backend            | You want the fewest moving parts, need backend-owned request resolution, or have no application server |
+| Manifest in the browser        | The browser, using supplied or unknown location                                       | Inth or your c15t backend   | You deliberately want client resolution and have planned geography, bundle size and policy refresh     |
+| Offline                        | The browser or local runtime, using bundled rules                                     | No backend submission       | Local development and tests. Not recommended for production environments.                              |
+| Custom transport               | Your implementation                                                                   | Your implementation         | An existing service cannot use the c15t backend protocol                                               |
+
+## What is a consent manifest?
+
+A manifest is a versioned policy document served by `GET /manifest`. It contains
+policy rules, translation configuration and related consent configuration. It
+is public configuration, not a visitor's saved choices. A resolver combines the
+manifest with country, region, language and privacy signals to produce an init
+result for one visitor.
+
+Reusing the public document avoids asking the consent backend to resolve policy
+for every application request. Cache misses and revalidation still fetch the
+manifest, and consent writes still need the backend. Measure the deployed
+request path before promising a latency improvement.
+
+Do not put secrets, visitor identifiers or consent records into a manifest.
+Keep personalized init responses out of shared caches. Changing a policy also
+requires a refresh strategy for cached or build-time manifests.
+
+## What does regular `/init` do?
+
+`hosted({ url })` uses `${url}/init` for initialization and `${url}/subjects` for
+consent submissions. The name `hosted` describes the transport protocol; the URL
+can belong to Inth or your own c15t backend.
+
+```ts title="src/consent-mode.ts"
+import { hosted } from 'c15t';
+
+export function createConsentMode(backendURL: string) {
+  return hosted({ url: backendURL });
+}
+```
+
+Pass the factory to your adapter's `mode` option. For request rendering, use the
+adapter's server helper and forward its prepared result to the browser. For
+static output, initialize in the browser with a reachable external URL.
+
+A regular backend `/init` request lets the backend resolve the visitor context.
+A same-origin URL named `/api/c15t/init` can instead resolve from a cached
+manifest in your application. The URL name alone does not tell you which path
+runs.
+
+## How do transports and proxies differ?
+
+A transport implements initialization, saving and optional record operations.
+A proxy changes where HTTP requests travel. It does not change the policy
+resolver or make personalized responses safe to cache.
+
+For a same-origin init route that resolves a manifest, the hosted transport can
+separate policy reads and record writes. With a backend rewrite mounted at
+`/api/c15t`, a client mode can use:
+
+```ts title="src/consent-mode.ts"
+import { hosted } from 'c15t';
+
+export const mode = hosted({
+  url: '/api/c15t',
+  initURL: '/api/c15t/init',
+  assertDecisionInputs: true,
+});
+```
+
+The route must return the c15t init response contract. `assertDecisionInputs`
+binds saves to the resolved policy when init did not return a signed policy
+snapshot token. The backend can then reject a stale policy decision. Next.js
+sets this option for you when `ConsentRoot` receives a `config` with
+`initURL`.
+
+The init route resolves policy; the backend rewrite forwards `/api/c15t/subjects`
+and other record endpoints. Configure both if you choose this optional proxy
+variant. The
+[Next.js rewrite recipe](https://c15t.com/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
+shows the configuration. A direct absolute backend URL works
+without a rewrite.
+
+This optional optimization keeps c15t requests on the app's origin and avoids a separate browser DNS lookup
+and TLS connection to the consent backend. The app server still connects to
+the upstream backend for manifest refreshes and consent writes. Vendor scripts
+and vendor requests keep their own origins.
+
+Set the absolute upstream endpoint through `C15T_BACKEND_URL` in Next.js server
+configuration. The endpoint URL is public connection information, not a secret.
+The browser uses `/api/c15t` without needing the upstream URL. A static export
+cannot serve a Next.js route or rewrite at runtime; use the absolute Inth URL or
+a proxy provided by the static host instead.
+
+## When should I use offline mode?
+
+Not recommended for production environments. Use Inth or a self-hosted backend
+for production policy and consent records.
+
+`offline()` resolves bundled policy rules without an init request and acknowledges
+saves locally. The runtime's persistence module stores the choice in browser
+storage. There is no backend audit history, cross-device record service or IP
+geolocation supplied by this transport.
+
+Use your adapter's offline factory so its translations and provider context are
+included. This React and Next.js example replaces the hosted mode in an existing
+client provider:
+
+```ts title="src/consent-mode.ts"
+import { offline } from 'c15t/react';
+
+export const mode = offline();
+```
+
+With no `policyRules`, the current offline transport uses the recommended rule
+pack. Supplying `policyRules` replaces that pack. Unknown country and region are
+real resolution inputs; offline mode does not discover a visitor's location.
+Use [policy rules](https://c15t.com/docs/frameworks/next/concepts/policy-presets) to understand
+matching and defaults, and test the missing-location case.
+
+Offline mode is an explicit architecture choice, not an automatic fallback for
+a failed Inth request. If hosted initialization fails before a policy resolves,
+optional permissions remain denied and the stock prompt stays hidden. Observe
+initialization failures instead of silently changing policy sources.
+
+## Can I provide my own transport?
+
+`custom(transport)` accepts a `KernelTransport` with the v3 `init` and `save`
+contract. It does not accept v2 endpoint handlers such as `setConsent`. Keep
+policy resolution, record acknowledgments and failure behavior consistent with
+the kernel contract. Prefer a built-in transport when your backend supports it.
+
+## Verify the selected path
+
+Inspect browser and server requests separately. A server manifest fetch will
+not appear in the browser's Network panel. On a warm manifest path, check that
+page requests do not call the backend `/init`, a visitor's choice still reaches
+the backend's `/subjects`, and policy changes become visible after the configured
+refresh. In the recommended Next.js setup, the browser should call only
+`/api/c15t` paths for consent HTTP traffic; inspect server logs to verify their
+upstream destinations.
+
+Test different locations, missing location headers, GPC, returning choices and
+backend failure. See [verification](./verify-consent.md).

package/docs/guides/deployment-modes.md

@@ -0,0 +1,63 @@
+---
+title: Choose a deployment mode
+description: Choose who runs your consent backend, then select manifest, init or
+  offline resolution for your deployment.
+group: guides
+---
+
+## Use Inth for managed policy and records
+
+Start with [Inth](https://inth.com) unless you need to operate the consent
+service yourself or deliberately need only local browser records. Configure
+policy rules and trusted origins in the project, then use its exact backend
+endpoint in your framework setup.
+
+| Backend ownership         | Policy source                                          | Record storage                           | Use when                                                                  |
+| ------------------------- | ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------- |
+| Inth hosted service       | Centrally managed policy through a manifest or `/init` | Browser records plus backend submissions | You want managed policy and consent records                               |
+| Self-hosted c15t          | Your backend's manifest or `/init`                     | Browser records plus your database       | You need to operate the service and its infrastructure                    |
+| Browser-only offline mode | Bundled `policyRules`                                  | Browser persistence                      | Local development and tests. Not recommended for production environments. |
+
+Hosted and self-hosted c15t use the same transport protocol. Switching who runs
+the backend does not require switching from manifests to `/init`.
+
+## Choose data fetching separately
+
+For Next.js deployments with a runtime server, use the
+[manifest setup](https://c15t.com/docs/frameworks/next/data-fetching). It reuses public policy data
+in your application while consent writes still go to Inth. Regular backend
+`/init` is available when you want backend-owned request resolution or a simpler
+browser setup. See [data fetching and transports](./data-fetching.md) for
+the comparison, including custom transports and offline mode.
+
+## Match initialization to your application output
+
+| Application output | Initial state             | Required setup                                              |
+| ------------------ | ------------------------- | ----------------------------------------------------------- |
+| Request SSR        | Prepared for this visitor | Adapter request helper and matching client configuration    |
+| Static HTML or SPA | Resolved in the browser   | Reachable external URLs or deliberately bundled local rules |
+
+Request SSR can include the visitor's prompt in the initial HTML. Pass the
+prepared records and policy resolution through to hydration. Do not convert
+effective permissions into new stored choices.
+
+Static HTML is shared across visitors. It cannot contain a choice resolved from
+each visitor's cookies or geography at build time. A static site can still use
+Inth through browser requests. A same-origin `/api/c15t` URL only works if a
+service actually serves it; a Next.js static export does not run API routes.
+
+A manifest contains reusable public policy data. A resolved init response and
+personalized consent HTML belong to a request. Do not give them the same shared
+cache treatment.
+
+## Handle initialization and storage failures
+
+While no policy resolves, optional permissions stay denied and the stock
+consent UI stays hidden. No banner can mean pending or failed initialization.
+It does not mean permission to load analytics. Observe errors before changing
+presentation, and do not silently switch to offline policy after a hosted
+request fails.
+
+Browser storage can also be unavailable. A working in-memory interaction does
+not prove the choice survives reload. Use
+[verification](./verify-consent.md) to test the actual deployment.

package/docs/guides/troubleshooting.md

@@ -0,0 +1,68 @@
+---
+title: Troubleshoot consent
+description: Diagnose missing banners, early vendor requests, lost choices and
+  hydration differences.
+group: guides
+---
+
+## Why is there no banner?
+
+Inspect `resolution` and `promptRequirement` before changing styles. Pending or
+failed initialization, no matching rule, a valid stored choice and a rule that
+requires no prompt can all produce no banner for different reasons. A missing
+stylesheet can also make rendered controls appear incorrectly.
+
+Check the backend URL and Network response, then confirm the active policy for
+the visitor's location. Do not solve missing UI by granting every category or
+setting `enabled: false`: disabling the runtime permits optional loading.
+
+## Why does the UI disappear with a content blocker?
+
+Check the browser Network panel for `ERR_BLOCKED_BY_CLIENT` or a failed dynamic
+import. Older c15t builds used component filenames such as
+`consent-dialog-*.js`, which some cookie-annoyance lists block. Update the c15t
+packages and rebuild the app. Current component modules use neutral filenames;
+public component imports stay the same. This also covers Vite development
+requests used by TanStack Start and other Vite integrations.
+
+Extensions can separately hide elements with cosmetic filters or block a
+configured backend URL. Check the failed request or hidden element to distinguish
+those cases from a missing component module.
+
+## Why does analytics run before a choice?
+
+Check effective permission under the selected policy, then find every loader
+for that vendor. Remove unconditional script tags, framework analytics plugins
+and duplicate tag-manager entries. c15t's script registration only controls the
+scripts registered with it.
+
+Google helpers intentionally load with Consent Mode defaults. A Google request
+is not by itself proof that its storage consent was granted. If your requirement
+is no request at all, do not use an always-loaded helper unchanged.
+
+## Why does a choice disappear on reload?
+
+Check whether persistence is disabled, browser storage is blocked, the origin
+changed, or the receipt expired or no longer matches the current policy.
+A development example with `persistence: false` deliberately resets on reload.
+Do not "repair" persistence by saving permissions automatically on mount.
+
+## Why does hydration differ from server HTML?
+
+Use the adapter's request helper and pass the returned configuration unchanged
+to its boundary. Check that server and browser use the same backend and policy
+inputs. A module-level mutable runtime on a server can share one visitor's state
+with another request; create request-owned state instead.
+
+## Why does static hosting fail when development works?
+
+A static host has no app server for init routes, proxies or server functions.
+Use absolute external consent URLs or an explicitly local policy. Test the
+production output with a static file server, not the framework dev server.
+
+## Why does customization do nothing?
+
+Check the imported stylesheet, the correct token or slot, and which element
+carries the state attribute. `data-variant` on a banner root is not a matching
+attribute on its child card. Check cascade layers and the Tailwind version
+before adding specificity. See [customization](../customization/overview.md).