@c15t/react 2.2.1 → 2.3.0

package/docs/integrations/pinterest-tag.md

@@ -0,0 +1,236 @@
+---
+title: Pinterest Tag
+description: Track conversions and build audiences for Pinterest advertising campaigns.
+icon: pinterest
+group: integrations
+---
+Pinterest Tag is Pinterest's conversion tracking and audience building tool. It measures the actions people take on your site after seeing your Pins, so you can attribute conversions and build retargeting audiences for Pinterest Ads.
+
+## Official Pinterest documentation
+
+* [Install the Pinterest Tag (Pinterest Business Help)](https://help.pinterest.com/en/business/article/install-the-pinterest-tag)
+* [Pinterest Tag event codes](https://help.pinterest.com/en/business/article/add-event-codes)
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { pinterestTag } from '@c15t/scripts/pinterest-tag';
+
+const scripts = [pinterestTag({ tagId: '2613654212508' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { pinterestTag } from '@c15t/scripts/pinterest-tag';
+
+const scripts = [pinterestTag({ tagId: '2613654212508' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { pinterestTag } from '@c15t/scripts/pinterest-tag';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [pinterestTag({ tagId: '2613654212508' })],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `marketing` (Ads & Pixels)
+* **Loads when:** marketing consent is granted
+* **On revocation:** [persists](/docs/frameworks/react/script-loader#persist-after-revocation) — c15t calls `pintrk('setconsent', false)`, which stops Pinterest from sending events and clears its first-party cookies without removing the script
+
+Before the loader runs, c15t recreates Pinterest's base code: it defines the `pintrk` queue stub with `version = "3.0"`, then queues `pintrk('load', tagId)`, `pintrk('setconsent', true)`, and `pintrk('page')`. Pinterest's `core.js` replays the queue once it loads.
+
+## Configure the integration
+
+You can pass extra load options and disable the default page-visit event when you need finer control:
+
+```ts
+pinterestTag({
+  tagId: '2613654212508',
+  loadOptions: {
+    em: 'hello@example.com',
+  },
+  trackPageVisit: false,
+});
+```
+
+`loadOptions` is forwarded as the third argument to `pintrk('load', tagId, loadOptions)`. Pinterest uses `em` (email) and `external_id` for enhanced match, and hashes plain values before sending them.
+
+> ⚠️ **Warning:**
+> Enhanced match values are personal data. Only pass em or external\_id when your application has separately obtained consent to share them with Pinterest — marketing consent alone does not cover this.
+
+## Tracking events in your app
+
+c15t gates the Pinterest Tag from loading until `marketing` consent is granted. After consent is granted the script stays in the DOM, and c15t calls `pintrk('setconsent', false)` if consent is later revoked, so Pinterest itself suppresses events.
+
+This means `window.pintrk` is only defined after the user has granted marketing consent at least once. Use `pinterestTagEvent()` for typed standard and custom events — it's a no-op until `pintrk` exists, so it's safe to call before consent, and it doesn't bypass consent afterwards. Guarding with `has('marketing')` is still good practice so you don't queue events Pinterest will drop:
+
+```tsx
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+import { pinterestTagEvent } from '@c15t/scripts/pinterest-tag';
+
+function useTrackCheckout() {
+  const { has } = useConsentManager();
+  return useCallback(() => {
+    if (has('marketing')) {
+      pinterestTagEvent('checkout', {
+        event_id: 'eventId0001',
+        value: 99.99,
+        order_quantity: 1,
+        currency: 'USD',
+        order_id: 'X-15148',
+        line_items: [
+          {
+            product_name: 'Parker Boots',
+            product_id: '1414',
+            product_category: 'Shoes',
+            product_price: 99.99,
+            product_quantity: 1,
+          },
+        ],
+      });
+    }
+  }, [has]);
+}
+
+function CheckoutButton() {
+  const trackCheckout = useTrackCheckout();
+  return <button onClick={trackCheckout}>Complete checkout</button>;
+}
+```
+
+From plain JavaScript:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { pinterestTagEvent } from '@c15t/scripts/pinterest-tag';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('marketing')) {
+  pinterestTagEvent('lead', { lead_type: 'newsletter' });
+}
+```
+
+Pass `event_id` when you also send the same event through the Pinterest Conversions API so Pinterest can deduplicate the two. Product details (`product_name`, `product_id`, `product_price`, and so on) go inside `line_items`, one entry per product — Pinterest ignores them at the top level.
+
+### Event names
+
+Pinterest recognises 20 event types for conversion tracking: `checkout`, `addtocart`, `pagevisit`, `signup`, `watchvideo`, `lead`, `search`, `viewcategory`, `custom`, `addpaymentinfo`, `addtowishlist`, `initiatecheckout`, `subscribe`, `viewcontent`, `contact`, `schedule`, `findlocation`, `customizeproduct`, `submitapplication`, and `starttrial`. `pinterestTagEvent()` also accepts any other string as a user-defined event, which Pinterest uses for audience targeting only — it logs a console warning for these.
+
+Which events you need depends on the campaign type. Conversions campaigns require at least one of `signup`, `lead`, `addtocart`, or `checkout`; catalog sales, conversion insights, dynamic retargeting, and the Verified Merchant Program all require `pagevisit`, `addtocart`, and `checkout` with `currency` set. See [Add event codes](https://help.pinterest.com/en/business/article/add-event-codes) for the full matrix.
+
+### Debugging with a callback
+
+Pinterest accepts an optional `(didInit, error)` callback after the event data. Pass it as the third argument to `pinterestTagEvent()` to surface tag errors during development:
+
+```ts
+import { pinterestTagEvent } from '@c15t/scripts/pinterest-tag';
+
+pinterestTagEvent('lead', { lead_type: 'Newsletter' }, (didInit, error) => {
+  if (!didInit) {
+    console.error('Pinterest Tag error:', error);
+  }
+});
+```
+
+## Types
+
+### PinterestTagOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagOptions" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagLoadOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagLoadOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagLoadOptions" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagEventData
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagEventData\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagEventData" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagLineItem
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagLineItem\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagLineItem" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagEventCallback
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagEventCallback\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagEventCallback" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/concepts/client-modes.md

@@ -5,7 +5,7 @@ group: reference
 ---
 c15t supports three client modes that determine how consent data is stored and synchronized. Choose the mode that matches your infrastructure:
 
-* **Hosted mode** - Recommended for production. Backend-backed consent with geolocation, centralized policy resolution, audit history, and offline fallback.
+* **Hosted mode** - Recommended for production. Backend-backed consent with geolocation, centralized policy resolution, audit history, and a temporary fallback when the backend is unreachable.
 * **Offline mode** - Browser-only storage with no network requests. Best for local development, demos, static deployments, or controlled fallback scenarios.
 * **Custom mode** - Bring your own backend with custom endpoint handlers
 
@@ -25,7 +25,9 @@ The default mode. Connects to a c15t backend for full consent lifecycle manageme
 
 1. On page load, the client calls `/init` to fetch geolocation, jurisdiction, localized translation strings
 2. When the user grants or changes consent, it is saved locally before being synced to the backend.
-3. If the backend is unreachable, it falls back to Offline mode and re-syncs with the backend when it's available
+3. If `/init` fails after retries, c15t uses a temporary opt-in fallback. Optional categories are denied during fallback, while the saved choice and its hosted policy fingerprint remain in browser storage.
+
+A saved rejection survives an outage and recovery, including recovery to an opt-out or no-banner policy. A rejection saved during fallback also survives recovery. Grants saved during fallback are not sent to the backend and need fresh confirmation under the hosted policy. Previously valid grants can resume on a later load if the original hosted policy returns and the user has not changed their choice.
 
 **Configuration:**
 
@@ -36,7 +38,7 @@ The default mode. Connects to a c15t backend for full consent lifecycle manageme
 * The backend stays the source of truth for policy, translations, and jurisdiction logic
 * Consent decisions can be stored beyond the current browser session for audit and support workflows
 * Server-side systems can preload consent-aware behavior instead of waiting for client-only storage
-* If the backend is temporarily unavailable, c15t can fall back locally and re-sync later
+* If the backend is temporarily unavailable, c15t falls back locally and re-syncs rejections later. Grants made during the outage wait for fresh confirmation.
 
 **Best for:** Production apps that need geolocation-based jurisdiction detection, consent record storage, and compliance audit trails.
 

package/docs/shared/concepts/consent-models.md

@@ -9,7 +9,7 @@ c15t supports four consent models that control how consent defaults, banner visi
 |--|--|--|--|
 |`opt-in`|Explicit consent required|Blocking banner|`false` (except `necessary`)|
 |`opt-out`|Processing allowed by default|Non-blocking notice|`true` (all granted)|
-|`iab`|IAB TCF 2.3 for programmatic ads|TCF banner|Managed by TCF framework|
+|`iab`|IAB TCF 2.4 for programmatic ads|TCF banner|Managed by TCF framework|
 |`null`|No regulation detected|No banner|`true` (all auto-granted)|
 
 There are two ways c15t determines which model applies:
@@ -39,7 +39,7 @@ When the policy has `consent.gpc: true`, the browser's Global Privacy Control si
 
 ### IAB
 
-IAB Transparency and Consent Framework (TCF) 2.3 mode for programmatic advertising compliance. Only activates when two conditions are met: the jurisdiction is `GDPR` or `UK_GDPR`, and `iab.enabled` is `true` in your configuration.
+IAB Transparency and Consent Framework (TCF) 2.4 mode for programmatic advertising compliance. Only activates when two conditions are met: the jurisdiction is `GDPR` or `UK_GDPR`, and `iab.enabled` is `true` in your configuration.
 
 When active, IAB mode generates TC strings, registers the `__tcfapi` CMP API, and works with the Global Vendor List (GVL) for machine-readable consent signals. If `iab.enabled` is not set, GDPR jurisdictions fall back to standard opt-in.
 

package/docs/shared/concepts/cookie-management.md

@@ -14,6 +14,10 @@ There are four sources of cookies on a typical website:
 **1. c15t itself**
 c15t stores the user's consent state in a `c15t` cookie (and mirrors it to localStorage). This cookie records which categories the user consented to, when they consented, and their subject ID. This is a strictly necessary cookie - it exists so the site remembers the user's consent choice.
 
+If reading `window.localStorage` or calling a storage method throws, c15t logs a warning and skips unavailable pending-submission queues. Runtime construction still completes, and cookie-backed choices can still be read and saved. In v2, a failed localStorage access check skips policy initialization and hides the banner. Optional categories without a saved choice remain denied.
+
+If the browser also blocks cookies, it cannot retain your choice across page loads. Do not use `enabled: false` to handle storage restrictions: that option grants every category.
+
 **2. Third-party scripts**
 When you load a tracking script (Google Analytics, Meta Pixel, etc.), that script sets its own cookies. Google Analytics creates `_ga` and `_gid` cookies. Meta creates `_fbp` and `_fbc`. These cookies are set by the script's code running in the browser - c15t prevents them by not loading the script until the user consents.
 

package/docs/shared/concepts/glossary.md

@@ -20,5 +20,5 @@ group: reference
 |--|--|
 |`jurisdiction`|A privacy regulation code (e.g., `GDPR`, `CCPA`, `PIPEDA`, `QC_LAW25`) detected from the user's geolocation. Maps to a consent model. See [Consent Models](/docs/frameworks/react/concepts/consent-models) for the full mapping table.|
 |GPC|Global Privacy Control — a browser signal (`Sec-GPC: 1`) indicating the user opts out of data sale/sharing. Honored when a policy sets `consent.gpc: true` (enabled by default in California presets).|
-|TCF|IAB Transparency and Consent Framework (v2.3) — a standard for programmatic advertising consent in GDPR jurisdictions. See [IAB TCF](/docs/frameworks/react/iab/overview).|
+|TCF|IAB Transparency and Consent Framework (v2.4) — a standard for programmatic advertising consent in GDPR jurisdictions. See [IAB TCF](/docs/frameworks/react/iab/overview).|
 |GVL|Global Vendor List — an IAB-maintained registry of ad-tech vendors and their declared purposes, used by the TCF consent flow.|

package/docs/shared/concepts/initialization-flow.md

@@ -69,9 +69,9 @@ sequenceDiagram
 
 **Init** — The store fetches the resolved policy, location, and translation data. In hosted mode this calls `GET /init` on your backend; in offline mode it resolves from `offlinePolicy.policyPacks` locally. If SSR data was passed to the provider, the network fetch is skipped entirely. See [Server-Side Utilities](/docs/frameworks/react/server-side) for SSR setup.
 
-**Policy resolution** — When [policy packs](/docs/frameworks/react/concepts/policy-packs) are configured, the backend resolves the right policy for the visitor based on their geo-location (region → country → fallback → default). The resolved policy determines the consent model (`opt-in`, `opt-out`, `iab`, or `none`), which categories are in scope, and what UI to show. For `opt-out` and `none` models, all categories are auto-granted — unless the resolved policy has `consent.gpc: true` and the browser sends a Global Privacy Control signal, in which case `marketing` and `measurement` are denied. If no policy pack is configured, the legacy jurisdiction-to-model mapping is used instead. See [Consent Models](/docs/frameworks/react/concepts/consent-models) for details.
+**Policy resolution** — When [policy packs](/docs/frameworks/react/concepts/policy-packs) are configured, the backend resolves the right policy for the visitor based on their geo-location (region → country → fallback → default). The resolved policy determines the consent model (`opt-in`, `opt-out`, `iab`, or `none`), which categories are in scope, and what UI to show. For `opt-out` and `none` models, categories are auto-granted only when there is no saved choice — unless the resolved policy has `consent.gpc: true` and the browser sends a Global Privacy Control signal, in which case `marketing` and `measurement` are denied. If no policy pack is configured, the legacy jurisdiction-to-model mapping is used instead. See [Consent Models](/docs/frameworks/react/concepts/consent-models) for details.
 
-**Re-prompting** — If the resolved policy's material fingerprint differs from the fingerprint stored with the user's last consent, the banner is shown again. This happens automatically when you change consent-affecting fields (model, categories, scope mode, allowed actions). Presentation-only changes do not trigger re-prompts. See [Policy Packs — Re-Prompting](/docs/frameworks/react/concepts/policy-packs#re-prompting) for details.
+**Re-prompting** — If the resolved policy's material fingerprint differs from the fingerprint stored with the user's last consent, previous grants become invalid, while the saved choice and its denials remain. The consent UI opens again when the resolved policy has one; under a no-banner policy, invalidated grants stay denied until the user makes a new choice. This happens automatically when you change consent-affecting fields (model, categories, scope mode, allowed actions). Presentation-only changes do not trigger re-prompts. See [Policy Packs — Re-Prompting](/docs/frameworks/react/concepts/policy-packs#re-prompting) for details.
 
 **Save** — When the user interacts with the banner or dialog, their choices are persisted to localStorage/cookies and synced to the backend (along with the `policySnapshotToken` if snapshot signing is configured). Script, iframe, and network gating rules update immediately based on the new consent state. See the [Script Loader](/docs/frameworks/react/script-loader), [Iframe Blocking](/docs/frameworks/react/iframe-blocking), and [Network Blocker](/docs/frameworks/react/network-blocker) guides for gating details.
 
@@ -85,7 +85,7 @@ The banner appears when any of these conditions are true:
 2. **Policy changed** — the material policy fingerprint differs from the fingerprint stored with the user's last consent (re-prompting)
 3. **Storage is accessible** — the browser allows localStorage (not blocked in private mode)
 
-If the resolved model is `none` or `opt-out` (and `ui.mode` is `none`), consents are auto-granted and the banner never appears. See [Consent Models](/docs/frameworks/react/concepts/consent-models) and [Policy Packs](/docs/frameworks/react/concepts/policy-packs) for details.
+If the resolved model is `none` or `opt-out` (and `ui.mode` is `none`) and no saved choice exists, consents are auto-granted and the banner never appears. An existing saved choice keeps its denials, but grants invalidated by a policy change stay denied until the user makes a new choice. See [Consent Models](/docs/frameworks/react/concepts/consent-models) and [Policy Packs](/docs/frameworks/react/concepts/policy-packs) for details.
 
 ## Debugging the Lifecycle
 

package/docs/shared/concepts/policy-packs.md

@@ -32,7 +32,7 @@ const policies = [
 |Preset|Model|UI|Matches|
 |--|--|--|--|
 |`europeOptIn()`|`opt-in`|banner|EEA + UK countries + geo fallback|
-|`europeIab()`|`iab`|banner|EEA + UK countries + geo fallback (TCF 2.3)|
+|`europeIab()`|`iab`|banner|EEA + UK countries + geo fallback (TCF 2.4)|
 |`californiaOptOut()`|`opt-out`|none|US-CA region|
 |`quebecOptIn()`|`opt-in`|banner|CA-QC region|
 |`worldNoBanner()`|`none`|none|default fallback|
@@ -65,7 +65,7 @@ Each policy combination produces a different consent experience:
 |`model: 'opt-out'`, `ui.mode: 'none'`|No banner, everything loads immediately — user opts out via a "Do Not Sell" link|
 |`model: 'none'`, `ui.mode: 'none'`|No banner, all categories auto-granted silently|
 |`model: 'opt-in'`, `ui.mode: 'dialog'`|Full-screen dialog, nothing loads until the user consents|
-|`model: 'iab'`, `ui.mode: 'banner'`|IAB TCF 2.3 banner with vendor-level controls|
+|`model: 'iab'`, `ui.mode: 'banner'`|IAB TCF 2.4 banner with vendor-level controls|
 
 ## How Policy Resolution Works
 
@@ -176,6 +176,8 @@ back to the `eu` profile's `fallbackLanguage`.
 
 When you change a policy in a way that affects consent semantics — like adding a category, changing the consent model, or modifying allowed actions — c15t automatically re-prompts returning users.
 
+A material policy change invalidates previous grants but keeps the user's choice record and denials. Optional categories stay denied until the user makes a new choice. The resolved policy controls whether a banner or dialog appears; a no-banner policy does not silently grant previously rejected categories. A temporary hosted initialization failure does not count as an authoritative policy change.
+
 This works through the **material policy fingerprint**: a hash of only the consent-affecting fields (model, categories, scope, allowed actions, grouped action layout, direction, proof settings). Presentation-only changes like copy, button styling, or scroll lock do not trigger re-prompts.
 
 |Change|Re-prompts?|

package/docs/shared/react/guides/iframe-blocking.md

@@ -51,6 +51,8 @@ For iframes outside of React (e.g., CMS content, server-rendered HTML), add `dat
 
 When consent for the specified category is granted, c15t automatically swaps `data-src` to `src`, loading the iframe. When consent is revoked, `src` is moved back to `data-src`.
 
+The `data-category` value must be one of `necessary`, `functionality`, `measurement`, `experience`, or `marketing`. An iframe with any other value, including an empty one, stays blocked, and c15t logs a warning to the console.
+
 ### Dynamic Iframes
 
 c15t uses a `MutationObserver` to watch for dynamically added iframes. Any iframe with `data-category` added to the DOM after initialization is automatically processed.

package/docs/shared/react/guides/policy-packs.md

@@ -72,7 +72,7 @@ Available presets:
 |Preset|Model|Matches|
 |--|--|--|
 |`europeOptIn()`|`opt-in`|EEA + UK countries + geo fallback|
-|`europeIab()`|`iab`|EEA + UK countries + geo fallback (TCF 2.3)|
+|`europeIab()`|`iab`|EEA + UK countries + geo fallback (TCF 2.4)|
 |`californiaOptOut()`|`opt-out`|US-CA region|
 |`quebecOptIn()`|`opt-in`|CA-QC region|
 |`worldNoBanner()`|`none`|default fallback|

package/docs/shared/react/hooks/use-consent-manager/overview.md

@@ -70,5 +70,5 @@ type Model = 'opt-in' | 'opt-out' | 'iab' | null;
 
 * `'opt-in'` — Explicit consent required before tracking (GDPR)
 * `'opt-out'` — Tracking allowed by default, user can opt out (CCPA)
-* `'iab'` — IAB TCF 2.3 compliance mode
+* `'iab'` — IAB TCF 2.4 compliance mode
 * `null` — No jurisdiction detected yet

package/docs/shared/react/iab/consent-banner.md

@@ -6,7 +6,7 @@ group: reference
 > ℹ️ **Info:**
 > c15t's IAB TCF support can be used in production. Use Inth for a hosted, IAB TCF-certified CMP setup with a managed CMP ID, or register your own CMP with IAB Europe and configure your own CMP ID.
 
-`IABConsentBanner` is a pre-built consent banner that follows the [IAB Transparency & Consent Framework (TCF) 2.3](https://iabeurope.eu/tcf-2-0/) specification. It renders when the consent model is set to `'iab'` and includes required disclosures like partner count, purpose summaries, and legitimate interest notices.
+`IABConsentBanner` is a pre-built consent banner that follows the [IAB Transparency & Consent Framework (TCF) 2.4](https://iabeurope.eu/tcf-2-0/) specification. It renders when the consent model is set to `'iab'` and includes required disclosures like partner count, purpose summaries, and legitimate interest notices.
 
 Use this component instead of `ConsentBanner` when you need IAB TCF compliance for programmatic advertising in EU jurisdictions.
 

package/docs/shared/react/iab/consent-dialog.md

@@ -6,7 +6,7 @@ group: reference
 > ℹ️ **Info:**
 > c15t's IAB TCF support can be used in production. Use Inth for a hosted, IAB TCF-certified CMP setup with a managed CMP ID, or register your own CMP with IAB Europe and configure your own CMP ID.
 
-`IABConsentDialog` is an IAB TCF 2.3 compliant consent dialog that provides a tabbed interface for managing purpose consent and vendor preferences. It includes purpose grouping via stacks, individual purpose/vendor toggles, special purpose and feature disclosures, and legitimate interest handling.
+`IABConsentDialog` is an IAB TCF 2.4 compliant consent dialog that provides a tabbed interface for managing purpose consent and vendor preferences. It includes purpose grouping via stacks, individual purpose/vendor toggles, special purpose and feature disclosures, and legitimate interest handling.
 
 ## Tabs
 
@@ -19,7 +19,8 @@ Displays all IAB purposes grouped into:
 * **Standalone purposes** — Purpose 1 (Store and/or access information on a device) is always shown standalone per IAB TCF spec
 * **Stacks** — Groups of related purposes determined by the GVL. Each stack is expandable to show individual purpose toggles
 * **Special features** — Opt-in features like precise geolocation
-* **Essential functions** — Special purposes and features that are locked (no user toggle) because they're required for basic operation
+* **Essential functions** — Special purposes, which are locked (no user toggle) because vendors need them for basic operation
+* **Features** — An informational section, shown when at least one vendor declares a feature
 
 Each purpose shows:
 
@@ -29,6 +30,14 @@ Each purpose shows:
 * Legitimate interest toggle where applicable
 * Expandable vendor list
 
+### Features section
+
+TCF Policies v5.0.b treat features as information, not choices. The Features section follows those rules:
+
+* Under the heading, the dialog shows the IAB standard text from the vendor list (`standardTexts.features`). If the vendor list does not include it, the dialog shows the `iab.preferenceCenter.features.description` translation.
+* Each feature shows its name, description, IAB illustrations under **Examples**, and the names of the vendors that use it.
+* The section has no switches, lock icons or per-vendor toggles. Features only serve the purposes the user chooses elsewhere in the dialog.
+
 ### Vendors Tab
 
 Displays all vendors from the GVL plus any custom vendors:

package/docs/shared/react/iab/overview.md

@@ -5,7 +5,7 @@ group: reference
 ---
 ## What is IAB TCF?
 
-The [IAB Transparency & Consent Framework (TCF)](https://iabeurope.eu/tcf-2-0/) is a standardized protocol for communicating user consent choices to ad tech vendors in the programmatic advertising ecosystem. TCF 2.3 is the current version and is widely adopted across the EU/EEA.
+The [IAB Transparency & Consent Framework (TCF)](https://iabeurope.eu/tcf-2-0/) is a standardized protocol for communicating user consent choices to ad tech vendors in the programmatic advertising ecosystem. TCF 2.4 is the current version and is widely adopted across the EU/EEA.
 
 When your site participates in the IAB ecosystem (ad exchanges, SSPs, DSPs, DMPs), you need to:
 
@@ -25,7 +25,7 @@ If you self-host the c15t backend or want to operate as your own CMP, register y
 
 ## How c15t Implements TCF
 
-c15t provides a complete IAB TCF 2.3 CMP (Consent Management Platform) implementation:
+c15t provides a complete IAB TCF 2.4 CMP (Consent Management Platform) implementation:
 
 1. **Global Vendor List (GVL)** — Automatically fetched from the c15t backend. Contains the official IAB vendor registry with purposes, features, and stacks.
 2. **IABConsentBanner** — A pre-built banner showing partner count, purpose summaries, and legitimate interest notices.
@@ -57,7 +57,11 @@ Purposes are grouped into **stacks** by the GVL for a simplified UI presentation
 
 ### Special Features
 
-Features like precise geolocation or device scanning that require explicit opt-in beyond standard consent.
+Features like precise geolocation, or identifying devices based on information actively requested, that require explicit opt-in beyond standard consent.
+
+### Features
+
+Features, such as linking different devices, are means of processing that vendors use only for the purposes the user chooses. They have no consent toggle. The preference center lists them in an informational section with the IAB standard text.
 
 ### Legitimate Interest
 
@@ -67,11 +71,19 @@ Some purposes can be processed under legitimate interest rather than consent. Us
 
 Each vendor in the GVL declares which purposes it uses, whether via consent or legitimate interest. The preference center lets users toggle consent per-vendor.
 
+## Consent Scope
+
+c15t stores TCF choices per site and browser, so every TC string it creates is service-specific. c15t does not sync TCF choices across devices.
+
+Do not use `/consent/check` or your own account data to skip the TCF UI on another device. Reusing choices across devices is a multi-device scope, and the TCF requires you to disclose that scope in the first layer of the UI, which the prebuilt IAB components do not do.
+
+The `isServiceSpecific` option is deprecated. TCF requires IsServiceSpecific=1 in every TC string, so c15t always encodes `true` and logs a warning if you pass `false`.
+
 ## Standard vs IAB Components
 
 |Feature|ConsentBanner / ConsentDialog|IABConsentBanner / IABConsentDialog|
 |--|--|--|
-|Consent model|opt-in / opt-out|IAB TCF 2.3|
+|Consent model|opt-in / opt-out|IAB TCF 2.4|
 |Granularity|Category-level (measurement, marketing, etc.)|Purpose-level + vendor-level|
 |Vendor management|No|Yes (full GVL integration)|
 |TC String|No|Yes|

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/react",
-	"version": "2.2.1",
+	"version": "2.3.0",
 	"description": "React cookie banner, consent manager, preference center, and headless CMP components with IAB TCF and Consent Mode support.",
 	"keywords": [
 		"react",
@@ -163,16 +163,16 @@
 		"not op_mini all"
 	],
 	"dependencies": {
-		"@c15t/ui": "2.2.1",
+		"@c15t/ui": "2.2.2",
 		"@types/google.maps": "3.65.3",
-		"c15t": "2.2.1"
+		"c15t": "2.3.0"
 	},
 	"devDependencies": {
-		"@c15t/backend": "2.2.1",
-		"@c15t/iab": "2.2.1",
+		"@c15t/backend": "2.3.0",
+		"@c15t/iab": "2.3.0",
 		"@c15t/typescript-config": "0.0.1",
 		"@c15t/vitest-config": "1.0.0",
-		"@iabtechlabtcf/core": "^1.5.20",
+		"@iabtechlabtcf/core": "^1.5.22",
 		"genversion": "3.2.0",
 		"msw": "^2.14.6"
 	},

package/readme.json

@@ -8,7 +8,7 @@
 		"Headless hooks for custom consent flows",
 		"Minimal configuration with TypeScript-first design",
 		"Comprehensive Consent Management Platform (CMP)",
-		"IAB TCF 2.3 UI and hooks through the @c15t/react/iab subpath",
+		"IAB TCF 2.4 UI and hooks through the @c15t/react/iab subpath",
 		"Google Tag Manager, Google Consent Mode v2, Meta Pixel, and analytics integrations through @c15t/scripts",
 		"Built-in internationalization support",
 		"Seamless consent storage and tracking"