@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

package/docs/frameworks/next/troubleshooting.md

@@ -1,148 +1,138 @@
 ---
-title: Troubleshooting
-description: Solutions for common issues with @c15t/nextjs — provider errors,
-  missing banners, consent persistence, and more.
+title: Troubleshoot Next.js consent
+description: Diagnose failed Next.js prefetch, verify manifest requests, and fix
+  consent rendering or persistence problems.
 group: frameworks
 ---
-## "Provider not found" Error
 
-**Symptom:** `useConsentManager must be used within a ConsentManagerProvider` error.
-
-**Fix:** Ensure the component calling `useConsentManager()` (or any c15t hook) is rendered inside a `ConsentManagerProvider`:
-
-```tsx
-// Wrong — hook is outside the provider
-function App() {
-  const { consents } = useConsentManager(); // throws
-  return <ConsentManagerProvider options={...}>...</ConsentManagerProvider>;
-}
-
-// Correct — hook is inside the provider
-function App() {
-  return (
-    <ConsentManagerProvider options={...}>
-      <MyComponent /> {/* useConsentManager works here */}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## Banner Doesn't Show
-
-**Possible causes:**
-
-1. **Opt-out jurisdiction** — In CCPA/opt-out regions, the banner is not shown because tracking is allowed by default. Check `model` from `useConsentManager()` — if it's `'opt-out'`, the banner is intentionally hidden.
-
-2. **Consent already given** — If the user has already made a consent choice, the banner won't reappear. Clear cookies or use `resetConsents()` to test again.
-
-3. **`activeUI` is `'none'`** — Something is explicitly setting `activeUI` to `'none'`. Check the DevTools panel for the current consent state.
-
-4. **Backend not responding** — In `'c15t'` mode, the banner waits for the backend `/init` response. Check the Network tab for failed requests to your `backendURL`.
-
-```tsx
-// Debug: check what the consent manager sees
-const { activeUI, model, isLoadingConsentInfo } = useConsentManager();
-console.log({ activeUI, model, isLoadingConsentInfo });
-```
-
-## Consent Not Persisting
-
-**Symptom:** Consent is lost after page reload.
-
-**Possible causes:**
-
-1. **Incognito/private mode** — Some browsers restrict cookie storage in private browsing.
-
-2. **Cookie settings** — In `'offline'` mode, consent is stored in cookies. Ensure cookies are not being blocked by browser settings or extensions.
-
-3. **Different domains** — Cookies are domain-scoped. If your dev server uses a different domain than production, consent won't carry over.
-
-4. **Backend errors** — In `'c15t'` mode, check that the backend is saving consent successfully. Enable `debug: true` in provider options to see detailed logs.
-
-## Scripts Not Loading
-
-**Symptom:** Third-party scripts configured in the `scripts` option don't load after consent is granted.
-
-**Checklist:**
-
-1. **Wrong category name** — The `category` on the script must match one of the `consentCategories` names. For example, `'measurement'` not `'analytics'`.
-
-2. **Consent condition not met** — Use `has('measurement')` to verify the category is actually consented.
-
-3. **Script error** — Check the browser DevTools Console for script loading errors. The `onError` callback can help debug:
-
-```tsx
-{
-  id: 'analytics',
-  src: 'https://...',
-  category: 'measurement',
-  onError: ({ error }) => console.error('Script failed:', error),
-}
-```
-
-4. **Ad blocker** — Browser extensions may block the script regardless of consent. The `anonymizeId` option (default: `true`) helps avoid pattern-based blocking.
-
-## SSR Hydration Mismatch
-
-**Symptom:** React hydration warnings, consent banner flashes briefly, or consent state differs between server and client.
-
-**Fixes:**
-
-1. **Missing `ssrData`** — Ensure you're passing the SSR data Promise to the provider. Do **not** `await` `fetchInitialData()` in Server Components:
-
-```tsx title="app/layout.tsx"
-import { fetchInitialData } from '@c15t/nextjs';
-import ConsentManager from '@/components/consent-manager';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  const ssrData = fetchInitialData({ backendURL: '/api/c15t' });
-
-  return (
-    <html lang="en">
-      <body>
-        <ConsentManager ssrData={ssrData}>
-          {children}
-        </ConsentManager>
-      </body>
-    </html>
-  );
-}
-```
-
-2. **Stale cache** — If using a CDN or caching layer, ensure the SSR data is fresh per-request and not shared across users.
-
-3. **Debug with `useSSRStatus`** — Check if SSR data was actually consumed:
-
-```tsx
-const { ssrDataUsed, ssrSkippedReason } = useSSRStatus();
-```
-
-See [Server-Side Data Fetching](/docs/frameworks/next/server-side) for full SSR setup.
-
-## TypeScript Errors
-
-**Common import issues:**
-
-```tsx
-// Components and hooks — main entry point
-import { ConsentManagerProvider, useConsentManager } from '@c15t/nextjs';
-
-// Server-side data fetching
-import { fetchInitialData } from '@c15t/nextjs';
-
-// Headless (hooks only, no components)
-import { useConsentManager } from '@c15t/nextjs/headless';
-```
-
-If you see type errors after updating, try:
-
-```sh
-rm -rf node_modules/.cache
-bun install
-```
-
-## Still Stuck?
-
-* Enable `debug: true` in provider options for verbose console logging
-* Use the [DevTools](/docs/frameworks/next/components/dev-tools) panel to inspect live consent state
-* Check the [GitHub issues](https://github.com/c15t/c15t/issues) for known bugs
+## Why does the page render when consent prefetch fails?
+
+`resolveConsent` returns its baseline state when a manifest or
+backend request fails. The page can still render, and the client retries
+initialization. Until policy resolution succeeds, optional categories stay
+denied and the stock banner stays hidden.
+
+Pass `onError` to `resolveConsent` to report failures in production.
+Without it, the helper logs a warning only outside production. Check the failed
+URL and response in your server logs, as browser Network tools cannot show a
+server-side fetch.
+
+If the local manifest handler repeatedly calls itself, check its upstream URL.
+`C15T_BACKEND_URL` must be the absolute Inth or self-hosted backend endpoint.
+The browser can use `/api/c15t` with an optional rewrite, but that local prefix
+must not become the handler's upstream backend. See
+[Next.js optimization](./optimization.md) for the rewrite setup.
+
+## How do I verify manifest fetching?
+
+Check the Next.js server and browser requests after following the
+[App Router](./app-router.md) or
+[Pages Router](./pages-router.md) guide:
+
+1. Load the page twice. A warm manifest setup resolves policy without calling
+   the upstream backend `/init`. A browser request to your local
+   `/api/c15t/init` is expected when client initialization is needed.
+2. Make a consent choice. Confirm the submission reaches the backend
+   `/subjects` endpoint and reload to check that the choice persists.
+3. Test two locations with different configured policies. Confirm the resolved
+   policy matches each location and that your host passes trusted geography
+   headers to Next.js.
+4. Change a policy, then check it after the manifest caches refresh. Cache the
+   public manifest, never the visitor-specific init response.
+5. If you added a rewrite, confirm browser consent requests use `/api/c15t`,
+   including submissions. Direct requests to the backend are expected when you
+   have not configured a rewrite.
+
+## Why is the visitor's location unknown on the server?
+
+`resolveConsent` and the local init handler read the visitor's country
+and region from hosting platform headers such as `cf-ipcountry` and
+`x-vercel-ip-country`; c15t never derives location from an IP address itself.
+Some platforms expose those headers to Next.js middleware or proxy but strip
+them before Server Components and Route Handlers run, so every visitor falls
+back to your unknown-location rule. Confirm it by logging
+`(await headers()).get('x-vercel-ip-country')`, or your host's equivalent, in a
+Server Component. If the header is missing there, add `c15tProxy` as described in
+[Forward geography headers](./geography-headers.md); it
+forwards the resolved values as `x-c15t-country` and `x-c15t-region`, which take
+precedence everywhere c15t reads location.
+
+## Why does Next.js report an unstable `Date.now()` during prerendering?
+
+The error
+`Next.js encountered the unstable value Date.now() while prerendering`,
+pointing at the `await resolveConsent(...)` line, comes from
+`partialPrefetching: true` combined with `cacheComponents: true` (Next.js
+16.3 and later). During the runtime-prefetch stage Next.js resolves
+`headers()` and then flags the `Date.now()` that follows. It only appears in
+`next dev`; `next build` passes because build-time prerenders never resolve
+`headers()`.
+
+`resolveConsent` handles this itself: the default App Router request reader
+calls `await connection()` from `next/server` before reading the clock, so the
+component is already request-time when the clock is read. You do not need to
+add `connection()` to your layout. If you still see the error on the current
+release, report your Next.js version and config on
+[c15t/c15t#1107](https://github.com/c15t/c15t/issues/1107).
+
+## 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).

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](../frameworks/next/data-fetching.md).
+
+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](../frameworks/next/optimization.md#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](../frameworks/next/concepts/policy-presets.md) 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](../frameworks/next/data-fetching.md). 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).