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

package/docs/frameworks/react/network-blocker.md

@@ -0,0 +1,146 @@
+---
+title: Block network requests
+description: Block fetch and XHR calls to third-party domains in a React app
+  until the visitor grants their consent category.
+group: frameworks
+---
+
+## Add rules to the provider
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
+list until the visitor grants their category. Use it for beacons and API
+calls that bypass script loading, such as a pixel fired by an SDK that is
+already on the page.
+
+Add `networkBlocker` to the `ConsentProvider` options from your
+[quickstart](./quickstart.md). Set the URL to the endpoint
+supplied by your Inth project.
+
+```tsx title="components/consent.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import { ConsentBanner, ConsentDialog, ConsentProvider, hosted } from 'c15t/react';
+
+const mode = hosted({ url: 'https://your-project.inth.app' });
+const networkBlocker = {
+  rules: [
+    { id: 'google-analytics', domain: 'google-analytics.com', category: 'measurement' },
+    { id: 'meta-pixel', domain: 'facebook.com', pathIncludes: '/tr', category: 'marketing' },
+  ],
+};
+
+export function Consent({ children }: { children: ReactNode }) {
+  return (
+    <ConsentProvider options={{ mode, networkBlocker }}>
+      {children}
+      <ConsentBanner />
+      <ConsentDialog />
+    </ConsentProvider>
+  );
+}
+```
+
+Render your app inside `ConsentProvider`. Blocking starts when it renders, so
+components outside it that send requests while rendering, or modules evaluated
+before it, are not covered. See the limits below.
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains: `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. A request is
+blocked when a matching rule's condition is not met by the visitor's
+effective permissions.
+
+`category` takes the same conditions as scripts:
+
+```ts
+{ category: 'measurement' }
+{ category: { and: ['measurement', 'marketing'] } }
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+Add `vendor` to also block the request while the visitor has turned that
+vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
+instead.
+
+| Option               | Default  | Purpose                                                      |
+| -------------------- | -------- | ------------------------------------------------------------ |
+| `rules`              | required | Rules described above                                        |
+| `enabled`            | `true`   | Set `false` to keep the rules but stop blocking              |
+| `logBlockedRequests` | `true`   | Log each blocked request with `console.warn`                 |
+| `onRequestBlocked`   | none     | Called with `{ method, url, rule }` for each blocked request |
+
+## What a blocked request looks like
+
+The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
+resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The provider holds matching requests from its first render in the browser,
+before any of its children render or run effects. That covers requests from
+child components, including their mount effects, and from effects in
+components rendered next to the provider. The blocker module itself loads
+after mount and decides each held request. Apps without `networkBlocker` do
+not download it.
+
+The standalone `useNetworkBlocker` hook works the same way from the first
+render of the component that calls it. That render patches `fetch` and
+`XMLHttpRequest`. If React throws the render away and never commits it, the
+hold ends after 10 seconds. Nothing checked consent for the requests it held,
+so they fail the way the blocker fails a blocked request: a 451 response for
+`fetch`, a failed XHR. The same happens when the component unmounts before
+the blocker loads.
+
+While consent is unknown, a matching request that would be blocked waits
+instead of failing. Consent is unknown until the policy has loaded, which is
+also when a returning visitor's stored choice takes effect. The request is
+then sent if the choice allows it and blocked otherwise. If the policy fails
+to load, optional categories stay denied and waiting requests are blocked.
+If the policy request never finishes, they keep waiting and are never sent.
+
+A synchronous XHR cannot wait. Before the blocker module has loaded, a
+matching one throws a `NetworkError` from `send()`. After that, one that
+consent does not allow yet is blocked.
+
+## What the network blocker cannot stop
+
+The blocker only sees requests made after the provider starts rendering in
+the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:
+
+* Code that runs before the provider renders: inline scripts in the HTML,
+  third-party tags in `<head>`, scripts loaded before hydration (such as
+  `next/script` with `beforeInteractive`), and client modules that evaluate
+  earlier. Webpack builds evaluate a route's client component modules when
+  its chunk loads, so their top-level code runs first. Turbopack evaluates a
+  client component module when its first element renders, which inside the
+  provider is after blocking starts.
+* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
+  provider rendered.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
+  `<img>`, `<script>` or `<iframe>` elements, web workers and service
+  workers.
+* With the standalone `useNetworkBlocker` hook instead of the provider
+  option, requests sent before the component that calls it renders.
+  Blocking starts in that component's first render, not the provider's.
+
+Keep tracking calls out of that window:
+
+* Send them from an effect or an event handler, never at module top level.
+* Load vendor SDKs through `scripts` instead of a `<script>` tag or
+  `next/script`, so they wait for consent before they run at all.
+* Check `useConsent('measurement')` (or the category you need) before you
+  call a vendor from your own code, and treat the blocker as a backstop.
+
+## Verify
+
+Open the browser's network panel, clear site data and reload. Requests
+matching a rule should not appear until you grant their category; with
+logging on, the console lists each blocked request. Reject, reload, and
+check that they still do not appear. The
+[verification guide](../../guides/verify-consent.md) covers automated checks.

package/docs/frameworks/react/script-loader.md

@@ -61,3 +61,9 @@ already wrote. Add `clearOnRevocation` to `ConsentProvider.options` to remove
 declared data when its category is denied. See
 [clear on revocation](../../integrations/clear-on-revocation.md) for configuration
 and browser limits.
+
+## Shared lifecycle controls
+
+See [shared consent controls](../../guides/shared-consent-controls.md) for external CMPs,
+preference delegation, withdrawal reloads, and application events. These controls
+use the same core runtime across frameworks.

package/docs/frameworks/react/styling/overview.md

@@ -29,28 +29,47 @@ and `utilities` directives:
 
 ## Tokens
 
-The provider snippets below are partial configuration examples. Apply them to
-your existing `ConsentProvider` from `c15t/react`, keeping its `mode`, children
-and other options.
-
 Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
-properties. Set them on the provider through `theme`, or override the
-variables directly in your CSS.
-
-React and Next.js render the theme stylesheet in the server HTML before
-the banner. Pass the same theme on the server and the first client render
-so your custom tokens apply before hydration. The provider's `nonce`
-option also applies to this stylesheet for Content Security Policy.
-
-`colorScheme: 'dark'` applies dark tokens in the server HTML.
-`colorScheme: 'system'` uses a CSS media query to follow the visitor's
-preference before hydration. If your app manages dark mode through a
-root class instead, include that class in the server HTML too.
-
-```tsx
-import { ConsentProvider, defineTheme } from 'c15t/react';
-
-const theme = defineTheme({
+properties. The package stylesheet sets the default values. To change them,
+render `ConsentTheme` with your theme where your app renders on the server,
+or override the variables directly in your CSS.
+
+`ConsentTheme` renders a `<style id="c15t-theme">` element with the
+variables for `theme`. It is not a client component: rendered from a Server
+Component or another server-only file, the theme generator stays out of the
+browser bundle. Rendered from a client component it still works, but the
+browser downloads the generator (about 1.7 KB gzip). The provider no longer
+turns `theme` tokens into CSS. It still reads `consentActions` and slot
+styles from its `theme` option, and warns in development when `theme` holds
+tokens but the page has no `c15t-theme` stylesheet.
+
+| `ConsentTheme` prop | Purpose                                                                                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `theme`             | Colors, `dark` colors, typography, spacing, radius, shadows and motion. Defaults to the built-in theme.                                                                                     |
+| `colorScheme`       | `'dark'` makes the dark tokens the default before hydration. `'system'` follows `prefers-color-scheme` with a CSS media query. Omit it to follow a `dark` or `c15t-dark` class on `<html>`. |
+| `nonce`             | Content Security Policy nonce for the `<style>` element.                                                                                                                                    |
+
+Pass the same `colorScheme` to `ConsentTheme` and to the provider. The
+provider keeps the `c15t-dark` class on `<html>` in sync after hydration.
+If your app manages dark mode through a root class, such as next-themes'
+`dark` class, omit `colorScheme` and include that class in the server
+HTML.
+
+To switch between light and dark at runtime, render `ConsentTheme` without
+`colorScheme` and toggle the `dark` class on `<html>`: its output already
+holds the variables for both schemes. To switch between different token
+sets, render `ConsentTheme` from a client component and change its props,
+which ships the generator.
+
+Outside React, call `generateThemeCSS(theme, colorScheme)` from
+`@c15t/ui/theme` on the server or at build time and put the result in a
+`<style>` element or your stylesheet. It escapes `<`, so the result is safe
+inside `<style>`.
+
+```ts title="src/consent-theme.ts"
+import { defineTheme } from 'c15t/react';
+
+export const theme = defineTheme({
 	colors: { primary: '#2f6f4e' },
 	radius: { lg: '4px' },
 	consentActions: {
@@ -58,10 +77,40 @@ const theme = defineTheme({
 		dismiss: { variant: 'neutral', mode: 'stroke' },
 	},
 });
+```
 
-<ConsentProvider options={{ mode, theme }} />;
+With server rendering, render `ConsentTheme` in the server-only part of your
+document, next to the provider. In a single-page app with no server render,
+either render it next to the provider, which ships the generator, or write the
+variables into your stylesheet. This partial example keeps the provider's
+`mode`, children and other options:
+
+```tsx
+import { ConsentProvider, ConsentTheme } from 'c15t/react';
+
+import { theme } from './consent-theme';
+
+<>
+	<ConsentTheme theme={theme} />
+	<ConsentProvider options={{ mode, theme }}>{children}</ConsentProvider>
+</>;
 ```
 
+The provider's `theme` option only supplies `consentActions` and slot styles.
+
+Earlier v3 alphas generated theme CSS in the browser from the provider's
+`theme` option. To migrate:
+
+1. Move the theme into a module without `'use client'`, so server and
+   client files can both import it.
+2. Render `<ConsentTheme theme={theme} />` next to the consent root, from a
+   Server Component or another server-rendered file. Pass `colorScheme` and
+   `nonce` if you set them on the provider.
+3. Keep passing `theme` to the provider only for `consentActions` and slot
+   styles. A theme with tokens only can be removed from the provider.
+4. Keep the package stylesheet import. It carries the default tokens the
+   provider used to inject.
+
 `consentActions` decides how each action role looks: `default` applies to
 every button, `primary` to whichever actions the policy or your props mark
 primary, and `accept`, `reject`, `customize`, and `dismiss` to one role each.

package/docs/guides/consent-state.md

@@ -20,6 +20,23 @@ grant.
 | Explain regional behavior                   | `policyRule`                                         |
 | Diagnose initialization                     | `resolution`                                         |
 
+## Gate IAB vendors on the TC string
+
+Under an IAB policy, a script, network rule or iframe that names a `vendorId`
+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.
+
+A refused category is the one exception. It does not block an IAB target that
+processes only on legitimate interest, after publisher restrictions, because
+the TCF lets that processing run without consent. The visitor's control for it
+is the objection, which the legitimate interest signals record. The category
+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
@@ -37,6 +54,45 @@ confirmation times. Do not call all three in one handler.
 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:
+
+1. In the click task, the explicit choice and effective permissions change,
+   `onChoiceRecorded` and `onPermissionsChanged` run, gated scripts, iframes
+   and network rules follow the new permissions, and the surface leaves the
+   active state. Its exit animation still plays.
+2. In the next task, the choice is written to the cookie and localStorage.
+3. After that write is queued, the request to the backend starts.
+4. When the request settles, the kernel emits `command:save:completed`. The
+   promise returned by `kernel.commands.save()`, React's `performAction()` and
+   Svelte's `saveConsents()` resolves or rejects only then.
+5. If the save turned off a category or vendor that was granted, the page
+   reloads in the next task, after `onBeforeConsentRevocationReload` runs.
+   Removing a script cannot stop code that already ran, so the reload starts a
+   page with only permitted code. With several saves in flight, it waits for
+   the last one. Set `reloadOnConsentRevoked: false` to handle revocation
+   yourself.
+
+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
+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
+token expires, which is 30 minutes by default for the self-hosted backend. A
+save still queued by then is recorded only in the browser.
+
+IAB surfaces close in the click task too, but an IAB choice is recorded only
+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
@@ -58,3 +114,274 @@ 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.
+
+## Keep open tabs in step
+
+Tabs and windows on the same origin (scheme, host and port) share the consent
+cookie and localStorage. When a visitor rejects in one tab, every other open tab
+on that origin applies the rejection without a reload. Scripts and features
+gated on `effectivePermissions` lose permission, subscribers are notified once
+and `onPermissionsChanged` fires. Clearing records in one tab returns the others
+to the active policy's defaults: an opt-in policy denies optional categories and
+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).
+
+The `storage` event only exists for localStorage. When localStorage is
+unavailable (blocked by the browser, a sandboxed frame or a privacy mode) and
+c15t stores in the cookie alone, another tab's change arrives only on the next
+focus or visibility change, or when you call `runtime.reconcileStorage()` or
+`persistence.reconcile()`. c15t does not poll the cookie or use a
+`BroadcastChannel` for this.
+
+Browser persistence reads stored records again at these moments:
+
+| Moment                                                                   | What happens                      |
+| ------------------------------------------------------------------------ | --------------------------------- |
+| Another tab or window on the same origin changes a c15t localStorage key | Reconciles on the `storage` event |
+| The page becomes visible again                                           | Reconciles on `visibilitychange`  |
+| The window regains focus                                                 | Reconciles on `focus`             |
+| The network reconnects                                                   | No storage read                   |
+
+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.
+
+Every adapter that mounts browser persistence does this: the React, Next.js and
+TanStack Start providers, Vue, Svelte, Astro, the script tag and
+`createConsentRuntime`. With `persistence: false` nothing is stored or read.
+
+### What a reconciliation applies
+
+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
+  wins in both tabs.
+* Tabs keep one subject. A stored subject is considered only when the record
+  that carries it changed, never on focus alone. It replaces a subject the tab
+  generated on its first save or copied from storage, so a tab that opened
+  before another tab stored a subject joins it. A subject id the server
+  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.
+* 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
+  choice seeded while storage was blocked, stays.
+* Blocked storage, or bytes that do not decode, change nothing. A failed read
+  never grants a category.
+
+Expiry is not decided here. The applied records are evaluated at the time of the
+read, the same way as at startup.
+
+### Clearing records across tabs
+
+`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
+never removes it. Every consent record written afterwards also records the
+epoch it was written under.
+
+A decision confirmed before the epoch was made before the clear, so it is void
+wherever it turns up. A decision stamped in the very millisecond of the clear
+counts only if it comes from a tab that had already seen that clear, so a tab's
+own choice right after its own clear stands while another tab's decision in the
+same millisecond does not. A stored record left with no decisions after the
+clear is void too, subject included.
+
+* A tab that reconciles only after another tab cleared and saved again drops
+  its pre-clear decisions instead of merging them back. Its subject from before
+  the clear is dropped too.
+* A tab that missed the clear writes only decisions it made after it. Its queued
+  write of an earlier decision is discarded, so it cannot bring back a cleared
+  record.
+* Browser hydration and server reads (`readStoredRecordsFromCookieHeader`, used
+  by the Next.js, TanStack Start, Nuxt, SvelteKit and Astro helpers) apply the
+  same rule, so a server render agrees with the browser.
+
+Records from before any clear, including v2 and legacy records, read as epoch 0
+and are unaffected. A corrupt epoch, or one that cannot be read, also reads as
+0: it voids nothing, so a failed read never grants a category. A consent record
+whose own epoch field is corrupt is kept, and only its epoch is ignored.
+
+Each clear moves the epoch forward, even when the device clock went back, so a
+later clear never lets earlier decisions back in. Two clears in the same
+millisecond therefore leave the epoch a millisecond ahead, and a decision saved
+in that millisecond is void. An epoch up to one hour ahead
+of the clock is kept, as it is when the clock was set back after a clear. Until
+the clock catches up, decisions saved in that window are void too. An epoch more
+than an hour ahead is treated as corrupt and reads as 0, so a clear never writes
+one: after the clock went back more than an hour, the new epoch is capped at an
+hour ahead of the clock.
+
+That cap is a known limit. A cleared record carries times from before the clock
+went back, and a runtime that missed the clear can write those times back. The
+capped epoch is lower than them, so once the clock has recovered, such a
+decision counts again. Leaving the epoch uncapped does not help: every tab
+whose clock is still behind reads it as corrupt, which voids nothing. Times
+alone cannot order a clear against decisions stamped by a clock that went back
+more than an hour.
+
+This changes the stored format. After a clear, the consent cookie carries
+`&e=<time>` (16 bytes) and the localStorage record an `epoch` field (22 bytes),
+and the epoch cookie itself holds a 13-digit time. Visitors who never cleared
+their records store exactly what they did before. An older c15t build rejects
+both the cookie and the localStorage record once they carry the epoch, so a page
+still running one treats the visitor as undecided. Under an opt-out policy that
+page grants optional categories by default until a new choice is saved, and the
+configured prompt may appear again. Deploy the new build to every page of the
+site before visitors can clear their records.
+
+### When the cookie and localStorage disagree
+
+When both copies hold a decision for a category from the same millisecond and
+the two conflict, the denial wins.
+
+The subject and IAB metadata come from the cookie. A server response, such as
+server-side consent restoration, and a sibling subdomain sharing the cookie
+with `crossSubdomain` can both rewrite it without touching this origin's
+localStorage, so the local copy can be the older one. The local copy's subject
+is used only when this browser's last consent write reached localStorage but
+not the cookie, for example because the cookie grew past the size limit, and
+the cookie has not changed since. Such a write stores the cookie as it stood
+under `<storageKey>-cookie-miss` in localStorage; the next write that reaches
+the cookie, or a clear, removes it. When localStorage rejects a write that the
+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
+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.
+
+The consent record is stored twice: as a cookie, which a server render reads,
+and in localStorage. The cookie is authoritative. A well-formed cookie wins
+even when it has expired, so a local copy can never bring back a grant the
+cookie no longer carries.
+
+A browser can still drop a cookie write, for example when the record grows past
+the cookie size limit, while localStorage takes it. A denial in the local copy
+that is newer than the cookie's decision for that category is therefore applied
+on top of the cookie. A newer local grant is not, so a dropped cookie write only
+ever leaves the visitor with less permission. A server render sees only the
+cookie; after a dropped write that carried a denial, the browser is the stricter
+of the two.
+
+When the two copies were written under different clear epochs, each loses its
+decisions from before the later epoch first, and the same rule applies to what
+remains. A later epoch in the local copy never lets its grant replace a cookie
+denial. The subject and IAB metadata come from the copy written under the later
+epoch; a record written before the clear in force keeps its later decisions but
+no subject.
+
+A server render cannot know about a clear that never reached a cookie. If the
+page could write localStorage but its cookie writes failed during
+`clearRecords()` (cookies blocked for the page, or a cookie setter that
+throws), the removal of the consent cookie failed too, and so did the epoch
+cookie. The browser then applies the clear from localStorage, while a server
+render still reads the old consent cookie until the next successful cookie
+write. The same applies to a consent cookie set with a different `domain` than
+the current `storageConfig` uses, which the clear cannot remove.
+
+### Ordering with pending writes
+
+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.
+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
+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.
+
+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
+already sent still reaches the backend, which may record it; this tab ignores
+the response, so it queues no retry and applies no subject id from it. A save
+already queued for retry keeps its original decision time.
+
+### Reconcile yourself or turn it off
+
+Browsers send no event for a change made in the same document, or for a cookie
+rewritten without a localStorage change, such as a `Set-Cookie` response header
+or another subdomain sharing the cookie. The next focus or visibility change
+picks it up. To apply it at once, call the method yourself:
+
+```ts
+// Runtime owners: returns true when any record changed.
+runtime.reconcileStorage();
+
+// Kernel owners with createPersistence from c15t/modules/persistence:
+persistence.reconcile();
+```
+
+To keep storage but stop automatic reconciliation, pass `sync: false` in the
+persistence options, for example `createConsentRuntime({ persistence: { sync:
+false } })` or `createPersistence({ kernel, sync: false })`. The manual methods
+still work.
+
+`dispose()` removes the listeners and cancels a scheduled reconciliation.

package/docs/guides/deployment-modes.md

@@ -30,6 +30,18 @@ in your application while consent writes still go to Inth. Regular backend
 browser setup. See [data fetching and transports](./data-fetching.md) for
 the comparison, including custom transports and offline mode.
 
+Manifest resolution removes the per-visitor `/init` request, and with it the
+backend's only count of visitors. The server adapters replace it with a session
+report: after each resolution, on a server-rendered page or the same-origin
+init route, the host posts a small report to the backend's `POST /sessions`,
+server-to-server and detached from the response. The browser makes no request
+and the report stores no identity; the visitor's IP and user agent travel as
+forwarded headers under the backend's usual IP handling. Each report is one
+resolution; a page view can produce a `render` and a `route` report, and the
+consuming side groups them into sessions by address and user agent within a
+window. Static output resolves in the browser and sends none. Set `reportSessions: false` on an adapter to turn
+it off.
+
 ## Match initialization to your application output
 
 | Application output | Initial state             | Required setup                                              |