@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/youtube.md

@@ -1,193 +1,405 @@
 ---
 title: YouTube
-description: Keep YouTube iframes unmounted until consent with a
-  privacy-enhanced, lazy-loaded React or Next.js embed.
-icon: youtube
+description: Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React,
+  Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
 group: integrations
 ---
-`YouTubeEmbed` is a renderable integration for React and Next.js. It uses c15t's
-`Frame` consent boundary, so the YouTube iframe is not mounted and no YouTube
-request is made until the configured consent category is allowed.
 
-The component does not load the YouTube IFrame Player API. It is intended for
-standard iframe embeds and keeps script readiness separate from iframe gating.
+## Configure the video
 
-## Integrate with c15t
+Use the ID of an embeddable video and the category matching its purpose in your
+policy. The current v3 adapters use consent-gated iframes rather than the v2
+`YouTubeEmbed` convenience component.
 
-`YouTubeEmbed` must render inside a `ConsentManagerProvider`. Complete the
-[React quickstart](/docs/frameworks/react/quickstart) or
-[Next.js quickstart](/docs/frameworks/next/quickstart) first.
+```ts title="src/embed-config.ts"
+export const embedCategory = 'marketing' as const;
+export const embedURL = 'https://www.youtube-nocookie.com/embed/VIDEO_ID?playsinline=1';
+export const embedTitle = 'Product walkthrough';
+export const embedAspectRatio = '16 / 9';
+```
 
-**React**
+Replace `VIDEO_ID` before running the example.
+
+## 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';
 
-```tsx
-import { YouTubeEmbed } from '@c15t/react';
+import { Frame } from 'c15t/next';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
-export function ProductVideo() {
+export function ConsentEmbed() {
   return (
-    <YouTubeEmbed
-      consentCategory="marketing"
-      params={{ controls: true, playsinline: true }}
-      title="Product overview"
-      videoId="dQw4w9WgXcQ"
-    />
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
   );
 }
 ```
 
-**Next.js**
+`Frame` keeps the iframe absent while permission is denied and removes it
+on revocation. Keep your existing consent styles and preferences dialog.
 
-```tsx
-'use client';
+**TanStack Start**
+
+Render this component inside your existing consent boundary or provider.
 
-import { YouTubeEmbed } from '@c15t/nextjs';
+```tsx title="src/consent-embed.tsx"
+import { Frame } from 'c15t/tanstack-start';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
-export function ProductVideo() {
+export function ConsentEmbed() {
   return (
-    <YouTubeEmbed
-      consentCategory="marketing"
-      params={{ controls: true, playsinline: true }}
-      title="Product overview"
-      videoId="dQw4w9WgXcQ"
-    />
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
   );
 }
 ```
 
-`marketing` is the default category. Choose a different category only when it
-matches the purpose of the embed and the policy presented to your users.
-
-## How c15t loads it
-
-* **Before consent:** c15t renders a placeholder and does not mount the iframe.
-* **After consent:** the iframe mounts with its final embed URL.
-* **On revocation:** the `Frame` boundary unmounts the iframe, stopping the
-  embedded player and future requests from that document.
-* **Loading behavior:** c15t reserves the final player size, shows a localized
-  loading state, and uses native iframe lazy loading by default.
-* **Default layout:** the placeholder and player share a responsive 16:9,
-  borderless frame with a `200px` minimum height.
-* **Privacy-enhanced mode:** URLs built from `videoId` use
-  `youtube-nocookie.com` by default.
-
-Privacy-enhanced mode changes the YouTube host but does not replace consent
-gating. Keep the iframe behind the category required by your privacy policy.
-
-## Build the embed URL
-
-Prefer `videoId` when you control the video:
-
-```tsx
-<YouTubeEmbed
-  consentCategory="marketing"
-  params={{
-    autoplay: false,
-    controls: true,
-    playsinline: true,
-    rel: false,
-  }}
-  start={36}
-  title="Quarterly product update"
-  videoId="dQw4w9WgXcQ"
-/>
+`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>
+  );
+}
 ```
 
-Boolean `params` are serialized as YouTube's `1` and `0` values. `start` is
-serialized as the player's start time in seconds. If `params.start` is also
-present, the top-level `start` prop takes precedence.
+`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>
+```
 
-Set `privacyEnhanced={false}` only when you intentionally need the regular
-`youtube.com` host.
+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>
+```
 
-### Migrate an existing iframe URL
+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;
+    }
+  }
 
-Use `src` when you already have a complete embed URL:
+  if (!customElements.get('c15t-consent-embed')) {
+    customElements.define('c15t-consent-embed', ConsentEmbed);
+  }
+</script>
+```
 
-```tsx
-<YouTubeEmbed
-  consentCategory="marketing"
-  src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?start=36"
-  title="Quarterly product update"
-/>
+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>
 ```
 
-When `src` is provided, c15t uses it unchanged. TypeScript treats `src` and
-`videoId` as mutually exclusive source modes: `start`, `params`, and
-`privacyEnhanced` are available only with `videoId`.
+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>
+```
 
-## Style the wrapper and iframe
+The Svelte `Frame` waits until the browser is mounted and the category is
+allowed. Its default placeholder opens preferences. Revocation removes the
+iframe.
 
-`wrapperClassName` targets the consent-gated `Frame`. `className` and the
-forwarded ref target the iframe itself.
+**JavaScript**
 
-The defaults are responsive and stable without utility classes. Override them
-only when your layout needs a different aspect ratio or height:
+Use the shared browser helper below with your existing kernel. Put an
+empty container where the embed should appear:
 
-```tsx
-<YouTubeEmbed
-  consentCategory="marketing"
-  frameProps={{ style: { aspectRatio: '4 / 3', minHeight: 280 } }}
-  style={{ borderRadius: 4 }}
-  title="Product overview"
-  videoId="dQw4w9WgXcQ"
-/>
+```html
+<div id="consent-embed"></div>
 ```
 
-`frameProps.style` is merged after the wrapper defaults. The iframe fills that
-wrapper, has no border, and inherits the wrapper radius by default.
+In your browser entry point, after creating the kernel:
 
-## Customize the placeholder
+```ts
+import { mountConsentEmbed } from './consent-embed';
 
-```tsx
-import { Frame, YouTubeEmbed } from '@c15t/react';
+const container = document.querySelector<HTMLElement>('#consent-embed');
+if (!container) throw new Error('Missing consent embed container');
 
-<YouTubeEmbed
-  consentCategory="marketing"
-  placeholder={
-    <Frame.Root>
-      <Frame.Title>Allow marketing consent to watch this video.</Frame.Title>
-      <Frame.Button category="marketing" />
-    </Frame.Root>
-  }
-  title="Product overview"
-  videoId="dQw4w9WgXcQ"
-/>
+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();
+  };
+}
 ```
 
-Custom placeholders should explain why the content is blocked and provide a
-clear way to change consent. Always give the iframe a meaningful `title`.
+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.
 
-Use `loadingFallback` to replace the post-consent loading message and
-`errorFallback` to replace the configuration error state. If neither `videoId`
-nor `src` is supplied at runtime, the component renders that error state instead
-of mounting an iframe.
+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`.
 
-Standard cross-origin iframes do not provide a reliable player-error signal.
-`YouTubeEmbed` forwards the iframe's native `onError` when a browser emits it,
-but player-level errors require the YouTube IFrame Player API and are outside
-this iframe-only component.
+## Customize the player and placeholder
 
-## Verify setup
+Set playback options in the iframe URL. For example, append `start=36` to begin
+36 seconds into the video. Use supported
+[YouTube player parameters](https://developers.google.com/youtube/player_parameters)
+and reserve at least a 200-by-200-pixel player area.
 
-1. Clear saved consent and reload the page.
-2. Confirm there is no YouTube iframe or YouTube network request before consent.
-3. Grant the configured category and confirm exactly one iframe mounts.
-4. Confirm a `videoId` embed uses `youtube-nocookie.com` unless
-   `privacyEnhanced={false}`.
-5. Revoke consent and confirm the iframe is removed.
-6. Confirm the default 16:9 frame is borderless and reserves the same space at
-   mobile and desktop widths.
+React and Svelte `Frame` components provide a blocked-state placeholder and
+consent action. Their `placeholder` APIs differ: React takes a node, Svelte
+takes a snippet. Keep a clear way to reopen preferences when customizing them.
+The Vue and browser examples show that action explicitly. `loading="lazy"` delays an
+allowed iframe for performance; it does not implement consent gating.
 
-See YouTube's [embedded player parameters](https://developers.google.com/youtube/player_parameters)
-for the supported query parameters.
+## Consent behavior
 
-## Types
+Each example keeps the iframe absent until the category is allowed. After
+permission, the iframe can load. Revoking permission removes the iframe and its
+embedded document. Requests already sent cannot be recalled.
 
-### YouTubeEmbedProps
+The `youtube-nocookie.com` hostname does not replace the consent boundary. Avoid
+loading a remote thumbnail, preconnecting to YouTube, or installing the IFrame
+Player API separately if you require no YouTube request before permission.
+This recipe embeds a video; it does not load the JavaScript Player API.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`YouTubeEmbedProps\`|
-|Source Path|\`./packages/react/src/components/integrations/youtube-embed.tsx\`|
+## Verify the integration
 
-\*ExtractedTypeTable: Could not extract "YouTubeEmbedProps" from "./packages/react/src/components/integrations/youtube-embed.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+In a fresh opt-in session, confirm no iframe or YouTube request exists. Grant
+marketing permission and play the video, then revoke it and confirm the iframe
+is removed. Test a narrow viewport and keyboard access to the placeholder and
+player. See [consent verification](../guides/verify-consent.md).