@c15t/browser 3.0.0-alpha.0

package/docs/integrations/fathom-analytics.md

@@ -0,0 +1,293 @@
+---
+title: Fathom Analytics
+description: Configure Fathom Analytics with c15t v3, understand measurement
+  permission and verify loading and revocation.
+group: integrations
+---
+
+## Configure Fathom Analytics
+
+Copy the site ID from your Fathom snippet. Set SPA behavior deliberately when your application navigates without full page reloads.
+
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
+
+```ts title="src/consent-scripts.ts"
+import { fathomAnalytics } from '@c15t/scripts/fathom-analytics';
+
+export const scripts = [fathomAnalytics({ site: 'YOUR_SITE_ID', spa: 'auto' })];
+```
+
+## Register the scripts
+
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry so c15t owns loading once.
+
+The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
+initializer. Add it to your existing consent owner using the registration point
+below. These are partial edits to that owner, not additional providers.
+
+**Next.js**
+
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
+
+Keep the server-resolved `state` and shared `consentConfig` from your
+router guide. Its manifest, init and save URLs stay in effect. Add
+`scripts` as a top-level prop on the existing root:
+
+```tsx
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
+
+For a Pages Router or static-export setup using `ConsentProvider`, add
+`scripts` to its existing `options` instead. Keep the router-specific setup
+from [Next.js script loading](https://c15t.com/docs/frameworks/next/script-loader).
+
+**TanStack Start**
+
+In your existing root route component, import the scripts alongside
+`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
+
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
+
+function Root() {
+  const state = Route.useLoaderData();
+  return (
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
+  );
+}
+```
+
+This edits the existing route. `Route` and `backendURL` come from its setup;
+keep the document shell and head components if they are part of your root.
+`initRoute={false}` keeps the quickstart's direct-backend initialization.
+If your app mounts a consent server route, retain its existing `initRoute`
+instead. Do not return script callbacks from a server function or route loader.
+
+**React**
+
+Import the scripts into your existing provider component:
+
+```ts
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
+
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
+
+Here `consentOptions` is your existing configuration, including
+`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
+link inside the provider. See [React script loading](https://c15t.com/docs/frameworks/react/script-loader).
+
+**Nuxt**
+
+Attach one loader from the root `app.vue`, after the Nuxt module has
+started its browser runtime. This keeps vendor callbacks in application code rather
+than serialized `nuxt.config.ts` runtime configuration.
+
+```vue title="app/app.vue"
+<script setup lang="ts">
+import { onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from '../src/consent-scripts';
+
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
+});
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
+```
+
+Merge the setup code into your root and retain its footer and preferences
+link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
+relative script import if your `app.vue` is at the project root. This loader
+waits until the module has applied browser persistence and privacy signals,
+then reads the current snapshot and observes future changes. Do not also register these scripts
+in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
+
+**Vue**
+
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
+
+```vue title="src/App.vue"
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { useConsentKernel } from 'c15t/vue/vue-plugin';
+import ConsentRoot from 'c15t/vue/consent-root';
+import { scripts } from './consent-scripts';
+
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => loader?.dispose());
+</script>
+
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
+```
+
+Keep your existing page content and preferences link. The plugin still owns
+the kernel and persistence; this component owns only the vendor loader.
+Do not register the same scripts in plugin configuration as well. See the
+[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
+
+**Astro**
+
+Point the existing Astro integration at a client module. Keep its `mode`,
+`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
+Import `fileURLToPath` in your Astro configuration:
+
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
+
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
+
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
+
+Export the scripts from that module:
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+The integration passes this extension to its shared browser runtime. Vendor
+helpers contain callbacks, so do not put them in the serialized `scripts`
+option in `astro.config.mjs`. Keep one runtime across consent islands and
+`ClientRouter` navigation.
+
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
+
+  const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+  const mode = hosted({ url: backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
+
+**SvelteKit**
+
+Add the scripts to the existing root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
+
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`.
+For static hosting, keep your browser-only `mode` setup and omit request
+prefetch; the `scripts` prop stays the same. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**JavaScript**
+
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
+
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
+```
+
+Call `loader.dispose()` when that application instance is destroyed.
+`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
+already has a loader; do not attach a second one. See
+[JavaScript script loading](../frameworks/javascript/script-loader.md).
+
+## Options
+
+| Option                        | Behavior                                                                                        |
+| ----------------------------- | ----------------------------------------------------------------------------------------------- |
+| `site`                        | Required site ID, passed as `data-site`.                                                        |
+| `spa`                         | `auto`, `history` or `hash`. Omitted by default, so the helper does not enable SPA routing.     |
+| `auto / canonical / honorDnt` | Optional booleans passed as data attributes. Omitted values leave the vendor defaults in place. |
+| `scriptUrl`                   | Defaults to `https://cdn.usefathom.com/script.js`.                                              |
+
+## Consent behavior
+
+The script waits for measurement permission. The helper does not call a Fathom stop API after revocation. Application event calls and any routing listeners need separate verification.
+
+## Verify the integration
+
+Check the site ID and `data-spa` attribute, then compare a full page load with client navigation. Avoid installing both this helper and another Fathom routing plugin.
+
+Use a fresh session with an opt-in policy to check initial denial. Then grant
+`measurement`, revoke it, and reload. Inspect both network requests and future
+application events. Removing a script cannot undo code or requests that already
+ran. Follow the [consent verification guide](https://c15t.com/docs/guides/verify-consent).

package/docs/integrations/google-maps.md

@@ -0,0 +1,384 @@
+---
+title: Google Maps
+description: Prevent a map iframe from mounting before the required permission.
+group: integrations
+---
+
+## Configure the map
+
+Copy the map's iframe embed URL. Choose the category matching its use in your
+application; this example uses functionality permission.
+
+```ts title="src/embed-config.ts"
+export const embedCategory = 'functionality' as const;
+export const embedURL = 'https://www.google.com/maps/embed?pb=YOUR_EMBED_PARAMETERS';
+export const embedTitle = 'Map showing our office location';
+export const embedAspectRatio = '4 / 3';
+```
+
+Replace the example URL with the complete embed URL for your map. Keep the
+address and a directions link outside the consent-gated embed.
+
+## Add the embed to your framework
+
+Create `src/embed-config.ts` using the configuration on this page, then select
+your framework. Keep the existing [consent setup](https://c15t.com/docs/frameworks), its policy
+and preferences UI. These examples do not create a second consent provider.
+
+**Next.js**
+
+Render this component inside your existing consent boundary or provider.
+
+```tsx title="src/consent-embed.tsx"
+'use client';
+
+import { Frame } from 'c15t/next';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+export function ConsentEmbed() {
+  return (
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
+  );
+}
+```
+
+`Frame` keeps the iframe absent while permission is denied and removes it
+on revocation. Keep your existing consent styles and preferences dialog.
+
+**TanStack Start**
+
+Render this component inside your existing consent boundary or provider.
+
+```tsx title="src/consent-embed.tsx"
+import { Frame } from 'c15t/tanstack-start';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+export function ConsentEmbed() {
+  return (
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
+  );
+}
+```
+
+`Frame` keeps the iframe absent while permission is denied and removes it
+on revocation. Keep your existing consent styles and preferences dialog.
+
+**React**
+
+Render this component inside your existing consent boundary or provider.
+
+```tsx title="src/consent-embed.tsx"
+import { Frame } from 'c15t/react';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+export function ConsentEmbed() {
+  return (
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
+  );
+}
+```
+
+`Frame` keeps the iframe absent while permission is denied and removes it
+on revocation. Keep your existing consent styles and preferences dialog.
+
+**Nuxt**
+
+Use the reactive snapshot from the existing consent runtime. The Nuxt module auto-imports the consent composables.
+
+```vue title="app/components/ConsentEmbed.vue"
+<script setup lang="ts">
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../../src/embed-config';
+
+const snapshot = useConsentSnapshot();
+const activeUI = useConsentActiveUI();
+</script>
+
+<template>
+  <iframe
+    v-if="snapshot.effectivePermissions[embedCategory]"
+    :src="embedURL"
+    :title="embedTitle"
+    loading="lazy"
+    allowfullscreen
+    :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+  />
+  <button v-else type="button" @click="activeUI = 'manager'">
+    Open privacy settings to view this content
+  </button>
+</template>
+```
+
+Use `v-if` so a denied iframe is removed from the DOM. Hiding an existing
+iframe with `v-show` or CSS does not prevent its requests.
+
+**Vue**
+
+Use the reactive snapshot from the existing consent runtime. The c15t Vue plugin must already be installed on this app.
+
+```vue title="src/ConsentEmbed.vue"
+<script setup lang="ts">
+import { useConsentSnapshot, useConsentActiveUI } from 'c15t/vue/vue-plugin';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+const snapshot = useConsentSnapshot();
+const activeUI = useConsentActiveUI();
+</script>
+
+<template>
+  <iframe
+    v-if="snapshot.effectivePermissions[embedCategory]"
+    :src="embedURL"
+    :title="embedTitle"
+    loading="lazy"
+    allowfullscreen
+    :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+  />
+  <button v-else type="button" @click="activeUI = 'manager'">
+    Open privacy settings to view this content
+  </button>
+</template>
+```
+
+Use `v-if` so a denied iframe is removed from the DOM. Hiding an existing
+iframe with `v-show` or CSS does not prevent its requests.
+
+**Astro**
+
+Use the shared browser helper below with Astro's existing page runtime.
+Add this component to pages using your consent-enabled base layout:
+
+```astro title="src/components/ConsentEmbed.astro"
+<c15t-consent-embed style="display: block"></c15t-consent-embed>
+
+<script>
+  import { getConsentClient } from '@c15t/astro/client';
+  import { mountConsentEmbed } from '../consent-embed';
+
+  class ConsentEmbed extends HTMLElement {
+    dispose?: () => void;
+
+    connect = () => {
+      if (this.dispose) return;
+      const client = getConsentClient();
+      if (!client) return;
+      this.dispose = mountConsentEmbed(
+        this,
+        client.runtime.kernel,
+        () => { void client.openDialog(); },
+      );
+    };
+
+    connectedCallback() {
+      document.addEventListener('DOMContentLoaded', this.connect, { once: true });
+      this.connect();
+    }
+
+    disconnectedCallback() {
+      document.removeEventListener('DOMContentLoaded', this.connect);
+      this.dispose?.();
+      this.dispose = undefined;
+    }
+  }
+
+  if (!customElements.get('c15t-consent-embed')) {
+    customElements.define('c15t-consent-embed', ConsentEmbed);
+  }
+</script>
+```
+
+The first mount waits for the page's module scripts, including c15t's boot
+script. Later `ClientRouter` mounts reuse the existing runtime. Removing the
+component unsubscribes and removes the iframe. Do not create another consent
+runtime for this embed.
+
+**Svelte**
+
+Render this component inside the existing `ConsentManagerProvider`.
+The provider from your quickstart supplies its consent state.
+
+```svelte title="src/ConsentEmbed.svelte"
+<script lang="ts">
+  import { Frame } from '@c15t/svelte';
+  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+</script>
+
+<Frame category={embedCategory}>
+  <iframe
+    src={embedURL}
+    title={embedTitle}
+    loading="lazy"
+    allowfullscreen
+    style:width="100%"
+    style:aspect-ratio={embedAspectRatio}
+    style:min-height="200px"
+    style:border="0"
+  ></iframe>
+</Frame>
+```
+
+The Svelte `Frame` waits until the browser is mounted and the category is
+allowed. Its default placeholder opens preferences. Revocation removes the
+iframe.
+
+**SvelteKit**
+
+Render this component inside the existing `ConsentManagerProvider`.
+Keep the SvelteKit root provider and its server prefetch unchanged.
+
+```svelte title="src/lib/ConsentEmbed.svelte"
+<script lang="ts">
+  import { Frame } from '@c15t/svelte';
+  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../embed-config';
+</script>
+
+<Frame category={embedCategory}>
+  <iframe
+    src={embedURL}
+    title={embedTitle}
+    loading="lazy"
+    allowfullscreen
+    style:width="100%"
+    style:aspect-ratio={embedAspectRatio}
+    style:min-height="200px"
+    style:border="0"
+  ></iframe>
+</Frame>
+```
+
+The Svelte `Frame` waits until the browser is mounted and the category is
+allowed. Its default placeholder opens preferences. Revocation removes the
+iframe.
+
+**JavaScript**
+
+Use the shared browser helper below with your existing kernel. Put an
+empty container where the embed should appear:
+
+```html
+<div id="consent-embed"></div>
+```
+
+In your browser entry point, after creating the kernel:
+
+```ts
+import { mountConsentEmbed } from './consent-embed';
+
+const container = document.querySelector<HTMLElement>('#consent-embed');
+if (!container) throw new Error('Missing consent embed container');
+
+const disposeEmbed = mountConsentEmbed(container, kernel, openPreferences);
+```
+
+`kernel` is the instance from your quickstart. `openPreferences` is your
+application's function for showing its consent preferences UI. Call
+`disposeEmbed()` when the page or component is destroyed. The helper observes
+both the current snapshot and later changes.
+
+## Browser helper for Astro and JavaScript
+
+Only the Astro and JavaScript examples need this helper. It creates the iframe
+when permission allows it, keeps an existing player mounted across unrelated
+snapshot updates, and removes it on revocation.
+
+```ts title="src/consent-embed.ts"
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+type EmbedKernel = {
+  getSnapshot: () => {
+    effectivePermissions: Record<typeof embedCategory, boolean>;
+  };
+  subscribe: (listener: () => void) => () => void;
+};
+
+export function mountConsentEmbed(
+  container: HTMLElement,
+  kernel: EmbedKernel,
+  openPreferences: () => void,
+) {
+  const render = () => {
+    if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
+      if (container.querySelector('iframe')) return;
+      const frame = document.createElement('iframe');
+      frame.src = embedURL;
+      frame.title = embedTitle;
+      frame.loading = 'lazy';
+      frame.allowFullscreen = true;
+      Object.assign(frame.style, {
+        width: '100%',
+        aspectRatio: embedAspectRatio,
+        minHeight: '200px',
+        border: '0',
+      });
+      container.replaceChildren(frame);
+    } else {
+      if (container.querySelector('button')) return;
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.textContent = 'Open privacy settings to view this content';
+      button.onclick = openPreferences;
+      container.replaceChildren(button);
+    }
+  };
+
+  render();
+  const unsubscribe = kernel.subscribe(render);
+  return () => {
+    unsubscribe();
+    container.replaceChildren();
+  };
+}
+```
+
+Keep a transcript, address or other useful alternative outside the embed.
+`loading="lazy"` is a performance hint; the consent condition controls whether
+the iframe exists at all. A denied category may be fixed by policy, so opening
+preferences does not guarantee that the visitor can grant it.
+
+## Gate existing iframe markup
+
+For markup that uses `data-category` and `data-src`, the
+`createIframeBlocker` module from `c15t/modules/iframe-blocker` promotes
+`data-src` only when the category has consent and the URL resolves to HTTP or
+HTTPS. Relative URLs resolve against the iframe document's base URL.
+Malformed URLs and other schemes, including `javascript:`, `data:` and `blob:`,
+remain in `data-src` without loading. Correct the URL and call
+`processAllIframes()` to retry.
+
+Keep the initial URL in `data-src`, without `src`, so the browser cannot load
+it before the blocker runs. The module does not sanitize arbitrary HTML or
+modify iframes without `data-category`.
+
+## Verify before and after permission
+
+On a fresh opt-in session, inspect Network and confirm the iframe has not
+requested the map. Grant the category and confirm the map mounts. Revoke it and
+check the frame returns to its blocked state. Keep useful fallback information,
+such as the address and directions link, available outside the map.
+
+For a JavaScript Maps SDK instead of an iframe, register a category-gated script
+and manage the widget's cleanup. Do not use this iframe recipe as evidence that
+an independently loaded Maps SDK is blocked.