@c15t/react 3.1.0 → 3.2.0-canary.0

package/dist-types/components/prompt/prompt.d.ts

@@ -151,8 +151,8 @@ export interface ConsentBannerProps {
     /**
      * Placement of the prompt. Overrides `presentation.prompt.position`.
      * @remarks Must be valid for the resolved variant; otherwise the variant
-     * default is used and a development diagnostic is logged. Host-chosen
-     * positions are never mirrored for right-to-left text.
+     * default is used and a development diagnostic is logged. Right-to-left
+     * text does not move the prompt.
      */
     position?: PromptPosition;
     /**
@@ -164,7 +164,8 @@ export interface ConsentBannerProps {
 }
 /**
  * The stock banner. It reads the policy to choose its buttons, so all of
- * it renders where the server can stream it: see `StreamedSurface`.
+ * it renders where the server can stream it: see
+ * `StreamedConsentSurface`.
  */
 export declare const ConsentBanner: FC<ConsentBannerProps>;
 /**

package/dist-types/components/prompt/surface-context.d.ts

@@ -9,7 +9,7 @@ import type { PromptPosition, PromptVariant } from '@c15t/core';
 export interface ConsentBannerSurface {
     /** Shape of the first-layer prompt. */
     variant: PromptVariant;
-    /** Placement, already mirrored for right-to-left text when defaulted. */
+    /** Placement. It stays the same for right-to-left text. */
     position: PromptPosition;
     /** Whether the host chose the position or the resolver defaulted it. */
     positionSource: 'host' | 'default';
@@ -30,16 +30,3 @@ export declare const ConsentBannerSurfaceContext: import("react").Context<Consen
  * @public
  */
 export declare const useConsentBannerSurface: () => ConsentBannerSurface;
-/**
- * Mirror a defaulted corner for right-to-left text so the banner keeps
- * hugging the reading start. Host-chosen positions and edge or center
- * placements are returned unchanged.
- *
- * @param position - The resolved position.
- * @param positionSource - Whether the host chose it.
- * @param variant - The resolved variant; only corners of floating and widget mirror.
- * @param textDirection - Document text direction.
- * @returns The position to render.
- * @internal
- */
-export declare const mirrorDefaultPosition: (position: PromptPosition, positionSource: 'host' | 'default', variant: PromptVariant, textDirection: 'ltr' | 'rtl') => PromptPosition;

package/dist-types/components/prompt/use-banner-copy.d.ts

@@ -4,13 +4,18 @@
  * @remarks
  * A notice prompt reads the `noticeTitle` and `noticeDescription` copy so
  * it informs rather than asks. Languages that have not translated the notice
- * copy fall back to the choice copy rather than to English.
+ * copy fall back to their own choice copy, then to English.
  *
  * @returns The copy the banner should render when no props override it.
+ *
+ * @example
+ * ```tsx
+ * const { title, description } = useBannerCopy();
+ * ```
  * @public
  */
 export declare const useBannerCopy: () => {
-    title: string | undefined;
-    description: string | undefined;
+    title: string;
+    description: string;
     prompt: 'choice' | 'notice' | 'none';
 };

package/dist-types/components/shared/streamed-surface.d.ts

@@ -8,16 +8,53 @@ import type { ReactNode } from 'react';
  * @internal
  */
 export declare const readRecorded: <Value>(thenable: PromiseLike<Value>) => Value;
+/** Props for {@link StreamedConsentSurface}. */
+export interface StreamedConsentSurfaceProps {
+    /** The surface. Its consent hooks must run inside this component. */
+    children: ReactNode;
+}
 /**
- * Renders a consent surface the server can stream. While the provider's
- * `prefetch` is a promise, the surface waits for it in its own Suspense
- * boundary: the rest of the page streams at once, and the surface follows
- * in a later chunk of the same response, rendered from the resolved
- * config. It shows only when that config carries a policy that shows it.
- * Hydration reads the same config, so the surface hydrates in place.
+ * Renders a consent surface the server can stream, such as a banner built
+ * with the headless hooks. The stock `ConsentBanner` uses it too.
  *
- * @internal
+ * While the provider's `prefetch` is a promise, as with Next.js
+ * `<ConsentRoot state={resolveConsent()}>`, the surface waits for it in its
+ * own Suspense boundary: the rest of the page streams at once, and the
+ * surface follows in a later chunk of the same response, rendered from the
+ * resolved config. It shows only when that config carries a policy that
+ * shows it. Hydration reads the same config, so the surface hydrates in
+ * place. Without a pending `prefetch`, it renders its children as they are.
+ *
+ * Call the hooks in a component inside it. Hooks called above it read the
+ * snapshot from before consent resolved, which has no banner.
+ *
+ * @param props - The surface to stream.
+ * @returns The children, in a Suspense boundary while consent streams.
+ * @example
+ * ```tsx
+ * 'use client';
+ * import {
+ *   StreamedConsentSurface,
+ *   useHeadlessConsentUI,
+ * } from 'c15t/next/headless';
+ *
+ * function BannerContent() {
+ *   const { banner, performAction } = useHeadlessConsentUI();
+ *   if (!banner.isVisible) return null;
+ *   return (
+ *     <section aria-label="Cookie consent">
+ *       <button onClick={() => performAction('accept')}>Accept</button>
+ *     </section>
+ *   );
+ * }
+ *
+ * export function ConsentBanner() {
+ *   return (
+ *     <StreamedConsentSurface>
+ *       <BannerContent />
+ *     </StreamedConsentSurface>
+ *   );
+ * }
+ * ```
  */
-export declare const StreamedSurface: ({ children }: {
-    children: ReactNode;
-}) => string | number | bigint | boolean | React.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | React.ReactPortal | null | undefined> | null | undefined;
+export declare const StreamedConsentSurface: ({ children, }: StreamedConsentSurfaceProps) => string | number | bigint | boolean | React.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | React.ReactPortal | null | undefined> | null | undefined;

package/dist-types/headless.d.ts

@@ -4,10 +4,19 @@
  *
  * Pair with `ConsentProvider` from `@c15t/react` (or `@c15t/react/provider`).
  */
-export { defaultTranslationConfig, detectBrowserLanguage, mergeTranslationConfigs, prepareTranslationConfig, } from '@c15t/core';
+export { defaultTranslationConfig, detectBrowserLanguage, mergeTranslationConfigs, prepareTranslationConfig, resolveActionLabels, resolvePreferenceControlLabels, resolvePromptCopy, } from '@c15t/core';
+export type { PreferenceControl, PresentationAction, PromptCopy, ResolvedVendor, } from '@c15t/core';
+export { type ConsentLabels, useConsentLabels, } from './component-hooks/use-consent-labels.js';
+export { useConsentTextDirection } from './component-hooks/use-consent-text-direction.js';
+export { type ConsentGateState, type UseConsentGateResult, useConsentGate, } from './component-hooks/use-consent-gate.js';
 export { type ConsentDialogTriggerVisibility, type UseConsentDialogTriggerOptions, type UseConsentDialogTriggerResult, useConsentDialogTrigger, } from './component-hooks/use-panel-trigger.js';
 export { type HeadlessConsentBannerAction, type HeadlessConsentBannerState, type HeadlessConsentDialogAction, type HeadlessConsentDialogState, type HeadlessConsentSurface, type HeadlessConsentSurfaceAction, type HeadlessConsentSurfaceState, type HeadlessConsentWriteAction, useHeadlessConsentUI, } from './component-hooks/use-headless-consent-ui.js';
 export { useTranslations } from './component-hooks/use-translations.js';
+export { useVendorsListedUnder } from './component-hooks/use-vendors-listed-under.js';
+export { useBannerCopy } from './components/prompt/use-banner-copy.js';
+export { StreamedConsentSurface, type StreamedConsentSurfaceProps, } from './components/shared/streamed-surface.js';
 export { useColorScheme } from './hooks/use-color-scheme.js';
 export { useFocusTrap } from './hooks/use-focus-trap.js';
+export { useIABPolicyGuard } from './hooks/use-iab-policy-guard.js';
+export { useScrollLock } from './hooks/use-scroll-lock.js';
 export type { ReactUIOptions } from './types/manager.js';

package/dist-types/hooks/use-iab-policy-guard.d.ts

@@ -28,8 +28,24 @@ export declare const missingIABProviderError: () => IABUnavailableError;
  * around them, so a missing IAB context alone does not prove the app has
  * none. The check also passes once `@c15t/react/iab` has loaded.
  *
+ * A custom banner or preference center that only handles opt-in and
+ * opt-out should call this too, and render nothing when `useModel()` is
+ * `'iab'`, as the standard surfaces do.
+ *
  * @throws {IABUnavailableError} When the policy needs IAB and neither an
  * IAB context nor `@c15t/react/iab` is present.
- * @internal
+ *
+ * @example
+ * ```tsx
+ * function Banner() {
+ *   useIABPolicyGuard();
+ *   const model = useModel();
+ *   const { banner } = useHeadlessConsentUI();
+ *   const copy = useBannerCopy();
+ *   if (model === 'iab' || !banner.isVisible) return null;
+ *   return <section>{copy.title}</section>;
+ * }
+ * ```
+ * @public
  */
 export declare const useIABPolicyGuard: () => void;

package/dist-types/hooks/use-scroll-lock.d.ts

@@ -1,5 +1,19 @@
 /**
- * Hook to manage document scroll locking.
- * React wrapper for `@c15t/ui` setupScrollLock.
+ * Locks page scroll while `shouldLock` is true, as the stock banner does
+ * when its policy is blocking.
+ *
+ * @remarks
+ * Locks are counted, so a banner and a dialog can both hold one and the page
+ * scrolls again only when both release. Unmounting releases the lock.
+ *
+ * @param shouldLock - Whether the page should stop scrolling
+ *
+ * @example
+ * ```tsx
+ * const { banner } = useHeadlessConsentUI();
+ * useScrollLock(banner.isVisible && banner.blocking);
+ * ```
+ *
+ * @public
  */
 export declare const useScrollLock: (shouldLock: boolean) => void;

package/dist-types/index-parts/offline.d.ts

@@ -4,4 +4,4 @@
  * (esbuild) does not treat every module the index names as part of an app
  * that imports one hook: only the groups it uses are live.
  */
-export { offline } from '../transports/offline.js';
+export { local, offline } from '../transports/offline.js';

package/dist-types/modes.d.ts

@@ -22,5 +22,5 @@ export { hosted } from './transports/hosted.js';
 export type { HostedOptions } from './transports/hosted.js';
 export { manifest } from './transports/manifest.js';
 export type { BrowserManifestModeFactory, ManifestModeOptions, } from './transports/manifest.js';
-export { offline } from './transports/offline.js';
+export { local, offline } from './transports/offline.js';
 export type { OfflineModeOptions } from './transports/offline.js';

package/dist-types/module-hooks/script-loader.d.ts

@@ -1,6 +1,15 @@
 import type { Script, ScriptLoaderDebugEvent, ScriptLoaderHandle } from '@c15t/core/modules/script-loader';
 export interface UseScriptLoaderOptions {
     onDebug?: (event: ScriptLoaderDebugEvent) => void;
+    /**
+     * Set `false` to start every `scripts` entry after hydration. By default
+     * `ConsentRoot` in `c15t/next` and `c15t/tanstack-start` starts the
+     * entries the visitor's consent already allows from the server HTML,
+     * before the page hydrates.
+     *
+     * @default true
+     */
+    serverStart?: boolean;
 }
 export declare const useScriptLoader: (scripts: Script[], options?: UseScriptLoaderOptions) => ScriptLoaderHandle;
 export type { Script, ScriptLoaderDebugEvent, ScriptLoaderHandle };

package/dist-types/provider.d.ts

@@ -66,20 +66,20 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
     /**
      * Transport factory the provider builds its kernel with. Required.
      *
-     * Pass `hosted()` to talk to a c15t backend, `offline()` to resolve
+     * Pass `hosted()` to talk to a c15t backend, `local()` to resolve
      * policies locally with no network, or `custom()` to supply your own
      * kernel transport. This is an initial-only
      * option: remount the provider to change it.
      *
      * @example
      * ```tsx
-     * import { ConsentProvider, hosted, offline } from '@c15t/react';
+     * import { ConsentProvider, hosted, local } from '@c15t/react';
      *
      * <ConsentProvider options={{ mode: hosted({ backendURL: '/api/c15t' }) }}>
      *   {children}
      * </ConsentProvider>
      *
-     * <ConsentProvider options={{ mode: offline() }}>{children}</ConsentProvider>
+     * <ConsentProvider options={{ mode: local() }}>{children}</ConsentProvider>
      * ```
      */
     mode: ProviderTransportFactory;

package/dist-types/transports/offline.d.ts

@@ -1,9 +1,9 @@
 /**
- * Offline mode for the React provider: core's `offline()`, which resolves
+ * Local mode for the React provider: core's `local()`, which resolves
  * policy rules locally and switches copy when `overrides.language` or
  * `useSetLanguage()` names a language the bundle or `i18n.messages` has.
  * The language a server prefetch detected from `Accept-Language` keeps the
  * startup copy.
  */
-export { offline } from '@c15t/core';
+export { local, offline } from '@c15t/core';
 export type { OfflineModeOptions } from '@c15t/core';

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.1.0";
+export declare const version = "3.2.0-canary.0";

package/docs/README.md

@@ -39,7 +39,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Customize](./frameworks/react/customize.md): Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a React app with theme tokens, provider options and slots, and load the stylesheet yourself when you need to.
 - [Embeds](./frameworks/react/embeds.md): Keep YouTube videos, maps and other iframes out of a React page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentProvider.
 - [IAB GPP](./frameworks/react/gpp.md): Add the IAB Global Privacy Platform API (__gpp) to a React app with ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
-- [Headless](./frameworks/react/headless.md): Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.
+- [Headless](./frameworks/react/headless.md): Build a custom consent banner or embed gate in React with the c15t/react/headless hooks inside your ConsentProvider.
 - [Hooks](./frameworks/react/hooks.md): Gate features and save consent choices in React components with the focused hooks exported from c15t/react.
 - [IAB TCF](./frameworks/react/iab.md): Mount the IAB TCF banner and dialog inside a React ConsentProvider and configure the CMP ID, policy and vendor data.
 - [Network blocker](./frameworks/react/network-blocker.md): Hold fetch and XMLHttpRequest calls in a React app until their consent category is allowed, with networkBlocker rules in the ConsentProvider options.
@@ -56,9 +56,9 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Choose your setup](./concepts/choose-your-setup.md): Pick the c15t setup for your framework, rendering mode and hosting, and decide who runs the consent backend.
 - [Consent categories](./concepts/consent-categories.md): Assign scripts, embeds and features to c15t consent categories, and understand which categories the preference dialog shows.
 - [Consent state reference](./concepts/consent-state.md): How c15t saves choices, gates IAB vendors, hydrates server records and keeps browser tabs and storage in step.
-- [Data fetching](./concepts/data-fetching.md): Choose the recommended build-time policy snapshot or runtime manifest fetching, backend /init, browser resolution or offline rules, and understand where consent choices are saved.
+- [Data fetching](./concepts/data-fetching.md): Choose the recommended build-time policy snapshot or runtime manifest fetching, backend /init, browser resolution or local rules, and understand where consent choices are saved.
 - [How consent works](./concepts/how-consent-works.md): What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.
-- [Consent modes](./concepts/modes.md): Reference for manifest(), hosted() and offline() in every c15t framework package, where each one resolves the visitor's policy, what it adds to first-load JavaScript, the build-time manifest fetch and its failure policy, and the backend URL variable each framework reads.
+- [Consent modes](./concepts/modes.md): Reference for manifest(), hosted() and local() in every c15t framework package, where each one resolves the visitor's policy, what it adds to first-load JavaScript, the build-time manifest fetch and its failure policy, and the backend URL variable each framework reads.
 - [Policies](./concepts/policies.md): How policy models, prompts and scope decide what c15t asks visitors, where to change the rules, and why a banner may not appear.
 
 ## Guides
@@ -86,6 +86,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Load Ahrefs Web Analytics only after measurement consent with the c15t ahrefsAnalytics helper, and check it in DevTools.
 - [Amplitude](./integrations/amplitude.md): Load the Amplitude Browser SDK 2 only after measurement consent with the c15t amplitude helper, which opts the SDK out on revocation and back in on a new grant.
 - [Custom integrations](./integrations/building-integrations.md): Gate a vendor that has no @c15t/integrations helper, or sync consent with an SDK your app already loads, using a c15t script configuration.
+- [Clay](./integrations/clay.md): Load Clay web intent only after marketing consent and understand its storage and revocation limits.
 - [Clearbit](./integrations/clearbit.md): Load the Clearbit enrichment tag only after marketing consent with the c15t clearbit helper, and check it in DevTools.
 - [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Load the Cloudflare Web Analytics beacon only after measurement consent with the c15t cloudflareWebAnalytics helper, and check it in DevTools.
 - [Cloudflare Zaraz](./integrations/cloudflare-zaraz.md): Sync c15t permissions to Cloudflare Zaraz purposes with the c15t cloudflareZaraz bridge, which runs on every page without loading a script, and check the tools it controls.
@@ -110,7 +111,12 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Mixpanel](./integrations/mixpanel-analytics.md): Load the Mixpanel SDK on every page with the c15t mixpanelAnalytics helper, which switches Mixpanel tracking on and off with measurement consent, and check it in DevTools.
 - [OneDollarStats](./integrations/one-dollar-stats.md): Load the OneDollarStats tracker only after measurement consent with the c15t oneDollarStats helper, forward its data-attribute settings, and check it in DevTools.
 - [OpenAI Pixel](./integrations/openai-pixel.md): Load the ChatGPT Ads Measurement Pixel only after marketing consent with the c15t openaiPixel helper, guard oaiq conversion calls, and check it in DevTools.
-- [Integrations](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, email and SMS, chat and embedded content.
+- [Other ads and pixels](./integrations/other-ads-and-pixels.md): Consent-gated helpers for ad platforms and conversion pixels that don't need a full guide.
+- [Other analytics tools](./integrations/other-analytics.md): Consent-gated helpers for analytics tools that don't need a full guide.
+- [Other chat and support tools](./integrations/other-chat-and-support.md): Consent-gated helpers for chat and support tools that don't need a full guide.
+- [Other email, SMS and marketing automation tools](./integrations/other-email-and-sms.md): Consent-gated helpers for email, SMS and marketing automation tools that don't need a full guide.
+- [Experimentation and personalization tools](./integrations/other-experience.md): Consent-gated helpers for experimentation and personalization tools that don't need a full guide.
+- [Integrations](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, experimentation and personalization, email and SMS, chat and embedded content.
 - [Pinterest Tag](./integrations/pinterest-tag.md): Load the Pinterest Tag only after marketing consent with the c15t pinterestTag helper, guard pintrk event calls, and check it in DevTools.
 - [Pirsch](./integrations/pirsch.md): Load Pirsch Analytics only after measurement consent with the c15t pirsch helper, keep custom event bindings working, and check it in DevTools.
 - [Plausible Analytics](./integrations/plausible-analytics.md): Load the Plausible Analytics tracker only after measurement consent with the c15t plausibleAnalytics helper, and check it in DevTools.
@@ -121,6 +127,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Rybbit Analytics](./integrations/rybbit-analytics.md): Load Rybbit Analytics only after measurement consent with the c15t rybbitAnalytics helper, map its tracking options to data attributes, and check it in DevTools.
 - [Segment](./integrations/segment.md): Load Segment Analytics.js only after measurement consent with the c15t segment helper, guard your own track and identify calls, and check it in DevTools.
 - [Sentry](./integrations/sentry.md): Configure Sentry's CDN or your own SDK with consent for error monitoring, Session Replay and user data.
+- [Shopify](./integrations/shopify.md): Send c15t consent to Shopify's Customer Privacy API from a Hydrogen storefront, so Shopify analytics wait for the visitor's choice and follow each later change.
 - [Snapchat Pixel](./integrations/snapchat-pixel.md): Load the Snapchat Pixel only after marketing consent with the c15t snapchatPixel helper, guard snaptr event calls, and check it in DevTools.
 - [TikTok Pixel](./integrations/tiktok-pixel.md): Load the TikTok Pixel only after marketing consent with the c15t tiktokPixel helper, guard ttq event calls, and check it in DevTools.
 - [Umami Analytics](./integrations/umami-analytics.md): Load the Umami Analytics tracker only after measurement consent with the c15t umamiAnalytics helper, point it at a self-hosted instance, and check it in DevTools.

package/docs/concepts/choose-your-setup.md

@@ -45,11 +45,11 @@ and subscribe to it from your components.
 The backend supplies policies and stores consent records. Every setup above
 works with each option; only the URL changes.
 
-| Option                                                               | Use it when                                                                                                                                                    |
-| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Inth](https://inth.com)                                             | You want hosted policies and consent records. The guides use this.                                                                                             |
-| [Self-hosted c15t backend](https://c15t.com/docs/self-host/overview) | You need to run the service and its database yourself.                                                                                                         |
-| Offline mode                                                         | Local development and tests. Policies live in your code and choices stay in the browser, with no consent records. Not recommended for production environments. |
+| Option                                                               | Use it when                                                                                                                                                                        |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Inth](https://inth.com)                                             | You want hosted policies and consent records. The guides use this.                                                                                                                 |
+| [Self-hosted c15t backend](https://c15t.com/docs/self-host/overview) | You need to run the service and its database yourself.                                                                                                                             |
+| [Local mode](./modes.md#local)                                       | Local development and tests. Policies live in your code and choices stay in the browser. c15t keeps no server-side record of consent. Not recommended for production environments. |
 
 To use Inth, create a project, set its policy rules, add your site's origin to
 its trusted origins, and copy the backend URL. The guides use the placeholder
@@ -60,10 +60,10 @@ including any path prefix.
 
 Where consent resolves decides what the visitor's first HTML contains.
 
-| Rendering                                    | What the visitor gets                                                                                                                                                                   |
-| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| The server resolves consent for each request | The server reads the visitor's cookie and location headers, so the browser starts with the answer. Gated scripts can run right after hydration, and the banner can be part of the HTML. |
-| The browser resolves consent                 | The HTML is the same for everyone. After the page loads, the browser requests the policy, then shows the banner or runs gated scripts.                                                  |
+| Rendering                                    | What the visitor gets                                                                                                                                                                                                                                       |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The server resolves consent for each request | The server reads the visitor's cookie and location headers, so the browser starts with the answer. The banner can be part of the HTML. In Next.js, TanStack Start, Nuxt and SvelteKit, scripts the visitor's consent already allows start before hydration. |
+| The browser resolves consent                 | The HTML is the same for everyone. After the page loads, the browser requests the policy, then shows the banner or runs gated scripts.                                                                                                                      |
 
 A static or prerendered page cannot contain one visitor's consent, because the
 same HTML goes to everyone. Static sites still use Inth; the browser talks to it

package/docs/concepts/consent-state.md

@@ -63,6 +63,23 @@ If your own scripts depend on such a category, do one of these:
 Check `effectivePermissions` after Accept All on a fresh visit to see which
 categories your vendor list leaves denied.
 
+## A subject ID from the first page load
+
+Every visitor gets a subject ID (`sub_…`) before they decide anything, so
+you can link activity to the visitor from the first page load and still
+find it when they opt out later. It is in `snapshot.subject.subjectId` from
+the first snapshot.
+
+* A framework server sets the ID in the `c15t-sid` cookie on the first
+  response, where the adapter's server hook runs. Otherwise the browser
+  creates it when c15t starts and stores it in `c15t-sid` at once.
+* The ID stays the same across reloads. The first save records the same ID
+  with the choice.
+* `c15t-sid` is not a choice. A visitor with only an ID still sees the
+  banner.
+* Clearing choices and revoking consent keep the ID. Only setting the subject
+  to `null` starts over with a new one.
+
 ## When a choice is saved
 
 A save records the choice in the browser first and sends it to the backend
@@ -204,10 +221,12 @@ Stored records are merged into the ones in memory:
   wins in both tabs.
 * Tabs keep one subject. A stored subject is considered only when the record
   that carries it changed, never on focus alone. It replaces a subject the tab
-  generated on its first save or copied from storage, so a tab that opened
-  before another tab stored a subject joins it. A subject id the server
-  resolved (at init, from a prefetch or in a save response) is replaced only by
-  a strictly newer stored choice, and an identity set with `identify()` is
+  generated at startup or on its first save, or copied from storage, so a tab
+  that opened before another tab stored a subject joins it. When it replaces
+  an ID the tab generated at startup and never used, the kernel emits
+  `subject:resolved` with `previousSubjectId`. A subject id the server
+  resolved (at init, from a prefetch or in a save response) is replaced only
+  by a strictly newer stored choice, and an identity set with `identify()` is
   never replaced.
 * Under an IAB policy, the TC string follows the reconciled choice. See
   [How the TC string is reconciled](#how-the-tc-string-is-reconciled).
@@ -281,11 +300,13 @@ wherever it turns up. A decision stamped in the very millisecond of the clear
 counts only if it comes from a tab that had already seen that clear, so a tab's
 own choice right after its own clear stands while another tab's decision in the
 same millisecond does not. A stored record left with no decisions after the
-clear is void too, subject included.
+clear is void too, subject included. The subject ID itself survives the clear:
+it lives in its own key, `c15t-sid`, which clearing never removes, so a
+withdrawal stays linked to the same visitor.
 
 * A tab that reconciles only after another tab cleared and saved again drops
-  its pre-clear decisions instead of merging them back. Its subject from before
-  the clear is dropped too.
+  its pre-clear decisions instead of merging them back. The external identity
+  linked to its subject before the clear is dropped too; the subject ID stays.
 * A tab that missed the clear writes only decisions it made after it. Its queued
   write of an earlier decision is discarded, so it cannot bring back a cleared
   record.
@@ -348,13 +369,38 @@ When a server render seeded the page from the consent cookie
 localStorage is still applied on top of it when the page mounts, since it can
 only restrict, if it is newer than the seeded decision or from the same
 millisecond as a seeded grant. A stored grant is not.
+`persistence: { skipHydration: false }` reads storage back over the seed
+instead, so an older stored decision replaces it. A server render then starts
+no scripts from the HTML, since it can't tell what that read will return.
 
 The notice dismissal and vendor denials are stored twice as well. A vendor
 list in localStorage at least as new as the cookie's adds its denials but never
 lifts one the cookie holds; a copy confirmed before the last clear is ignored, so its
 denials never come back. The newer notice dismissal applies; it still only hides a
-notice with the fingerprint it names. The consent record follows the rules
-below.
+notice with the fingerprint it names.
+
+Every notice acknowledgement also stores the visitor's subject ID with it,
+including a choice that acknowledges a notice. For a visitor whose only action
+was acknowledging a prompt that offers only necessary categories, this record
+is what keeps the ID. The acknowledgement still grants no optional category. The `<key>-notice` cookie keeps its v1 format, so older
+runtimes still read it. A separate `<key>-notice-subject` cookie binds the
+subject ID to that acknowledgement: readers use it only while its timestamp and
+fingerprint match the notice, so removing or replacing the notice makes a stale
+identity cookie ineffective. When the subject ID changes, through a save
+response or `set.subjectId()`, c15t rewrites the acknowledgement with the new
+ID, so a reload does not bring the old one back. For the same acknowledgement,
+the cookie identity wins unless a failed cookie write left a newer local
+identity or a local identity removal. That exception lasts only while both
+notice cookies match the values observed after the failed write; a later server
+or sibling-subdomain cookie update takes precedence. Category-based data cleanup
+protects these records and `<key>-sid` even when a configured wildcard matches
+their names.
+
+Clearing the stored records removes the acknowledgement and its
+`<key>-notice-subject` cookie. The subject ID stays in `<key>-sid`, as after any
+other clear. External identity fields supplied through `identify()` go with the
+record that carried them. Call `set.subjectId(null)` to give the visitor a new
+ID. The consent record follows the rules below.
 
 The consent record is stored twice: as a cookie, which a server render reads,
 and in localStorage. The cookie is authoritative. A well-formed cookie wins
@@ -385,6 +431,32 @@ render still reads the old consent cookie until the next successful cookie
 write. The same applies to a consent cookie set with a different `domain` than
 the current `storageConfig` uses, which the clear cannot remove.
 
+The subject ID follows the same split. When its cookie writes succeed, the
+server render and the browser use the same ID. When the browser refuses the
+rewrite of a record cookie after the subject ID changed (the consent cookie,
+`c15t-vendors` or `c15t-notice-subject`), that cookie keeps the old ID while
+localStorage holds the new one. A server render then reports the old ID, and
+the browser starts with the new ID from its storage. This happens even when the
+request's `c15t-sid` cookie already holds the new ID. It lasts until a later
+write of that record reaches the cookie, which may never happen while the
+browser keeps refusing it. The server never replaces a `c15t-sid` cookie the
+request already has with the old ID. When this browser's storage holds the
+newer ID, the browser does not store the old one again either.
+
+The vendor record has a separate limit. A local vendor copy at least as new as
+the cookie's keeps its subject ID, and a rekey to a new subject ID keeps the
+original decision time. So with `crossSubdomain`, a visitor whose only record is
+a vendor decision (no consent record) can hold a local copy and a shared cookie
+copy with the same time but different subject IDs, for example after another
+subdomain rekeyed it at any later moment. This origin then starts with the ID
+from its local copy, on server-rendered loads as well as loads that hydrate. It
+does not write that ID over the shared `c15t-sid` cookie when that cookie and
+the record cookies agree on another ID. A later vendor save from this origin
+does store its ID in the shared vendor cookie, where the other subdomains read
+it. Once that cookie carries it, this origin can also write it to the shared
+`c15t-sid` cookie on a later page load. No optional category is granted and no
+denial is lifted.
+
 ### Ordering with pending writes
 
 A tab writes its own choices in a later task, not during the click. Before it

package/docs/concepts/data-fetching.md

@@ -1,7 +1,7 @@
 ---
 title: Data fetching
 description: Choose the recommended build-time policy snapshot or runtime
-  manifest fetching, backend /init, browser resolution or offline rules, and
+  manifest fetching, backend /init, browser resolution or local rules, and
   understand where consent choices are saved.
 group: concepts
 ---
@@ -10,18 +10,18 @@ group: concepts
 
 Where policy resolves and where choices are saved are separate from who runs
 the backend. Inth and a [self-hosted backend](https://c15t.com/docs/self-host/quickstart) speak
-the same protocol, so every path below works with either. Only `offline()`
+the same protocol, so every path below works with either. Only `local()`
 removes backend requests. For a recommendation by framework, start with
 [choose your setup](./choose-your-setup.md).
 
-| Fetching path                                             | Where policy resolves                                                                        | Where choices are submitted | Choose it when                                                                                                                                       |
-| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Build-time manifest, recommended for server-rendered apps | Your server resolves a bundled policy snapshot with each visitor's inputs                    | Inth or your c15t backend   | Your framework renders on the server, supports a build integration, and policy changes can ship with a rebuild                                       |
-| Cached manifest on your server                            | Your application resolves public policy data with each request's location and signals        | Inth or your c15t backend   | Policy changes must reach the app without rebuilding, or builds cannot access the backend                                                            |
-| Regular backend `/init`                                   | The consent backend                                                                          | The same backend            | You have no application server, as in a React, Vue or Svelte single-page app, want the fewest moving parts, or need backend-owned request resolution |
-| Manifest in the browser                                   | The browser, using a supplied location, or `/init` when the policy needs one it doesn't have | Inth or your c15t backend   | The policy has no location rules or the page knows the visitor's location, and you accept about 3 KB more bundle and a rebuild for policy edits      |
-| Offline                                                   | The browser or local runtime, using bundled rules                                            | No backend submission       | Local development and tests. Not recommended for production environments.                                                                            |
-| Custom transport                                          | Your implementation                                                                          | Your implementation         | An existing service cannot use the c15t backend protocol                                                                                             |
+| Fetching path                                             | Where policy resolves                                                                        | Where choices are submitted                                         | Choose it when                                                                                                                                       |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Build-time manifest, recommended for server-rendered apps | Your server resolves a bundled policy snapshot with each visitor's inputs                    | Inth or your c15t backend                                           | Your framework renders on the server, supports a build integration, and policy changes can ship with a rebuild                                       |
+| Cached manifest on your server                            | Your application resolves public policy data with each request's location and signals        | Inth or your c15t backend                                           | Policy changes must reach the app without rebuilding, or builds cannot access the backend                                                            |
+| Regular backend `/init`                                   | The consent backend                                                                          | The same backend                                                    | You have no application server, as in a React, Vue or Svelte single-page app, want the fewest moving parts, or need backend-owned request resolution |
+| Manifest in the browser                                   | The browser, using a supplied location, or `/init` when the policy needs one it doesn't have | Inth or your c15t backend                                           | The policy has no location rules or the page knows the visitor's location, and you accept about 3 KB more bundle and a rebuild for policy edits      |
+| Local                                                     | The browser or local runtime, using bundled rules                                            | No backend submission. c15t keeps no server-side record of consent. | Local development and tests. Not recommended for production environments.                                                                            |
+| Custom transport                                          | Your implementation                                                                          | Your implementation                                                 | An existing service cannot use the c15t backend protocol                                                                                             |
 
 ## What is a consent manifest?
 
@@ -226,36 +226,43 @@ needing the upstream URL. A static export cannot serve a Next.js route or
 rewrite at runtime; use the absolute Inth URL or a proxy provided by the static
 host instead.
 
-## When should I use offline mode?
+## When should I use local mode?
 
 Not recommended for production environments. Use Inth or a self-hosted backend
 for production policy and consent records.
 
-`offline()` resolves bundled policy rules without an init request and acknowledges
-saves locally. The runtime's persistence module stores the choice in browser
-storage. There is no backend audit history, cross-device record service or IP
-geolocation supplied by this transport.
+`local()`, called `offline()` before c15t 3.2, resolves bundled policy rules
+without an init request and acknowledges saves locally. The runtime's
+persistence module stores the choice in browser storage. c15t keeps no
+server-side record of consent, so there is no audit history, no cross-device
+record and no IP geolocation. [What a consent record proves](./modes.md#what-a-consent-record-proves)
+explains what that leaves out.
 
-Use your framework's `offline()` so its translations and provider context are
+Use your framework's `local()` so its translations and provider context are
 included. In a React app it replaces the mode passed to `ConsentProvider`:
 
 ```ts title="src/consent-mode.ts"
-import { offline } from 'c15t/react';
+import { local } from 'c15t/react';
 
-export const mode = offline();
+export const mode = local();
 ```
 
+In development builds, local mode warns once per page that c15t keeps no
+server-side record of consent. Pass `local({ acknowledgeNoRecords: true })` to
+hide the warning once you have decided a browser-only record is enough; see
+[the development warning](./modes.md#the-development-warning).
+
 In Next.js, TanStack Start, Nuxt, Astro and SvelteKit, pass the data
-`offline()` from the framework package where the config takes `mode`; see
+`local()` from the framework package where the config takes `mode`; see
 [consent modes](./modes.md#import-the-factories-from-your-framework-package).
 
-With no `policyRules`, the current offline transport uses the recommended rule
-pack. Supplying `policyRules` replaces that pack. Unknown country and region are
-real resolution inputs; offline mode does not discover a visitor's location.
+With no `policyRules`, the local transport uses the recommended rule pack.
+Supplying `policyRules` replaces that pack. Unknown country and region are
+real resolution inputs; local mode does not discover a visitor's location.
 Use [policy rules](./policies.md) to understand
 matching and defaults, and test the missing-location case.
 
-Offline mode is an explicit architecture choice, not an automatic fallback for
+Local mode is an explicit architecture choice, not an automatic fallback for
 a failed Inth request. If hosted initialization fails before a policy resolves,
 optional permissions remain denied and the stock prompt stays hidden. Observe
 initialization failures instead of silently changing policy sources.