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

package/docs/integrations/pinterest-tag.md

@@ -0,0 +1,321 @@
+---
+title: Pinterest Tag
+description: Configure the Pinterest Tag with c15t v3, track typed events and
+  verify marketing permission, revocation and reload.
+group: integrations
+---
+
+## Configure Pinterest Tag
+
+Use the numeric tag ID from Pinterest Ads Manager. The helper recreates
+Pinterest's base code: it defines the `pintrk` queue, queues `load`,
+`setconsent(true)` and a page visit, then loads `core.js`.
+
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
+
+```ts title="src/consent-scripts.ts"
+import { pinterestTag } from '@c15t/scripts/pinterest-tag';
+
+export const scripts = [pinterestTag({ tagId: 'YOUR_TAG_ID' })];
+```
+
+## Register the scripts
+
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry so c15t owns loading once.
+
+The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
+initializer. Add it to your existing consent owner using the registration point
+below. These are partial edits to that owner, not additional providers.
+
+**Next.js**
+
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
+
+Keep the server-resolved `state` and shared `consentConfig` from your
+router guide. Its manifest, init and save URLs stay in effect. Add
+`scripts` as a top-level prop on the existing root:
+
+```tsx
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
+
+For a Pages Router or static-export setup using `ConsentProvider`, add
+`scripts` to its existing `options` instead. Keep the router-specific setup
+from [Next.js script loading](../frameworks/next/script-loader.md).
+
+**TanStack Start**
+
+In your existing root route component, import the scripts alongside
+`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
+
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
+
+function Root() {
+  const state = Route.useLoaderData();
+  return (
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
+  );
+}
+```
+
+This edits the existing route. `Route` and `backendURL` come from its setup;
+keep the document shell and head components if they are part of your root.
+`initRoute={false}` keeps the quickstart's direct-backend initialization.
+If your app mounts a consent server route, retain its existing `initRoute`
+instead. Do not return script callbacks from a server function or route loader.
+
+**React**
+
+Import the scripts into your existing provider component:
+
+```ts
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
+
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
+
+Here `consentOptions` is your existing configuration, including
+`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
+link inside the provider. See [React script loading](../frameworks/react/script-loader.md).
+
+**Nuxt**
+
+Attach one loader from the root `app.vue`, after the Nuxt module has
+started its browser runtime. This keeps vendor callbacks in application code rather
+than serialized `nuxt.config.ts` runtime configuration.
+
+```vue title="app/app.vue"
+<script setup lang="ts">
+import { onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from '../src/consent-scripts';
+
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
+});
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
+```
+
+Merge the setup code into your root and retain its footer and preferences
+link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
+relative script import if your `app.vue` is at the project root. This loader
+waits until the module has applied browser persistence and privacy signals,
+then reads the current snapshot and observes future changes. Do not also register these scripts
+in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
+
+**Vue**
+
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
+
+```vue title="src/App.vue"
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { useConsentKernel } from 'c15t/vue/vue-plugin';
+import ConsentRoot from 'c15t/vue/consent-root';
+import { scripts } from './consent-scripts';
+
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => loader?.dispose());
+</script>
+
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
+```
+
+Keep your existing page content and preferences link. The plugin still owns
+the kernel and persistence; this component owns only the vendor loader.
+Do not register the same scripts in plugin configuration as well. See the
+[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
+
+**Astro**
+
+Point the existing Astro integration at a client module. Keep its `mode`,
+`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
+Import `fileURLToPath` in your Astro configuration:
+
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
+
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
+
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
+
+Export the scripts from that module:
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from 'c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+The integration passes this extension to its shared browser runtime. Vendor
+helpers contain callbacks, so do not put them in the serialized `scripts`
+option in `astro.config.mjs`. Keep one runtime across consent islands and
+`ClientRouter` navigation.
+
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-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 });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
+
+**SvelteKit**
+
+Add the scripts to the existing root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`.
+For static hosting, keep your browser-only `mode` setup and omit request
+prefetch; the `scripts` prop stays the same. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**JavaScript**
+
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
+
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
+```
+
+Call `loader.dispose()` when that application instance is destroyed.
+`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
+already has a loader; do not attach a second one. See
+[JavaScript script loading](../frameworks/javascript/script-loader.md).
+
+Pinterest's `<noscript>` image fallback is not emitted. It fires without
+JavaScript, so c15t cannot gate it.
+
+## Options
+
+| Option           | Behavior                                                                                                               |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `tagId`          | Required Pinterest Tag ID.                                                                                             |
+| `loadOptions`    | Third argument to `pintrk('load')`, such as `em` for enhanced match. Pass user data only with the permission it needs. |
+| `trackPageVisit` | Queues `pintrk('page')` during setup. Defaults to `true`.                                                              |
+| `scriptUrl`      | Defaults to `https://s.pinimg.com/ct/core.js`.                                                                         |
+
+## Track events
+
+`pinterestTagEvent()` sends a typed `pintrk('track')` call. It covers Pinterest's
+20 event types and accepts user-defined names, which Pinterest uses for audience
+targeting only. Put product details in `line_items`.
+
+```ts
+import { pinterestTagEvent } from '@c15t/scripts/pinterest-tag';
+
+pinterestTagEvent('checkout', {
+	currency: 'USD',
+	event_id: 'order-123',
+	line_items: [{ product_id: '1414', product_price: 99.99, product_quantity: 1 }],
+	order_id: 'order-123',
+	value: 99.99,
+});
+```
+
+Set `event_id` to deduplicate against the Conversions API. An optional third
+argument receives Pinterest's `(didInit, error)` result. The helper does nothing
+until the tag has loaded, and it checks API availability, not consent.
+
+## Consent behavior
+
+The first load waits for marketing permission. On revocation the helper keeps
+the tag and calls `pintrk('setconsent', false)`, which Pinterest documents as
+stopping events and clearing its first-party cookies. c15t then reloads the page.
+A later grant calls `setconsent(true)`.
+
+## Verify the integration
+
+Use a fresh session with an opt-in policy and confirm `core.js` is absent. Grant
+`marketing` and check the page visit in Pinterest's Tag Helper. Revoke it and
+confirm the page reloads and no further events are sent. Follow the
+[consent verification guide](../guides/verify-consent.md).

package/docs/integrations/pirsch.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/plausible-analytics.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/posthog.md

@@ -206,7 +206,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/promptwatch.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/reddit-pixel.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/rudderstack.md

@@ -203,7 +203,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/rybbit-analytics.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/segment.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/snapchat-pixel.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/tiktok-pixel.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/umami-analytics.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/vercel-analytics.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/x-pixel.md

@@ -194,7 +194,7 @@ clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)
 Export the scripts from that module:
 
 ```ts title="src/c15t.client.ts"
-import type { C15tClientOptionsExtension } from '@c15t/astro';
+import type { C15tClientOptionsExtension } from 'c15t/astro';
 import { scripts } from './consent-scripts';
 
 export default { scripts } satisfies C15tClientOptionsExtension;

package/docs/integrations/youtube.md

@@ -176,7 +176,7 @@ Add this component to pages using your consent-enabled base layout:
 <c15t-consent-embed style="display: block"></c15t-consent-embed>
 
 <script>
-  import { getConsentClient } from '@c15t/astro/client';
+  import { getConsentClient } from 'c15t/astro/client';
   import { mountConsentEmbed } from '../consent-embed';
 
   class ConsentEmbed extends HTMLElement {

package/docs/upgrade-v3.md

@@ -87,6 +87,115 @@ be true before a visitor acts. A notice dismissal updates `noticeDismissal` and
 does not record consent. Global Privacy Control updates privacy signals and
 configured opt-out directives without turning a browser signal into a choice.
 
+## Replace `useConsentManager()`
+
+`useConsentManager()` is gone from `c15t/react`, `c15t/next`,
+`c15t/tanstack-start` and their `/headless` entries. It subscribed to the whole
+consent snapshot, so every component that called it re-rendered on every
+change, including changes to categories it never read. Call one hook per field
+instead; each re-renders only when its own value changes.
+
+Before, in v2 and earlier v3 alphas:
+
+```tsx title="components/marketing-banner.tsx"
+import { useConsentManager } from 'c15t/react';
+
+export function MarketingBanner() {
+  const { activeUI, has, saveConsents } = useConsentManager();
+  if (activeUI !== 'banner' || has('marketing')) {
+    return null;
+  }
+  return <button type="button" onClick={() => void saveConsents('all')}>Accept</button>;
+}
+```
+
+After:
+
+```tsx title="components/marketing-banner.tsx"
+import { useActiveUI, useConsent } from 'c15t/react';
+import { useHeadlessConsentUI } from 'c15t/react/headless';
+
+export function MarketingBanner() {
+  const activeUI = useActiveUI();
+  const marketing = useConsent('marketing');
+  const { performAction } = useHeadlessConsentUI();
+  if (activeUI !== 'banner' || marketing) {
+    return null;
+  }
+  return <button type="button" onClick={() => void performAction('accept')}>Accept</button>;
+}
+```
+
+Import hooks from the same entry you used for `useConsentManager()`:
+`c15t/next` and `c15t/next/headless` in Next.js, `c15t/tanstack-start` and
+`c15t/tanstack-start/headless` in TanStack Start.
+
+| `useConsentManager()` field                                   | v3 replacement                                                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `activeUI`                                                    | `useActiveUI()`. It returns `null` before the kernel picks a surface; the old field reported `'none'`. |
+| `setActiveUI(ui)`                                             | `useSetActiveUI()`                                                                                     |
+| `has(category)`                                               | `useConsent(category)`, one call per category at the top of the component                              |
+| `consents`                                                    | `useConsents()`                                                                                        |
+| `effectivePermissions`                                        | `useEffectivePermissions()`                                                                            |
+| `explicitChoice`                                              | `useExplicitChoice()`                                                                                  |
+| `promptRequirement`                                           | `usePromptRequirement()`                                                                               |
+| `noticeDismissal`                                             | `useNoticeDismissal()`                                                                                 |
+| `privacySignals`                                              | `usePrivacySignals()`                                                                                  |
+| `optOutDirectives`                                            | `useOptOutDirectives()`                                                                                |
+| `restrictions`                                                | `useRestrictions()`                                                                                    |
+| `resolution`                                                  | `usePolicyResolution()`                                                                                |
+| `policyRule`                                                  | `usePolicyRule()`                                                                                      |
+| `policyCategories`                                            | `usePolicyCategories()`. The old list started with `'necessary'`; this one does not.                   |
+| `policyScopeMode`                                             | `usePolicyScopeMode()`                                                                                 |
+| `policyBanner`                                                | `usePromptPresentation()`                                                                              |
+| `policyDialog`                                                | `usePreferencesPresentation()`                                                                         |
+| `model`                                                       | `useModel()`. It returns `null` while no policy matches; the old field reported `'opt-in'`.            |
+| `branding`                                                    | `useBranding()`. It returns `null` when unset; the old field reported `'c15t'`.                        |
+| `iab`                                                         | `useIABSnapshot()`                                                                                     |
+| `vendors`                                                     | `useDeclaredVendors()`                                                                                 |
+| `vendorChoice`                                                | `useVendorChoice()`                                                                                    |
+| `getDisplayedVendors(category)`                               | `useDeclaredVendors()`, filtered to vendors whose category condition names the category                |
+| `subscribeToConsentChanges(listener)`                         | `useSubscribeToConsentChanges()`, or the provider's `onPermissionsChanged` callback                    |
+| `updateConsentCategories(categories)`                         | `useRegisterConsentCategories()`                                                                       |
+| `translationConfig`                                           | `useTranslations()` for the active strings                                                             |
+| `selectedConsents`, `selectedConsentTypes`                    | `useConsentDraft().values`                                                                             |
+| `setSelectedConsent(name, value)`                             | `useConsentDraft().set(name, value)`                                                                   |
+| `selectedVendors`                                             | `useConsentDraft().vendors`, or `useVendorDraft().vendors`                                             |
+| `setSelectedVendor(id, granted)`                              | `useConsentDraft().setVendor(id, granted)`                                                             |
+| `resetDraft()`                                                | `useConsentDraft().reset()`                                                                            |
+| `draftIsStale`                                                | `useConsentDraft().isStale`                                                                            |
+| `consentCategories`, `consentTypes`, `getDisplayedConsents()` | `useConsentDraft().displayedCategories`, with labels from `useTranslations().consentTypes`             |
+| `saveConsents('all')`                                         | `useHeadlessConsentUI().performAction('accept')`                                                       |
+| `saveConsents('necessary')`                                   | `useHeadlessConsentUI().performAction('reject')`                                                       |
+| `saveConsents('custom')`                                      | `useHeadlessConsentUI().performAction('save')`                                                         |
+| `manager`                                                     | Nothing. It was always `null` in v3.                                                                   |
+
+The old hook kept one private draft per component, shared by its selection and
+its save. `useConsentDraft()` and `useHeadlessConsentUI()` read the nearest
+`ConsentDraftProvider` instead. When one component stages choices and another
+saves them, or one component calls both hooks, render them inside the same
+`ConsentDraftProvider`; without one, each hook keeps its own draft and a custom
+save commits nothing you staged. `ConsentWidget` already provides one.
+
+`useHeadlessConsentUI()` saves the way the stock buttons do: it closes the
+surface after a successful save and refuses a draft that the policy made stale.
+`useSaveConsents()` calls the kernel directly and does neither.
+
+The CLI rewrites the common destructuring forms for you:
+
+```bash
+c15t codemods use-consent-manager-to-hooks --dry-run --json
+```
+
+It replaces each field that has a one-hook equivalent, turns `has('marketing')`
+calls with a literal category into `useConsent('marketing')`, and maps
+`saveConsents('all' | 'necessary' | 'custom')` calls to
+`useHeadlessConsentUI().saveCustomPreferences()`. Fields it cannot rewrite stay
+on a `useConsentManager()` call under a `TODO(c15t v3)` comment that names the
+replacement, so the build fails at each place that needs manual work. It also
+marks components that now need a shared `ConsentDraftProvider`. Review the
+result, then run it without `--dry-run`.
+
 ## Replace choice callbacks
 
 ```tsx
@@ -191,7 +300,7 @@ Notice acknowledgement uses `common.acknowledge`, falling back to
 
 ```astro
 ---
-import ConsentBanner from '@c15t/astro/components/consent-banner.astro';
+import ConsentBanner from 'c15t/astro/components/consent-banner.astro';
 ---
 
 <ConsentBanner dismissButtonText="Got it" />
@@ -277,6 +386,25 @@ translation keys, `--frame-*` CSS custom properties and
 `data-testid="frame-placeholder"`, so custom copy, styles and tests continue
 to apply.
 
+## Split dialog and widget entries are deferred
+
+`c15t/react/consent-dialog` and `c15t/react/consent-widget` (and their
+`@c15t/react/*` equivalents) now export the same deferred `ConsentDialog` and
+`ConsentWidget` as `c15t/react`. The dialog's code loads when it first opens
+instead of with every page. `<ConsentDialog />`, `<ConsentWidget />` and the
+`ConsentDialog.<Part>` properties need no change.
+
+The two entries no longer export the individual parts. Import those from the
+component entries, which keep the old, eagerly bundled exports:
+
+| Before                                                          | After                                                                      |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `import { Card, Header } from 'c15t/react/consent-dialog'`      | `import { Card, Header } from 'c15t/react/components/consent-dialog'`      |
+| `import { Accordion, Switch } from 'c15t/react/consent-widget'` | `import { Accordion, Switch } from 'c15t/react/components/consent-widget'` |
+
+To keep the dialog in the first load so its first open needs no download,
+import `ConsentDialog` from `c15t/react/components/consent-dialog`.
+
 ## Next.js RSC banner removal
 
 The `@c15t/nextjs/rsc` entry (`c15t/next/rsc`) and its `RscConsentBanner`,