@c15t/react 3.0.0-alpha.3 → 3.0.0-alpha.5

package/docs/concepts/choose-your-setup.md

@@ -0,0 +1,87 @@
+---
+title: Choose your setup
+description: Pick the c15t setup for your framework, rendering mode and hosting,
+  and decide who runs the consent backend.
+group: concepts
+---
+
+## Find your app in this table
+
+Most apps need one row. Follow its guide from start to finish; each guide links
+to the alternatives it rules out.
+
+| Your app                                                                               | Setup                                                                                  | Guide                                                                                                                             |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js App Router with a Next.js server                                               | Server resolves consent from a cached manifest and streams it to the page              | [App Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                            |
+| Next.js App Router, banner must be in the first HTML                                   | Await consent inside `Suspense`                                                        | [Stream or await](https://c15t.com/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)                      |
+| Next.js with static, ISR or `'use cache'` pages                                        | Browser resolves consent on those pages                                                | [Static, ISR and cached pages](https://c15t.com/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)                |
+| Next.js Pages Router                                                                   | Resolve consent in `getServerSideProps`                                                | [Pages Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                          |
+| Next.js with `output: 'export'`                                                        | Browser resolves consent                                                               | [Static export](https://c15t.com/docs/frameworks/next/static-export)                                                              |
+| TanStack Start with a server                                                           | Root loader resolves consent on the server                                             | [TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart)                                                      |
+| TanStack Start on a serverless host, banner may follow the page                        | Root loader streams consent                                                            | [TanStack Start rendering](https://c15t.com/docs/frameworks/tanstack-start/rendering#stream-the-page-while-consent-resolves)      |
+| TanStack Start in SPA mode or prerendered                                              | Browser resolves consent                                                               | [TanStack Start rendering](https://c15t.com/docs/frameworks/tanstack-start/rendering#spa-mode-prerendered-pages-and-static-hosts) |
+| React with Vite, or another single-page app                                            | Browser resolves consent                                                               | [React](../frameworks/react/quickstart.md)                                                                                        |
+| React Router framework mode, Remix, or another server-rendered React app               | Browser resolves consent after hydration                                               | [React rendering](../frameworks/react/rendering.md#react-router-remix-and-other-server-rendered-apps)                             |
+| Nuxt with a Nuxt server                                                                | Nuxt module resolves consent on the server from a cached manifest                      | [Nuxt](https://c15t.com/docs/frameworks/nuxt/quickstart)                                                                          |
+| Nuxt with prerendered or cached routes                                                 | Nuxt server for most pages, the browser on prerendered and cached routes               | [Nuxt prerendered and cached routes](https://c15t.com/docs/frameworks/nuxt/rendering#prerendered-and-cached-routes)               |
+| Nuxt with `nuxt generate` on static hosting                                            | Nuxt module, browser resolves consent from the manifest or `/init`                     | [Nuxt static hosting](https://c15t.com/docs/frameworks/nuxt/rendering#deploy-to-static-hosting)                                   |
+| Nuxt with `ssr: false`                                                                 | Nuxt module, browser resolves consent from the manifest                                | [Nuxt single-page app](https://c15t.com/docs/frameworks/nuxt/rendering#build-a-single-page-app-with-ssr-false)                    |
+| Vue with Vite                                                                          | Vue plugin, browser resolves consent                                                   | [Vue](https://c15t.com/docs/frameworks/vue/quickstart)                                                                            |
+| Vue rendered on the server without Nuxt                                                | Vue plugin; the banner mounts after hydration. Use Nuxt for the banner in server HTML. | [Vue rendering](https://c15t.com/docs/frameworks/vue/rendering#server-rendering-without-nuxt)                                     |
+| Astro with static output                                                               | Browser resolves consent through the hosted backend                                    | [Astro static output](https://c15t.com/docs/frameworks/astro/rendering#static-output-with-hosted)                                 |
+| Astro with server output and an adapter                                                | Middleware resolves consent from a cached manifest                                     | [Astro server output](https://c15t.com/docs/frameworks/astro/rendering#server-output-with-manifest)                               |
+| Svelte with Vite                                                                       | Svelte provider, browser resolves consent                                              | [Svelte](https://c15t.com/docs/frameworks/svelte/quickstart)                                                                      |
+| SvelteKit with a server                                                                | Root layout load resolves consent on the server                                        | [SvelteKit](https://c15t.com/docs/frameworks/sveltekit/quickstart)                                                                |
+| SvelteKit with `adapter-static`, prerendered pages or SPA mode                         | Browser resolves consent                                                               | [SvelteKit rendering](https://c15t.com/docs/frameworks/sveltekit/rendering#build-a-static-site)                                   |
+| Plain HTML, a CMS, a page builder, or a static site generator such as Hugo or Eleventy | One script tag, stock banner included                                                  | [HTML](https://c15t.com/docs/frameworks/html/quickstart)                                                                          |
+| JavaScript with a bundler and no UI framework                                          | `@c15t/browser` module, stock banner included                                          | [JavaScript](https://c15t.com/docs/frameworks/javascript/quickstart)                                                              |
+| Your own UI, or a framework without an adapter such as Solid                           | Headless runtime                                                                       | [JavaScript headless](https://c15t.com/docs/frameworks/javascript/headless)                                                       |
+
+Solid has no c15t adapter. Use the [headless runtime](https://c15t.com/docs/frameworks/javascript/headless#use-c15t-with-solid)
+and subscribe to it from your components.
+
+## Decide who runs the consent backend
+
+The backend supplies policies and stores consent records. Every setup above
+works with each option; only the URL changes.
+
+| Option                                                               | Use it when                                                                                                                                                    |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Inth](https://inth.com)                                             | You want hosted policies and consent records. The guides use this.                                                                                             |
+| [Self-hosted c15t backend](https://c15t.com/docs/self-host/overview) | You need to run the service and its database yourself.                                                                                                         |
+| Offline mode                                                         | Local development and tests. Policies live in your code and choices stay in the browser, with no consent records. Not recommended for production environments. |
+
+To use Inth, create a project, set its policy rules, add your site's origin to
+its trusted origins, and copy the backend URL. The guides use the placeholder
+`https://your-project.inth.app`; replace it with your project's backend URL,
+including any path prefix.
+
+## Server rendering or browser rendering
+
+Where consent resolves decides what the visitor's first HTML contains.
+
+| Rendering                                    | What the visitor gets                                                                                                                                                                   |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The server resolves consent for each request | The server reads the visitor's cookie and location headers, so the browser starts with the answer. Gated scripts can run right after hydration, and the banner can be part of the HTML. |
+| The browser resolves consent                 | The HTML is the same for everyone. After the page loads, the browser requests the policy, then shows the banner or runs gated scripts.                                                  |
+
+A static or prerendered page cannot contain one visitor's consent, because the
+same HTML goes to everyone. Static sites still use Inth; the browser talks to it
+directly. A same-origin `/api/c15t` route only works where a server runs it.
+
+Pages that are cached and shared between visitors, such as Next.js ISR or
+`'use cache'` routes, need browser resolution for the same reason. Cache the
+public policy manifest, never a response that contains a visitor's consent.
+
+## How the server gets the policy
+
+Server setups fetch policy one of two ways:
+
+* **Manifest**, used by the Next.js, Nuxt and Astro server guides.
+  Your server downloads the project's public policy file, caches it, and
+  resolves each visitor locally. Consent saves still go to the backend.
+* **`/init`**. Each visit asks the backend to resolve the visitor. Simpler, but
+  every page load makes a request to the backend.
+
+[Data fetching](./data-fetching.md) compares them in detail,
+including proxies and custom transports.

package/docs/{frameworks/react/concepts → concepts}/consent-categories.md

@@ -1,8 +1,8 @@
 ---
 title: Consent categories
-description: Assign optional features to categories and understand how policy
-  scope affects permission.
-group: frameworks
+description: Assign scripts, embeds and features to c15t consent categories, and
+  understand which categories the preference dialog shows.
+group: concepts
 ---
 
 ## Choose categories by purpose
@@ -27,8 +27,23 @@ Compound script and network conditions contribute every category they reference.
 Discovered categories are added to `consentCategories`, when supplied. The dialog
 always includes Necessary and offers the optional categories in that combined
 set that are also in the resolved policy scope. Choice completion uses the same
-set. If neither configuration nor integrations supply categories, the dialog
-uses the full policy scope.
+set.
+
+If neither configuration nor integrations supply categories, the result depends
+on the policy's `scopeMode`:
+
+* Under a permissive policy, the dialog lists only Necessary. The banner still
+  appears when the policy prompts for a choice. Accept All, Reject All and Save
+  each record that the visitor saw it, send a consent receipt for Necessary
+  alone in hosted and manifest modes, and keep the banner dismissed after
+  reload. The acknowledgement expires with the policy's choice validity and
+  after a policy change, like a choice would. A stored choice that is still
+  valid under the current policy also counts as an acknowledgement.
+* Under a strict policy, or an IAB TCF policy, the dialog uses the full policy
+  scope. TCF consent is given per purpose and recorded in the TC string.
+
+A category declared after that acknowledgement, such as a newly registered
+script or a discovered iframe, needs a choice, so the banner asks again.
 
 Categories discovered later are added immediately and retained until the provider
 or runtime is recreated. Adding a category can require a new choice; removing a
@@ -65,5 +80,5 @@ client render. Set
 `useIframeBlocker({ disableAutomaticBlocking: true }).processAllIframes()`.
 
 Use effective permissions to gate work and explicit choices to inspect what the
-visitor confirmed. Read [consent state](../../../guides/consent-state.md) for that
-distinction and [migration](../../../upgrade-v3.md) for v3 policy configuration.
+visitor confirmed. Read [how consent works](./how-consent-works.md#a-permission-is-not-a-recorded-choice) for that
+distinction and [migration](../upgrade-v3.md) for v3 policy configuration.

package/docs/{guides → concepts}/consent-state.md

@@ -1,24 +1,14 @@
 ---
-title: Understand consent state
-description: Distinguish policy resolution, effective permissions, explicit
-  choices, notices and privacy signals.
-group: guides
+title: Consent state reference
+description: How c15t saves choices, gates IAB vendors, hydrates server records
+  and keeps browser tabs and storage in step.
+group: concepts
 ---
 
-## 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`                                         |
+This reference covers the edge cases behind the model in
+[how consent works](./how-consent-works.md). You need it when you
+build custom consent UI, run c15t across subdomains, or debug a choice that
+changes between tabs.
 
 ## Gate IAB vendors on the TC string
 
@@ -27,7 +17,7 @@ or IAB purposes is an IAB target. It runs only while a confirmed TC string
 grants what it declares: purpose and vendor consent for `iabPurposes`, purpose
 and vendor legitimate interest for `iabLegIntPurposes`, and opt-ins for
 `iabSpecialFeatures`. Every category it names must also be free of
-restrictions, so GPC, an opt-out directive or strict scope blocks it.
+restrictions, so GPC or strict scope blocks it.
 
 A refused category is the one exception. It does not block an IAB target that
 processes only on legitimate interest, after publisher restrictions, because
@@ -37,29 +27,13 @@ itself stays refused: its `effectivePermissions` entry is `false`, and targets
 that name only the category, or that also declare a consent purpose or special
 feature, stay blocked.
 
-## 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.
-
 ## When a choice is saved
 
 A save records the choice in the browser first and sends it to the backend
 afterwards. The stock banner, preference dialog and IAB surfaces in every
-framework adapter, and the browser client's `acceptAll()`, `rejectAll()`
-and `save()`, close without waiting for the backend. In order:
+framework adapter, and the `acceptAll()`, `rejectAll()` and `save()` methods
+of the browser and Astro clients, close without waiting for the backend. In
+order:
 
 1. In the click task, the explicit choice and effective permissions change,
    `onChoiceRecorded` and `onPermissionsChanged` run, gated scripts, iframes
@@ -79,9 +53,10 @@ and `save()`, close without waiting for the backend. In order:
 
 A failed request does not reopen the surface or roll the choice back. The
 kernel emits `command:error`, which reaches the `onError` callback in adapters
-that accept one, and queues the payload in localStorage. The queue is replayed
-after the next successful initialization and when the browser comes back
-online, up to 10 attempts over 7 days. A replay carries the original action
+that accept one, and queues the payload in localStorage. Where localStorage is
+unavailable, the queue lives in memory until the page unloads. The queue is
+replayed after the next successful initialization and when the browser comes
+back online, up to 10 attempts over 7 days. A replay carries the original action
 time and policy snapshot token, so the backend records when the visitor
 decided, and a duplicate submission resolves to the same consent record. A
 backend that signs policy snapshot tokens rejects a replay made after the
@@ -93,17 +68,13 @@ after its TC string is encoded, which can wait for the TCF library to load.
 If that local step records nothing, for example because the vendor list
 failed to load, the surface comes back so the visitor can try again.
 
-## 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.
+Every adapter leaves the same surface after a save: the banner while the
+policy still owes a choice or a notice, and nothing once no prompt is owed,
+while the policy is still loading, or after it failed to resolve. A banner
+the visitor reopened closes too. A save that records nothing new, such as an
+unchanged selection, closes the surface when it resolves successfully. Opening
+or closing a surface, or starting another save, before then leaves the surface
+as the visitor set it.
 
 ## Preserve records during hydration
 
@@ -128,7 +99,8 @@ shows the prompt again.
 Tabs on another subdomain that shares the consent cookie do not share
 localStorage, so the browser sends them no `storage` event. They pick up the
 change on their next focus or visibility change, or when you reconcile
-yourself (see below).
+yourself as described in
+[Reconcile yourself or turn it off](#reconcile-yourself-or-turn-it-off).
 
 The `storage` event only exists for localStorage. When localStorage is
 unavailable (blocked by the browser, a sandboxed frame or a privacy mode) and
@@ -150,8 +122,8 @@ Several triggers in quick succession run one reconciliation in a later task.
 Reconnecting does not read storage, because going online changes nothing in
 browser storage. On reconnect the kernel retries saves the backend did not
 accept and a failed initialization. Save retries do not write the cookie or
-localStorage. A write that follows initialization, such as a Global Privacy
-Control directive, obeys the ordering described below.
+localStorage. A write that follows initialization obeys the rules in
+[Ordering with pending writes](#ordering-with-pending-writes).
 
 Every adapter that mounts browser persistence does this: the React, Next.js and
 TanStack Start providers, Vue, Svelte, Astro, the script tag and
@@ -164,8 +136,6 @@ Stored records are merged into the ones in memory:
 * Category decisions merge per category. Each category keeps the decision with
   the newer confirmation time, so a tab that only changed marketing never
   reverts another tab's newer measurement decision.
-* Privacy directives, such as a Global Privacy Control opt-out, merge as a
-  union. A directive only restricts, so none is dropped.
 * The notice dismissal and the vendor record are single decisions. A stored one
   at least as new as the one in memory replaces it; an older one is ignored.
 * When two tabs record decisions in the same millisecond, the one stored first
@@ -177,38 +147,8 @@ Stored records are merged into the ones in memory:
   resolved (at init, from a prefetch or in a save response) is replaced only by
   a strictly newer stored choice, and an identity set with `identify()` is
   never replaced.
-* Under an IAB policy, the `@c15t/iab` module then loads the TC string the other
-  tab stored, together with its purpose, vendor and special-feature selections,
-  so `__tcfapi` and the preference controls show the choice now in force.
-  Selections the visitor changed in this tab without saving are kept. A missing
-  or older stored TC string leaves the current one in place, unless it conflicts
-  with the reconciled choice: then it is withdrawn and `__tcfapi` reports no
-  consent until the next save. A category denied after the TC string was saved
-  conflicts if the TC string grants any of its purposes. A partial selection
-  saved through IAB, which records its category as denied because not every
-  purpose is granted, keeps its TC string. A TC string confirmed before the
-  choice's newest decision no longer describes it and is withdrawn too, unless
-  a newer receipt replaces it. That receipt is adopted even when its TC string
-  is identical, since TC strings round their time to the day and custom-vendor
-  selections live only in the receipt; its expiry then applies. The TC
-  string and its receipt (`euconsent-v2`, `c15t-iab-authority-v1`) belong to one
-  origin, so after a save on a sibling subdomain that shares the consent cookie,
-  this subdomain reports no consent through `__tcfapi` until it saves again.
-  Vendors never receive the stale TC string in between: it is withdrawn, or
-  held back, before `__tcfapi` publishes. A tab also reloads the TC string
-  when another tab on the same origin stores a new one, which covers a save in
-  the same millisecond or one that changed only vendors. When two tabs save in
-  the same millisecond with different selections, the more restrictive TC
-  string wins in both, so a revoked vendor is never advertised again. If each
-  grants something the other denies, neither is published until the next save:
-  the stored receipt is removed, so a page opened later does not restore it.
-  When another tab removes the receipt, or clears localStorage, the TC string
-  is withdrawn here too, since a page opened now would find none, and a
-  receipt this tab was still decoding is not installed. The removal after a
-  tie checks that the stored receipt is the one it read, but localStorage has
-  no conditional removal, so a receipt another tab stored a moment earlier can
-  still be removed. Every tab then withdraws its TC string until the next save,
-  so the race only ever withholds consent.
+* Under an IAB policy, the TC string follows the reconciled choice. See
+  [How the TC string is reconciled](#how-the-tc-string-is-reconciled).
 * A record removed from readable storage since this tab last saw it present is
   cleared, and the active policy decides again. A record this tab never saw in
   storage, such as a receipt merged from the server after `identify()` or a
@@ -219,8 +159,55 @@ Stored records are merged into the ones in memory:
 Expiry is not decided here. The applied records are evaluated at the time of the
 read, the same way as at startup.
 
+### How the TC string is reconciled
+
+Under an IAB policy, a tab adopts the TC string another tab stored, unless that
+TC string conflicts with the reconciled choice. A conflicting TC string is
+withdrawn, and `__tcfapi` reports no consent until the next save. Vendors never
+receive a stale TC string: c15t withdraws it, or holds it back, before
+`__tcfapi` publishes.
+
+1. The `@c15t/iab` module loads the TC string the other tab stored, with its
+   purpose, vendor and special-feature selections, so `__tcfapi` and the
+   preference controls show the choice now in force. Selections the visitor
+   changed in this tab without saving are kept.
+2. A missing or older stored TC string leaves the current one in place, unless
+   the current one conflicts with the reconciled choice. Then it is withdrawn.
+3. A category denied after the TC string was saved conflicts if the TC string
+   grants any of its purposes. A partial selection saved through IAB, which
+   records its category as denied because not every purpose is granted, keeps
+   its TC string.
+4. A TC string confirmed before the choice's newest decision no longer
+   describes it and is withdrawn, unless a newer receipt replaces it. That
+   receipt is adopted even when its TC string is identical, because TC strings
+   round their time to the day and custom-vendor selections live only in the
+   receipt. The receipt's expiry then applies.
+5. The TC string and its receipt (`euconsent-v2`, `c15t-iab-authority-v1`)
+   belong to one origin. After a save on a sibling subdomain that shares the
+   consent cookie, this subdomain reports no consent through `__tcfapi` until
+   it saves again.
+6. A tab reloads the TC string when another tab on the same origin stores a
+   new one. This covers a save in the same millisecond, or one that changed
+   only vendors.
+7. When two tabs save in the same millisecond with different selections, the
+   more restrictive TC string wins in both, so a revoked vendor is never
+   advertised again. If each grants something the other denies, neither is
+   published until the next save, and the stored receipt is removed so a page
+   opened later does not restore it.
+8. When another tab removes the receipt or clears localStorage, this tab
+   withdraws its TC string too, because a page opened now would find none. A
+   receipt this tab was still decoding is not installed.
+9. The removal after a tie checks that the stored receipt is the one it read.
+   localStorage has no conditional removal, so a receipt another tab stored a
+   moment earlier can still be removed. Every tab then withdraws its TC string
+   until the next save, so the race only ever withholds consent.
+
 ### Clearing records across tabs
 
+`clearRecords()` also drops every save queued for replay, with or without
+browser persistence, so nothing the visitor decided before the clear reaches
+the backend afterwards.
+
 `clearRecords()` removes every record and then stores the time of the clear,
 the clear epoch, under its own key: `c15t-epoch` in localStorage and a cookie
 of the same name (`<storageKey>-epoch` with a custom `storageKey`). Clearing
@@ -295,15 +282,14 @@ cookie takes, for example because storage is full, the older localStorage copy
 is removed.
 
 When a server render seeded the page from the consent cookie
-(`skipHydration`), that seed stays authoritative. A denial or privacy directive
-that reached only localStorage is still applied on top of it when the page
-mounts, since it can only restrict, if it is newer than the seeded decision or
-from the same millisecond as a seeded grant. A stored grant is not.
-
-The notice dismissal, privacy directives and vendor denials are stored twice
-as well. Privacy directives from both copies all apply. A vendor list in
-localStorage at least as new as the cookie's adds its denials but never lifts
-one the cookie holds; a copy confirmed before the last clear is ignored, so its
+(`skipHydration`), that seed stays authoritative. A denial that reached only
+localStorage is still applied on top of it when the page mounts, since it can
+only restrict, if it is newer than the seeded decision or from the same
+millisecond as a seeded grant. A stored grant is not.
+
+The notice dismissal and vendor denials are stored twice as well. A vendor
+list in localStorage at least as new as the cookie's adds its denials but never
+lifts one the cookie holds; a copy confirmed before the last clear is ignored, so its
 denials never come back. The newer notice dismissal applies; it still only hides a
 notice with the fingerprint it names. The consent record follows the rules
 below.
@@ -343,20 +329,18 @@ A tab writes its own choices in a later task, not during the click. Before it
 reads storage, it lands its own queued writes, so a reconciliation never undoes
 the visitor's latest action in that tab. A queued write follows the same rules
 as a read: it stores the per-category merge of its choice and the stored one,
-the union of directives, and never replaces a newer notice or vendor record. It
-keeps the stored subject unless this tab identified a different user.
+and never replaces a newer notice or vendor record. It keeps the stored subject
+unless this tab identified a different user.
 When a slow save response returns a server subject id, the tab adds it only to
 the record it wrote; it does not recreate records another tab cleared or
 overwrite another tab's newer choice.
 
 Two tabs that write at the same moment can both read storage before either
-writes, and the later write can then drop the other tab's category or privacy
-directive. The tab whose decision was dropped still holds it, and on its next
+writes, and the later write can then drop the other tab's category decision.
+The tab whose decision was dropped still holds it, and on its next
 reconciliation it writes it back, merged with what storage holds. It does so
 only for decisions it actually stored itself, never for one a clear voided or
-another tab replaced with a newer one. A directive write stores the directives
-it kept from storage too, so if another write drops one of those, this tab
-restores it and applies it as well.
+another tab replaced with a newer one.
 
 If another tab's change reaches this tab while one of its saves is pending, the
 save depends on how far it got. A save not yet sent is dropped. A request

package/docs/{guides → concepts}/data-fetching.md

@@ -1,23 +1,17 @@
 ---
-title: Data fetching and transports
-description: Choose cached manifests, backend init or offline policy resolution,
-  and understand where consent records are saved.
-group: guides
+title: Data fetching
+description: How c15t gets policy data through a cached manifest, backend /init,
+  the browser or offline rules, and where consent choices are saved.
+group: concepts
 ---
 
-## Start with Inth and a cached manifest
+## Compare the fetching paths
 
-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.
+Where policy resolves and where choices are saved are separate from who runs
+the backend. Inth and a [self-hosted backend](https://c15t.com/docs/self-host/quickstart) speak
+the same protocol, so every path below works with either. Only `offline()`
+removes backend requests. For a recommendation by framework, start with
+[choose your setup](./choose-your-setup.md).
 
 | Fetching path                  | Where policy resolves                                                                 | Where choices are submitted | Choose it when                                                                                         |
 | ------------------------------ | ------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
@@ -44,6 +38,16 @@ 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.
 
+## How manifest mode counts visitors
+
+The backend counts visitors from `/init` requests, and manifest resolution
+skips them. To keep the count, the server adapters send a session report after
+each resolution: the host posts to the backend's `POST /sessions` from the
+server, after the response. The browser sends nothing, and the report stores
+no identity; the visitor's IP address and user agent are forwarded under the
+backend's usual IP handling. Static output resolves in the browser and sends
+no report. Set `reportSessions: false` on an adapter to turn it off.
+
 ## What does regular `/init` do?
 
 `hosted({ url })` uses `${url}/init` for initialization and `${url}/subjects` for
@@ -54,7 +58,7 @@ can belong to Inth or your own c15t backend.
 import { hosted } from 'c15t';
 
 export function createConsentMode(backendURL: string) {
-  return hosted({ url: backendURL });
+	return hosted({ url: backendURL });
 }
 ```
 
@@ -81,9 +85,9 @@ separate policy reads and record writes. With a backend rewrite mounted at
 import { hosted } from 'c15t';
 
 export const mode = hosted({
-  url: '/api/c15t',
-  initURL: '/api/c15t/init',
-  assertDecisionInputs: true,
+	url: '/api/c15t',
+	initURL: '/api/c15t/init',
+	assertDecisionInputs: true,
 });
 ```
 
@@ -105,11 +109,11 @@ 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.
+The rewrite destination and the init route use the absolute upstream endpoint,
+such as `https://your-project.inth.app`. 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?
 
@@ -134,7 +138,7 @@ 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
+Use [policy rules](./policies.md) to understand
 matching and defaults, and test the missing-location case.
 
 Offline mode is an explicit architecture choice, not an automatic fallback for
@@ -160,4 +164,4 @@ refresh. In the recommended Next.js setup, the browser should call only
 upstream destinations.
 
 Test different locations, missing location headers, GPC, returning choices and
-backend failure. See [verification](./verify-consent.md).
+backend failure. See [verification](../guides/verify-consent.md).