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

package/docs/customization/tokens.md

@@ -1,88 +1,22 @@
 ---
-title: Theme tokens and CSS
-description: Style c15t with semantic tokens and use the stylesheet that matches
-  your CSS tooling.
+title: Theme tokens
+description: Change c15t's colors, type, radius, spacing, shadows and motion
+  with theme tokens, and see every --c15t-* variable with its default.
 group: customization
 ---
 
-## Load the stock stylesheet once
+## Where tokens come from
 
-React, Next.js and Svelte provide `styles.css`. Import the adapter's stylesheet
-at the app's global entry point. Vue includes styles in its components; Astro
-adds styles through its integration.
-
-The stylesheet blocks rendering, so it carries only what a first paint can
-show: the default tokens, every c15t CSS variable, and the rules for the
-banner, `ConsentDialogTrigger` and the `ConsentGate` placeholder. The consent
-dialog and preference widget bring their own rules. Each rule reaches the page
-once.
-
-```tsx
-import 'c15t/react/styles.css';
-```
-
-| File                             | Holds                                                                  | Loaded by                                                         |
-| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `styles.css` or `styles.tw3.css` | Default tokens, all variables, banner, trigger and `ConsentGate` rules | Your app, once                                                    |
-| `@c15t/ui/styles/dialog.css`     | Dialog and preference widget rules                                     | The dialog component, with its lazy chunk                         |
-| `@c15t/ui/styles/primitives.css` | Rules for the `@c15t/ui/styles/primitives` class maps                  | Svelte's `styles.css`, or your app if it renders those class maps |
-| `iab/styles.css`                 | IAB TCF banner and dialog rules and variables                          | Your app, after `styles.css`                                      |
-
-In React, Next.js and TanStack Start, the dialog's module imports
-`@c15t/ui/styles/dialog.css`. The bundler emits it with the dialog's chunk and
-loads it before that chunk runs, so the dialog never renders unstyled. The
-chunk loads after first paint, by the time the dialog first opens. Do not
-import `dialog.css` yourself. The `@c15t/react/components/consent-dialog`,
-`/components/consent-widget`, `/primitives`, `/primitives/*` and `/iab` entry
-points import it as soon as you import them, because they render dialog parts
-outside the lazy chunk.
-
-These modules import the stylesheet through `@c15t/ui/styles/dialog`. Under
-the `node` export condition that module imports nothing, so server code that
-loads `@c15t/react` with plain Node, such as the Pages Router or an SSR build
-that keeps dependencies external, does not fail on the `.css` file. In your
-own components, import `@c15t/ui/styles/dialog` rather than the `.css` file
-if the module can run on the server.
-
-Svelte loads its dialog with the page, so `c15t/svelte/styles.css` also
-imports the dialog and primitive rules. Astro injects the banner rules; the
-React and Svelte dialog islands import the rest, and Astro links those
-stylesheets on every page, so in Astro the dialog rules still block rendering.
-Vue components import their own stylesheets.
-
-The dialog rules sit in `@layer components` and declare no variables, so
-tokens from `theme`, variables you override in your own CSS, and Tailwind 4
-utilities still win over them even though they load later. If you import
-`styles.css` into a named layer, such as `@import 'c15t/react/styles.css'
-layer(c15t)`, the dialog rules still join the top-level `components` layer.
-List `components` in your layer order statement, for example
-`@layer c15t, components, app;`, so it does not land after your own layers.
-
-The standard stylesheet places rules in `@layer components`. For Tailwind 3,
-use the `styles.tw3.css` entry instead of the standard stylesheet, between the
-components and utilities directives in your Tailwind entry:
-
-```css
-@tailwind base;
-@tailwind components;
-@import 'c15t/react/styles.tw3.css';
-@tailwind utilities;
-```
-
-Tailwind 3 also processes the dialog stylesheet the bundler loads, and it
-rejects a stylesheet that uses `@layer components` without its own
-`@tailwind components` directive. Add the c15t plugin before `tailwindcss` in
-your PostCSS config. It removes the layer wrapper from c15t's stylesheets so
-Tailwind 3 accepts them and its preflight does not override them:
-
-```js title="postcss.config.mjs"
-export default {
-  plugins: ['@c15t/ui/postcss-tailwind3', 'tailwindcss', 'autoprefixer'],
-};
-```
-
-Do not load both c15t stylesheet variants. For Tailwind 4 or unlayered CSS,
-inspect layer order before reaching for `!important`.
+c15t's components take their colors from `--c15t-*` CSS variables, and most
+of their fonts, radii, spacing, shadows and motion too. c15t's stylesheet sets
+the defaults. You change them with a theme object or with CSS, and every part
+that reads a token changes with it. Some values are still fixed for one
+component, such as button padding, the radius of the "Secured by" tag and
+several font sizes and weights, so a token change does not move them. Restyle
+those parts through [slots](./slots.md) or your own CSS.
+[Stylesheets and CSS layers](./stylesheets.md)
+covers which stylesheet to load, and [dark mode](./dark-mode.md)
+covers the dark set of tokens.
 
 ## Set semantic values together
 
@@ -94,27 +28,117 @@ readable in each state.
 import { defineTheme } from '@c15t/ui/theme';
 
 export const theme = defineTheme({
-  colors: { primary: '#2f6f4e' },
-  radius: { lg: '4px' },
-  consentActions: {
-    primary: { variant: 'primary', mode: 'filled' },
-    dismiss: { variant: 'neutral', mode: 'stroke' },
-  },
+	colors: { primary: '#2f6f4e' },
+	radius: { lg: '4px' },
+	consentActions: {
+		primary: { variant: 'primary', mode: 'filled' },
+		dismiss: { variant: 'neutral', mode: 'stroke' },
+	},
 });
 ```
 
-Install `@c15t/ui` if importing its theme helper directly. The browser does
-not turn tokens into CSS. In React and Next.js, render
-`<ConsentTheme theme={theme} />` where the app renders on the server, and pass
-`theme` in your provider options for `consentActions`. Elsewhere, call
-`generateThemeCSS(theme)` from `@c15t/ui/theme` on the server or at build time
-and put the result in a `<style>` element or your stylesheet. See
-[React styling](https://c15t.com/docs/frameworks/react/styling/overview) and
-[Next.js styling](https://c15t.com/docs/frameworks/next/styling/overview).
+Install `@c15t/ui` if importing its theme helper directly. Where the theme
+goes depends on the framework:
+
+| Framework                      | Tokens                                                                                                                            | `consentActions`                    |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| Next.js, TanStack Start, React | `<ConsentTheme theme={theme} />`, rendered on the server where the app has one                                                    | `theme` in the provider options     |
+| Nuxt, Vue                      | `theme` or `tokens` in the module or plugin options                                                                               | Not available                       |
+| Astro                          | `theme` in the integration options                                                                                                | The same `theme`                    |
+| Svelte, SvelteKit              | `generateThemeCSS(theme)` from `@c15t/ui/theme` on the server, in a `<style>` element, or `--c15t-*` variables in your stylesheet | `theme` on `ConsentManagerProvider` |
+| HTML, JavaScript               | `ui.theme`                                                                                                                        | Not available                       |
+
+React and Svelte providers do not turn tokens in their `theme` option into
+CSS, and warn in development when a theme holds tokens but the page has no
+`<style id="c15t-theme">`. Your framework's customize page shows the full
+setup.
 
 `consentActions` selects styling by action role. A per-action entry overrides
 `primary`, which overrides `default`.
 
+## Combine a generated theme with your own CSS
+
+`generateThemeCSS` writes its variables on `:root:root` and
+`.c15t-theme-root.c15t-theme-root`, one step more specific than the defaults
+in `styles.css`. The theme therefore overrides the defaults whether its
+`<style>` element comes before or after the stylesheet. The same output backs
+`ConsentTheme` in React, Next.js and TanStack Start, Astro's `theme` option and
+the script tag's `ui.theme`.
+
+A `--c15t-*` variable you set on plain `:root` in your own CSS loses to a
+generated theme that sets the same variable, even when your rule loads later.
+Put the value in the theme, or raise your selector:
+
+```css
+:root:root {
+  --c15t-primary: #2f6f4e;
+}
+```
+
+Scoped rules such as `[data-prompt] { --c15t-primary: ... }` set the variable
+on the banner element itself, so they still apply inside it.
+
+## Every token
+
+Every framework uses the same tokens. A theme object, such as `ConsentTheme`'s
+`theme`, Astro's and Vue's `theme` or the script tag's `ui.theme`, takes the
+theme key, such as `radius.lg`. Vue and Nuxt `tokens` take the CSS variable
+name without the leading `--`, such as `c15t-radius-lg`. A stylesheet sets the
+CSS variable itself. Your framework's customize page shows where each one goes.
+[Motion and animation](./motion.md) explains the duration and
+easing tokens.
+
+| CSS variable                  | Theme key                        | Default                                         |
+| ----------------------------- | -------------------------------- | ----------------------------------------------- |
+| `--c15t-primary`              | `colors.primary`                 | `hsl(228, 100%, 60%)`                           |
+| `--c15t-primary-hover`        | `colors.primaryHover`            | `hsl(228, 100%, 55%)`                           |
+| `--c15t-surface`              | `colors.surface`                 | `hsl(0, 0%, 100%)`                              |
+| `--c15t-surface-hover`        | `colors.surfaceHover`            | `hsl(0, 0%, 98%)`                               |
+| `--c15t-border`               | `colors.border`                  | `hsl(0, 0%, 90%)`                               |
+| `--c15t-border-hover`         | `colors.borderHover`             | `hsl(0, 0%, 85%)`                               |
+| `--c15t-text`                 | `colors.text`                    | `hsl(0, 0%, 10%)`                               |
+| `--c15t-text-muted`           | `colors.textMuted`               | `hsl(0, 0%, 40%)`                               |
+| `--c15t-text-on-primary`      | `colors.textOnPrimary`           | auto-derived from `colors.primary` when omitted |
+| `--c15t-overlay`              | `colors.overlay`                 | `hsla(0, 0%, 0%, 0.5)`                          |
+| `--c15t-switch-track`         | `colors.switchTrack`             | `hsl(0, 0%, 85%)`                               |
+| `--c15t-switch-track-active`  | `colors.switchTrackActive`       | `hsl(228, 100%, 60%)`                           |
+| `--c15t-switch-thumb`         | `colors.switchThumb`             | `hsl(0, 0%, 100%)`                              |
+| `--c15t-font-family`          | `typography.fontFamily`          | `system-ui, -apple-system, sans-serif`          |
+| `--c15t-font-size-sm`         | `typography.fontSize.sm`         | `0.875rem`                                      |
+| `--c15t-font-size-base`       | `typography.fontSize.base`       | `1rem`                                          |
+| `--c15t-font-size-lg`         | `typography.fontSize.lg`         | `1.125rem`                                      |
+| `--c15t-font-weight-normal`   | `typography.fontWeight.normal`   | `400`                                           |
+| `--c15t-font-weight-medium`   | `typography.fontWeight.medium`   | `500`                                           |
+| `--c15t-font-weight-semibold` | `typography.fontWeight.semibold` | `600`                                           |
+| `--c15t-line-height-tight`    | `typography.lineHeight.tight`    | `1.25`                                          |
+| `--c15t-line-height-normal`   | `typography.lineHeight.normal`   | `1.5`                                           |
+| `--c15t-line-height-relaxed`  | `typography.lineHeight.relaxed`  | `1.75`                                          |
+| `--c15t-space-xs`             | `spacing.xs`                     | `0.25rem`                                       |
+| `--c15t-space-sm`             | `spacing.sm`                     | `0.5rem`                                        |
+| `--c15t-space-md`             | `spacing.md`                     | `1rem`                                          |
+| `--c15t-space-lg`             | `spacing.lg`                     | `1.5rem`                                        |
+| `--c15t-space-xl`             | `spacing.xl`                     | `2rem`                                          |
+| `--c15t-radius-sm`            | `radius.sm`                      | `0.25rem`                                       |
+| `--c15t-radius-md`            | `radius.md`                      | `0.5rem`                                        |
+| `--c15t-radius-lg`            | `radius.lg`                      | `0.75rem`                                       |
+| `--c15t-radius-full`          | `radius.full`                    | `9999px`                                        |
+| `--c15t-shadow-sm`            | `shadows.sm`                     | `0 1px 2px hsla(0, 0%, 0%, 0.05)`               |
+| `--c15t-shadow-md`            | `shadows.md`                     | `0 4px 12px hsla(0, 0%, 0%, 0.08)`              |
+| `--c15t-shadow-lg`            | `shadows.lg`                     | `0 8px 24px hsla(0, 0%, 0%, 0.12)`              |
+| `--c15t-duration-fast`        | `motion.duration.fast`           | `80ms`                                          |
+| `--c15t-duration-normal`      | `motion.duration.normal`         | `150ms`                                         |
+| `--c15t-duration-slow`        | `motion.duration.slow`           | `200ms`                                         |
+| `--c15t-easing`               | `motion.easing`                  | `cubic-bezier(0.4, 0, 0.2, 1)`                  |
+| `--c15t-easing-out`           | `motion.easingOut`               | `cubic-bezier(0.215, 0.61, 0.355, 1)`           |
+| `--c15t-easing-in-out`        | `motion.easingInOut`             | `cubic-bezier(0.645, 0.045, 0.355, 1)`          |
+| `--c15t-easing-spring`        | `motion.easingSpring`            | `cubic-bezier(0.34, 1.56, 0.64, 1)`             |
+
+The radius tokens round different parts. `radius.lg` rounds the banner card,
+the preference dialog, `ConsentGate` placeholders and the floating trigger.
+`radius.md` rounds buttons, accordions, tabs and the vendor list.
+`radius.sm` rounds small parts inside the banner and dialog. To give the banner
+and its buttons the same 4px corners, set both `lg` and `md`.
+
 ## Target a prompt with CSS
 
 ```css
@@ -126,8 +150,9 @@ and put the result in a `<style>` element or your stylesheet. See
 ```
 
 Use attributes exposed by the rendered component, not guessed class names.
-Test the prompt and the preferences dialog separately because tokens scoped to
-one prompt do not automatically reach a portaled dialog.
+The script tag's banner has no `data-prompt` or `data-model`. Test the prompt
+and the preferences dialog separately because tokens scoped to one prompt do
+not automatically reach a portaled dialog.
 
 | Size variable                       | Default | Target        |
 | ----------------------------------- | ------- | ------------- |
@@ -135,5 +160,47 @@ one prompt do not automatically reach a portaled dialog.
 | `--consent-banner-widget-max-width` | `20rem` | Widget        |
 | `--consent-banner-wall-max-width`   | `30rem` | Choice wall   |
 
+The banner footer lays out its actions by the card's width, not the
+viewport's. With the default `compact` profile, a card narrower than 22rem
+puts Reject and Accept on one row and Customize on a full-width row below
+them, on any screen size.
+
 Test long translations and small screens after changing width or typography.
 A compact banner must still fit the required actions.
+
+## Restyle the "Secured by" tag
+
+The tag sits on the edge of the banner and dialog cards and uses the primary
+color by default. Set these variables on `:root`, or on an element that
+contains the tag. The dialog renders in a portal, so a variable set on the
+banner does not reach the dialog's tag.
+
+| Variable                                     | Default                                 | Target                                 |
+| -------------------------------------------- | --------------------------------------- | -------------------------------------- |
+| `--consent-branding-tag-background-color`    | `var(--c15t-primary)`                   | Tag background                         |
+| `--consent-branding-tag-border-color`        | `--c15t-primary` mixed 14% toward black | Tag border                             |
+| `--consent-branding-tag-text-color`          | `var(--c15t-text-on-primary, #fff)`     | "Secured by" and the wordmark          |
+| `--consent-branding-tag-mark-color`          | The text color                          | c15t mark or inth logo                 |
+| `--consent-branding-tag-shadow`              | Inset highlight and a 1px drop shadow   | Tag shadow                             |
+| `--consent-branding-tag-attached-edge-width` | `0px`                                   | Border on the edge that meets the card |
+
+The stylesheet does not declare these variables. Each default resolves on the
+tag, so a `--c15t-primary` you scope to a banner still colors the tag.
+
+This makes the tag look like a tab of the card:
+
+```css
+:root {
+  --consent-branding-tag-background-color: var(--c15t-surface);
+  --consent-branding-tag-border-color: var(--c15t-border);
+  --consent-branding-tag-text-color: var(--c15t-text-muted);
+  --consent-branding-tag-mark-color: var(--c15t-primary);
+  --consent-branding-tag-shadow: none;
+}
+```
+
+The edge that meets the card has no border by default. Above the banner the
+tag overlaps the card's top border by 1px and covers it. Below the dialog the
+tag starts under the card's bottom border. Set
+`--consent-branding-tag-attached-edge-width: 1px` to draw that edge. It is
+drawn over the card's border, so the two borders do not stack.

package/docs/customization/translations.md

@@ -27,9 +27,25 @@ i18n: {
 
 Supply the same message keys in each supported locale. A one-off component prop
 such as `dismissButtonText` is useful for one banner; use translations for a
-site-wide change. Astro's serializable integration options and Vue's module
-configuration have their own types, so verify those shapes before copying a
-React object.
+site-wide change. Astro's serializable integration options have their own
+types, so verify that shape before copying a React object. The Vue plugin and
+Nuxt module have no `i18n` option; their copy comes from the backend.
+
+## Combine messages with backend copy
+
+With a backend or a manifest, the copy it sends for the visitor's language is
+the base. Your `i18n.messages` for that language replace it key by key, and
+keys you leave out keep the backend's wording, including copy edited in your
+Inth project. c15t looks up messages for the exact language first, then for
+its primary language, so `de-AT` uses your `de` messages when there is no
+`de-AT` entry. Messages for other languages are not applied.
+
+A key only overrides the backend when your text differs from c15t's built-in
+wording for that language. So passing the stock bundles from
+`@c15t/translations/all` to enable languages keeps backend edits visible,
+while a key you actually reworded stays pinned in code. Core bundles only
+English; for other languages, import `@c15t/translations/all` so c15t can
+recognize its stock wording.
 
 ## Write labels that describe the action
 
@@ -41,6 +57,47 @@ The notice acknowledgement uses `common.acknowledge`, with `common.dismiss` as
 a fallback for older translation bundles. Keep the displayed label and the
 command's effect aligned.
 
+## Translate the ConsentGate placeholder
+
+The `ConsentGate` placeholder reads the `consentGate` section:
+
+| Key                         | Where it shows                                                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `consentGate.title`         | The placeholder text. `{category}` is replaced by the category's translated title.                                  |
+| `consentGate.actionButton`  | The button that opens preferences, with the same `{category}` replacement.                                          |
+| `consentGate.policyBlocked` | React and Vue show it in place of the title, with no button, when a strict policy leaves the category out of scope. |
+
+Earlier versions called this section `frame`. Copy under `frame` in
+`i18n.messages` or custom translations still applies. c15t reads it as `consentGate`, a key set under `consentGate`
+wins over the same key under `frame`, and c15t logs a warning once outside
+production. Rename the section to `consentGate` to remove the warning.
+
+## Show right-to-left languages
+
+c15t sets `dir="rtl"` on its surfaces when the resolved language is Arabic,
+Hebrew, Persian, Urdu, Pashto, Sindhi, Kurdish or Dhivehi. It matches the
+primary language, so `ar-EG` counts as Arabic. Hebrew is the only
+right-to-left translation c15t ships. For the others, supply your own
+messages or the copy from your Inth project.
+
+What follows the direction:
+
+* Text, headings and the button row in the banner, the preference dialog and
+  the preference widget flow right to left.
+* A floating or widget banner in its default corner moves to the mirrored
+  corner, so `bottom-left` becomes `bottom-right`. A `position` you set
+  yourself stays where you put it.
+* The HTML script tag, `@c15t/browser` and Astro's banner also set `lang` on
+  their surfaces. React, Vue and Svelte set `dir` only, so set `lang` on
+  `<html>` yourself.
+
+What does not follow yet:
+
+* The IAB TCF dialog aligns several labels, indents and borders to the left.
+* The floating `ConsentDialogTrigger` keeps the corner you give it.
+
+Test right-to-left pages with a real translation before you ship them.
+
 ## Test more than English
 
 Try the longest labels you support at a narrow width, with browser zoom and

package/docs/frameworks/astro/embeds.md

@@ -0,0 +1,160 @@
+---
+title: Embeds
+description: Gate YouTube videos, maps, social posts and other iframes on an
+  Astro site so they load only after the visitor allows their consent category,
+  with a custom element or the c15t iframe blocker.
+group: frameworks
+---
+
+## Why an embed needs gating
+
+An iframe sends requests to its host as soon as it is in the page with a
+`src`, before any script can stop it. `ConsentBanner` does not block iframes
+you already have. Render an embed only while its category is allowed, and
+remove it when the visitor withdraws permission.
+
+Astro has no consent gate component. Use one of these:
+
+| Approach                                                | Use it when                                                |
+| ------------------------------------------------------- | ---------------------------------------------------------- |
+| A custom element that renders the iframe                | You want a placeholder with a button in place of the embed |
+| The iframe blocker, with `data-category` and `data-src` | You have iframe markup to gate as it is                    |
+
+## Gate an embed with a custom element
+
+This component shows a placeholder with a preferences button until
+measurement is allowed. It adds the iframe once the visitor allows
+measurement, and removes it when permission is withdrawn. It also keeps the
+iframe out while the visitor has switched YouTube off in
+[vendor consent](https://c15t.com/docs/frameworks/astro/vendor-consent).
+
+The component reads `client.isVendorAllowed('youtube')`, so declare `youtube`
+in the `vendors` option of `c15t()` with `category: 'measurement'`. An
+undeclared vendor reads as not allowed, and the video never loads:
+
+```astro title="src/components/consent-video.astro"
+---
+import ConsentDialogTrigger from 'c15t/astro/components/consent-dialog-trigger.astro';
+---
+
+<consent-video>
+	<div data-video>
+		<p>Allow measurement to load this YouTube video.</p>
+	</div>
+	<ConsentDialogTrigger>Open privacy settings</ConsentDialogTrigger>
+</consent-video>
+
+<script>
+	import { getConsentClient } from 'c15t/astro/client';
+
+	class ConsentVideo extends HTMLElement {
+		dispose?: () => void;
+
+		connect = () => {
+			const client = getConsentClient();
+			const container = this.querySelector('[data-video]');
+			if (this.dispose || !client || !container) {
+				return;
+			}
+			const render = () => {
+				// Measurement is allowed and the visitor has not switched YouTube
+				// off. An undeclared vendor is never allowed, so declare youtube.
+				if (!client.isVendorAllowed('youtube')) {
+					container.textContent =
+						'Allow measurement to load this YouTube video. No video request is sent before permission.';
+					return;
+				}
+				if (container.querySelector('iframe')) {
+					return;
+				}
+				const frame = document.createElement('iframe');
+				frame.src = 'https://www.youtube-nocookie.com/embed/czTksCF6X8Y';
+				frame.title = 'YouTube video';
+				frame.allowFullscreen = true;
+				container.replaceChildren(frame);
+			};
+			render();
+			this.dispose = client.subscribe(render);
+		};
+
+		connectedCallback() {
+			// c15t boots from a module script, which can run after this one.
+			document.addEventListener('DOMContentLoaded', this.connect, {
+				once: true,
+			});
+			this.connect();
+		}
+
+		disconnectedCallback() {
+			document.removeEventListener('DOMContentLoaded', this.connect);
+			this.dispose?.();
+			this.dispose = undefined;
+		}
+	}
+
+	if (!customElements.get('consent-video')) {
+		customElements.define('consent-video', ConsentVideo);
+	}
+</script>
+```
+
+Use it like any Astro component. How it works:
+
+* The iframe does not exist in the server HTML, so nothing loads before
+  consent, even before the consent runtime starts.
+* `client.subscribe(render)` renders again on every consent change.
+* `connectedCallback` runs again when `ClientRouter` swaps in a page that
+  contains the element, so the embed works across navigation.
+* The first `connect()` can run before c15t has started, so the element tries
+  again on `DOMContentLoaded`.
+
+Change the category, the iframe `src` and the placeholder text for other
+embeds. The [YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides use the same pattern with
+a reusable browser helper. [Integrations](../../integrations/overview.md) lists
+the other vendors.
+
+## Gate existing iframe markup
+
+The consent runtime includes an iframe blocker, on by default. Mark an iframe
+with a category and move its URL from `src` to `data-src`:
+
+```html title="src/pages/contact.astro (partial)"
+<iframe
+  data-category="marketing"
+  data-src="https://www.google.com/maps/embed?pb=..."
+  title="Office location"
+></iframe>
+```
+
+When the category is allowed, the blocker copies `data-src` to `src`. When it
+is withdrawn, the blocker removes `src` again. `data-vendor` gates the iframe
+on one vendor as well. See [vendor consent](https://c15t.com/docs/frameworks/astro/vendor-consent).
+
+Always use `data-src`, never `src`, for a gated iframe. The browser starts
+loading a `src` from the HTML before the blocker runs, so an iframe with `src`
+in the markup loads before consent.
+
+The blocker watches the whole document, so it also gates iframes on pages you
+reach with `ClientRouter`, which replaces `<body>` on each navigation.
+
+## Gate an embed on the server
+
+On a server-rendered page, `Astro.locals.c15t.snapshot.effectivePermissions`
+tells you whether the visitor had allowed the category when the request
+arrived. Rendering the iframe on the server from it works for returning
+visitors. A visitor who allows the category on the page sees the embed only
+after the next navigation, so pair it with the custom element, or use the
+custom element alone. See [Server API](https://c15t.com/docs/frameworks/astro/server).
+
+## Check the embeds
+
+1. Open the page in a private window with DevTools Network open. There is no
+   request to the embed's host, and no iframe from it in the Elements panel.
+2. Allow the embed's category from **Cookie preferences**. The iframe appears
+   and loads.
+3. Reload. The iframe loads again without a new choice.
+4. Withdraw the category and save. The page reloads, and the embed's host
+   gets no request.
+
+See [Verify consent](../../guides/verify-consent.md) for the full checklist.

package/docs/frameworks/astro/network-blocker.md

@@ -0,0 +1,86 @@
+---
+title: Network blocker
+description: Block fetch and XMLHttpRequest calls to tracking hosts on an Astro
+  site until the visitor allows their consent category, with c15t's network
+  blocker rules and an onRequestBlocked handler.
+group: frameworks
+---
+
+## What the network blocker does
+
+`networkBlocker` stops `fetch` and `XMLHttpRequest` calls that match a rule
+until the visitor allows the rule's category. A blocked `fetch` resolves to a
+`451` response, and nothing is sent. It covers requests that code already on
+the page makes, such as an SDK you load yourself or a tag manager's own calls.
+
+It does not stop `navigator.sendBeacon`, WebSockets, image pixels, `<script>`
+tags or iframes. Load scripts through c15t and gate iframes as
+[Scripts](./scripts.md) and
+[Embeds](./embeds.md) describe.
+
+## Add rules
+
+Rules are plain data, so they can go in the integration options:
+
+```js title="astro.config.mjs (partial)"
+c15t({
+	mode: hosted({ url: 'https://your-project.inth.app' }),
+	networkBlocker: {
+		rules: [
+			{ category: 'measurement', domain: 'google-analytics.com' },
+			{
+				category: 'marketing',
+				domain: 'ads.example.com',
+				pathIncludes: '/collect',
+				methods: ['POST'],
+			},
+		],
+	},
+});
+```
+
+| Rule field     | Effect                                                            |
+| -------------- | ----------------------------------------------------------------- |
+| `category`     | The category that must be allowed for the request to go through   |
+| `domain`       | The host to match. It also matches every subdomain                |
+| `pathIncludes` | Matches only URLs whose path contains this text                   |
+| `methods`      | Matches only these HTTP methods                                   |
+| `vendor`       | Also requires this vendor to be allowed, for vendor-level consent |
+
+| Option               | Default  | Effect                                                              |
+| -------------------- | -------- | ------------------------------------------------------------------- |
+| `rules`              | Required | The rules to apply                                                  |
+| `enabled`            | `true`   | Set `false` to keep the rules but stop blocking                     |
+| `logBlockedRequests` | `true`   | Logs each blocked request to the console. Set `false` to silence it |
+
+The blocker starts with the consent runtime, from a module script. A request
+made before that, such as from an inline script at the top of `<head>`, is not
+blocked.
+
+## Log or report blocked requests
+
+`onRequestBlocked` is a function, so it cannot go in `astro.config.mjs`. Set
+`networkBlocker` in the default export of your client entrypoint instead. It
+replaces the integration's `networkBlocker` completely, so repeat the rules
+there:
+
+```ts title="src/consent-client.ts (partial)"
+export default {
+	scripts,
+	networkBlocker: {
+		rules: [{ category: 'measurement', domain: 'google-analytics.com' }],
+		onRequestBlocked: ({ url, rule }) => {
+			console.info('Blocked until consent:', url, rule?.category);
+		},
+	},
+} satisfies C15tClientOptionsExtension;
+```
+
+## Check the network blocker
+
+1. Open the site in a private window with DevTools Network open, and trigger
+   the code that calls a blocked host. The request does not appear, and a
+   `fetch` receives a `451` response.
+2. Allow the rule's category. The next request to that host goes through.
+3. Withdraw the category and save. After the reload, requests to the host are
+   blocked again.