@c15t/react 3.0.0-alpha.7 → 3.0.0-alpha.9

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

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { ReactNode } from 'react';
+/**
+ * React 18's way to suspend: throw the promise, and read its recorded
+ * result on the retry. The runtime's `settled` records its own result.
+ * Exported for tests.
+ *
+ * @internal
+ */
+export declare const readRecorded: <Value>(thenable: PromiseLike<Value>) => Value;
+/**
+ * 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.
+ *
+ * @internal
+ */
+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;

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

@@ -0,0 +1,36 @@
+/** A stylesheet from `@c15t/ui/styles/sheets/*`. */
+export interface SurfaceStyleSheet {
+    /** Dedupes the stylesheet: a page renders each `id` once. */
+    id: string;
+    /** The stylesheet text. */
+    css: string;
+}
+/**
+ * Renders the stylesheets a stock surface needs as `<style>` elements.
+ *
+ * The banner, trigger, ConsentGate, dialog and widget each render the
+ * sheets they use, so an app that imports no c15t stylesheet still gets
+ * styled surfaces, and no stylesheet `<link>` holds back the first paint.
+ * A server-rendered surface puts its rules in the HTML. A surface that
+ * renders in the browser, like the dialog, inserts them with its own code.
+ *
+ * In React 19 the elements move to `<head>` and each `id` renders once per
+ * page; later sheets follow earlier ones, which keeps the cascade order of
+ * `styles.css`. React 18 renders them in place, next to the surface, and
+ * so does React 19 when the provider sets a `nonce`: React drops the nonce
+ * from a style it moves to `<head>` unless the app passed the same nonce to
+ * React's server renderer, and a style without it would break a
+ * nonce-based policy.
+ *
+ * Renders nothing when the provider sets `styles: false` (the app imports
+ * `styles.css` itself) or `noStyle`.
+ *
+ * @param props.sheets - The stylesheets, in cascade order.
+ * @param props.noStyle - The surface's own `noStyle` prop.
+ * @returns The `<style>` elements, or `null`.
+ * @internal
+ */
+export declare const SurfaceStyles: ({ sheets, noStyle, }: {
+    sheets: readonly SurfaceStyleSheet[];
+    noStyle?: boolean;
+}) => import("react").JSX.Element[] | null;

package/dist-types/context.d.ts

@@ -1,4 +1,5 @@
-import type { AllConsentNames, ConsentKernel, ConsentPresentation } from '@c15t/core';
+import type { AllConsentNames, ConsentKernel, ConsentPresentation, ConsentSnapshot } from '@c15t/core';
+import type { StreamedPrefetch } from '@c15t/core/runtime';
 /**
  * React context carrying the kernel instance.
  *
@@ -21,3 +22,18 @@ export interface ProviderServices {
     setLanguage: (code: string) => void;
 }
 export declare const ProviderServicesContext: import("react").Context<ProviderServices | null>;
+/**
+ * The provider runtime's streamed `prefetch`, while `prefetch` is a promise.
+ * Consent surfaces render inside a boundary that waits for it.
+ *
+ * @internal
+ */
+export declare const StreamedPrefetchContext: import("react").Context<StreamedPrefetch | undefined>;
+/**
+ * The snapshot a streamed consent surface was server-rendered from, which
+ * its hydration must read in place of the kernel's own server snapshot.
+ * `null` everywhere else.
+ *
+ * @internal
+ */
+export declare const HydrationSnapshotContext: import("react").Context<ConsentSnapshot | null>;

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

@@ -0,0 +1,35 @@
+import { IABUnavailableError } from '@c15t/core';
+/**
+ * Record that `IABProvider` is part of the app. `@c15t/react/iab` calls
+ * this when it loads.
+ *
+ * @internal
+ */
+export declare const markIABProviderLoaded: () => void;
+/**
+ * The error the standard surfaces throw for an `iab` policy without
+ * `<IABProvider>`.
+ *
+ * @returns A fresh {@link IABUnavailableError}.
+ * @internal
+ */
+export declare const missingIABProviderError: () => IABUnavailableError;
+/**
+ * Throw while rendering when the visitor's policy needs a CMP and the app
+ * has none.
+ *
+ * The standard banner and dialog do not answer for the IAB model, so
+ * without `<IABProvider>` a visitor under an `iab` policy would see no
+ * consent UI at all. Throwing during render reaches error boundaries and
+ * framework error overlays, on the server render and in the browser alike,
+ * since both read the same snapshot.
+ *
+ * `<IABProvider>` usually sits beside the standard surfaces rather than
+ * 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.
+ *
+ * @throws {IABUnavailableError} When the policy needs IAB and neither an
+ * IAB context nor `@c15t/react/iab` is present.
+ * @internal
+ */
+export declare const useIABPolicyGuard: () => void;

package/dist-types/kernel-selector.d.ts

@@ -16,6 +16,16 @@ import type { AllConsentNames, ConsentKernel, ConsentSnapshot } from '@c15t/core
  * @internal
  */
 export declare const useKernel: () => ConsentKernel;
+/**
+ * Reads the snapshot hydration renders: the kernel's server snapshot, or,
+ * inside a streamed consent surface, the snapshot the server rendered that
+ * surface from.
+ *
+ * @param kernel - The provider's kernel.
+ * @returns A `getServerSnapshot` for `useSyncExternalStore`.
+ * @internal
+ */
+export declare const useServerSnapshot: (kernel: ConsentKernel | null) => () => ConsentSnapshot | undefined;
 /**
  * Subscribes to one slice of the kernel snapshot. React re-renders the
  * caller only when the selected value `Object.is`-differs, so a selector

package/dist-types/provider.d.ts

@@ -40,11 +40,29 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * @remarks
      * Set this when your CSP uses a nonce-based policy instead of
      * `'unsafe-inline'`. The provider forwards it to every `<script>`
-     * element created by the script loader. A per-script `nonce` still takes
+     * element created by the script loader, and to the `<style>` elements
+     * the stock surfaces render. A per-script `nonce` still takes
      * precedence. Pass the same nonce to `ConsentTheme`, which renders the
      * theme `<style>` element.
      */
     nonce?: string;
+    /**
+     * Whether the stock surfaces render their own stylesheets.
+     *
+     * @remarks
+     * The banner, dialog trigger, ConsentGate, dialog and preference widget
+     * each render the c15t rules they use as a `<style>` element: in the
+     * server-rendered HTML, or with the surface's own code in the browser.
+     * No c15t stylesheet `<link>` then holds back the page's first paint.
+     * React 19 moves them into `<head>` and renders each once. They carry
+     * {@link ConsentProviderOptions.nonce}.
+     *
+     * Set `false` when the app imports `styles.css` itself, for example to
+     * run it through Tailwind CSS 3 or to put it in a named cascade layer.
+     *
+     * @default true
+     */
+    styles?: boolean;
     /**
      * Transport factory the provider builds its kernel with. Required.
      *
@@ -85,9 +103,12 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * Pass the pending `Promise<KernelConfig>` instead and the provider
      * mounts at once with a provisional policy, so `children` render (and
      * the static shell can prerender) while the consent data streams in.
-     * Consent surfaces stay hidden until the promise resolves; its first
-     * `init()` then applies the resolved config in place of the transport's
-     * network init. A config that resolves without a policy (persisted
+     * Consent surfaces stay hidden until the promise resolves. On the
+     * server, `ConsentBanner` waits for it in its own Suspense boundary and
+     * follows the page in a later chunk of the same response, before
+     * hydration, when the resolved policy shows a banner; see
+     * `streamBanner`. The resolved config then answers the first `init()`
+     * in place of the transport's network init. A config that resolves without a policy (persisted
      * consents, geo, language only) is applied to the kernel and the
      * transport init runs as usual; a rejected promise is logged outside
      * production and falls through to the transport init. Initial-only:
@@ -105,6 +126,17 @@ export interface ConsentProviderOptions extends ConsentControlOptions, Pick<Reac
      * ```
      */
     prefetch?: ConsentProviderPrefetch | Promise<ConsentProviderPrefetch>;
+    /**
+     * Whether `ConsentBanner` renders on the server once a `prefetch`
+     * promise resolves, so it arrives in the streamed response before the
+     * page hydrates. It shows only when the resolved policy shows a banner
+     * for this visitor. Set `false` to mount the banner after hydration
+     * instead, as with a client-only provider. No effect when `prefetch` is
+     * not a promise. Use the same value on the server and in the browser.
+     *
+     * @default true
+     */
+    streamBanner?: boolean;
     callbacks?: ConsentProviderCallbacks;
     /**
      * Remove configured browser data when its consent permission is revoked.

package/dist-types/ui-config-context.d.ts

@@ -12,6 +12,10 @@ export interface V3UIConfigValue {
     theme?: Theme;
     legalLinks?: LegalLinks;
     preloadDialog?: DialogPreload;
+    /** CSP nonce for the `<style>` elements the surfaces render. */
+    nonce?: string;
+    /** `false` when the app loads `styles.css` itself. */
+    styles?: boolean;
 }
 export declare const V3UIConfigContext: import("react").Context<V3UIConfigValue>;
 export declare const useUIConfig: () => V3UIConfigValue;

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.7";
+export declare const version = "3.0.0-alpha.9";

package/docs/README.md

@@ -36,7 +36,7 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [DevTools](./frameworks/react/components/dev-tools.md): Inspect consent state, location, loaded scripts and consent events in a React app during development with the c15t DevTools panel.
 - [Compose your own banner](./frameworks/react/compose.md): Build a React consent banner from the ConsentBanner parts in c15t/react, with your own markup and buttons, while the policy still decides which actions appear.
 - [Content Security Policy](./frameworks/react/content-security-policy.md): Run c15t in a React app under a Content Security Policy, allow the consent backend and vendor hosts, and pass a nonce to ConsentProvider and ConsentTheme.
-- [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 the stylesheet, theme tokens, provider options and slots.
+- [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.
@@ -74,8 +74,8 @@ These docs describe c15t v3. Find your app's row in Choose your setup, then foll
 - [Customize the interface](./customization/overview.md): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
 - [Banner designs](./customization/recipes.md): Five consent banner designs built with c15t, from one prop to your own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.
 - [Component parts](./customization/slots.md): Find every part of c15t's banner, dialog, widget, trigger and ConsentGate placeholder, its key in your framework's part API, and the data attributes to select on.
-- [Stylesheets and CSS layers](./customization/stylesheets.md): Load the right c15t stylesheet for your framework, see which file holds the dialog's rules, order c15t's cascade layer against your own, and run c15t without its styles.
-- [Tailwind CSS](./customization/tailwind.md): Load c15t's styles next to Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
+- [Stylesheets and CSS layers](./customization/stylesheets.md): See how c15t delivers its styles in each framework without a render-blocking stylesheet, when to import styles.css yourself with styles false, which file holds the dialog's rules, and how c15t's cascade layer meets your own.
+- [Tailwind CSS](./customization/tailwind.md): Use c15t's styles with Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
 - [Theme tokens](./customization/tokens.md): Change c15t's colors, type, radius, spacing, shadows and motion with theme tokens, and see every --c15t-* variable with its default.
 - [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
 

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

@@ -13,7 +13,7 @@ to the alternatives it rules out.
 | Your app                                                                               | Setup                                                                                  | Guide                                                                                                                             |
 | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | Next.js App Router with a Next.js server                                               | Server resolves consent from a build-time manifest and streams it to the page          | [App Router](https://c15t.com/docs/frameworks/next/quickstart)                                                                    |
-| Next.js App Router, banner must be in the first HTML                                   | Await consent inside `Suspense`                                                        | [Stream or await](https://c15t.com/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)                      |
+| Next.js App Router, page must arrive with its banner                                   | Await consent inside `Suspense`                                                        | [Stream or await](https://c15t.com/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)                      |
 | Next.js with static, ISR, `'use cache'` or `ensureStatic = 'navigation'` pages         | Browser resolves consent on those pages                                                | [Static, ISR and cached pages](https://c15t.com/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)                |
 | Next.js Pages Router                                                                   | Resolve consent in `getServerSideProps`                                                | [Pages Router](https://c15t.com/docs/frameworks/next/rendering#pick-your-rendering-path)                                          |
 | Next.js with `output: 'export'`                                                        | Browser resolves consent                                                               | [Static export](https://c15t.com/docs/frameworks/next/static-export)                                                              |
@@ -88,7 +88,9 @@ The snapshot is fixed at build time:
 
 * Rebuild after changing policies, translations or vendors. If your CI caches
   build output, force a fresh build.
-* The build must reach the backend. A failed fetch fails the build.
+* The build must reach the backend. A failed fetch stops Next.js, TanStack
+  Start, SvelteKit and Vite builds. By default, Astro and Nuxt log a warning
+  instead and fetch the policy at runtime.
 * Consent choices still go to the backend.
 
 For deployments that need policy updates without a rebuild, choose a runtime

package/docs/concepts/data-fetching.md

@@ -55,7 +55,9 @@ The snapshot is fixed at build time:
 
 * Rebuild after changing policies, translations or vendors. If your CI caches
   build output, force a fresh build.
-* The build must reach the backend. A failed fetch fails the build.
+* The build must reach the backend. A failed fetch stops Next.js, TanStack
+  Start, SvelteKit and Vite builds. By default, Astro and Nuxt log a warning
+  instead and fetch the policy at runtime.
 * Consent choices still go to the backend.
 
 ## How manifest mode counts visitors

package/docs/customization/overview.md

@@ -67,8 +67,9 @@ policy requires, c15t puts it back.
   dark first paint.
 * [Motion and animation](./motion.md): duration and easing
   tokens, `disableAnimation` and reduced motion.
-* [Stylesheets and CSS layers](./stylesheets.md): which file to
-  load, when the dialog's CSS loads, and how to run without c15t's styles.
+* [Stylesheets and CSS layers](./stylesheets.md): how c15t
+  loads its rules, when to import `styles.css` yourself, when the dialog's CSS
+  loads, and how to run without c15t's styles.
 * [Component parts](./slots.md): every part, its keys in each
   framework, and the `data-*` attributes to select on.
 * [Class names and CSS-in-JS](./class-names.md): CSS Modules,

package/docs/customization/stylesheets.md

@@ -1,45 +1,145 @@
 ---
 title: Stylesheets and CSS layers
-description: Load the right c15t stylesheet for your framework, see which file
-  holds the dialog's rules, order c15t's cascade layer against your own, and run
-  c15t without its styles.
+description: See how c15t delivers its styles in each framework without a
+  render-blocking stylesheet, when to import styles.css yourself with styles
+  false, which file holds the dialog's rules, and how c15t's cascade layer meets
+  your own.
 group: customization
 ---
 
-## Load one stylesheet for your framework
-
-| Framework         | What to load                     | Where                                                                |
-| ----------------- | -------------------------------- | -------------------------------------------------------------------- |
-| Next.js           | `c15t/next/styles.css`           | Your global stylesheet, or the layout that renders the consent root  |
-| TanStack Start    | `c15t/tanstack-start/styles.css` | A `<link>` from the root route's `head()`, or your global stylesheet |
-| React             | `c15t/react/styles.css`          | The module that renders `ConsentProvider`, or your global stylesheet |
-| Nuxt, Vue         | Nothing                          | Each Vue component imports its own stylesheet                        |
-| Astro             | Nothing                          | The integration adds `c15t/astro/styles.css` to every page           |
-| Svelte, SvelteKit | `@c15t/svelte/styles.css`        | Your entry module or root layout                                     |
-| HTML              | Nothing                          | `c15t.js` carries its stylesheet into the UI's shadow root           |
-| JavaScript        | Nothing                          | `init()` carries its stylesheet into the UI's shadow root            |
-
-Load it once. With IAB TCF in Next.js, TanStack Start, React, Svelte or
-SvelteKit, also load the adapter's `iab/styles.css`, such as
-`c15t/next/iab/styles.css`, after `styles.css`. Astro adds its IAB stylesheet
-when the integration sets `iab`. Tailwind 3 uses the same files and adds a
-PostCSS plugin; [Tailwind CSS](./tailwind.md#set-up-tailwind-css-3)
-shows the setup.
+## What each framework loads
+
+| Framework                      | What you import | How the styles arrive                                                                                                                                                                                                     |
+| ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start, React | Nothing         | Each stock surface renders the rules it uses as `<style>` elements                                                                                                                                                        |
+| Nuxt, Vue                      | Nothing         | Each Vue component imports its own stylesheet                                                                                                                                                                             |
+| Astro                          | Nothing         | `<ConsentScript />` inlines the banner's rules into the HTML. The client links the dialog's rules when a dialog first opens. On a Tailwind CSS 3 site, the integration adds `c15t/astro/styles.css` to every page instead |
+| Svelte                         | Nothing         | Each stock surface inserts the rules it uses into `<head>`                                                                                                                                                                |
+| SvelteKit                      | Nothing         | `c15tHandle` writes a server-rendered banner's rules into the HTML. The other surfaces insert theirs in the browser                                                                                                       |
+| HTML                           | Nothing         | `c15t.js` carries its stylesheet into the UI's shadow root                                                                                                                                                                |
+| JavaScript                     | Nothing         | `init()` carries its stylesheet into the UI's shadow root                                                                                                                                                                 |
+
+Inline c15t styles avoid a stylesheet request before the page's first paint.
+A linked stylesheet in `<head>` used to delay it by a round trip. With 4x
+CPU throttling, 1.6 Mbps download and 150 ms RTT, a Next.js page first painted
+at about 370 ms instead of 650 ms once the link was gone.
+
+Inline rules add bytes to each server-rendered HTML response. Enable HTTP
+compression on the production host to reduce their transfer cost. On repeat
+document visits, a cached external stylesheet can paint sooner than sending
+the inline rules again. To use that cache, keep the stylesheet imports and
+set `styles: false` as described below.
+
+Load `styles.css` yourself with Tailwind CSS 3 or a named cascade layer.
+[Import the stylesheet yourself](#import-the-stylesheet-yourself)
+covers those cases.
+
+## How the surfaces deliver their rules
+
+c15t splits its rules into two sheets. The first-paint sheet holds the
+default tokens, every c15t CSS variable, and the rules for the banner, the
+floating trigger and the `ConsentGate` placeholder. The dialog sheet holds the
+preference dialog's and the preference widget's rules.
+
+In React, Next.js and TanStack Start, `ConsentBanner`, `ConsentDialogTrigger`
+and the default `ConsentGate` placeholder render the first-paint sheet.
+`ConsentDialog` and `ConsentWidget` render it plus the dialog sheet. The
+dialog sheet ships with the dialog's lazily loaded code, so it is not part of
+the first page load. A server-rendered banner puts its rules in the HTML.
+
+`IABConsentBanner` also delivers the IAB variables and banner rules.
+`IABConsentDialog` adds the IAB dialog rules when it opens, including the
+shared rules it needs when rendered without a banner. IAB setups need no
+stylesheet imports with automatic styling enabled.
+
+Streamed React IAB banners become visible once their complete card markup
+arrives. This prevents the centered card from moving as the browser parses
+its remaining content, without waiting for hydration.
+
+* In React 19, React moves the elements into `<head>` and renders each sheet
+  once per page, as `<style data-precedence="c15t" data-href="c15t-first-paint">`.
+* In React 18, the elements render in place, next to the surface.
+* In React 19 with the provider's `nonce` option set, they also render in
+  place and carry the nonce. React drops the nonce of a style it moves to
+  `<head>` unless the app passed that nonce to React's server renderer.
+
+In Svelte, each stock surface inserts the sheets it uses into `<head>` as
+`<style data-c15t-styles="…">`, once per page, before its own elements
+render. The elements stay after the surface unmounts. The Svelte dialog's
+sheets, its rules and the primitives, load with the dialog's code.
+
+On a server-rendered SvelteKit page, the banner leaves a
+`<meta name="c15t-styles">` marker, and `c15tHandle` from `@c15t/svelte/kit`
+writes the sheets into the HTML `<head>` as `<style>` elements. The banner is
+styled before hydration with no stylesheet request. Without `c15tHandle` in
+`src/hooks.server.ts`, a server-rendered banner shows unstyled until
+hydration. The [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart)
+adds the handle.
+
+In Astro, `<ConsentScript />`, or the banner on a layout without it, inlines
+the first-paint sheet into the HTML as
+`<style data-c15t-styles="c15t-first-paint">` with the page nonce. When
+`tailwindcss` resolves to version 3 from the Astro root, the integration
+inlines nothing and adds `c15t/astro/styles.css` to every page through
+Astro's CSS pipeline, so the site's `c15t/postcss-tailwind3` plugin processes
+it. That stylesheet still holds back the first paint.
+
+The surfaces render no stylesheet with `noStyle`, or when the provider sets
+`styles: false`.
+
+## Import the stylesheet yourself
+
+Set `styles: false` in the provider options and import `styles.css` when you
+need control over the file:
+
+* **Tailwind CSS 3.** c15t's `<style>` rules sit in a native
+  `@layer components`, and Tailwind 3's unlayered preflight beats them. Import
+  `styles.css` through the `postcss-tailwind3` plugin instead, as
+  [Tailwind CSS](./tailwind.md#set-up-tailwind-css-3) shows.
+  Astro sites skip this: the integration detects Tailwind 3 and links the
+  stylesheet itself.
+* **A named cascade layer.** Import the stylesheet into your own layer, as in
+  [order c15t's layer against your CSS](#order-c15ts-layer-against-your-css).
+* **Cached styles across document visits.** Keep external CSS when its HTTP
+  cache performs better for your site's repeat visits. Compare cold and warm
+  visits on your production host before choosing this option.
+
+| Framework         | Option                                       | Files to import                                                                        |
+| ----------------- | -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Next.js           | `options.styles` on `ConsentRoot`            | `c15t/next/styles.css`, and `c15t/next/iab/styles.css` for IAB TCF                     |
+| TanStack Start    | `options.styles` on `ConsentRoot`            | `c15t/tanstack-start/styles.css`, and `c15t/tanstack-start/iab/styles.css` for IAB TCF |
+| React             | `options.styles` on `ConsentProvider`        | `c15t/react/styles.css`, and `c15t/react/iab/styles.css` for IAB TCF                   |
+| Svelte, SvelteKit | `options.styles` on `ConsentManagerProvider` | `@c15t/svelte/styles.css`, and `@c15t/svelte/iab/styles.css` for IAB TCF               |
+| Astro             | `styles` in the `c15t()` integration options | See [load Astro's stylesheets yourself](#load-astros-stylesheets-yourself)             |
+
+```tsx title="components/consent.tsx (partial)"
+<ConsentRoot
+	state={state}
+	config={consentConfig}
+	options={{ styles: false }}
+>
+```
+
+`styles: false` turns off only the stylesheets. Tokens from `ConsentTheme`
+and slot classes still apply.
+
+If you keep a `styles.css` import without `styles: false`, the surfaces still
+look right, but the rules ship twice and the stylesheet link still holds back
+the first paint. Remove the import, or add `styles: false` if you need it.
 
 ## Where the dialog's rules come from
 
-`styles.css` holds the default tokens, every c15t CSS variable and the rules
-for every stock surface: the banner, the floating trigger, the `ConsentGate`
-placeholder, the preference dialog and the preference widget. Only the IAB TCF
-surfaces need a second file, `iab/styles.css`.
+| Framework                      | The preference dialog's rules                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start, React | In the dialog sheet that `ConsentDialog` and `ConsentWidget` render. It ships with the dialog's lazily loaded code. With `styles: false`, in `styles.css`. No `@c15t/react` or `@c15t/ui` module imports CSS, so a Next.js app that uses only the Pages Router builds without `transpilePackages`                                                                                                                                           |
+| Nuxt, Vue                      | The dialog component imports its stylesheet, so the rules load with the dialog's code, not the banner's                                                                                                                                                                                                                                                                                                                                     |
+| Astro                          | In `@c15t/ui/styles/sheets/dialog.css`. The Svelte dialog, the default `ui`, also needs the primitives stylesheet. c15t links both when a visitor first points at, focuses or opens a control that opens the dialog, waits for them before it shows the dialog, and keeps them across `ClientRouter` navigation. On a Tailwind CSS 3 site, the dialog's rules are in `c15t/astro/styles.css`, and c15t links only the primitives stylesheet |
+| Svelte, SvelteKit              | In the dialog's sheets, which load with the dialog's code. With `styles: false`, in `@c15t/svelte/styles.css`                                                                                                                                                                                                                                                                                                                               |
+| HTML, JavaScript               | Part of the stylesheet in the shadow root, which holds only the rules the stock surfaces use                                                                                                                                                                                                                                                                                                                                                |
 
-| Framework                      | The preference dialog's rules                                                                                                                                                                                                                        |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js, TanStack Start, React | In `styles.css`. No `@c15t/react` or `@c15t/ui` module imports CSS, so a Next.js app that uses only the Pages Router builds without `transpilePackages`                                                                                              |
-| Nuxt, Vue                      | The dialog component imports its stylesheet, so the rules load with the dialog's code, not the banner's                                                                                                                                              |
-| Astro                          | In `c15t/astro/styles.css`. The Svelte dialog, the default `ui`, also needs the primitives stylesheet, which c15t links when a visitor first points at, focuses or opens a control that opens the dialog, and keeps across `ClientRouter` navigation |
-| Svelte, SvelteKit              | In `@c15t/svelte/styles.css`                                                                                                                                                                                                                         |
-| HTML, JavaScript               | Part of the stylesheet in the shadow root, which holds only the rules the stock surfaces use                                                                                                                                                         |
+`styles.css` still holds every stock surface's rules for apps that set
+`styles: false`. In that manual mode, IAB TCF also needs `iab/styles.css`
+after the base stylesheet.
 
 Earlier 3.0 alphas shipped the dialog's rules in `@c15t/ui/styles/dialog.css`,
 which the dialog's code imported. That file, the `@c15t/ui/styles/dialog`
@@ -49,8 +149,8 @@ imports keep resolving. Remove those imports.
 ## Order c15t's layer against your CSS
 
 c15t puts its component rules in the cascade layer `components`. Tokens,
-variables and keyframes stay unlayered. Each stylesheet opens with Tailwind
-CSS 4's layer order:
+variables and keyframes stay unlayered. Each stylesheet, and each `<style>`
+element the surfaces render, opens with Tailwind CSS 4's layer order:
 
 ```css
 @layer properties, theme, base, components, utilities;
@@ -71,18 +171,23 @@ What this means for your overrides:
   [theme tokens](./tokens.md).
 
 If your CSS declares its own layer order, load that statement before c15t's
-stylesheet. You can import c15t's stylesheet into a named layer, such as
+rules. To put c15t's rules in a named layer, set `styles: false` and import
+the stylesheet into that layer, such as
 `@import 'c15t/react/styles.css' layer(c15t)`. Its component rules then sit
 in `c15t.components`, so order `c15t` against your own layers.
 
 ## Load Astro's stylesheets yourself
 
-The Astro integration adds `c15t/astro/styles.css` to every page ahead of your
-own CSS. To control the order yourself, for example from a global stylesheet
-that names its own layers, set `styles: false` in the `c15t()` options and
-import the files after your layer order statement. With `styles: false`, c15t
-links no stylesheet when the dialog opens either. The Svelte dialog, the
-default `ui`, needs the primitives stylesheet next to `styles.css`:
+By default the Astro integration inlines the banner's rules into each page,
+including the IAB banner rules when it sets `iab`, and links the dialog's
+rules when a dialog opens. On a Tailwind CSS 3 site it adds
+`c15t/astro/styles.css` and, with IAB, `c15t/astro/iab/styles.css` to every
+page instead of inlining the banner's rules. To load the
+files yourself, for example from a global stylesheet that names its own
+layers, set `styles: false` in the `c15t()` options and import them after
+your layer order statement. With `styles: false`, c15t inlines no rules and
+links no stylesheet when the dialog opens. The Svelte dialog, the default
+`ui`, needs the primitives stylesheet next to `styles.css`:
 
 ```css title="src/styles/global.css"
 @import 'c15t/astro/styles.css';
@@ -92,9 +197,9 @@ default `ui`, needs the primitives stylesheet next to `styles.css`:
 @import 'c15t/astro/iab/styles.css';
 ```
 
-Keep c15t's stylesheet when you restyle the surfaces. The browser hides the
-Astro banner with the `hidden` attribute, and the stylesheet makes that
-attribute beat the banner's own `display` rule.
+Keep c15t's rules when you restyle the surfaces. The browser hides the Astro
+banner with the `hidden` attribute, and c15t's rules make that attribute beat
+the banner's own `display` rule.
 
 ## Style the script tag's shadow root
 
@@ -129,9 +234,17 @@ selector before you reach for `noStyle`.
 
 ## Check the result
 
-1. Open DevTools Network, clear site data and reload. Your framework's c15t
-   stylesheet loads once, and no second copy appears.
-2. Open the preference dialog. It is styled on its first frame, and in React,
-   Next.js and TanStack Start no new stylesheet request appears.
-3. Select a banner part and read the Styles panel. c15t's rules appear under
+1. Open DevTools Network, clear site data and reload. No c15t stylesheet
+   request appears before the first paint. In the HTML or the Elements panel,
+   `<head>` holds c15t's rules: `<style data-href="c15t-first-paint">` in
+   React 19, or a `<style data-c15t-styles>` element in Svelte, SvelteKit
+   and Astro. In React 18, or with a `nonce`, the `<style>` sits next to the
+   banner instead.
+2. Open the preference dialog. It is styled on its first frame. Opening it
+   adds the dialog's rules: a second `<style>` element in React, Next.js,
+   TanStack Start, Svelte and SvelteKit, or a linked
+   `@c15t/ui/styles/sheets/dialog.css` in Astro.
+3. With `styles: false`, your imported `styles.css` loads once, and no c15t
+   `<style>` element appears.
+4. Select a banner part and read the Styles panel. c15t's rules appear under
    `@layer components`, and your unlayered rules for the same property win.