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

package/docs/frameworks/react/{iab/overview.md → iab.md}

@@ -11,6 +11,12 @@ Use the IAB integration when your application needs the Transparency and Consent
 Framework. Configure an IAB policy, the correct CMP identity and vendor data for
 your deployment. A demo CMP ID is not a production configuration.
 
+A CMP ID is assigned to a company when it registers as a CMP with IAB Europe
+([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
+String names the CMP that wrote it, so an ID you did not register attributes
+your users' consent records to someone else. Omitting it leaves the add-on
+unmounted: no `__tcfapi`, and no TC String written.
+
 Install `@c15t/iab` alongside your framework adapter, then mount the IAB
 components inside an existing consent provider connected to Inth.
 
@@ -21,15 +27,19 @@ stylesheet holds only the IAB rules and uses the tokens from the base
 stylesheet.
 
 ```tsx title="src/iab-consent.tsx"
-import { IABProvider, IABConsentBanner, IABConsentDialog } from 'c15t/react/iab';
+import {
+	IABProvider,
+	IABConsentBanner,
+	IABConsentDialog,
+} from 'c15t/react/iab';
 
 export function IABConsent({ cmpId }: { cmpId: number }) {
-  return (
-    <IABProvider cmpId={cmpId}>
-      <IABConsentBanner />
-      <IABConsentDialog />
-    </IABProvider>
-  );
+	return (
+		<IABProvider cmpId={cmpId}>
+			<IABConsentBanner />
+			<IABConsentDialog />
+		</IABProvider>
+	);
 }
 ```
 
@@ -44,7 +54,7 @@ Global Vendor List response before changing rendering conditions.
 
 IAB presentation follows `presentation.prompt.blocking` and
 `presentation.preferences.blocking`. A blocking dialog needs focus management,
-scroll locking and a backdrop together. See [migration](../../../upgrade-v3.md) for
+scroll locking and a backdrop together. See [migration](../../upgrade-v3.md) for
 legacy option behavior.
 
 ## Verify vendor and purpose choices
@@ -62,22 +72,26 @@ placeholders; use vendors from your list whose declarations allow each
 restriction.
 
 ```tsx title="src/iab-consent.tsx"
-import { IABProvider, IABConsentBanner, IABConsentDialog } from 'c15t/react/iab';
+import {
+	IABProvider,
+	IABConsentBanner,
+	IABConsentDialog,
+} from 'c15t/react/iab';
 
 const publisherRestrictions = [
-  // Vendors 10 and 755 may not use purpose 4.
-  { purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
-  // Vendor 755 must use legitimate interest for purpose 7.
-  { purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
+	// Vendors 10 and 755 may not use purpose 4.
+	{ purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
+	// Vendor 755 must use legitimate interest for purpose 7.
+	{ purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
 ];
 
 export function IABConsent({ cmpId }: { cmpId: number }) {
-  return (
-    <IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
-      <IABConsentBanner />
-      <IABConsentDialog />
-    </IABProvider>
-  );
+	return (
+		<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
+			<IABConsentBanner />
+			<IABConsentDialog />
+		</IABProvider>
+	);
 }
 ```
 
@@ -90,8 +104,9 @@ Each restriction type has a requirement that depends on the vendor list:
 | `2`               | Legitimate interest required           | declares the purpose for consent and lists it in `flexiblePurposes`             |
 
 Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
-only with consent. Restrictions also require a service-specific CMP, the
-default. Setting `isServiceSpecific: false` with restrictions is an error.
+only with consent. TCF allows restrictions only in service-specific TC strings.
+c15t always writes those, so the deprecated `isServiceSpecific` option has no
+effect on restrictions.
 c15t copies the restrictions when the CMP starts, so changing your array
 afterwards has no effect.
 
@@ -140,7 +155,7 @@ objection control is the opt-out. Such a purpose does not decide its c15t
 category: the category follows the purposes in it that the visitor can
 consent to. Legitimate interest never grants a category on its own. If none of
 a category's purposes has a consent basis, the category needs all of them
-consented, which only Accept all does. Stack switches
+consented, which only Accept All does. Stack switches
 cover only the purposes some vendor processes on consent. Display-model rows
 expose this as `hasConsentBasis`. Custom preference UIs can call
 `applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
@@ -162,12 +177,46 @@ Types `1` and `2` block the target when the vendor list does not mark the
 purpose as flexible for that vendor. Targets without a `vendorId` ignore
 restrictions. A target that uses only legitimate interest once restrictions
 apply is not blocked by a refused category, since it needs no consent; its
-legitimate interest signals and the visitor's objection decide. GPC, opt-out
-directives and strict scope still block it, and the category stays refused for
-scripts that depend on it. Accept all grants the vendor signal a restriction
-moves a purpose to, including legitimate interest for a vendor that declares
-none. Legitimate interest a restriction introduces applies until the visitor
-objects: the preference centres show it as allowed, and saving without touching
-it encodes it as allowed. `introducedLegitimateInterest` from
-`@c15t/iab/headless` lists those purposes and vendors for custom preference
-UIs.
+legitimate interest signals and the visitor's objection decide. GPC and strict
+scope still block it, and the category stays refused for scripts that depend on
+it. Accept All grants the vendor signal a restriction moves a purpose to,
+including legitimate interest for a vendor that declares none. Legitimate
+interest a restriction introduces applies until the visitor objects: the
+preference centres show it as allowed, and saving without touching it encodes
+it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
+those purposes and vendors for custom preference UIs.
+
+## How the preference centre shows features
+
+The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
+script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
+locked section with a lock icon, because the visitor cannot object to them.
+
+Features get their own section after the special purposes. It shows the IAB
+standard text for features from the Global Vendor List's
+`standardTexts.features`. If the list has no standard text, it shows the
+`iab.preferenceCenter.features.description` translation. Each feature lists
+its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
+TCF forbids showing features next to a control that cannot be disabled.
+
+The feature section follows the theme's spacing and typography tokens.
+Its disclosure arrows are decorative and stay out of the accessibility tree.
+
+A custom preference UI gets the same rows from
+`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
+the special purposes only. `featureRows` holds the features, with
+`locked: false` and `toggle: 'none'`, so render them without a control.
+`featuresStandardText` is the standard text, or `null` when you should use the
+translation.
+
+## Consent scope
+
+c15t stores TCF choices per site and browser, which the TCF calls
+service-specific scope. It does not sync TC strings across devices, and every
+TC string it writes has `IsServiceSpecific` set to `1`.
+
+Do not use `/consent/check` or your own account data to skip the TCF banner on
+another device. That turns the choice into multi-device scope, which the TCF
+requires you to disclose in the first layer, and c15t does not show that
+disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
+logs a warning when you pass `false`.

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

@@ -1,50 +1,42 @@
 ---
-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.
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls in a React app until their
+  consent category is allowed, with networkBlocker rules in the ConsentProvider
+  options.
 group: frameworks
 ---
 
-## Add rules to the provider
+## Add rules
 
-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.
+Some SDKs are already on the page and send beacons or API calls of their own.
+Add `networkBlocker` rules to the provider options to stop `fetch` and
+`XMLHttpRequest` calls to those domains until the category is allowed. Load
+vendor SDKs through [`scripts`](./scripts.md) first, so they
+do not run at all before consent.
 
-Add `networkBlocker` to the `ConsentProvider` options from your
-[quickstart](./quickstart.md). Set the URL to the endpoint
-supplied by your Inth project.
+This partial example adds the option next to the existing `mode` and
+`scripts`:
 
-```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' });
+```tsx title="src/consent.tsx"
 const networkBlocker = {
-  rules: [
-    { id: 'google-analytics', domain: 'google-analytics.com', category: 'measurement' },
-    { id: 'meta-pixel', domain: 'facebook.com', pathIncludes: '/tr', category: 'marketing' },
-  ],
+	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>
-  );
-}
+<ConsentProvider options={{ mode, scripts, networkBlocker }}>
 ```
 
-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
@@ -137,10 +129,12 @@ Keep tracking calls out of that window:
 * 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
+## Verify the blocked requests
+
+Open DevTools Network in a private window, under a policy that asks for
+consent.
 
-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.
+1. Before a choice, requests matching a rule are absent, and the console logs
+   each blocked request.
+2. Allow the rule's category and save. Matching requests go out.
+3. Reject, reload, and check that they stay absent.

package/docs/frameworks/react/quickstart.md

@@ -1,143 +1,181 @@
 ---
 title: Quickstart
-description: Connect a React application to Inth and add consent UI, persistence
-  and a preferences link.
+description: Add a consent banner, preferences dialog and consent-gated scripts
+  to a React single-page app built with Vite, using Inth as the consent backend.
 group: frameworks
 ---
 
-## Connect Inth
+## Before you start
 
-[Create an Inth project](https://inth.com), configure policy rules and the app's
-allowed origin, and copy its backend endpoint. This guide uses a client-rendered
-React app with Vite. Applications with a framework server should use that
-framework's adapter for request prefetch.
+This guide sets up a client-rendered React app built with Vite. The browser
+loads the page, asks the consent backend for the visitor's policy, then shows
+the banner or runs the scripts the visitor allowed.
 
-| Package manager | Command                          |
-| :-------------- | :------------------------------- |
-| npm             | `npm install c15t @c15t/scripts` |
-| pnpm            | `pnpm add c15t @c15t/scripts`    |
-| yarn            | `yarn add c15t @c15t/scripts`    |
-| bun             | `bun add c15t @c15t/scripts`     |
+* **Next.js or TanStack Start?** Use that framework's guide from the
+  [framework list](https://c15t.com/docs/frameworks). Their adapters resolve consent on the
+  server.
+* **React Router framework mode, Remix or another server-rendered React app?**
+  This guide still works. The server renders the page without consent state and
+  the browser resolves it after hydration. Read
+  [rendering](./rendering.md#react-router-remix-and-other-server-rendered-apps)
+  for what that means for the first paint.
 
-Set `VITE_C15T_BACKEND_URL` to the endpoint from Inth. Vite embeds public values
-at build time, so rebuild when changing it. Keep management credentials out of
-public variables.
+You need an [Inth](https://inth.com) project. In the project, set the policy
+rules for your regions, add your site's origin to the trusted origins, and copy
+the backend URL.
+[Choose your setup](../../concepts/choose-your-setup.md#decide-who-runs-the-consent-backend)
+covers self-hosting and offline mode.
 
-## Register consent-gated scripts
+## Install c15t
 
-Include measurement and marketing categories in your policy for these vendors.
-Remove any existing loaders for them so each script loads once.
+| Package manager | Command                                           |
+| :-------------- | :------------------------------------------------ |
+| npm             | `npm install c15t@alpha @c15t/integrations@alpha` |
+| pnpm            | `pnpm add c15t@alpha @c15t/integrations@alpha`    |
+| yarn            | `yarn add c15t@alpha @c15t/integrations@alpha`    |
+| bun             | `bun add c15t@alpha @c15t/integrations@alpha`     |
 
-This setup uses Vite's public environment variables. Set the Inth endpoint and
-add your PostHog project key, PostHog API host and X Pixel ID in `.env.local`:
+`c15t` contains the React adapter at `c15t/react`. `@c15t/integrations` holds the
+vendor loaders used below.
 
-```dotenv title=".env.local"
-VITE_C15T_BACKEND_URL=
-VITE_POSTHOG_KEY=
-VITE_POSTHOG_HOST=
-VITE_X_PIXEL_ID=
-```
-
-Copy the exact backend endpoint from Inth. The vendor IDs are optional: leaving
-an ID empty disables that integration. When enabling PostHog, fill in both its project key and the API host
-shown in your PostHog project. Restart Vite after editing these values and
-rebuild for deployment. Other bundlers need their own configuration mechanism.
+## Register your vendor scripts
 
-Create `src/scripts.ts`. PostHog waits for measurement permission with
-`loadMode: 'after-consent'` and disables cookieless capture with
-`cookieless_mode: 'never'`. X Pixel waits for marketing permission.
+Create `src/scripts.ts`. PostHog waits for measurement permission and X Pixel
+waits for marketing permission, so your policy must include both categories.
+Remove any other PostHog or X Pixel loader from your app so each vendor loads
+once.
 
 ```ts title="src/scripts.ts"
-import { posthog } from '@c15t/scripts/posthog';
-import { xPixel } from '@c15t/scripts/x-pixel';
-
-const posthogKey = import.meta.env.VITE_POSTHOG_KEY;
-const xPixelId = import.meta.env.VITE_X_PIXEL_ID;
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
 
 export const scripts = [
-	...(posthogKey
-		? [
-				posthog({
-					apiHost: import.meta.env.VITE_POSTHOG_HOST,
-					id: posthogKey,
-					initOptions: { cookieless_mode: 'never' },
-					loadMode: 'after-consent',
-				}),
-			]
-		: []),
-	...(xPixelId ? [xPixel({ pixelId: xPixelId })] : []),
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
 ];
 ```
 
-## Mount the provider and UI
+Replace `phc_your_project_key` with your PostHog project key and
+`your-pixel-id` with your X Pixel ID. PostHog uses its EU host; add
+`region: 'us'` for a US project. Remove the loader for a vendor you don't use.
+
+`loadMode: 'after-consent'` keeps the PostHog SDK off the page until the
+visitor allows measurement. `cookieless_mode: 'never'` turns off PostHog's
+cookieless capture. See [integrations](../../integrations/overview.md) for other
+vendors.
+
+## Mount the provider
+
+Create `src/consent.tsx`. `ConsentProvider` creates the consent runtime and
+loads the scripts. `ConsentBanner` and `ConsentDialog` render when the policy
+asks for them, and `ConsentDialogLink` keeps preferences reachable after the
+banner closes.
 
 ```tsx title="src/consent.tsx"
-import type { ReactNode } from 'react';
 import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentDialogLink,
-  ConsentProvider,
-  hosted,
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentProvider,
+	hosted,
 } from 'c15t/react';
-import 'c15t/react/styles.css';
+import type { ReactNode } from 'react';
+
 import { scripts } from './scripts';
 
-const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
-if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
-const mode = hosted({ url: backendURL });
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, scripts }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <footer><ConsentDialogLink>Privacy settings</ConsentDialogLink></footer>
-    </ConsentProvider>
-  );
-}
+import 'c15t/react/styles.css';
+
+const mode = hosted({ url: 'https://your-project.inth.app' });
+
+export const Consent = ({ children }: { children: ReactNode }) => (
+	<ConsentProvider options={{ mode, scripts }}>
+		{children}
+		<ConsentBanner />
+		<ConsentDialog />
+		<footer>
+			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+		</footer>
+	</ConsentProvider>
+);
 ```
 
+Replace `https://your-project.inth.app` with your project's backend URL,
+exactly as Inth shows it, including any path prefix.
+
+Wrap your app with it in `src/main.tsx`:
+
 ```tsx title="src/main.tsx"
 import { createRoot } from 'react-dom/client';
-import App from './App';
+
+import { App } from './app';
 import { Consent } from './consent';
 
 const root = document.getElementById('root');
-if (!root) throw new Error('Missing #root element');
-createRoot(root).render(<Consent><App /></Consent>);
+if (!root) {
+	throw new Error('Missing #root element');
+}
+createRoot(root).render(
+	<Consent>
+		<App />
+	</Consent>
+);
 ```
 
-Keep `Consent` mounted across navigation. The banner appears when the resolved
-policy requires a prompt; not every region or returning visitor needs one.
-The dialog link keeps preferences reachable after the prompt closes.
+Keep `Consent` mounted for the life of the app. If you use a client-side
+router, render the router inside `Consent` so navigation does not remount the
+provider. The stylesheet import in `src/consent.tsx` styles the banner and
+dialog; import it once.
+
+## Gate your own features
 
-## Gate optional functionality
+Read a category's permission with `useConsent` inside the provider:
 
-```tsx
+```tsx title="src/marketing-banner.tsx"
 import { useConsent } from 'c15t/react';
 
-export function MarketingContent() {
-  return useConsent('marketing') ? <div>Optional marketing content</div> : null;
+export function MarketingBanner() {
+	return useConsent('marketing') ? <aside>Spring sale</aside> : null;
 }
 ```
 
-This controls the rendered component. Move vendor SDKs into the
-[script loader](./script-loader.md) too. An independently
-loaded analytics script does not wait merely because a consent provider exists.
-
-`useConsent` returns effective permission, not proof of an explicit grant.
-Read [consent state](../../guides/consent-state.md) when recording choice events.
-
-## Verify and customize
-
-Reject under an opt-in policy, reload and confirm optional requests stay blocked.
-Reopen preferences, save a different choice and test navigation. Follow
-[verification](../../guides/verify-consent.md), then
-[customization](../../customization/overview.md) to apply your design.
-
-## Run the complete example
-
-Try the [runnable example](https://c15t.com/docs/examples) with PostHog, X Pixel, a consent-gated
-YouTube video and a persistent preferences control. Use it to test rejection, permission changes and reloads.
+`useConsent` returns the permission right now. Under an opt-out policy it can be
+`true` before the visitor has chosen anything. Read
+[how consent works](../../concepts/how-consent-works.md#a-permission-is-not-a-recorded-choice)
+before you record or report choices. For iframes, use
+[`ConsentGate`](./components/consent-gate.md).
+
+## Check that it works
+
+Build and preview the production bundle with `vite build` and `vite preview`,
+then open the site in a private window with DevTools open on the Network tab.
+Test under a policy that asks for a choice, such as an EU opt-in policy.
+
+1. **Before a choice.** The banner shows. There are no requests to
+   `posthog.com` or `static.ads-twitter.com`.
+2. **Reject All.** The banner closes and the vendor requests stay absent.
+3. **Reload.** The banner stays closed and the vendor requests stay absent.
+4. **Privacy settings.** The footer link opens the dialog with **Analytics** (the
+   `measurement` category) and **Marketing** off. Turn on **Analytics** and save. PostHog's `array.js` loads and
+   X Pixel stays absent.
+5. **Turn Analytics off again.** The page reloads and PostHog does not load.
+
+If the banner never appears, check the Network tab for the request to
+`/init` on your backend URL. [Troubleshooting](./troubleshooting.md)
+covers the common causes. [Verify consent](../../guides/verify-consent.md) has the
+full release checklist.
+
+## Next steps
+
+* [Rendering](./rendering.md) for server-rendered React apps and
+  what the first paint contains.
+* [Scripts and embeds](./scripts.md) for more vendors, network
+  blocking and data cleanup.
+* [Customize](./customize.md) for colors, fonts, layout and copy.
+* [Components](./components/consent-provider.md) for
+  every provider option and component prop.
+* The runnable app in `examples/react` of the
+  [c15t repository](https://github.com/c15t/c15t) contains this setup.