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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/react",
-	"version": "3.0.0-alpha.3",
+	"version": "3.0.0-alpha.4",
 	"description": "React cookie banner, consent manager, preference center, and headless CMP components with IAB TCF and Consent Mode support.",
 	"keywords": [
 		"ccpa",
@@ -46,6 +46,7 @@
 		"dist",
 		"dist-types",
 		"AGENTS.md",
+		"SKILL.md",
 		"docs",
 		"styles.css",
 		"styles.tw3.css",
@@ -150,6 +151,11 @@
 		"./styles.tw3.css": "./dist/styles.tw3.css",
 		"./iab/styles.css": "./dist/iab/styles.css",
 		"./iab/styles.tw3.css": "./dist/iab/styles.tw3.css",
+		"./postcss-tailwind3": {
+			"types": "./dist-types/postcss-tailwind3.d.ts",
+			"import": "./dist/postcss-tailwind3.js",
+			"default": "./dist/postcss-tailwind3.js"
+		},
 		"./primitives": {
 			"types": "./dist-types/primitives.d.ts",
 			"import": "./dist/primitives.js",
@@ -243,20 +249,20 @@
 		"test:watch": "bun prebuild && vitest"
 	},
 	"dependencies": {
-		"@c15t/core": "3.0.0-alpha.3",
-		"@c15t/dev-tools": "3.0.0-alpha.3",
-		"@c15t/iab": "3.0.0-alpha.3",
-		"@c15t/schema": "3.0.0-alpha.2",
-		"@c15t/translations": "3.0.0-alpha.2",
-		"@c15t/ui": "3.0.0-alpha.3",
+		"@c15t/core": "3.0.0-alpha.4",
+		"@c15t/dev-tools": "3.0.0-alpha.4",
+		"@c15t/iab": "3.0.0-alpha.4",
+		"@c15t/schema": "3.0.0-alpha.3",
+		"@c15t/translations": "3.0.0-alpha.4",
+		"@c15t/ui": "3.0.0-alpha.4",
 		"@types/google.maps": "3.65.3"
 	},
 	"devDependencies": {
-		"@c15t/backend": "3.0.0-alpha.3",
+		"@c15t/backend": "3.0.0-alpha.4",
 		"@c15t/conformance": "0.0.1",
 		"@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",
 		"typescript": "7.0.2"

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

@@ -1,95 +0,0 @@
----
-title: ConsentProvider
-description: Configure the v3 consent runtime and share its state with child components.
-group: frameworks
----
-
-## Mount one provider
-
-```tsx
-import type { ReactNode } from 'react';
-import { ConsentProvider, ConsentBanner, ConsentDialog, ConsentDialogLink, hosted } from 'c15t/react';
-
-const mode = hosted({ url: 'https://your-project.inth.app' });
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-    </ConsentProvider>
-  );
-}
-```
-
-Replace the URL with your Inth project endpoint. Import the adapter stylesheet
-once at the app root. In Next.js this component needs a client boundary; prefer
-the framework's `ConsentRoot` when passing server-resolved state.
-
-## Provider responsibilities
-
-The provider owns initialization, persistence, configured script loading and
-subscriptions. Keep it mounted across client navigation. Its initial mode and
-prefetch configuration belong to the runtime's creation, not a per-render
-mechanism for switching visitors or backends.
-
-| Option                   | Purpose                                                                                                                               |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`                   | Hosted, offline or custom transport factory                                                                                           |
-| `scripts`                | Consent-managed script configurations                                                                                                 |
-| `callbacks`              | Choice, permission and error events                                                                                                   |
-| `theme`, `components`    | Consent-action styles, theme slots and component slot attributes. Tokens render through `ConsentTheme`                                |
-| `presentation`           | Prompt and preferences layout behavior                                                                                                |
-| `preloadDialog`          | When the deferred `ConsentDialog` starts loading: `'idle'` (default) or `'intent'`; see [ConsentDialog](./consent-dialog.md#behavior) |
-| `i18n`                   | Languages and message overrides                                                                                                       |
-| `storageConfig`          | Browser record storage configuration                                                                                                  |
-| `enabled`                | Set false only when intentionally bypassing consent enforcement                                                                       |
-| `reloadOnConsentRevoked` | Reload the page after the visitor turns off a granted category or vendor; defaults to `true`                                          |
-
-`enabled: false` grants categories and allows gated loading while suppressing
-consent UI. It is not a way to fix failed initialization or hide a banner in
-production.
-
-## Observe changes without inventing choices
-
-`onChoiceRecorded` reports explicit accept, reject and save actions.
-`onPermissionsChanged` also covers changes caused by policy, expiry or privacy
-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. Passing a different `runtime` moves the provider and its
-hooks to the new runtime's kernel and unsubscribes them from the previous one.
-The previous runtime keeps running until its owner disposes it. Switch the
-provider to another runtime, or unmount it, before disposing the runtime it
-renders. Changing between a borrowed runtime and a provider-created one still
-requires remounting the provider. IAB actions taken before its handle is ready
-wait for that handle. If the provider unmounts or switches runtimes 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).
-
-## Reload after revocation
-
-Removing a script cannot stop code that already ran. A vendor's listeners,
-timers and widgets keep working until the page unloads. When an accept, reject
-or save turns off a category or vendor that was granted, the provider reloads
-the page once the save request settles, so the next page runs only permitted
-code. `onBeforeConsentRevocationReload` runs just before the reload. With a
-[`consentSource`](../../../guides/shared-consent-controls.md), any withdrawal the
-external CMP reports reloads the same way, including expiry.
-
-Otherwise, expiry, policy changes and privacy signals do not reload the page. Set
-`reloadOnConsentRevoked: false` only when every gated vendor stops itself on
-revocation, for example through its own opt-out API.
-
-## Clear data when consent is denied
-
-Set `options.clearOnRevocation` to declare cookies, localStorage keys, and
-sessionStorage keys by optional consent category. Cleanup waits for policy
-resolution, then clears denied categories and later allowed-to-denied
-transitions. This option is initial-only. See
-[clear on revocation](../../../integrations/clear-on-revocation.md) for examples,
-cookie scopes, and browser limits.

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

@@ -1,69 +0,0 @@
----
-title: Load scripts with consent
-description: Register vendor scripts once and let effective permissions control loading.
-group: frameworks
----
-
-## Register scripts on the provider
-
-Install `@c15t/scripts` for vendor helpers. This React-compatible client component
-uses Inth as the backend. Set the URL to the endpoint supplied by your Inth
-project and keep the component mounted around your application.
-
-```tsx title="components/consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import { ConsentProvider, ConsentBanner, ConsentDialog, ConsentDialogLink, hosted } from 'c15t/react';
-import { metaPixel } from '@c15t/scripts/meta-pixel';
-
-const mode = hosted({ url: 'https://your-project.inth.app' });
-const scripts = [metaPixel({ pixelId: '123456789012345' })];
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, scripts }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-    </ConsentProvider>
-  );
-}
-```
-
-Import your adapter's stylesheet globally, as in the framework quickstart. For
-an existing server-resolved `ConsentRoot`, keep that root and pass
-`scripts` as a top-level prop instead of mounting a second provider.
-
-## Understand loading and revocation
-
-Ordinary scripts wait for their category's effective permission. Give each
-script a stable unique `id` and remove any other loader for the same vendor.
-Some helpers use `alwaysLoad` to load the SDK and signal consent through its own
-API. Read the vendor guide; a category field alone does not guarantee no
-requests.
-
-Removing a script element cannot undo JavaScript that already executed or
-requests already sent. Use the vendor's supported consent and cleanup behavior,
-and stop future event calls after revocation. Test both initial denial and a
-change from allowed to denied.
-
-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.
-
-## Shared lifecycle controls
-
-See [shared consent controls](../../guides/shared-consent-controls.md) for external CMPs,
-preference delegation, withdrawal reloads, and application events. These controls
-use the same core runtime across frameworks.

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

@@ -1,266 +0,0 @@
----
-title: Styling
-description: Import the React stylesheet and theme c15t components with tokens,
-  slots, and class names on ConsentProvider.
-group: frameworks
----
-
-## Stylesheet
-
-Import the stylesheet once, next to your global CSS, in the entry module that
-renders `ConsentProvider`:
-
-```tsx
-import 'c15t/react/styles.css';
-```
-
-Every rule lives in `@layer components`, so unlayered utilities from Tailwind
-v4 and atomic classes from StyleX override it without specificity tricks.
-Tailwind v3 treats `@layer components` as its own directive, so import the
-Tailwind 3 build from your Tailwind entry instead, between the `components`
-and `utilities` directives:
-
-```css
-@tailwind base;
-@tailwind components;
-@import 'c15t/react/styles.tw3.css';
-@tailwind utilities;
-```
-
-## Tokens
-
-Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
-properties. The package stylesheet sets the default values. To change them,
-render `ConsentTheme` with your theme where your app renders on the server,
-or override the variables directly in your CSS.
-
-`ConsentTheme` renders a `<style id="c15t-theme">` element with the
-variables for `theme`. It is not a client component: rendered from a Server
-Component or another server-only file, the theme generator stays out of the
-browser bundle. Rendered from a client component it still works, but the
-browser downloads the generator (about 1.7 KB gzip). The provider no longer
-turns `theme` tokens into CSS. It still reads `consentActions` and slot
-styles from its `theme` option, and warns in development when `theme` holds
-tokens but the page has no `c15t-theme` stylesheet.
-
-| `ConsentTheme` prop | Purpose                                                                                                                                                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `theme`             | Colors, `dark` colors, typography, spacing, radius, shadows and motion. Defaults to the built-in theme.                                                                                     |
-| `colorScheme`       | `'dark'` makes the dark tokens the default before hydration. `'system'` follows `prefers-color-scheme` with a CSS media query. Omit it to follow a `dark` or `c15t-dark` class on `<html>`. |
-| `nonce`             | Content Security Policy nonce for the `<style>` element.                                                                                                                                    |
-
-Pass the same `colorScheme` to `ConsentTheme` and to the provider. The
-provider keeps the `c15t-dark` class on `<html>` in sync after hydration.
-If your app manages dark mode through a root class, such as next-themes'
-`dark` class, omit `colorScheme` and include that class in the server
-HTML.
-
-To switch between light and dark at runtime, render `ConsentTheme` without
-`colorScheme` and toggle the `dark` class on `<html>`: its output already
-holds the variables for both schemes. To switch between different token
-sets, render `ConsentTheme` from a client component and change its props,
-which ships the generator.
-
-Outside React, call `generateThemeCSS(theme, colorScheme)` from
-`@c15t/ui/theme` on the server or at build time and put the result in a
-`<style>` element or your stylesheet. It escapes `<`, so the result is safe
-inside `<style>`.
-
-```ts title="src/consent-theme.ts"
-import { defineTheme } from 'c15t/react';
-
-export const theme = defineTheme({
-	colors: { primary: '#2f6f4e' },
-	radius: { lg: '4px' },
-	consentActions: {
-		primary: { variant: 'primary', mode: 'filled' },
-		dismiss: { variant: 'neutral', mode: 'stroke' },
-	},
-});
-```
-
-With server rendering, render `ConsentTheme` in the server-only part of your
-document, next to the provider. In a single-page app with no server render,
-either render it next to the provider, which ships the generator, or write the
-variables into your stylesheet. This partial example keeps the provider's
-`mode`, children and other options:
-
-```tsx
-import { ConsentProvider, ConsentTheme } from 'c15t/react';
-
-import { theme } from './consent-theme';
-
-<>
-	<ConsentTheme theme={theme} />
-	<ConsentProvider options={{ mode, theme }}>{children}</ConsentProvider>
-</>;
-```
-
-The provider's `theme` option only supplies `consentActions` and slot styles.
-
-Earlier v3 alphas generated theme CSS in the browser from the provider's
-`theme` option. To migrate:
-
-1. Move the theme into a module without `'use client'`, so server and
-   client files can both import it.
-2. Render `<ConsentTheme theme={theme} />` next to the consent root, from a
-   Server Component or another server-rendered file. Pass `colorScheme` and
-   `nonce` if you set them on the provider.
-3. Keep passing `theme` to the provider only for `consentActions` and slot
-   styles. A theme with tokens only can be removed from the provider.
-4. Keep the package stylesheet import. It carries the default tokens the
-   provider used to inject.
-
-`consentActions` decides how each action role looks: `default` applies to
-every button, `primary` to whichever actions the policy or your props mark
-primary, and `accept`, `reject`, `customize`, and `dismiss` to one role each.
-Per-action keys win over `primary`, which wins over `default`.
-
-Banner sizing has its own variables. Override them in CSS when a variant
-needs a different footprint:
-
-| Variable                            | Default | Applies to       |
-| ----------------------------------- | ------- | ---------------- |
-| `--consent-banner-max-width`        | `440px` | `floating` cards |
-| `--consent-banner-widget-max-width` | `20rem` | `widget` chips   |
-| `--consent-banner-wall-max-width`   | `30rem` | `wall` cards     |
-
-## Colors by consent model
-
-The primary action can change while the brand color stays the same. Set
-`consentActions.primary` once, then select `primaryButton` per policy as
-shown in [ConsentBanner](../components/consent-banner.md#per-policy-buttons).
-
-To give opt-in and opt-out banners different colors, scope the tokens to
-the root's attributes. Include hover and foreground colors when overriding
-CSS tokens directly:
-
-```css
-[data-prompt][data-model='opt-in'] {
-	--c15t-primary: #2f6f4e;
-	--c15t-primary-hover: #24563c;
-	--c15t-text-on-primary: #fff;
-}
-
-[data-prompt][data-model='opt-out'] {
-	--c15t-primary: #6b3fa0;
-	--c15t-primary-hover: #55327f;
-	--c15t-text-on-primary: #fff;
-}
-```
-
-These colors apply to the action marked primary. Button layout and color
-changes do not change the policy or expire a saved choice.
-
-## Slots
-
-Each component part is a slot. A slot accepts any attributes the element
-takes, so the contract is the same whether you write class strings or pass an
-object with `className` and `style`. Set slots on the provider under
-`components`, keyed by component and part.
-
-For a full-width notice, use the supported `bar` variant. Inside your existing
-provider, replace the stock banner with:
-
-```tsx title="src/regional-banner.tsx"
-import { ConsentBanner, usePolicyRule } from 'c15t/react';
-
-export function RegionalBanner() {
-  const policy = usePolicyRule();
-  return <ConsentBanner variant={policy?.prompt === 'notice' ? 'bar' : 'floating'} />;
-}
-```
-
-To remove the notice card's radius, add these values to the existing
-`options.components.banner` slots. The root owns `data-prompt`, so the card
-uses Tailwind's `group` selector to read it:
-
-```ts
-const bannerSlots = {
-  root: { className: 'group' },
-  card: { className: 'group-data-[prompt=notice]:rounded-none' },
-  rightLink: {
-    className: 'underline-offset-4 data-[right=opt-out]:text-red-700',
-  },
-};
-
-// In the existing options.components object:
-// banner: bannerSlots
-```
-
-The root also carries `data-variant`, so you can restyle one shape without
-touching the others. Tailwind, giving a `bar` a brand-colored top edge and
-tighter text:
-
-```tsx
-<ConsentProvider
-	options={{
-		mode,
-		presentation: { prompt: { variant: 'bar' } },
-		components: {
-			banner: {
-				root: { className: 'group' },
-				card: {
-					className:
-						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
-				},
-			},
-			description: {
-				banner: { className: 'group-data-[variant=bar]:text-xs' },
-			},
-		},
-	}}
-/>
-```
-
-`data-variant` sits on the root, so child slots use Tailwind's `group`
-prefix to read it.
-
-StyleX, spreading the result of `stylex.props()` into a slot:
-
-```tsx
-import * as stylex from '@stylexjs/stylex';
-
-const styles = stylex.create({
-	card: { borderRadius: 0, boxShadow: 'none' },
-	rightLink: { textUnderlineOffset: 4, color: 'rgb(185 28 28)' },
-});
-
-<ConsentProvider
-	options={{
-		mode,
-		components: {
-			banner: {
-				card: stylex.props(styles.card),
-				rightLink: stylex.props(styles.rightLink),
-			},
-		},
-	}}
-/>;
-```
-
-Set `noStyle` on a component to drop the built-in classes from every part and
-keep only what your slots pass. Set `noStyle` in the provider options to do it
-for every component.
-
-Banner slot keys under `components.banner`:
-
-| Key           | Element                                                                                                           |
-| ------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `root`        | Fixed-position wrapper carrying `data-prompt`, `data-model`, `data-variant`, `data-position`, and `data-blocking` |
-| `cardShell`   | Sizes the card and holds the branding tag                                                                         |
-| `card`        | The visible card, carrying `data-state`                                                                           |
-| `header`      | Title and description container                                                                                   |
-| `title`       | Heading                                                                                                           |
-| `footer`      | Action area                                                                                                       |
-| `actions`     | Group of action groups                                                                                            |
-| `actionGroup` | One group of equally prominent actions                                                                            |
-| `rights`      | Group of right links, rendered before the actions                                                                 |
-| `rightLink`   | One right link, carrying `data-action="right"` and `data-right`                                                   |
-| `overlay`     | Backdrop shown when the banner blocks the page                                                                    |
-
-Action buttons carry `data-action` and `data-variant`, and right links carry
-`data-action="right"`, so a single rule such as `[data-action='dismiss']` or
-`[data-action='right']` styles one role across every surface. Right links are
-underlined text by default, so the only button on a notice is the primary
-action.

package/docs/guides/deployment-modes.md

@@ -1,75 +0,0 @@
----
-title: Choose a deployment mode
-description: Choose who runs your consent backend, then select manifest, init or
-  offline resolution for your deployment.
-group: guides
----
-
-## Use Inth for managed policy and records
-
-Start with [Inth](https://inth.com) unless you need to operate the consent
-service yourself or deliberately need only local browser records. Configure
-policy rules and trusted origins in the project, then use its exact backend
-endpoint in your framework setup.
-
-| Backend ownership         | Policy source                                          | Record storage                           | Use when                                                                  |
-| ------------------------- | ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------- |
-| Inth hosted service       | Centrally managed policy through a manifest or `/init` | Browser records plus backend submissions | You want managed policy and consent records                               |
-| Self-hosted c15t          | Your backend's manifest or `/init`                     | Browser records plus your database       | You need to operate the service and its infrastructure                    |
-| Browser-only offline mode | Bundled `policyRules`                                  | Browser persistence                      | Local development and tests. Not recommended for production environments. |
-
-Hosted and self-hosted c15t use the same transport protocol. Switching who runs
-the backend does not require switching from manifests to `/init`.
-
-## Choose data fetching separately
-
-For Next.js deployments with a runtime server, use the
-[manifest setup](https://c15t.com/docs/frameworks/next/data-fetching). It reuses public policy data
-in your application while consent writes still go to Inth. Regular backend
-`/init` is available when you want backend-owned request resolution or a simpler
-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                                              |
-| ------------------ | ------------------------- | ----------------------------------------------------------- |
-| Request SSR        | Prepared for this visitor | Adapter request helper and matching client configuration    |
-| Static HTML or SPA | Resolved in the browser   | Reachable external URLs or deliberately bundled local rules |
-
-Request SSR can include the visitor's prompt in the initial HTML. Pass the
-prepared records and policy resolution through to hydration. Do not convert
-effective permissions into new stored choices.
-
-Static HTML is shared across visitors. It cannot contain a choice resolved from
-each visitor's cookies or geography at build time. A static site can still use
-Inth through browser requests. A same-origin `/api/c15t` URL only works if a
-service actually serves it; a Next.js static export does not run API routes.
-
-A manifest contains reusable public policy data. A resolved init response and
-personalized consent HTML belong to a request. Do not give them the same shared
-cache treatment.
-
-## Handle initialization and storage failures
-
-While no policy resolves, optional permissions stay denied and the stock
-consent UI stays hidden. No banner can mean pending or failed initialization.
-It does not mean permission to load analytics. Observe errors before changing
-presentation, and do not silently switch to offline policy after a hosted
-request fails.
-
-Browser storage can also be unavailable. A working in-memory interaction does
-not prove the choice survives reload. Use
-[verification](./verify-consent.md) to test the actual deployment.