@c15t/scripts 3.0.0-alpha.1 → 3.0.0-alpha.3

package/docs/guides/troubleshooting.md

@@ -1,68 +1,141 @@
 ---
-title: Troubleshoot consent
-description: Diagnose missing banners, early vendor requests, lost choices and
-  hydration differences.
+title: Troubleshooting
+description: Fix a missing banner, analytics that load before consent, choices
+  lost on reload, CORS errors, hydration differences and failed static builds in
+  c15t v3.
 group: guides
 ---
 
+## Start with three checks
+
+Most problems show up in one of these places. Run them before changing code.
+
+1. **Which c15t is running.** In the browser console, run `window.c15t`. v3
+   prints `{ version, pkg, mode }`, for example `mode: 'manifest'` from
+   `@c15t/nextjs`. `undefined` means no c15t provider has mounted on this
+   page. A `window.c15tStore` object means the page runs v2. With the script
+   tag, `window.c15t` is the full browser API instead.
+2. **The backend request.** In DevTools Network, filter by your backend URL.
+   Look for `/init` or `/manifest` and check its status. A CORS error means
+   the backend does not trust your site's origin.
+3. **Consent state.** Add the c15t DevTools panel from your framework's guide.
+   It shows the resolved policy, whether a prompt is needed, each category's
+   permission and the scripts c15t manages.
+
+Your framework's troubleshooting page covers adapter-specific failures, such
+as Next.js prerendering errors or SvelteKit hydration.
+
+## "Can't resolve 'c15t/next'" or a missing export
+
+npm's `latest` tag still points to c15t v2, which has no framework entry
+points. A plain `npm install c15t` therefore installs v2, and imports such as
+`c15t/next`, `c15t/react` or `ConsentRoot` fail with "Package subpath is not
+defined by exports" or "Module not found".
+
+Install the v3 release and check the lockfile:
+
+| Package manager | Command                  |
+| :-------------- | :----------------------- |
+| npm             | `npm install c15t@alpha` |
+| pnpm            | `pnpm add c15t@alpha`    |
+| yarn            | `yarn add c15t@alpha`    |
+| bun             | `bun add c15t@alpha`     |
+
+Keep every c15t package, including `@c15t/integrations`, on the same release.
+Mixing v2 and v3 packages is not supported.
+
 ## 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.
+No banner is sometimes correct. Find out which case you have:
+
+| What DevTools shows                                | Cause                                                                                                                       | Fix                                                                                                                                                                                     |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The backend request failed or has a CORS error     | Wrong backend URL, or your origin is not trusted                                                                            | Copy the URL from your Inth project exactly, including any path. Add the site's origin, such as `https://www.example.com` or `http://localhost:3000`, to the project's trusted origins. |
+| Requests go to `your-project.inth.app` and fail    | The placeholder backend URL from the guides is still in your code                                                           | Replace `https://your-project.inth.app` with the URL from your Inth project, including any path prefix.                                                                                 |
+| No backend request at all                          | No provider mounted, or the provider runs in offline mode                                                                   | Check `window.c15t`. Confirm the provider receives `hosted()` with your backend URL, or the `backendURL` option your framework uses.                                                    |
+| The policy resolved and no prompt is needed        | The visitor's location maps to a policy without a prompt, such as a US state without a privacy law in the recommended rules | Expected. Test from a location that needs a prompt. Server helpers such as Next.js `resolveConsent` accept a `country` override for testing; remove it before you deploy.               |
+| The policy resolved and a choice is stored         | A returning visitor                                                                                                         | Expected. Clear site data or use a private window.                                                                                                                                      |
+| The banner is in the DOM but invisible or unstyled | The stylesheet is missing, or loaded before Tailwind CSS 4                                                                  | Import your framework's c15t stylesheet from your global CSS. See [customization](../customization/overview.md).                                                                        |
+
+Do not "fix" a missing banner by granting every category or turning c15t off.
+While the policy is unresolved, every optional category stays denied. Turning
+the runtime off lets optional scripts load.
+
+## Why does analytics load before the visitor chooses?
+
+c15t only controls scripts you register with it. Find every other loader:
+
+* A `<script>` tag in your HTML, layout or `_document`.
+* A framework plugin, such as `@next/third-parties`, `nuxt-gtag` or a Vercel
+  or Netlify analytics toggle.
+* A tag in Google Tag Manager that fires on page view.
+* An embed, such as a YouTube iframe, rendered without `ConsentGate`.
+
+Remove the extra loader and register the vendor through
+[integrations](../integrations/overview.md). Then reload with the Network panel
+open and cache disabled. The vendor's domain should be absent until you allow
+its category.
+
+Also check the policy. Under an opt-out policy, optional categories are allowed
+before a choice, so the request is expected.
 
-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.
+Google Tag and Google Tag Manager are an exception by design. Their helpers
+load before a choice and send Google Consent Mode signals, so a request to
+Google before consent is expected. If you need no request at all before
+consent, read [Google Tag Manager](../integrations/google-tag-manager.md) first.
 
-## Why does the UI disappear with a content blocker?
+## Why does the choice disappear on reload?
 
-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.
+| Check                                                                                         | Fix                                                                                                             |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| After saving, does DevTools Application show a `c15t` cookie and a `c15t` localStorage entry? | If not, look for `persistence: false` in your config. Examples use it on purpose; production apps should not.   |
+| Does the browser block storage, for example in a sandboxed iframe or a strict privacy mode?   | The choice works for the current page only. Nothing to fix in your app.                                         |
+| Did the domain, subdomain or protocol change between visits?                                  | Cookies and localStorage are per origin. Serve the site from one origin, or share the cookie across subdomains. |
+| Did the policy change since the visitor chose?                                                | A changed policy, a new required category or an expired choice prompts again. This is intended.                 |
 
-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.
+Never save a choice automatically on page load to make persistence "stick".
+That records consent the visitor did not give.
 
-## Why does analytics run before a choice?
+## Why does the page reload after saving preferences?
 
-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.
+A visitor turned off a category or vendor they had allowed. Scripts that
+already ran cannot be unloaded, so c15t reloads the page to start clean with
+only permitted code. Set `reloadOnConsentRevoked: false` if you clean up
+revoked vendors yourself; [clear on revocation for your framework](../integrations/overview.md#vendor-switches-and-cookie-cleanup)
+covers the options.
 
-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 the server HTML differ from the browser?
 
-## Why does a choice disappear on reload?
+Pass the value your framework's server helper returns to the provider
+unchanged. Do not merge it with defaults or rebuild it from permissions. Make
+sure the server and browser use the same backend URL, because two backends can
+resolve different policies.
 
-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.
+Never keep consent state in a module-level variable on the server. One
+visitor's state can leak into another request. Create it per request, as the
+framework guides do.
 
-## Why does hydration differ from server HTML?
+## Why does the static build fail when development works?
 
-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.
+A static host serves files only. Route handlers, server functions, rewrites
+and proxies that worked under the dev server do not exist after deployment.
+Point the browser at the absolute backend URL from Inth instead of a
+same-origin `/api/c15t` path, then test the built output with a static file
+server, not the dev server. [Choose your setup](../concepts/choose-your-setup.md)
+lists the static path for each framework.
 
-## Why does static hosting fail when development works?
+## Why does the UI disappear with an ad blocker?
 
-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.
+Check the Network panel for `ERR_BLOCKED_BY_CLIENT`. Some filter lists block
+the consent backend's domain or old c15t chunk names such as
+`consent-dialog-*.js`. Current releases use neutral chunk names; update and
+rebuild. If the backend domain is blocked, the banner cannot load policy and
+every optional category stays denied.
 
-## Why does customization do nothing?
+## Why does my theme 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).
+Check that the c15t stylesheet loads, that you set a token or slot the
+component actually reads, and that the state attribute you target is on the
+element you style. A `data-variant` on the banner root is not on its card.
+Check the Tailwind version and CSS layer order before adding specificity. See
+[customization](../customization/overview.md).

package/docs/guides/verify-consent.md

@@ -1,62 +1,94 @@
 ---
-title: Verify consent before shipping
-description: Test requests, policy resolution, persistence, navigation and
-  preference changes in a production build.
+title: Verify consent
+description: Check in a production build that vendor requests wait for consent,
+  rejection survives a reload, preferences reopen and privacy signals apply.
 group: guides
 ---
 
-## Establish the policy under test
+## What you are checking
 
-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.
+A banner on screen proves only that the banner renders. Before shipping,
+confirm four things in a production build:
 
-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.
+1. Optional vendors make no requests before the visitor allows them.
+2. A rejection survives a reload and a new tab.
+3. The visitor can reopen preferences and change their mind.
+4. The policy is right for each location you serve.
+
+Run the checks against `next build && next start`, `vite preview`, or your
+framework's equivalent. Dev servers load code differently and hide problems.
+
+## Set up the browser
+
+1. Open a private window, so no earlier choice is stored.
+2. Open DevTools, select Network, and turn on **Disable cache** and
+   **Preserve log**.
+3. List the vendors you expect, such as `posthog.com`, `googletagmanager.com`,
+   `connect.facebook.net` or `youtube-nocookie.com`. You will filter by each.
+
+Before testing, list every place a vendor could load: `<script>` tags,
+framework analytics plugins, tag manager tags and embeds. c15t cannot hold
+back code it does not load. Remove duplicates first, or the results mean
+nothing.
 
 ## 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.
+| Step                                         | What to check                                                                                                     |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Load the page                                | The banner appears under an opt-in policy. Filter Network by each vendor domain; opt-in vendors show no requests. |
+| Click Reject                                 | The banner closes. Vendor domains still show no requests.                                                         |
+| Reload                                       | No banner. Still no vendor requests. DevTools Application shows a `c15t` cookie.                                  |
+| Open a new tab on the same site              | Same result as the reload.                                                                                        |
+| Open preferences from your footer link       | The dialog opens with the categories you rejected turned off.                                                     |
+| Allow one category and save                  | Only vendors in that category start loading. The others stay silent.                                              |
+| Turn that category off again                 | The page reloads, and the vendor does not load after the reload.                                                  |
+| Navigate between pages without a full reload | Each vendor loads once, not once per navigation.                                                                  |
+
+Google Tag and Google Tag Manager load before consent on purpose and send
+Consent Mode signals. For them, check that the consent state in the request
+parameters changes when the visitor chooses, not that requests are absent.
+See [Google Tag Manager](../integrations/google-tag-manager.md).
+
+## Check each location
+
+Policies usually differ by region. Test at least:
+
+* A location that needs a choice, such as Germany or the United Kingdom.
+* A location without a prompt, such as a US state without a privacy law in
+  your rules.
+* A request with no location headers at all. c15t applies your policy's
+  fallback for unknown locations; make sure that fallback is what you want.
+
+Use a VPN, your host's geolocation preview, or the `country` option on your
+framework's server helper while testing. Remove test overrides before you
+deploy.
+
+## Check privacy signals
+
+Turn on Global Privacy Control in the browser. Brave and DuckDuckGo send it by
+default; in Firefox, enable it in Privacy settings. Reload and confirm the
+categories your policy restricts for GPC are denied, without the visitor
+having clicked anything. Turn GPC off and confirm the restriction ends.
+
+## Check failure behavior
+
+Block the backend URL in DevTools (right-click the request, then **Block
+request URL**) and reload. No banner appears, and no optional vendor loads.
+A missing banner must never mean "allowed". Then unblock it and confirm the
+page recovers.
 
 ## 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.
+* Tab through the banner and dialog with the keyboard only. Focus stays inside
+  a modal dialog and returns to the button that opened it when it closes.
+* Set the viewport to 375 pixels wide and switch to a language with long
+  labels, such as German.
+* After applying your theme, check text contrast and that focus rings are
+  visible.
+
+## Record the result
 
-Record the policy, framework, deployment and observed request behavior with the
-test result. "The banner appears" is only one assertion.
+Write down the framework, the rendering mode, the policy you tested, and the
+requests you saw before and after consent. "The banner appears" is not a test
+result. If something fails, [troubleshooting](./troubleshooting.md)
+starts with three checks that locate most problems.