@c15t/scripts 2.2.0 → 3.0.0-alpha.0

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).

package/docs/guides/verify-consent.md

@@ -0,0 +1,62 @@
+---
+title: Verify consent before shipping
+description: Test requests, policy resolution, persistence, navigation and
+  preference changes in a production build.
+group: guides
+---
+
+## Establish the policy under test
+
+Use a fresh browser profile and a known policy. For an opt-in choice policy,
+optional requests should be absent before a choice. Opt-out and notice policies
+have different defaults; inspect the resolved rule rather than expecting every
+region to show the same banner. Keep test geography overrides out of production.
+
+Inventory scripts in your HTML, application code, tag manager, plugins and
+embeds. A c15t provider cannot make an independently loaded vendor wait for a
+choice. Remove duplicate loaders before interpreting the result.
+
+## Run the visitor flow
+
+| Action                                     | Check                                                                                    |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| Load without a stored choice               | Correct policy and prompt; category-gated vendors stay blocked when permission is denied |
+| Reject optional categories                 | Prompt closes; denied vendors remain blocked                                             |
+| Reload                                     | Valid rejection persists; no new choice event is emitted by hydration                    |
+| Reopen preferences                         | Settings remain reachable after the banner closes                                        |
+| Save one category                          | Only that category gets a new confirmation time                                          |
+| Navigate without reloading                 | One runtime remains active; no duplicate vendor initialization                           |
+| Revoke a grant                             | Future gated work stops and configured cleanup runs                                      |
+| Load with an expired or incompatible grant | It does not silently restore optional permissions                                        |
+| Block the consent backend                  | Failed resolution is observable; absence of a banner does not grant permission           |
+| Block browser storage                      | Interaction still works where supported; verify whether the choice survives reload       |
+
+Inspect Network before the page starts loading, with cache disabled for the test.
+Filter by the vendor's script and collection domains. Hiding an iframe after it
+loads is too late to prevent the initial request.
+
+Google Consent Mode integrations intentionally load their scripts and send
+consent signals. Test their default and update commands separately from a
+zero-request gate. See [Google Tag Manager](../integrations/google-tag-manager.md)
+and [Google Tag](../integrations/google-tag.md).
+
+## Test the production hosting shape
+
+For static sites, serve the generated files. Confirm no request depends on an
+API route or rewrite that only exists in development. For SSR, inspect the
+initial HTML and check that hydration does not change a valid stored choice.
+Test a direct visit as well as client navigation.
+
+For a cross-origin backend, check allowed origins, protocol and reachable URLs.
+A public backend URL is not an API secret. Keep credentials out of client props
+and public environment variables.
+
+## Check the interface
+
+Use a narrow viewport, long translated labels and keyboard-only navigation.
+Check that blocking dialogs trap focus, return it to the trigger when closed,
+and do not leave scrolling locked. Non-blocking notices should allow interaction
+with the page. Test contrast and focus indicators after applying a theme.
+
+Record the policy, framework, deployment and observed request behavior with the
+test result. "The banner appears" is only one assertion.