@c15t/astro 3.0.0-alpha.0

package/dist-types/ui/svelte.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The Svelte dialog surface.
+ *
+ * Svelte 5 compiles to close to hand-written DOM code, so a Svelte island is
+ * the smallest way to get a real preference centre onto an Astro page
+ * without shipping a framework runtime to visitors who never open one.
+ * Mounting happens on the first open through `mount()`, so the import cost
+ * is paid only by people who click "Customize".
+ *
+ * The island itself is registered by `<ConsentDialog />` rather than
+ * imported here: a `.svelte` file can only be compiled by the consuming
+ * app's build, and keeping the specifier in the `.astro` component is what
+ * lets that build see it.
+ *
+ * The provider inside the island renders against the page runtime through
+ * its `runtime` prop, so there is one kernel per page no matter how many
+ * islands, scripts or frameworks read it.
+ */
+import type { ConsentDialogAdapter } from './adapter';
+/** The Svelte 5 dialog surface implementation. */
+export declare const svelteDialogAdapter: ConsentDialogAdapter;

package/dist-types/ui/vue.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Vue dialog surface.
+ *
+ * Same trade as the React adapter: a site already running Vue reuses that
+ * runtime for the preference centre instead of downloading Svelte for one
+ * dialog. Sites on neither should stay on the default.
+ *
+ * The island is mounted as its own Vue app rather than grafted onto the
+ * host app — Astro islands never share an app instance. The consent state
+ * lives on the page runtime, which the `c15tVue` plugin borrows: it builds
+ * no kernel of its own and disposes nothing.
+ *
+ * The island itself is registered by the integration rather than imported
+ * here: a `.vue` file can only be compiled by the consuming app's build,
+ * and only that build knows whether `@astrojs/vue` is present.
+ */
+import type { ConsentDialogAdapter } from './adapter';
+/** The Vue 3 dialog surface implementation. */
+export declare const vueDialogAdapter: ConsentDialogAdapter;

package/docs/README.md

@@ -0,0 +1,86 @@
+# @c15t/astro
+
+> Astro v3 static and server integration, dialog adapters and runtime ownership.
+
+These docs ship inside the package so coding agents can read them offline. Open the topic file you need from the list below — paths are relative to this file.
+
+## Using these docs
+
+These docs describe v3. Start with Inth hosted setup, identify the framework, router and deployment, then read its quickstart. Static sites can use Inth directly. Use page Markdown and package-bundled docs for targeted context. Verify scripts, rejection, reload and preferences; banner visibility alone is insufficient.
+
+## Start here
+
+- [Astro quickstart](./frameworks/astro/quickstart.md)
+- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
+- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.
+
+## More documentation
+
+[Documentation index](https://c15t.com/docs/llms.txt) · [Full Markdown context](https://c15t.com/llms-full.txt). Prefer the index and individual pages for focused tasks.
+
+## Frameworks
+
+- [Quickstart](./frameworks/astro/quickstart.md): Add c15t to static or server-rendered Astro pages and choose the framework used by preference dialogs.
+
+## Guides
+
+- [Understand consent state](./guides/consent-state.md): Distinguish policy resolution, effective permissions, explicit choices, notices and privacy signals.
+- [Data fetching and transports](./guides/data-fetching.md): Choose cached manifests, backend init or offline policy resolution, and understand where consent records are saved.
+- [Choose a deployment mode](./guides/deployment-modes.md): Choose who runs your consent backend, then select manifest, init or offline resolution for your deployment.
+- [Troubleshoot consent](./guides/troubleshooting.md): Diagnose missing banners, early vendor requests, lost choices and hydration differences.
+- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
+
+## Customization
+
+- [Customize your consent interface](./customization/overview.md): Choose presentation, theme tokens, slots or custom markup for the change you need.
+- [Banner styling recipes](./customization/recipes.md): See real v3 components and reuse the exact theme configuration behind the examples.
+- [Style component slots](./customization/slots.md): Target a specific c15t component part without replacing its markup or behavior.
+- [Theme tokens and CSS](./customization/tokens.md): Style c15t with semantic tokens and use the stylesheet that matches your CSS tooling.
+- [Copy and translations](./customization/translations.md): Change consent wording through i18n and test the complete prompt and preferences flow.
+
+## Integrations
+
+- [Adobe Analytics](./integrations/adobe-analytics.md): Configure Adobe Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Amplitude](./integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
+- [Custom integrations](./integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
+- [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
+- [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
+- [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
+- [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
+- [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
+- [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
+- [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
+- [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.
+- [Intercom](./integrations/intercom.md): Load the Intercom messenger with functionality permission and configure its region.
+- [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Configure LinkedIn Insight Tag with c15t v3, understand marketing permission and verify loading and revocation.
+- [LogRocket](./integrations/logrocket.md): Configure LogRocket with c15t v3, understand measurement permission and verify loading and revocation.
+- [Matomo Analytics](./integrations/matomo-analytics.md): Choose gated loading or Matomo consent signaling and configure the correct tracker endpoints.
+- [Meta Pixel](./integrations/meta-pixel.md): Register the Meta Pixel under marketing permission and verify event calls after revocation.
+- [Microsoft Clarity](./integrations/microsoft-clarity.md): Configure Microsoft Clarity with c15t v3, understand measurement permission and verify loading and revocation.
+- [Microsoft UET](./integrations/microsoft-uet.md): Configure Microsoft UET with c15t v3, understand marketing permission and verify loading and revocation.
+- [Mixpanel](./integrations/mixpanel-analytics.md): Configure Mixpanel with c15t v3, understand measurement permission and verify loading and revocation.
+- [OpenAI Pixel](./integrations/openai-pixel.md): Configure the OpenAI Measurement Pixel for ChatGPT Ads with c15t v3, manage marketing permission and verify conversion delivery.
+- [Overview](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, chat and embedded content.
+- [Pirsch](./integrations/pirsch.md): Configure Pirsch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Plausible Analytics](./integrations/plausible-analytics.md): Configure Plausible Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [PostHog](./integrations/posthog.md): Choose PostHog loading and cookieless behavior, configure the region, and synchronize v3 permissions.
+- [Promptwatch](./integrations/promptwatch.md): Configure Promptwatch with c15t v3, understand measurement permission and verify loading and revocation.
+- [Reddit Pixel](./integrations/reddit-pixel.md): Configure Reddit Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [RudderStack](./integrations/rudderstack.md): Gate the RudderStack browser SDK or map c15t categories to destination consent IDs.
+- [Rybbit Analytics](./integrations/rybbit-analytics.md): Configure Rybbit Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Segment](./integrations/segment.md): Configure Segment with c15t v3, understand measurement permission and verify loading and revocation.
+- [Snapchat Pixel](./integrations/snapchat-pixel.md): Configure Snapchat Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [TikTok Pixel](./integrations/tiktok-pixel.md): Configure TikTok Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [Umami Analytics](./integrations/umami-analytics.md): Configure Umami Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [Vercel Analytics](./integrations/vercel-analytics.md): Configure Vercel Analytics with c15t v3, understand measurement permission and verify loading and revocation.
+- [X Pixel](./integrations/x-pixel.md): Configure X Pixel with c15t v3, understand marketing permission and verify loading and revocation.
+- [YouTube](./integrations/youtube.md): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
+
+## Reference
+
+- [Upgrade to v3 policies](./upgrade-v3.md): Migrate policy configuration, consent records, callbacks, and custom transports to the v3 policy system.

package/docs/customization/overview.md

@@ -0,0 +1,45 @@
+---
+title: Customize your consent interface
+description: Choose presentation, theme tokens, slots or custom markup for the
+  change you need.
+group: customization
+---
+
+## Start with the change you want
+
+| Change                                    | Use                                 | Why                                                          |
+| ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------ |
+| Banner shape or location                  | Presentation or banner props        | Keeps policy actions and built-in layout behavior            |
+| Brand colors, radius, typography, spacing | Theme tokens                        | Changes related component parts together                     |
+| One card, footer, title or button group   | Component slots                     | Targets existing markup                                      |
+| Labels, descriptions or language          | i18n configuration                  | Keeps banner and preferences copy consistent                 |
+| A different component structure           | Compound components where available | Retains the component behavior while changing markup         |
+| Your own interaction and markup           | Headless APIs                       | You own rendering, focus behavior and policy action coverage |
+
+Most brand changes need tokens and a few slots. Start there before opting out
+of the stock styles. The [recipes](./recipes.md) show how each
+choice affects a real banner.
+
+## Keep behavior and appearance separate
+
+Presentation controls the prompt's shape, position and blocking behavior.
+Policy controls which actions and rights are required. Changing colors or button
+order does not change a saved choice or policy scope.
+
+A choice wall always blocks. Notices never block and cannot become a wall merely
+because `variant: 'wall'` was requested. Preference dialogs remain centered;
+prompt positioning does not move them. Required actions omitted from a custom
+layout can be restored by the policy renderer.
+
+## Use the adapter's configuration shape
+
+React and Next.js accept provider `theme`, `presentation` and `components`
+options. Vue and Nuxt expose their own shared configuration, including CSS
+`tokens` and component slots. Svelte accepts its provider options and theme
+contract. Astro serializes integration options and uses the selected adapter for
+dialogs. Do not move a configuration object between frameworks without checking
+the target types.
+
+Read [tokens and CSS](./tokens.md),
+[slots](./slots.md) or
+[copy and translations](./translations.md) for the next step.

package/docs/customization/recipes.md

@@ -0,0 +1,79 @@
+---
+title: Banner styling recipes
+description: See real v3 components and reuse the exact theme configuration
+  behind the examples.
+group: customization
+---
+
+## A branded floating card
+
+This theme uses a green primary action and a four-pixel large radius. Accept and
+Reject keep matching treatment. The component's required action behavior stays
+intact.
+
+![A v3 floating consent card with green Customize action, matching Accept and Reject buttons, and compact corners](../assets/v3/brand-card.png)
+
+```ts
+import { defineTheme } from '@c15t/ui/theme';
+
+export const brandTheme = defineTheme({
+	colors: { primary: '#2f6f4e' },
+	consentActions: {
+		primary: { mode: 'filled', variant: 'primary' },
+	},
+	radius: { lg: '4px' },
+});
+
+```
+
+Install `@c15t/ui` to use `defineTheme` directly. Pass `brandTheme` as `theme` in
+your existing React or Next.js provider options. Keep your Inth mode and script
+configuration. The theme source above is also imported by the runnable example,
+so the rendered result and the documentation use the same values.
+
+## Change the shape without rebuilding the banner
+
+```tsx
+<ConsentBanner variant="bar" />
+```
+
+![The same green theme on a full-width v3 consent bar with the actions arranged across its footer](../assets/v3/brand-bar.png)
+
+A bar changes the prompt's footprint. It does not change policy, grant categories
+or require a headless implementation.
+
+```tsx
+<ConsentBanner variant="wall" />
+```
+
+![A centered v3 choice wall with a backdrop, using the same green action theme](../assets/v3/choice-wall.png)
+
+A choice wall blocks interaction with the page. A notice never blocks; requesting
+a wall for a notice falls back to a non-blocking presentation.
+
+## Carry the theme into preferences
+
+![The v3 preferences dialog with optional category toggles and a green Save Settings action](../assets/v3/preferences.png)
+
+Keep a preferences link after the banner closes. Test a reject action, reopen
+the dialog, change one category and save. A branded prompt is only part of the
+consent flow.
+
+## Check narrow screens
+
+![The branded v3 floating card at a 375-pixel viewport, with Accept and Reject sharing a row and Customize below](../assets/v3/mobile-card.png)
+
+This example fits a 375-pixel viewport without horizontal overflow. Test your
+own longest translations and font settings before adopting the same sizing.
+
+## Run the examples
+
+The source repository contains resettable Storybook examples under
+`Docs / Customization`: Brand Card, Brand Bar and Choice Wall. Each demo uses
+in-memory consent and no analytics; Reset example returns it to a fresh choice.
+The screenshots above come from these v3 examples.
+
+The stories are suitable for isolated iframe previews on a version-matched
+Storybook deployment. Keep source code and the explanation on this page when
+embedding them, so the recipe remains usable in Markdown and offline package
+docs. A live preview must use the same v3 revision as the documentation.

package/docs/customization/slots.md

@@ -0,0 +1,55 @@
+---
+title: Style component slots
+description: Target a specific c15t component part without replacing its markup or behavior.
+group: customization
+---
+
+## Use slots for local changes
+
+In React and Next.js, put per-part attributes in `options.components`. This
+fragment belongs in an existing provider's options:
+
+```tsx
+components: {
+  banner: {
+    card: { className: 'rounded-none shadow-none' },
+    title: { className: 'font-semibold' },
+    footer: { className: 'border-t' },
+  },
+}
+```
+
+The class names above assume Tailwind. A slot can also receive `style` and other
+supported element attributes. Keep shared colors and radius scales in tokens;
+use slots when only one component part should change.
+
+## Read attributes on the right element
+
+The banner root carries `data-prompt`, `data-model`, `data-variant`,
+`data-position` and `data-blocking`. Its child card does not inherit those HTML
+attributes. In Tailwind, give the root `className: 'group'` and use
+`group-data-[variant=bar]:...` on a child slot.
+
+| React banner slot                  | Use                                   |
+| ---------------------------------- | ------------------------------------- |
+| `root`                             | Position wrapper and state attributes |
+| `cardShell`                        | Card sizing and branding container    |
+| `card`                             | Visible card                          |
+| `header`, `title`, `description`   | Heading and explanatory copy          |
+| `footer`, `actions`, `actionGroup` | Action layout                         |
+| `rights`, `rightLink`              | Preferences access controls           |
+| `overlay`                          | Backdrop for blocking presentation    |
+
+Buttons expose `data-action` for action-specific CSS. Test notices as well as
+choice prompts; a notice uses acknowledgement rather than accept/reject.
+
+## When to remove styles
+
+`noStyle` removes the built-in component styling. It does not supply replacement
+layout, spacing, focus indicators or responsive behavior. Use it when you intend
+to own all of that work, not as the first response to a token that appears to do
+nothing.
+
+If the markup itself must change, use the adapter's compound components or
+headless API. The slot objects above are the React contract; check Vue and Svelte
+slot types before reusing them.

package/docs/customization/tokens.md

@@ -0,0 +1,76 @@
+---
+title: Theme tokens and CSS
+description: Style c15t with semantic tokens and use the stylesheet that matches
+  your CSS tooling.
+group: customization
+---
+
+## Load the stock stylesheet once
+
+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.
+
+```tsx
+import 'c15t/react/styles.css';
+```
+
+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;
+```
+
+Do not load both c15t stylesheet variants. For Tailwind 4 or unlayered CSS,
+inspect layer order before reaching for `!important`.
+
+## Set semantic values together
+
+This React theme changes the brand color and large corner radius. Include
+hover and foreground colors when overriding raw variables so the button remains
+readable in each state.
+
+```ts
+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' },
+  },
+});
+```
+
+Install `@c15t/ui` if importing its theme helper directly. Pass `theme` in your
+provider options. `consentActions` selects styling by action role. A per-action
+entry overrides `primary`, which overrides `default`.
+
+## Target a prompt with CSS
+
+```css
+[data-prompt][data-model='opt-in'] {
+  --c15t-primary: #2f6f4e;
+  --c15t-primary-hover: #24563c;
+  --c15t-text-on-primary: #fff;
+}
+```
+
+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.
+
+| Size variable                       | Default | Target        |
+| ----------------------------------- | ------- | ------------- |
+| `--consent-banner-max-width`        | `440px` | Floating card |
+| `--consent-banner-widget-max-width` | `20rem` | Widget        |
+| `--consent-banner-wall-max-width`   | `30rem` | Choice wall   |
+
+Test long translations and small screens after changing width or typography.
+A compact banner must still fit the required actions.

package/docs/customization/translations.md

@@ -0,0 +1,49 @@
+---
+title: Copy and translations
+description: Change consent wording through i18n and test the complete prompt
+  and preferences flow.
+group: customization
+---
+
+## Configure shared messages
+
+Use provider `i18n` for wording that should stay consistent across components.
+For React, this fragment belongs in `ConsentProvider` options:
+
+```tsx
+i18n: {
+  messages: {
+    en: {
+      common: {
+        acceptAll: 'Accept all',
+        rejectAll: 'Reject optional',
+        customize: 'Choose cookies',
+        acknowledge: 'Got it',
+      },
+    },
+  },
+}
+```
+
+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.
+
+## Write labels that describe the action
+
+Accept and Reject record a choice. Customize opens preferences. Acknowledge
+dismisses a notice and does not record a grant. Do not label a notice dismissal
+"Accept all" or make a preferences link sound like it submits an opt-out.
+
+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.
+
+## Test more than English
+
+Try the longest labels you support at a narrow width, with browser zoom and
+right-to-left text where relevant. Check banner actions, category descriptions,
+legal links and the preferences save action. Translate explanations as well as
+buttons so a visitor can make an informed choice.

package/docs/frameworks/astro/quickstart.md

@@ -0,0 +1,186 @@
+---
+title: Quickstart
+description: Add c15t to static or server-rendered Astro pages and choose the
+  framework used by preference dialogs.
+group: frameworks
+---
+
+[Create an Inth project](https://inth.com) and use its backend endpoint in
+this guide. Configure the project's policy rules and allowed app origins first.
+
+## Choose the dialog framework
+
+Astro renders the banner with native `.astro` components. Preference dialogs use
+an on-demand Svelte, React or Vue island. Choose the framework your site already
+uses; set `ui` explicitly. This example uses Svelte.
+
+| Package manager | Command                                                                     |
+| :-------------- | :-------------------------------------------------------------------------- |
+| npm             | `npm install @c15t/astro @c15t/svelte @astrojs/svelte svelte @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/astro @c15t/svelte @astrojs/svelte svelte @c15t/scripts`    |
+| yarn            | `yarn add @c15t/astro @c15t/svelte @astrojs/svelte svelte @c15t/scripts`    |
+| bun             | `bun add @c15t/astro @c15t/svelte @astrojs/svelte svelte @c15t/scripts`     |
+
+## Register consent-gated scripts
+
+Include measurement and marketing categories in your policy for these vendors.
+Remove any existing loaders for them so each script loads once.
+
+Add your PostHog project key and X Pixel ID to `.env`:
+
+```dotenv title=".env"
+PUBLIC_POSTHOG_KEY=
+PUBLIC_X_PIXEL_ID=
+```
+
+Astro exposes these public values to the client through `import.meta.env`.
+Restart development or rebuild for deployment after changing them.
+An empty ID disables that integration. Create `src/example-scripts.ts`
+using the helper below. It selects PostHog's EU region; change `region` to `'us'`
+for a US project. PostHog waits for measurement permission and disables
+cookieless capture. X Pixel waits for marketing permission.
+
+```ts title="src/example-scripts.ts"
+import { posthog } from '@c15t/scripts/posthog';
+import { xPixel } from '@c15t/scripts/x-pixel';
+
+export const createExampleScripts = (
+	posthogKey?: string,
+	xPixelId?: string
+) => [
+	...(posthogKey
+		? [
+				posthog({
+					id: posthogKey,
+					initOptions: { cookieless_mode: 'never' },
+					loadMode: 'after-consent',
+					region: 'eu',
+				}),
+			]
+		: []),
+	...(xPixelId ? [xPixel({ pixelId: xPixelId })] : []),
+];
+```
+
+Create the client extension so script callbacks stay out of serialized server
+configuration:
+
+```ts title="src/consent-client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { createExampleScripts } from './example-scripts';
+
+export default {
+  scripts: createExampleScripts(
+    import.meta.env.PUBLIC_POSTHOG_KEY,
+    import.meta.env.PUBLIC_X_PIXEL_ID,
+  ),
+} satisfies C15tClientOptionsExtension;
+```
+
+## Configure the integration
+
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'astro/config';
+import svelte from '@astrojs/svelte';
+import c15t, { hosted } from '@c15t/astro';
+
+const backendURL = process.env.C15T_BACKEND_URL;
+if (!backendURL) throw new Error('Set C15T_BACKEND_URL');
+
+export default defineConfig({
+  integrations: [
+    svelte(),
+    c15t({
+      mode: hosted({ url: backendURL }),
+      ui: 'svelte',
+      clientEntrypoint: fileURLToPath(new URL('./src/consent-client.ts', import.meta.url)),
+    }),
+  ],
+});
+```
+
+Set `C15T_BACKEND_URL` to your backend's absolute URL, with policy rules and the
+app origin configured. The integration serializes its options into browser
+configuration. Keep secrets and callbacks out of this configuration.
+
+For IAB policies in hosted mode, the browser fetches the vendor list from the
+configured backend's `/init` endpoint after server rendering. That endpoint must
+be publicly reachable from the app origin and allow its CORS requests without
+server-only credentials. A private hosted backend needs a public same-origin
+proxy that keeps authentication on the server.
+
+In manifest mode, Astro injects a local init route and the browser fetches the
+vendor list through that same-origin route. The backend does not need to allow
+browser access or CORS requests from the app.
+
+Past the manifest's `s-maxage` the injected routes and the middleware serve it
+stale and refresh it in the background. On adapters that expose
+`locals.runtime.ctx.waitUntil` (Cloudflare) the refresh is handed to it so it
+is not cut short when the response is sent; nothing is needed from you. For
+another lifetime API, pass `onBackgroundRevalidate` to
+`createConsentRouteHandlers` or `resolveConsentContext`.
+
+The framework integration must appear before `c15t()`. For React or Vue, install
+that framework's Astro integration and c15t adapter, register the matching
+integration, and set `ui: 'react'` or `ui: 'vue'`.
+
+## Add the shared layout
+
+```astro title="src/layouts/Base.astro"
+---
+import ConsentScript from '@c15t/astro/components/consent-script.astro';
+import ConsentBanner from '@c15t/astro/components/consent-banner.astro';
+import ConsentDialog from '@c15t/astro/components/consent-dialog.astro';
+import ConsentDialogTrigger from '@c15t/astro/components/consent-dialog-trigger.astro';
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My site</title>
+    <ConsentScript />
+  </head>
+  <body>
+    <slot />
+    <ConsentBanner />
+    <ConsentDialog />
+    <footer>
+      <ConsentDialogTrigger>Privacy settings</ConsentDialogTrigger>
+    </footer>
+  </body>
+</html>
+```
+
+Use this layout around each page. The integration supplies styles and the
+shared browser runtime. `ConsentScript` prepares the client configuration and
+color scheme. Do not create separate runtimes for each consent island.
+
+## Static pages and request SSR
+
+For prerendered pages, the middleware skips request prefetch. The browser
+resolves consent against the external backend. This avoids treating the build
+machine's cookies or geography as visitor state.
+
+For server-rendered pages, keep your Astro server adapter and output settings.
+The middleware can resolve request-specific state into `Astro.locals.c15t`.
+Pass the prepared state through the supplied components instead of constructing
+records from permission booleans.
+
+`manifest()` mode can inject init and manifest endpoints and therefore needs a
+server for those endpoints. Do not choose that setup for a purely static host
+without providing the routes elsewhere. Nonserializable extensions belong in
+the module selected by `clientEntrypoint`, not in `astro.config.mjs`.
+
+## Verify navigation and loading
+
+Test the built output, including a full page load and any navigation through
+Astro's `ClientRouter`. Open preferences twice and check the runtime retains the
+current choice. The dialog should reuse the selected framework, not load a
+second adapter. Follow [verification](../../guides/verify-consent.md) for rejection,
+reload and script requests.
+
+## Run the complete example
+
+Try the [runnable example](https://c15t.com/docs/examples) with PostHog, X Pixel, a consent-gated
+YouTube video and a persistent preferences control. Use it to test rejection, permission changes and reloads.