npm - @c15t/astro - Versions diffs - 3.0.0-alpha.0 - Mend

@c15t/astro 3.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/AGENTS.md +86 -0
package/SKILL.md +14 -0
package/dist/api/handlers.js +91 -0
package/dist/api/index.js +3 -0
package/dist/api/init.js +10 -0
package/dist/api/manifest-init.js +103 -0
package/dist/api/manifest.js +10 -0
package/dist/browser/iab.js +5 -0
package/dist/browser/inline-scripts.js +47 -0
package/dist/client.js +276 -0
package/dist/index.js +5 -0
package/dist/integration.js +170 -0
package/dist/libs/cookies.js +9 -0
package/dist/middleware-handler.js +31 -0
package/dist/middleware.js +6 -0
package/dist/mode.js +50 -0
package/dist/server.js +291 -0
package/dist/styles.css +2 -0
package/dist/types.js +0 -0
package/dist/ui/adapter.js +37 -0
package/dist/ui/provider-props.js +12 -0
package/dist/ui/react.js +34 -0
package/dist/ui/svelte.js +36 -0
package/dist/ui/vue.js +38 -0
package/dist-types/api/handlers.d.ts +85 -0
package/dist-types/api/index.d.ts +13 -0
package/dist-types/api/init.d.ts +10 -0
package/dist-types/api/manifest-init.d.ts +73 -0
package/dist-types/api/manifest.d.ts +9 -0
package/dist-types/browser/iab.d.ts +14 -0
package/dist-types/browser/inline-scripts.d.ts +38 -0
package/dist-types/client.d.ts +152 -0
package/dist-types/index.d.ts +33 -0
package/dist-types/integration.d.ts +53 -0
package/dist-types/libs/cookies.d.ts +15 -0
package/dist-types/middleware-handler.d.ts +35 -0
package/dist-types/middleware.d.ts +20 -0
package/dist-types/mode.d.ts +75 -0
package/dist-types/server.d.ts +130 -0
package/dist-types/types.d.ts +305 -0
package/dist-types/ui/adapter.d.ts +122 -0
package/dist-types/ui/provider-props.d.ts +37 -0
package/dist-types/ui/react.d.ts +19 -0
package/dist-types/ui/svelte.d.ts +21 -0
package/dist-types/ui/vue.d.ts +19 -0
package/docs/README.md +86 -0
package/docs/assets/v3/brand-bar.png +0 -0
package/docs/assets/v3/brand-card.png +0 -0
package/docs/assets/v3/choice-wall.png +0 -0
package/docs/assets/v3/mobile-card.png +0 -0
package/docs/assets/v3/preferences.png +0 -0
package/docs/customization/overview.md +45 -0
package/docs/customization/recipes.md +79 -0
package/docs/customization/slots.md +55 -0
package/docs/customization/tokens.md +76 -0
package/docs/customization/translations.md +49 -0
package/docs/frameworks/astro/quickstart.md +186 -0
package/docs/guides/consent-state.md +60 -0
package/docs/guides/data-fetching.md +163 -0
package/docs/guides/deployment-modes.md +63 -0
package/docs/guides/troubleshooting.md +68 -0
package/docs/guides/verify-consent.md +62 -0
package/docs/integrations/adobe-analytics.md +294 -0
package/docs/integrations/ahrefs-analytics.md +291 -0
package/docs/integrations/amplitude.md +292 -0
package/docs/integrations/building-integrations.md +47 -0
package/docs/integrations/clearbit.md +291 -0
package/docs/integrations/cloudflare-web-analytics.md +292 -0
package/docs/integrations/crisp.md +294 -0
package/docs/integrations/databuddy.md +311 -0
package/docs/integrations/fathom-analytics.md +293 -0
package/docs/integrations/google-maps.md +384 -0
package/docs/integrations/google-tag-manager.md +306 -0
package/docs/integrations/google-tag.md +305 -0
package/docs/integrations/heap.md +292 -0
package/docs/integrations/hightouch.md +293 -0
package/docs/integrations/hotjar.md +292 -0
package/docs/integrations/intercom.md +285 -0
package/docs/integrations/linkedin-insights.md +291 -0
package/docs/integrations/logrocket.md +293 -0
package/docs/integrations/matomo-analytics.md +316 -0
package/docs/integrations/meta-pixel.md +285 -0
package/docs/integrations/microsoft-clarity.md +292 -0
package/docs/integrations/microsoft-uet.md +291 -0
package/docs/integrations/mixpanel-analytics.md +295 -0
package/docs/integrations/openai-pixel.md +441 -0
package/docs/integrations/overview.md +111 -0
package/docs/integrations/pirsch.md +295 -0
package/docs/integrations/plausible-analytics.md +295 -0
package/docs/integrations/posthog.md +397 -0
package/docs/integrations/promptwatch.md +291 -0
package/docs/integrations/reddit-pixel.md +294 -0
package/docs/integrations/rudderstack.md +328 -0
package/docs/integrations/rybbit-analytics.md +296 -0
package/docs/integrations/segment.md +292 -0
package/docs/integrations/snapchat-pixel.md +293 -0
package/docs/integrations/tiktok-pixel.md +291 -0
package/docs/integrations/umami-analytics.md +295 -0
package/docs/integrations/vercel-analytics.md +293 -0
package/docs/integrations/x-pixel.md +291 -0
package/docs/integrations/youtube.md +405 -0
package/docs/upgrade-v3.md +334 -0
package/package.json +184 -0
package/src/components/branding.astro +152 -0
package/src/components/consent-script.astro +34 -0
package/src/components/iab-panel.astro +43 -0
package/src/components/iab-prompt.astro +316 -0
package/src/components/islands/iab-dialog-surface.svelte +15 -0
package/src/components/islands/iab-dialog-surface.tsx +25 -0
package/src/components/islands/iab-dialog-surface.vue +20 -0
package/src/components/islands/panel-surface.svelte +57 -0
package/src/components/islands/panel-surface.tsx +67 -0
package/src/components/islands/panel-surface.vue +39 -0
package/src/components/panel-trigger.astro +48 -0
package/src/components/panel.astro +65 -0
package/src/components/prompt-deferred.astro +54 -0
package/src/components/prompt.astro +325 -0

package/src/components/consent-script.astro ADDED Viewed

@@ -0,0 +1,34 @@
+---
+/**
+ * Inlines the server-resolved consent config for the browser.
+ *
+ * Put this in your layout's `<head>`. It hands the client boot script the
+ * decision the server already made — consents, policy, translations — so
+ * the page boots with no `/init` roundtrip and no banner flicker, and it
+ * writes the colour-scheme class before the stylesheet paints, so a
+ * system-dark visitor does not get a light banner for a frame.
+ *
+ * `<ConsentBanner />` renders both itself if they have not been emitted
+ * yet, so a site with a banner in every layout does not need this
+ * explicitly — but `<head>` is where the colour-scheme script belongs.
+ */
+import {
+	buildColorSchemeScript,
+	buildConfigScript,
+	markConfigEmitted,
+} from '@c15t/astro/server';
+const { c15t } = Astro.locals;
+const shouldEmit = c15t !== undefined && markConfigEmitted(Astro.locals);
+const colorSchemeScript = shouldEmit
+	? buildColorSchemeScript(c15t.options.colorScheme)
+	: '';
+---
+{colorSchemeScript && <script is:inline set:html={colorSchemeScript} />}
+{
+	shouldEmit && (
+		<script is:inline set:html={buildConfigScript(c15t.config)} />
+	)
+}

package/src/components/iab-panel.astro ADDED Viewed

@@ -0,0 +1,43 @@
+---
+/**
+ * The IAB TCF preference centre.
+ *
+ * Like `<ConsentDialog />`, this renders only a host element; the TCF
+ * surface and `@c15t/iab` are both loaded on first open, so a site with IAB
+ * configured still serves a banner-only page with no TCF bytes.
+ *
+ * ```astro
+ * ---
+ * import IABConsentDialog from '@c15t/astro/components/iab-consent-dialog.astro';
+ * ---
+ * <IABConsentDialog />
+ * ```
+ */
+interface Props {
+	/** Warm the island's chunk once the browser is idle. */
+	preload?: boolean;
+}
+const { preload = false } = Astro.props;
+---
+<div data-c15t-dialog-host="iab" data-preload={preload ? 'true' : undefined}></div>
+<script>
+	import { preloadDialog } from '@c15t/astro/client';
+	// The integration registers the island for the configured `ui`; see
+	// `<ConsentDialog />` for why the specifier does not live here.
+	const host = document.querySelector('[data-c15t-dialog-host="iab"]');
+	if (host?.getAttribute('data-preload') === 'true') {
+		const schedule = () => {
+			void preloadDialog();
+		};
+		if ('requestIdleCallback' in window) {
+			window.requestIdleCallback(schedule);
+		} else {
+			window.setTimeout(schedule, 2000);
+		}
+	}
+</script>

package/src/components/iab-prompt.astro ADDED Viewed

@@ -0,0 +1,316 @@
+---
+/**
+ * Server-rendered IAB TCF banner.
+ *
+ * The same deal as `<ConsentBanner />`: markup, copy and the purposes
+ * summary are produced on the server with no framework JavaScript, and the
+ * only client code is the delegated `data-c15t-action` handler every banner
+ * on the site already shares. `customize` opens the TCF preference centre
+ * through `<IABConsentDialog />`'s island, so the TCF surface downloads
+ * only when someone asks for it.
+ *
+ * The summary — which purposes, stacks and special features the banner
+ * names, how many it leaves out, how many vendors there are — comes from
+ * the shared model in `@c15t/iab/headless`, the same one the React, Svelte
+ * and Vue banners read. Same DOM shape and the same `data-testid`s, so the
+ * cross-framework parity gate compares like with like.
+ *
+ * It renders only when the server already has a vendor list. Hosted and
+ * manifest mode get one from `/init`; offline mode needs `iab.gvl` or
+ * `iab.gvlURL` on the integration options.
+ *
+ * ```astro
+ * ---
+ * import IABConsentBanner from '@c15t/astro/components/iab-consent-banner.astro';
+ * import IABConsentDialog from '@c15t/astro/components/iab-consent-dialog.astro';
+ * ---
+ * <IABConsentBanner />
+ * <IABConsentDialog />
+ * ```
+ */
+import { defaultTranslationConfig, resolveConsentPresentation } from '@c15t/core';
+import type { TranslationsResponse } from '@c15t/core';
+import { resolveIABBannerSummary } from '@c15t/iab/headless';
+import {
+	buildColorSchemeScript,
+	buildConfigScript,
+	markConfigEmitted,
+} from '@c15t/astro/server';
+import Branding from './branding.astro';
+import actionStyles from '@c15t/ui/styles/components/consent-actions';
+import styles from '@c15t/ui/styles/components/iab-consent-banner';
+import buttonStyles from '@c15t/ui/styles/components/button';
+import { getTextDirection } from '@c15t/ui/utils';
+type IABAction = 'reject' | 'accept' | 'customize';
+interface Props {
+	/** Which action gets the filled treatment. */
+	primaryButton?: IABAction;
+	/**
+	 * Which consent models this banner responds to. Matches the `models`
+	 * prop on the React, Svelte and Vue IAB banners.
+	 */
+	models?: string[];
+	/** Ship the DOM without the bundled stylesheet's class names. */
+	noStyle?: boolean;
+	/** Extra class on the banner root. */
+	class?: string;
+	/** Drop the "Secured by c15t" tag. */
+	hideBranding?: boolean;
+	/** Paint the backdrop that goes with the banner's `aria-modal`. */
+	scrollLock?: boolean;
+	/**
+	 * Render even when the server decided the banner should stay hidden.
+	 * Useful for visual testing.
+	 */
+	force?: boolean;
+}
+const {
+	primaryButton = 'customize',
+	models = ['iab'],
+	noStyle = false,
+	class: className,
+	hideBranding = false,
+	scrollLock,
+	force = false,
+} = Astro.props;
+const { c15t } = Astro.locals;
+if (!c15t) {
+	throw new Error(
+		'@c15t/astro: `Astro.locals.c15t` is missing. The c15t() integration registers the middleware that populates it — check it is listed in astro.config, and that you have not set `middleware: false`.'
+	);
+}
+const { snapshot } = c15t;
+const { blocking } = resolveConsentPresentation({
+	override: { scrollLock },
+	policy: snapshot.policyRule,
+	presentation: c15t.options.presentation,
+	surface: 'prompt',
+});
+const emitConfig = markConfigEmitted(Astro.locals);
+const colorSchemeScript = emitConfig
+	? buildColorSchemeScript(c15t.options.colorScheme)
+	: '';
+const summary = resolveIABBannerSummary(
+	snapshot.iab?.enabled === false ? null : (snapshot.iab ?? null)
+);
+// No vendor list, no banner: every line of copy below interpolates a count
+// the summary derives from it. The browser boots, fetches one and mounts
+// the client banner instead.
+const shouldRender =
+	c15t.hasConsentUi &&
+	(force || c15t.shouldShowBanner) &&
+	summary.isReady &&
+	models.includes(snapshot.policyRule.model);
+const fallback = defaultTranslationConfig.translations.en as TranslationsResponse;
+const bundle = (snapshot.translations?.translations ?? fallback) as TranslationsResponse;
+const iabFallback = fallback.iab as NonNullable<TranslationsResponse['iab']>;
+const iab = (bundle.iab ?? iabFallback) as NonNullable<TranslationsResponse['iab']>;
+const copy = {
+	accept: iab.common?.acceptAll ?? iabFallback.common.acceptAll,
+	andMore: iab.banner?.andMore ?? iabFallback.banner.andMore,
+	customize: iab.common?.customize ?? iabFallback.common.customize,
+	description: iab.banner?.description ?? iabFallback.banner.description,
+	legitimateInterestNotice:
+		iab.banner?.legitimateInterestNotice ??
+		iabFallback.banner.legitimateInterestNotice,
+	partnersLink: iab.banner?.partnersLink ?? iabFallback.banner.partnersLink,
+	reject: iab.common?.rejectAll ?? iabFallback.common.rejectAll,
+	scopeServiceSpecific:
+		iab.banner?.scopeServiceSpecific ?? iabFallback.banner.scopeServiceSpecific,
+	securedBy: bundle.common?.securedBy ?? fallback.common.securedBy,
+	title: iab.banner?.title ?? iabFallback.banner.title,
+};
+const textDirection = getTextDirection(snapshot.translations?.language);
+const descriptionText = copy.description.replace(
+	'{partnerCount}',
+	String(summary.vendorCount)
+);
+const partnersLinkText = copy.partnersLink.replace(
+	'{count}',
+	String(summary.vendorCount)
+);
+// The link sits inside the sentence, so the copy is split around it rather
+// than concatenated — a translation is free to put it anywhere.
+const [descriptionBefore = descriptionText, descriptionAfter = ''] =
+	descriptionText.split(partnersLinkText);
+const labels: Record<IABAction, string> = {
+	accept: copy.accept,
+	customize: copy.customize,
+	reject: copy.reject,
+};
+/**
+ * The shared button stylesheet keys its variants off `data-*`. `reject` is
+ * never filled even when it is the primary action, which is what the React
+ * and Svelte banners do too.
+ */
+const buttonAttrs = function buttonAttrs(action: IABAction) {
+	const primary = action === primaryButton;
+	return {
+		mode: primary && action !== 'reject' ? 'filled' : 'stroke',
+		variant: primary ? 'primary' : 'neutral',
+	};
+};
+const rootClass = [noStyle ? '' : styles.root, noStyle ? '' : styles.bannerVisible, className]
+	.filter(Boolean)
+	.join(' ');
+---
+{
+	emitConfig && colorSchemeScript && (
+		<script is:inline set:html={colorSchemeScript} />
+	)
+}
+{emitConfig && <script is:inline set:html={buildConfigScript(c15t.config)} />}
+{
+	shouldRender && blocking && (
+		<div
+			aria-hidden="true"
+			class={noStyle ? '' : `${styles.overlay} ${styles.overlayVisible}`}
+			data-testid="iab-consent-banner-overlay"
+		/>
+	)
+}
+{
+	shouldRender && (
+		<div
+			class={rootClass}
+			data-c15t-visible="true"
+			data-blocking={blocking ? 'true' : undefined}
+			data-position={textDirection === 'ltr' ? 'bottom-left' : 'bottom-right'}
+			data-testid="iab-consent-banner-root"
+			dir={textDirection}
+			lang={snapshot.translations?.language}
+			tabindex="-1"
+		>
+			<div class={noStyle ? '' : styles.cardShell}>
+				<Branding
+					branding={snapshot.branding}
+					data-testid="iab-consent-banner-branding"
+					hide={hideBranding}
+					hostname={Astro.url.hostname}
+					noStyle={noStyle}
+					securedBy={copy.securedBy}
+					variant="banner-tag"
+				/>
+				<div
+					aria-label={copy.title}
+					aria-modal={blocking ? 'true' : undefined}
+					class={noStyle ? '' : styles.card}
+					data-testid="iab-consent-banner-card"
+					role={blocking ? 'dialog' : 'region'}
+				>
+					<div
+						class={noStyle ? '' : styles.header}
+						data-testid="iab-consent-banner-header"
+					>
+						<h2 class={noStyle ? '' : styles.title}>{copy.title}</h2>
+						<p class={noStyle ? '' : styles.description}>
+							{descriptionBefore}
+							<button
+								class={noStyle ? '' : styles.partnersLink}
+								data-c15t-action="customize"
+								data-c15t-dialog="iab"
+								data-c15t-tab="vendors"
+								data-testid="iab-consent-banner-partners-link"
+								type="button"
+							>
+								{partnersLinkText}
+							</button>
+							{descriptionAfter}
+						</p>
+						<ul class={noStyle ? '' : styles.purposeList}>
+							{summary.displayItems.map((name) => (
+								<li>{name}</li>
+							))}
+							{summary.remainingCount > 0 && (
+								<li class={noStyle ? '' : styles.purposeMore}>
+									{copy.andMore.replace(
+										'{count}',
+										String(summary.remainingCount)
+									)}
+								</li>
+							)}
+						</ul>
+						<p class={noStyle ? '' : styles.legitimateInterestNotice}>
+							{`${copy.legitimateInterestNotice} ${copy.scopeServiceSpecific}`}
+						</p>
+					</div>
+					<div
+						class={[noStyle ? '' : actionStyles.actionRoot, noStyle ? '' : styles.footer]
+							.filter(Boolean)
+							.join(' ')}
+						data-direction="row"
+						data-split="true"
+						data-testid="iab-consent-banner-footer"
+					>
+						<div
+							class={noStyle ? '' : actionStyles.actionGroup}
+							data-direction="row"
+						>
+							{(['reject', 'accept'] as const).map((action) => (
+								<button
+									class={noStyle ? '' : buttonStyles.button}
+									data-action={action}
+									data-c15t-action={action}
+									data-mode={noStyle ? undefined : buttonAttrs(action).mode}
+									data-size={noStyle ? undefined : 'small'}
+									data-testid={`iab-consent-banner-${action}-button`}
+									data-variant={
+										noStyle ? undefined : buttonAttrs(action).variant
+									}
+									type="button"
+								>
+									{labels[action]}
+								</button>
+							))}
+						</div>
+						<div
+							class={noStyle ? '' : actionStyles.actionGroup}
+							data-direction="row"
+						>
+							<button
+								class={noStyle ? '' : buttonStyles.button}
+								data-action="customize"
+								data-c15t-action="customize"
+								data-c15t-dialog="iab"
+								data-mode={noStyle ? undefined : buttonAttrs('customize').mode}
+								data-size={noStyle ? undefined : 'small'}
+								data-testid="iab-consent-banner-customize-button"
+								data-variant={
+									noStyle ? undefined : buttonAttrs('customize').variant
+								}
+								type="button"
+							>
+								{labels.customize}
+							</button>
+						</div>
+					</div>
+				</div>
+			</div>
+		</div>
+	)
+}
+<script>
+	// One delegated listener, shared with `<ConsentBanner />` and every
+	// dialog trigger on the site. Astro bundles and dedupes it across pages.
+	import { attachBannerActions } from '@c15t/astro/client';
+	attachBannerActions();
+</script>

package/src/components/islands/iab-dialog-surface.svelte ADDED Viewed

@@ -0,0 +1,15 @@
+<!--
+	The IAB TCF preference centre, on its own chunk.
+	The TCF surface is the biggest thing either dialog can render — vendor
+	lists, purposes, stacks — and only a site that configured IAB ever shows
+	it. Keeping it in its own island means the preference-centre chunk that
+	every other site downloads does not carry it.
+-->
+<script lang="ts">
+	import { IABConsentDialog } from '@c15t/svelte';
+	let { tab }: { tab?: 'purposes' | 'vendors' } = $props();
+</script>
+<IABConsentDialog initialTab={tab} />

package/src/components/islands/iab-dialog-surface.tsx ADDED Viewed

@@ -0,0 +1,25 @@
+/**
+ * The IAB TCF preference centre, on its own chunk.
+ *
+ * The TCF surface is the biggest thing either dialog can render — vendor
+ * lists, purposes, stacks — and only a site that configured IAB ever shows
+ * it. Keeping it in its own island means the preference-centre chunk that
+ * every other site downloads does not carry it.
+ */
+import { ConsentDraftProvider } from '@c15t/react';
+import { IABConsentDialog } from '@c15t/react/iab';
+/** Props the dialog island passes down. */
+export interface IABDialogSurfaceProps {
+	/** Which preference-centre tab to open on. */
+	tab?: 'purposes' | 'vendors';
+}
+const IABDialogSurface = ({ tab }: IABDialogSurfaceProps) => (
+	<ConsentDraftProvider>
+		<IABConsentDialog initialTab={tab} />
+	</ConsentDraftProvider>
+);
+export default IABDialogSurface;

package/src/components/islands/iab-dialog-surface.vue ADDED Viewed

@@ -0,0 +1,20 @@
+<!--
+	The IAB TCF preference centre, on its own chunk.
+	The TCF surface is the biggest thing either dialog can render — vendor
+	lists, purposes, stacks — and only a site that configured IAB ever shows
+	it. Keeping it in its own island means the preference-centre chunk that
+	every other site downloads does not carry it.
+-->
+<script setup lang="ts">
+import IABConsentDialog from '@c15t/vue/runtime/components/iab-consent-dialog.vue';
+const props = defineProps<{
+	/** Which preference-centre tab to open on. */
+	tab?: 'purposes' | 'vendors';
+}>();
+</script>
+<template>
+	<IABConsentDialog :initial-tab="props.tab" />
+</template>

package/src/components/islands/panel-surface.svelte ADDED Viewed

@@ -0,0 +1,57 @@
+<!--
+	The on-demand dialog island.
+	Mounted with Svelte 5's `mount()` the first time something opens a
+	dialog — never with `client:load` — so a visitor who never opens the
+	preference centre downloads no framework code at all.
+	The provider renders against the page's runtime rather than building one
+	of its own: Astro islands cannot see each other's context, so the kernel
+	has to be owned outside the component tree. The provider borrows it and
+	leaves `start()`/`dispose()` to the owner.
+-->
+<script lang="ts">
+	import type { ConsentRuntime } from '@c15t/core/runtime';
+	import { ConsentDialog, ConsentManagerProvider } from '@c15t/svelte';
+	import type { Component } from 'svelte';
+	let {
+		options,
+		runtime,
+		kind = 'preferences',
+		tab,
+	}: {
+		options: Record<string, unknown>;
+		runtime: ConsentRuntime;
+		kind?: 'preferences' | 'iab';
+		/** Which IAB preference-centre tab to open on. */
+		tab?: 'purposes' | 'vendors';
+	} = $props();
+	// The TCF surface is the larger half of this island and only an IAB site
+	// ever opens it, so it arrives on its own chunk.
+	let IABDialog = $state<Component | null>(null);
+	$effect(() => {
+		if (kind !== 'iab' || IABDialog) {
+			return;
+		}
+		void (async () => {
+			const module = await import('./iab-dialog-surface.svelte');
+			IABDialog = module.default as Component;
+		})();
+	});
+</script>
+<ConsentManagerProvider
+	{runtime}
+	options={options as never}
+>
+	{#if kind === 'iab'}
+		{#if IABDialog}
+			<IABDialog {tab} />
+		{/if}
+	{:else}
+		<ConsentDialog />
+	{/if}
+</ConsentManagerProvider>

package/src/components/islands/panel-surface.tsx ADDED Viewed

@@ -0,0 +1,67 @@
+/**
+ * The on-demand React dialog island.
+ *
+ * Mounted with `createRoot()` the first time something opens a dialog —
+ * never with `client:load` — so a visitor who never opens the preference
+ * centre downloads no React from us at all.
+ *
+ * The provider renders against the page's runtime rather than building one
+ * of its own: Astro islands cannot see each other's context, so the kernel
+ * has to be owned outside the component tree. `<ConsentProvider runtime>`
+ * borrows it and leaves `start()`/`dispose()` to the owner.
+ *
+ * `<ConsentDraftProvider>` is what makes Save work. `useConsentDraft()`
+ * falls back to a draft per hook call when no provider is in scope, so the
+ * category toggles and the Save button would each stage into their own
+ * copy: the switch would flip, and the save would commit nothing.
+ */
+import type { ConsentRuntime } from '@c15t/core/runtime';
+import {
+	ConsentDialog,
+	ConsentDraftProvider,
+	ConsentProvider,
+} from '@c15t/react';
+import { lazy, Suspense } from 'react';
+import type { DialogPresentationOptions } from '../../ui/provider-props';
+// The TCF surface is the larger half of this island and only an IAB site
+// ever opens it, so it arrives on its own chunk.
+const IABDialogSurface = lazy(() => import('./iab-dialog-surface'));
+/** Props the React dialog adapter passes in. */
+export interface ConsentDialogSurfaceProps {
+	/** The page-level runtime. The provider borrows it, it does not own it. */
+	runtime: ConsentRuntime;
+	/** Presentation options forwarded to the provider. */
+	options: DialogPresentationOptions;
+	/** Which dialog to render. */
+	kind?: 'preferences' | 'iab';
+	/** Which IAB preference-centre tab to open on. */
+	tab?: 'purposes' | 'vendors';
+}
+const ConsentDialogSurface = ({
+	runtime,
+	options,
+	kind = 'preferences',
+	tab,
+}: ConsentDialogSurfaceProps) => (
+	<ConsentProvider
+		runtime={runtime}
+		options={options}
+	>
+		{kind === 'iab' ? (
+			<Suspense fallback={null}>
+				<IABDialogSurface tab={tab} />
+			</Suspense>
+		) : (
+			<ConsentDraftProvider>
+				<ConsentDialog />
+			</ConsentDraftProvider>
+		)}
+	</ConsentProvider>
+);
+export default ConsentDialogSurface;

package/src/components/islands/panel-surface.vue ADDED Viewed

@@ -0,0 +1,39 @@
+<!--
+	The on-demand Vue dialog island.
+	Mounted as its own Vue app the first time something opens a dialog —
+	never with `client:load` — so a visitor who never opens the preference
+	centre downloads no consent UI at all.
+	The adapter installs `c15tVue` with the page's runtime before mounting
+	this component: Astro islands cannot see each other's provides, so the
+	kernel has to be owned outside the app. The plugin borrows it and leaves
+	`start()`/`dispose()` to the owner.
+-->
+<script setup lang="ts">
+import ConsentManager from '@c15t/vue/runtime/components/consent-manager.vue';
+import { defineAsyncComponent } from 'vue';
+withDefaults(
+	defineProps<{
+		kind?: 'preferences' | 'iab';
+		/** Which IAB preference-centre tab to open on. */
+		tab?: 'purposes' | 'vendors';
+	}>(),
+	{ kind: 'preferences', tab: undefined }
+);
+// The TCF surface is the larger half of this island and only an IAB site
+// ever opens it, so it arrives on its own chunk.
+const IABDialogSurface = defineAsyncComponent(
+	() => import('./iab-dialog-surface.vue')
+);
+</script>
+<template>
+	<IABDialogSurface
+		v-if="kind === 'iab'"
+		:tab="tab"
+	/>
+	<ConsentManager v-else />
+</template>

package/src/components/panel-trigger.astro ADDED Viewed

@@ -0,0 +1,48 @@
+---
+/**
+ * A button that opens a consent dialog.
+ *
+ * Ships no JavaScript of its own — it carries `data-c15t-action` and the
+ * one delegated listener the banner already installed picks it up. Use it
+ * for the "Cookie preferences" link every footer needs.
+ *
+ * ```astro
+ * <ConsentDialogTrigger>Cookie preferences</ConsentDialogTrigger>
+ * <ConsentDialogTrigger kind="iab">Ad partners</ConsentDialogTrigger>
+ * ```
+ */
+interface Props {
+	/** Which dialog to open. */
+	kind?: 'preferences' | 'iab';
+	/** Extra class names. */
+	class?: string;
+	/** Render an `<a href="#">` instead of a `<button>`. */
+	as?: 'button' | 'a';
+}
+const { kind = 'preferences', class: className, as = 'button' } = Astro.props;
+const Tag = as;
+// Hidden until a resolved rule owes consent UI: nothing to manage before a
+// rule resolves, and nothing owed under a `none` rule with no rights. The
+// browser client toggles `hidden` as the snapshot changes.
+const hasConsentUi = Astro.locals.c15t?.hasConsentUi ?? true;
+---
+<Tag
+	class={className}
+	data-c15t-action="customize"
+	data-c15t-dialog={kind}
+	data-c15t-surface="trigger"
+	data-testid="consent-dialog-trigger"
+	hidden={hasConsentUi ? undefined : true}
+	href={as === 'a' ? '#c15t-preferences' : undefined}
+	type={as === 'button' ? 'button' : undefined}
+>
+	<slot />
+</Tag>
+<script>
+	import { attachBannerActions } from '@c15t/astro/client';
+	attachBannerActions();
+</script>