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

package/docs/README.md

@@ -25,10 +25,10 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
 - [ConsentDialog](./frameworks/react/components/consent-dialog.md): Open the c15t preference center as a modal ConsentDialog in a React app, wire its triggers and control blocking, focus and policy gating.
 - [ConsentDialogLink](./frameworks/react/components/consent-dialog-link.md): Add a ConsentDialogLink to a React footer so visitors reopen the c15t preference center from your own text link, with asChild and rights data.
 - [ConsentDialogTrigger](./frameworks/react/components/consent-dialog-trigger.md): Floating button and toolbar that reopen the preference center after the first prompt.
+- [ConsentGate](./frameworks/react/components/consent-gate.md): Gate a YouTube or map iframe behind consent with ConsentGate in React, showing a placeholder that opens the preference center until the category is allowed.
 - [ConsentProvider](./frameworks/react/components/consent-manager-provider.md): Configure the v3 consent runtime and share its state with child components.
 - [ConsentWidget](./frameworks/react/components/consent-widget.md): Embed the c15t preference center inline with ConsentWidget on a React privacy page, with draft toggles that record a choice only on Save.
 - [DevTools](./frameworks/react/components/dev-tools.md): A development tool for inspecting consent state, geolocation, loaded scripts, and consent events in real time.
-- [Frame](./frameworks/react/components/frame.md): Gate a YouTube or map iframe behind consent with Frame in React, showing a placeholder that opens the preference center until the category is allowed.
 - [Consent categories](./frameworks/react/concepts/consent-categories.md): Assign optional features to categories and understand how policy scope affects permission.
 - [Policy presets](./frameworks/react/concepts/policy-presets.md): Understand how policy rules affect React prompts, permissions and persistent privacy controls.
 - [Headless](./frameworks/react/headless.md): Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.
@@ -64,12 +64,14 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
 - [Clear on revocation](./integrations/clear-on-revocation.md): Remove configured first-party cookies and Web Storage keys when their consent category is denied.
 - [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
 - [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Cloudflare Zaraz](./integrations/cloudflare-zaraz.md): Synchronize c15t permissions with Zaraz purposes while Cloudflare manages your tools.
 - [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
 - [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
 - [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
 - [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
 - [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
 - [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
+- [Granular consent](./integrations/granular-consent.md): Let visitors grant a category and still turn one vendor off, without adopting IAB TCF.
 - [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
 - [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
 - [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.

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

@@ -93,7 +93,7 @@ it is `dialog`. These set that surface:
 * The Customize button on a `ConsentBanner`, and the "Manage preferences"
   or "Do not sell or share my data" button a notice renders.
 * `ConsentDialogLink` and `ConsentDialogTrigger`.
-* The button in a `Frame` placeholder.
+* The button in a `ConsentGate` placeholder.
 * `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
   from `useHeadlessConsentUI()` on the headless subpath.
 

package/docs/frameworks/react/components/{frame.md → consent-gate.md}

@@ -1,14 +1,14 @@
 ---
-title: Frame
-description: Gate a YouTube or map iframe behind consent with Frame in React,
-  showing a placeholder that opens the preference center until the category is
-  allowed.
+title: ConsentGate
+description: Gate a YouTube or map iframe behind consent with ConsentGate in
+  React, showing a placeholder that opens the preference center until the
+  category is allowed.
 group: frameworks
 ---
 
 ## Gate an embed behind consent
 
-`Frame` mounts its children only while the effective permission for one
+`ConsentGate` mounts its children only while the effective permission for one
 consent category is granted, and shows a placeholder otherwise. Wrap any
 iframe or third-party widget that would set cookies or contact a vendor on
 load. Render it anywhere inside the `ConsentProvider` from your
@@ -16,11 +16,11 @@ load. Render it anywhere inside the `ConsentProvider` from your
 placeholder button opens.
 
 ```tsx title="src/product-video.tsx"
-import { Frame } from 'c15t/react';
+import { ConsentGate } from 'c15t/react';
 
 export function ProductVideo() {
   return (
-    <Frame category="marketing" className="video-frame">
+    <ConsentGate category="marketing" className="video-frame">
       <iframe
         src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
         title="Product tour"
@@ -28,18 +28,18 @@ export function ProductVideo() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: '16 / 9', border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
 `marketing` must be in your policy scope. If you set a non-empty
 `options.consentCategories` list on `ConsentProvider`, include `marketing`
-there too so the preference center can display and save it. `Frame` does
+there too so the preference center can display and save it. `ConsentGate` does
 not add categories to that list.
 
 The placeholder names the category using its title from your translations. Set `className` or `style`
-on `Frame` to reserve the embed's space, so the page does not shift when the
+on `ConsentGate` to reserve the embed's space, so the page does not shift when the
 placeholder is replaced.
 
 ## Props
@@ -51,22 +51,22 @@ placeholder is replaced.
 | `placeholder` | `ReactNode`       | built-in placeholder | Replaces the built-in title and button while the category is not allowed. Falsy values such as `null`, `false`, `0` and an empty string use the built-in placeholder. Pass an empty fragment, `<></>`, to render no placeholder content. |
 
 Other `div` attributes such as `className`, `style` and `ref` apply to the
-wrapper element that stays in the page in both states. `FrameProps` also
+wrapper element that stays in the page in both states. `ConsentGateProps` also
 declares `noStyle` and `theme`, but the component does not apply them yet;
 style the wrapper with `className` and theme the placeholder through the
 provider `theme` option.
 
 ## Behavior
 
-`Frame` renders a `div` wrapper. Inside it, when the effective permission for
+`ConsentGate` renders a `div` wrapper. Inside it, when the effective permission for
 `category` is granted, it renders the children; otherwise it renders the
 placeholder. Permission is the same value `useConsent(category)` returns,
 so it can be granted under an opt-out rule before the visitor records a
 choice, and a recorded grant can be overridden by a privacy signal.
 
 While effective permission is denied, the children are absent from the DOM,
-so an iframe or a third-party widget inside `Frame` sends no requests. When the visitor later revokes it, the
-children unmount and the embed disappears. `Frame` does not depend on the
+so an iframe or a third-party widget inside `ConsentGate` sends no requests. When the visitor later revokes it, the
+children unmount and the embed disappears. `ConsentGate` does not depend on the
 network blocker or the iframe blocker modules; use those for markup you
 cannot wrap in a component.
 
@@ -89,13 +89,13 @@ A grant in the request cookie allows the embed only when policy and privacy
 signals permit it. Browser privacy signals detected during hydration can
 withdraw that permission. In a browser-only setup the
 provider has no permission until it resolves policy on the client, so
-`Frame` shows the placeholder first and swaps in the embed after resolution
+`ConsentGate` shows the placeholder first and swaps in the embed after resolution
 when the category is already granted.
 
-`Frame` is one component on this page; the per-vendor embed guides for
+`ConsentGate` is one component on this page; the per-vendor embed guides for
 [YouTube](../../../integrations/youtube.md) and
 [Google Maps](../../../integrations/google-maps.md) show a complete embed
-configuration with sizing, titles and the same `Frame` usage across
+configuration with sizing, titles and the same `ConsentGate` usage across
 frameworks.
 
 To read the same permission in your own components, use `useConsent` from
@@ -104,24 +104,24 @@ also import from there.
 
 ## Composition
 
-The placeholder parts are available as `Frame.Root`, `Frame.Title` and
-`Frame.Button` for a custom placeholder that keeps the built-in copy and
-behavior. `Frame.Title` and `Frame.Button` accept `category` and fill in the
+The placeholder parts are available as `ConsentGate.Root`, `ConsentGate.Title` and
+`ConsentGate.Button` for a custom placeholder that keeps the built-in copy and
+behavior. `ConsentGate.Title` and `ConsentGate.Button` accept `category` and fill in the
 translated text; pass children to either to replace it.
 
 ```tsx
-<Frame
+<ConsentGate
   category="marketing"
   placeholder={
-    <Frame.Root>
-      <Frame.Title category="marketing" />
+    <ConsentGate.Root>
+      <ConsentGate.Title category="marketing" />
       <p>The video is also available on our channel.</p>
-      <Frame.Button category="marketing">Choose cookies</Frame.Button>
-    </Frame.Root>
+      <ConsentGate.Button category="marketing">Choose cookies</ConsentGate.Button>
+    </ConsentGate.Root>
   }
 >
   <iframe src="https://www.youtube-nocookie.com/embed/..." title="Product tour" />
-</Frame>
+</ConsentGate>
 ```
 
 The built-in placeholder carries `data-testid="frame-placeholder"` and its
@@ -131,7 +131,7 @@ button `data-testid="frame-open-dialog"`.
 
 The placeholder is plain text and a `button`, so it is readable and
 operable without the embed. Give the iframe a descriptive `title`, and keep a
-transcript, address or link outside the `Frame` for visitors who decline
+transcript, address or link outside the `ConsentGate` for visitors who decline
 the category. A denied category may be fixed by policy, so opening the
 preference center does not guarantee that the visitor can grant it.
 

package/docs/frameworks/react/components/consent-manager-provider.md

@@ -58,7 +58,11 @@ signals. Hydration and notice dismissal do not become explicit choices.
 
 An externally owned runtime can be passed through `runtime`. Its owner must
 start and dispose it. A provider borrowing that runtime must not initialize or
-dispose a second copy. See [consent state](../../../guides/consent-state.md) and
+dispose a second copy. Keep the runtime stable for the provider's lifetime and
+unmount the borrowing provider when disposing the runtime. IAB actions taken
+before its handle is ready wait for that handle. If the provider unmounts first,
+a pending `save()` rejects with an `AbortError` instead of waiting indefinitely.
+See [consent state](../../../guides/consent-state.md) and
 [deployment modes](../../../guides/deployment-modes.md).
 
 ## Clear data when consent is denied

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/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