@c15t/react 3.0.0-alpha.0 → 3.0.0-alpha.2

package/docs/frameworks/react/components/consent-widget.md

@@ -85,6 +85,28 @@ Privacy Control overrides shows a note under its row: "Your saved choice is
 restricted by the current privacy settings." The switch still reflects the
 saved value; the effective permission is off.
 
+### Vendors
+
+When the provider declares `vendors`, each category's expanded description
+ends with one card per vendor whose category condition names that category,
+styled like a category row: the vendor's name and a switch on the header,
+and its description and privacy policy link behind the card's own expand
+control. Cards start collapsed, so a long list stays one line per vendor,
+and the category list scrolls inside the dialog rather than growing it.
+Vendor switches edit the same draft as the category
+switches and record on Save. Saving with one vendor off denies that vendor
+only; the category stays granted and its other vendors keep loading. While
+the category is off in the draft the vendor switches are disabled, with the
+hint "Turn on this category to choose vendors." A vendor declared
+`disabled`, or one that only falls under `necessary`, is listed without a
+switch. Accept all and Reject all clear every vendor denial, including one
+staged but not yet saved. Under an `iab` policy no vendor rows render.
+Vendors that are only referenced by a script slug, without a name and
+privacy policy URL, still gate loading but are not listed, and so does a
+vendor whose condition negates a category, since no category row can
+host it. See
+[granular consent](../../../integrations/granular-consent.md).
+
 ### Actions
 
 The preference center always renders Reject all, Accept all and Save, with
@@ -102,8 +124,12 @@ such as `['disclosure']`, renders the widget and Save completes without
 writing a consent record.
 
 For a fully custom preference center, `useConsentDraft()` returns the same
-draft: `values`, `displayedCategories`, `isDirty`, `isStale`, `set`,
-`update`, `acceptAll`, `rejectAll`, `save` and `reset`.
+draft: `values`, `displayedCategories`, `vendors`, `isDirty`, `isStale`,
+`set`, `update`, `setVendor`, `acceptAll`, `rejectAll`, `save` and `reset`.
+A custom vendor control alone takes `useVendorDraft()`, the vendor slice of
+that draft: `vendors`, `setVendor`, `isDirty`, `isStale`, `save` and `reset`.
+`useDeclaredVendors()`, `useVendorChoice()` and `useVendorAllowed(id)` read
+the declared list, the recorded denials and one vendor's effective result.
 
 `useConsentDraft` and `ConsentDraftProvider` import from `c15t/react`.
 
@@ -112,7 +138,10 @@ draft: `values`, `displayedCategories`, `isDirty`, `isStale`, `set`,
 Each row is a disclosure: a button that expands the category description
 and a switch beside it, so a visitor can read the description without
 changing the choice. Each switch has the category title as its accessible
-name. The policy-change alert uses `role="alert"`, and a restriction note is
+name. A category's vendor cards sit in a `region` named "Vendors" with the
+count; each card's expand button carries `aria-expanded`, each vendor
+switch is named "Allow" followed by the vendor name, and is described by
+the vendor's name element. The policy-change alert uses `role="alert"`, and a restriction note is
 an `output` element linked to its switch through `aria-describedby`. The
 root's `dir` attribute follows the active language.
 
@@ -122,7 +151,8 @@ Every part is available as `ConsentWidget.<Part>`. `Root` provides the
 draft and accepts `noStyle`, `disableAnimation` and `uiSource`. `Accordion`
 and `AccordionItems` render the stock rows; `AccordionItem`,
 `AccordionTrigger`, `AccordionTriggerInner`, `AccordionContent`,
-`AccordionArrow` and `Switch` build your own. `PolicyActions` renders the
+`AccordionArrow` and `Switch` build your own; `VendorList` renders one
+category's vendor rows and takes a `category` prop. `PolicyActions` renders the
 resolved actions in `Footer` and `FooterSubGroup` and accepts `renderAction`
 to replace one button; `AcceptAllButton`, `RejectButton`, `SaveButton` and
 `CustomizeButton` are the individual buttons.
@@ -155,8 +185,11 @@ export function PreferenceCenter() {
 Provider component slots for the stock structure are `manager.root`,
 `manager.footer`, `manager.actionGroup`, `accordion.root`,
 `accordion.triggerRow`, `accordion.title`, `accordion.control`,
-`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`
-and `tag.manager`.
+`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`,
+`vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`,
+`vendor-list.item`, `vendor-list.header`,
+`vendor-list.name`, `vendor-list.description`, `vendor-list.link`,
+`vendor-list.control` and `tag.manager`.
 
 The compound parts import from `c15t/react` as properties of `ConsentWidget`.
 See [Styling](../styling/overview.md) for slots and tokens.

package/docs/frameworks/react/concepts/consent-categories.md

@@ -17,8 +17,23 @@ group: frameworks
 
 `necessary` is always permitted. Assign categories based on what an integration
 does in your application; renaming analytics to necessary does not change its
-purpose. The provider's displayed categories and the resolved policy scope must
-agree.
+purpose.
+
+c15t discovers categories from registered scripts, network rules, React `ConsentGate`
+components, and iframes with `data-category` handled by the iframe blocker.
+The browser client also discovers inert scripts tagged with `data-c15t-category`.
+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.
+
+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
+script or unmounting a frame does not remove its category or erase consent.
+Discovery does not grant consent or change backend permission restrictions.
 
 ## Respect policy scope
 
@@ -28,6 +43,20 @@ only some optional categories, set `scopeMode` explicitly. An omitted scope,
 `['*']`, or a list containing only `necessary` expands to the default optional
 categories; a necessary-only list is not a shortcut for disabling all tracking.
 
+For example, a backend rule with `categories: ['necessary']` and scripts assigned
+to `marketing` and `measurement` displays Necessary, Marketing, and Analytics,
+even without `consentCategories`. Accept All records both optional choices and
+keeps the banner dismissed after reload. An explicit list of
+`['necessary', 'measurement']` with no other integrations displays Necessary and
+Analytics.
+
+Hidden optional categories do not need a choice to dismiss the banner. Their
+permissions still follow the backend policy, so hidden opt-in categories remain
+denied without a valid grant. React providers enable DOM iframe blocking and
+discovery by default; set `iframeBlocker: false` to disable it, or
+`iframeBlocker: { disableAutomaticBlocking: true }` to scan manually with
+`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.

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

@@ -53,3 +53,11 @@ Use [custom integrations](../../integrations/building-integrations.md) for an
 unlisted vendor and [verification](../../guides/verify-consent.md) for the network
 checks. Google helpers have a separate
 [Consent Mode contract](../../integrations/google-tag-manager.md).
+
+## Clear stored tracking data
+
+Script gating does not remove cookies or Web Storage entries that a script
+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.

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

@@ -37,6 +37,16 @@ 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';
 

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                                              |

package/docs/integrations/building-integrations.md

@@ -31,6 +31,11 @@ Replace the example URL and implement the vendor's initialization. This is a
 loader template, not a functioning analytics SDK. The script stays blocked
 while measurement permission is denied.
 
+Add `vendor: 'example-analytics'` and declare the vendor in the runtime's
+`vendors` option or in the backend manifest when visitors should be able to
+turn this vendor off inside a granted category. See
+[granular consent](./granular-consent.md).
+
 ## Define revocation deliberately
 
 `onConsentChange` receives current permission information. Use it to update the

package/docs/integrations/clear-on-revocation.md

@@ -0,0 +1,167 @@
+---
+title: Clear on revocation
+description: Remove configured first-party cookies and Web Storage keys when
+  their consent category is denied.
+group: integrations
+---
+
+## Configure cleanup
+
+Add `clearOnRevocation` to your provider or runtime options. Declare only the
+data owned by each optional category:
+
+```ts
+import { hosted, type ClearOnRevocationConfig } from 'c15t';
+import { createConsentRuntime } from 'c15t/runtime';
+
+const clearOnRevocation = {
+	measurement: {
+		cookies: ['_ga', '_ga_*'],
+		localStorage: ['analytics:*'],
+	},
+	marketing: {
+		cookies: ['_fbp'],
+		sessionStorage: ['campaign-id'],
+	},
+} satisfies ClearOnRevocationConfig;
+
+const runtime = createConsentRuntime({
+	mode: hosted({ url: '/api/c15t' }),
+	clearOnRevocation,
+});
+
+// Start in the browser after mount. The endpoint must serve your c15t backend.
+runtime.start();
+
+// Call runtime.dispose() when the app no longer needs consent management.
+```
+
+For React, pass the same configuration through `ConsentProvider.options`:
+
+```tsx
+import type { ReactNode } from 'react';
+import { ConsentProvider, hosted } from 'c15t/react';
+
+const mode = hosted({ url: '/api/c15t' });
+
+export function Consent({ children }: { children: ReactNode }) {
+	return (
+		<ConsentProvider
+			options={{
+				mode,
+				clearOnRevocation: {
+					measurement: { cookies: ['_ga', '_ga_*'] },
+				},
+			}}
+		>
+			{children}
+		</ConsentProvider>
+	);
+}
+```
+
+The same option is available in Next.js and TanStack Start `ConsentRoot` props, Vue and
+Nuxt configuration, Svelte providers, and Astro integration options. Solid and
+other headless integrations can use `createConsentRuntime` as shown above.
+Every adapter uses the same cleanup module.
+
+Omitting `clearOnRevocation` leaves cleanup disabled. The provider option is
+initial-only. Remount the provider to replace its cleanup configuration. For
+a shared runtime, configure the runtime owner rather than a borrowing provider.
+
+## Matching names and cookie scopes
+
+Use an exact string or a nonempty prefix followed by `*`. `_ga_*` matches
+`_ga_ABC123`; it does not match `_ga`. Regular expressions, wildcards in other
+positions, and a bare `*` are unsupported. Web Storage keys may contain spaces,
+Unicode, and punctuation. Cookie names use their raw spelling, without URL
+decoding.
+
+Cookies can share a name while having different domains or paths. Cleanup
+tries the current host and its parent domains, and the current path and its
+ancestors. To target a specific scope, use an object:
+
+```ts
+const clearOnRevocation = {
+	measurement: {
+		cookies: [
+			{ name: 'analytics-id', domain: 'example.com', path: '/' },
+			{ name: 'checkout-metrics', domain: '', path: '/checkout' },
+			{ name: 'partitioned-metrics', partitioned: true },
+		],
+	},
+};
+```
+
+An empty `domain` means host-only. Explicit domains and paths replace the
+automatic attempts for that field. Exact names can be deleted at a configured
+path even when the current page cannot read that cookie. Prefix matching can
+only discover cookie names visible to the current page, so use an exact name
+for a cookie on another path.
+
+Partitioned cookies require `partitioned: true`; ordinary targets remove
+unpartitioned cookies. Cookie deletion preserves the browser's `__Secure-`
+and `__Host-` prefix requirements. c15t protects its own consent, notice,
+privacy, pending-save, and IAB consent records in cookies and localStorage,
+including configured custom storage keys, even if your patterns match them.
+c15t does not store consent in sessionStorage, so targeted entries there are
+removed even when their names match consent storage keys.
+
+## When cleanup runs
+
+The runtime attaches cleanup after persistence and the script loader. Cleanup
+waits while the policy is pending. On the first settled snapshot, it removes
+configured data for every denied category. This includes a new opt-in visitor
+who has not made a choice and a returning visitor whose permission expired.
+
+After that first pass, cleanup runs when a category changes from allowed to
+denied. Saving a refusal, expiry, a policy change, Global Privacy Control,
+or synchronized records can cause that transition. Under an opt-out policy,
+an expired grant that remains effectively allowed does not trigger deletion.
+The `necessary` category cannot be configured for cleanup.
+
+Cleanup keeps waiting if a failed initial request leaves the policy pending.
+If a previously settled policy falls back to denial after an initialization
+failure, cleanup removes its configured data. A later successful retry cannot
+restore deleted data.
+
+Runtime construction, server rendering, draft checkbox edits, opening the
+dialog, and disposal do not clear data. Cleanup does not poll storage or repeat
+on unrelated UI updates.
+
+## Use an existing kernel
+
+For a manually assembled integration, attach the module in the browser after
+persistence hydration and script-loader setup:
+
+```ts
+import { createClearOnRevocation } from 'c15t/modules/clear-on-revocation';
+
+const cleanup = createClearOnRevocation({
+	kernel,
+	config: { measurement: { cookies: ['_ga', '_ga_*'] } },
+	storageConfig,
+});
+
+// Stop observing consent when this integration is torn down.
+cleanup.dispose();
+```
+
+Here `kernel` is your existing consent kernel. Pass the same `storageConfig`
+used by persistence so cleanup protects custom record keys. Attaching the
+module can immediately clear denied categories if the policy is already
+settled. Do not also attach it when your provider or runtime owns cleanup.
+
+## Browser limits
+
+Cleanup can remove JavaScript-accessible first-party cookies and keys in the
+current origin's `localStorage` and `sessionStorage`. It cannot remove
+`HttpOnly` cookies or another origin's data. Keep `HttpOnly` protections and
+use your server to expire cookies that require server access. Cookie deletion
+must match the cookie's scope. See the
+[browser cookie documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).
+
+Browser restrictions can prevent reads or deletions. Cleanup failures do not
+block consent updates. A running SDK may write data again after a sweep, so
+keep script gating and the integration's consent-change or teardown behavior
+configured. Deleting a script element cannot undo JavaScript it already ran.