@getvitops/astro 1.0.0 → 2.1.0

package/src/analytics.ts

@@ -0,0 +1,325 @@
+/**
+ * The `<Analytics />` resolution layer — provider config in, the exact tags to
+ * emit out.
+ *
+ * Kept separate from `Analytics.astro` for the same reason `seo.ts` is separate
+ * from `Seo.astro`: everything decidable is a pure function and asserted in
+ * `analytics.test.ts`, and the component only renders what this returns.
+ *
+ * Two properties here are the point of the whole file:
+ *
+ *  - **Which consent category a provider needs is derived, never declared.** It
+ *    follows from whether that provider sets cookies, which follows from its own
+ *    configuration (Matomo with `disableCookies` is genuinely cookieless; Matomo
+ *    with `cookies: true` is not). A consumer cannot mark Google Analytics
+ *    `necessary` to skip a banner, because `setsCookies` isn't theirs to set.
+ *  - **The same fact drives the legal documents.** `@getvitops/generator`'s
+ *    `legal/providers.ts` maps the *site config's* `analytics` block onto named
+ *    processors with cookie lists. If a provider is configured here but not
+ *    there, the site runs a tag its own cookie notice doesn't disclose — so the
+ *    integration warns, and `warnings` is returned as data so that check is a
+ *    test rather than a log line someone might scroll past.
+ */
+
+/**
+ * When a tag is allowed to load. Third-party analytics is never worth a
+ * millisecond of the critical path, so the default puts every tag after `load`.
+ */
+export type AnalyticsStrategy = 'idle' | 'async' | 'interaction';
+
+/**
+ * The consent vocabulary, mirroring `@getvitops/core`'s `consent/store.ts`.
+ * Mirrored rather than imported because this value is `JSON.stringify`d into the
+ * virtual module and the component reads it at build time, while core's copy is a
+ * browser runtime — `consent.test.ts` and `analytics.test.ts` pin both ends.
+ */
+export type ConsentCategory = 'necessary' | 'analytics' | 'marketing' | 'preferences';
+
+export type OptionalConsentCategory = Exclude<ConsentCategory, 'necessary'>;
+
+export interface GoogleAnalyticsOptions {
+  /** Measurement ID, e.g. `G-XXXXXXXXXX`. */
+  id: string;
+  /**
+   * Which category gates it (default `analytics`). Set `marketing` when the
+   * property feeds Google Ads — the tag is the same, the permission isn't.
+   */
+  category?: OptionalConsentCategory;
+  /** Extra `gtag('config', id, …)` parameters, e.g. `{ send_page_view: false }`. */
+  config?: Record<string, string | number | boolean>;
+}
+
+export interface ClarityOptions {
+  /** Clarity project ID. */
+  id: string;
+  category?: OptionalConsentCategory;
+}
+
+export interface MatomoOptions {
+  /** Instance base URL — self-hosted, or `https://<you>.matomo.cloud`. */
+  url: string;
+  /** Site ID within that instance. */
+  siteId: string | number;
+  /**
+   * Let Matomo set its cookies (default **false**).
+   *
+   * The default is what makes Matomo the cookieless option: with
+   * `disableCookies` it stores no identifier on the device, needs no banner, and
+   * the generated cookie notice can state positively that it sets none. Turning
+   * this on gives you returning-visitor metrics and a consent obligation.
+   */
+  cookies?: boolean;
+}
+
+export interface PlausibleOptions {
+  /** The domain as registered in Plausible, e.g. `example.com`. */
+  domain: string;
+  /** Script URL — override for a self-hosted instance or a custom-events build. */
+  src?: string;
+}
+
+export interface GetvitopsAnalyticsOptions {
+  googleAnalytics?: string | GoogleAnalyticsOptions;
+  clarity?: string | ClarityOptions;
+  matomo?: MatomoOptions;
+  plausible?: string | PlausibleOptions;
+  /** When tags load (default `'idle'`). */
+  strategy?: AnalyticsStrategy;
+}
+
+/**
+ * The consent gate, configured on the integration rather than inside `analytics`.
+ *
+ * That placement is the design, not an accident: analytics is one consumer of
+ * consent, not its owner. A/B assignment, account personalisation and third-party
+ * embeds gate on the same choice via `data-consent`, and a site can enable the
+ * banner with no analytics configured at all.
+ */
+export interface GetvitopsConsentOptions {
+  /**
+   * Categories the banner offers. Defaults to the ones the configured providers
+   * actually need — offering a choice nothing is waiting on is noise.
+   */
+  categories?: OptionalConsentCategory[];
+  /** Link the banner to the cookie notice (`vitops legal` renders one). */
+  policyUrl?: string;
+}
+
+/** One tag, fully resolved. */
+export interface ResolvedTag {
+  key: 'googleAnalytics' | 'clarity' | 'matomo' | 'plausible';
+  /** The provider as a reader would recognise it — used in warnings. */
+  provider: string;
+  category: ConsentCategory;
+  setsCookies: boolean;
+  /** Names (or `prefix*` patterns) to clear when consent is withdrawn. */
+  cookies: string[];
+  strategy: AnalyticsStrategy;
+  /**
+   * Emitted inert (`type="text/plain"`) for the runtime to activate, rather than
+   * as a live `<script>`. False only for the one case that needs no runtime at
+   * all: a cookieless provider with `strategy: 'async'`.
+   */
+  gated: boolean;
+  /** Bootstrap JS. Runs before `src`, so a queue is populated before it drains. */
+  inline: string;
+  src: string | null;
+  attrs: Record<string, string>;
+}
+
+export interface ResolvedAnalytics {
+  tags: ResolvedTag[];
+  /** Does anything here need `@getvitops/core/consent` loaded? */
+  needsRuntime: boolean;
+  /** Configuration problems, as prose. The integration logs these. */
+  warnings: string[];
+}
+
+export interface ResolveAnalyticsContext {
+  /** Is the consent gate enabled on this site (`getvitops({ consent })`)? */
+  consent?: boolean;
+}
+
+/**
+ * IDs land inside an inline `<script>`, so they are checked rather than trusted.
+ * A `</script>` in a measurement ID is not a plausible accident, but the cost of
+ * the guard is one regex and the cost of not having it is arbitrary script
+ * injection from a config file.
+ */
+const SAFE_ID = /^[\w.-]+$/;
+
+function bad(value: string): boolean {
+  return !SAFE_ID.test(value);
+}
+
+/** JSON is a subset of JS object-literal syntax; `<` can't appear unescaped. */
+function literal(value: Record<string, string | number | boolean>): string {
+  return JSON.stringify(value).replaceAll('<', '\\u003c');
+}
+
+function googleAnalytics(input: string | GoogleAnalyticsOptions): ResolvedTag | string {
+  const opts = typeof input === 'string' ? { id: input } : input;
+  if (bad(opts.id)) return `googleAnalytics: "${opts.id}" is not a valid measurement ID. Skipped.`;
+  const config = opts.config ? `,${literal(opts.config)}` : '';
+  return {
+    key: 'googleAnalytics',
+    provider: 'Google Analytics',
+    category: opts.category ?? 'analytics',
+    setsCookies: true,
+    cookies: ['_ga', '_ga_*', '_gid', '_gat', '_gat_*'],
+    strategy: 'idle',
+    gated: true,
+    inline:
+      `window.dataLayer=window.dataLayer||[];` +
+      `function gtag(){dataLayer.push(arguments)}` +
+      `gtag('js',new Date());` +
+      `gtag('config','${opts.id}'${config});`,
+    src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(opts.id)}`,
+    attrs: {},
+  };
+}
+
+function clarity(input: string | ClarityOptions): ResolvedTag | string {
+  const opts = typeof input === 'string' ? { id: input } : input;
+  if (bad(opts.id)) return `clarity: "${opts.id}" is not a valid project ID. Skipped.`;
+  const category = opts.category ?? 'analytics';
+  // Clarity's snippet injects its own <script>, so there is no `src` for us to
+  // schedule — activation *is* the load.
+  //
+  // The consentv2 call is not redundant with having gated the tag: Microsoft
+  // enforces consent signals for EEA/UK/CH traffic from the project side, and
+  // without one Clarity degrades to no-consent mode even though the visitor
+  // agreed. `ad_Storage` follows the category, because that is the only thing
+  // that tells us whether this tag was permitted for advertising.
+  return {
+    key: 'clarity',
+    provider: 'Microsoft Clarity',
+    category,
+    setsCookies: true,
+    cookies: ['_clck', '_clsk', 'MUID', 'CLID', 'ANONCHK', 'SM'],
+    strategy: 'idle',
+    gated: true,
+    inline:
+      `(function(c,l,a,r,i,t,y){c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};` +
+      `t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;` +
+      `y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y)})` +
+      `(window,document,"clarity","script","${opts.id}");` +
+      `window.clarity('consentv2',{ad_Storage:'${
+        category === 'marketing' ? 'granted' : 'denied'
+      }',analytics_Storage:'granted'});`,
+    src: null,
+    attrs: {},
+  };
+}
+
+function matomo(opts: MatomoOptions): ResolvedTag | string {
+  const siteId = String(opts.siteId);
+  if (bad(siteId)) return `matomo: "${siteId}" is not a valid site ID. Skipped.`;
+  let base: URL;
+  try {
+    base = new URL(opts.url);
+  } catch {
+    return `matomo: "${opts.url}" is not a valid URL. Skipped.`;
+  }
+  const url = `${base.origin}${base.pathname.replace(/\/*$/, '')}/`;
+  const cookies = opts.cookies === true;
+
+  // `disableCookies` must be pushed *before* trackPageView, or the first request
+  // of the visit sets the cookies this option exists to avoid.
+  return {
+    key: 'matomo',
+    provider: 'Matomo',
+    category: cookies ? 'analytics' : 'necessary',
+    setsCookies: cookies,
+    cookies: cookies ? ['_pk_id*', '_pk_ses*', '_pk_ref*', '_pk_cvar*', '_pk_hsr*'] : [],
+    strategy: 'idle',
+    gated: true,
+    inline:
+      `var _paq=window._paq=window._paq||[];` +
+      (cookies ? '' : `_paq.push(['disableCookies']);`) +
+      `_paq.push(['trackPageView']);_paq.push(['enableLinkTracking']);` +
+      `(function(){var u="${url}";` +
+      `_paq.push(['setTrackerUrl',u+'matomo.php']);_paq.push(['setSiteId','${siteId}']);` +
+      `var d=document,g=d.createElement('script'),s=d.getElementsByTagName('script')[0];` +
+      `g.async=true;g.src=u+'matomo.js';s.parentNode.insertBefore(g,s)})();`,
+    src: null,
+    attrs: {},
+  };
+}
+
+function plausible(input: string | PlausibleOptions): ResolvedTag | string {
+  const opts = typeof input === 'string' ? { domain: input } : input;
+  if (bad(opts.domain)) return `plausible: "${opts.domain}" is not a valid domain. Skipped.`;
+  return {
+    key: 'plausible',
+    provider: 'Plausible Analytics',
+    // Cookieless and storing no cross-site identifier, so there is nothing for a
+    // banner to ask about. It still goes through the runtime for scheduling.
+    category: 'necessary',
+    setsCookies: false,
+    cookies: [],
+    strategy: 'idle',
+    gated: true,
+    inline: '',
+    src: opts.src ?? 'https://plausible.io/js/script.js',
+    attrs: { 'data-domain': opts.domain },
+  };
+}
+
+/**
+ * Resolve the configured providers into the tags to emit.
+ *
+ * An invalid provider is dropped with a warning rather than throwing: one
+ * malformed ID should not take down a build, and a missing tag is visible in the
+ * output while a failed build is just a red wall.
+ */
+export function resolveAnalytics(
+  opts: GetvitopsAnalyticsOptions | undefined,
+  ctx: ResolveAnalyticsContext = {},
+): ResolvedAnalytics {
+  const warnings: string[] = [];
+  const tags: ResolvedTag[] = [];
+  if (!opts) return { tags, needsRuntime: false, warnings };
+
+  const strategy = opts.strategy ?? 'idle';
+  const results = [
+    opts.googleAnalytics === undefined ? null : googleAnalytics(opts.googleAnalytics),
+    opts.clarity === undefined ? null : clarity(opts.clarity),
+    opts.matomo === undefined ? null : matomo(opts.matomo),
+    opts.plausible === undefined ? null : plausible(opts.plausible),
+  ];
+
+  for (const result of results) {
+    if (result === null) continue;
+    if (typeof result === 'string') {
+      warnings.push(result);
+      continue;
+    }
+    // A cookieless tag on `async` needs nothing from the runtime, so it is emitted
+    // as an ordinary <script async> and that site ships no consent bundle at all.
+    const gated = result.category !== 'necessary' || strategy !== 'async';
+    tags.push({ ...result, strategy, gated });
+  }
+
+  const setting = tags.filter((t) => t.setsCookies);
+  if (setting.length && !ctx.consent) {
+    warnings.push(
+      `${setting.map((t) => t.provider).join(' and ')} ${setting.length === 1 ? 'sets' : 'set'} ` +
+        `cookies (${setting.flatMap((t) => t.cookies).join(', ')}) and \`consent\` is off, so ` +
+        `${setting.length === 1 ? 'it loads' : 'they load'} for every visitor with no way to ` +
+        'decline. Set `consent: true`, or switch to a cookieless provider (Plausible, or Matomo ' +
+        'with its default `cookies: false`).',
+    );
+  }
+
+  return { tags, needsRuntime: tags.some((t) => t.gated), warnings };
+}
+
+/** Which optional categories a set of tags actually needs a visitor to decide. */
+export function consentCategories(tags: ResolvedTag[]): OptionalConsentCategory[] {
+  const used = new Set<OptionalConsentCategory>();
+  for (const tag of tags) {
+    if (tag.category !== 'necessary') used.add(tag.category);
+  }
+  return (['analytics', 'marketing', 'preferences'] as const).filter((c) => used.has(c));
+}

package/src/components/Analytics.astro

@@ -0,0 +1,59 @@
+---
+/**
+ * <Analytics /> — the site's analytics tags, off the critical path and behind the
+ * consent gate. Place in your layout's <head>; requires the getvitops()
+ * integration, which supplies `virtual:getvitops/head`.
+ *
+ * A dumb renderer over `resolveAnalytics()` (src/analytics.ts) — every decision
+ * about which tag, which consent category and which cookies lives there and is
+ * unit-tested. Nothing in this file chooses anything.
+ *
+ * The gated tags are `type="text/plain"`, which is the whole trick: the browser
+ * never parses the body as script and never fetches the library, so an undecided
+ * or declining visitor's page issues no third-party request at all. Consent
+ * implemented by *asking a tracker not to track* is a promise; this is a fact
+ * about the document. `@getvitops/core/consent` (loaded by <Head />) activates
+ * them when their category is granted and their strategy has fired.
+ *
+ * Emits no `preconnect` on purpose: warming a connection at parse time is exactly
+ * the critical-path cost the `idle` strategy exists to avoid.
+ */
+import { type AnalyticsStrategy, resolveAnalytics } from '../analytics.ts';
+// @ts-ignore — virtual module provided by the getvitops() integration at build time
+import head from 'virtual:getvitops/head';
+
+interface Props {
+  /** Render nothing (e.g. on a preview deployment). Defaults to true. */
+  enabled?: boolean;
+  /** Override the configured load strategy for this page. */
+  strategy?: AnalyticsStrategy;
+}
+const { enabled = true, strategy } = Astro.props;
+
+const options = strategy ? { ...head.analytics, strategy } : head.analytics;
+const { tags } = enabled
+  ? resolveAnalytics(options, { consent: head.consent })
+  : { tags: [] };
+---
+
+{tags.map((tag) => tag.gated
+  ? (
+      <script
+        is:inline
+        type="text/plain"
+        data-vitops-tag
+        data-consent={tag.category}
+        data-strategy={tag.strategy}
+        data-src={tag.src}
+        data-consent-cookies={tag.cookies.length ? tag.cookies.join(',') : undefined}
+        {...tag.attrs}
+        set:html={tag.inline}
+      />
+    )
+  : (
+      <>
+        {tag.inline && <script is:inline set:html={tag.inline} />}
+        {tag.src && <script is:inline async src={tag.src} {...tag.attrs}></script>}
+      </>
+    )
+)}

package/src/components/CookieConsent.astro

@@ -0,0 +1,106 @@
+---
+/**
+ * <CookieConsent /> — the consent banner. Place near the end of <body>; requires
+ * the getvitops() integration with `consent` enabled, which is what loads
+ * `@getvitops/core/consent` (the gate + `<wc-consent>`).
+ *
+ * This renders the *fallback*: a real, semantic form with real buttons. The
+ * element parses and augments it — it never renders from empty. The markup ships
+ * `hidden` because with no JS the gate never runs, so no gated tag loads and no
+ * non-essential cookie is set: there is genuinely nothing to consent to, and a
+ * banner would be asking permission for something that isn't happening.
+ *
+ * The banner does not itself set a cookie. Only an explicit accept/reject/save
+ * writes one — otherwise the thing asking permission would be the thing needing
+ * it.
+ *
+ * **Consent is not an analytics feature.** The same gate covers A/B assignment,
+ * personalisation and embedded third-party content: mark any of them
+ * `data-consent="<category>"` and they wait on the same choice. Which categories
+ * this banner offers therefore comes from the integration, not from
+ * `<Analytics />`.
+ */
+// @ts-ignore — virtual module provided by the getvitops() integration at build time
+import head from 'virtual:getvitops/head';
+import type { OptionalConsentCategory } from '../analytics.ts';
+
+interface Props {
+  /** Categories to offer. Defaults to those the configured providers need. */
+  categories?: OptionalConsentCategory[];
+  /** Link to the cookie notice (`vitops legal` renders one). */
+  policyUrl?: string;
+  policyLabel?: string;
+  heading?: string;
+  acceptLabel?: string;
+  rejectLabel?: string;
+  saveLabel?: string;
+  /** Per-category wording, merged over the defaults. */
+  labels?: Partial<Record<OptionalConsentCategory, string>>;
+  /**
+   * Keep an already-running tracker alive after a revoke (default false — we
+   * reload). See `ConsentApi.reloadOnRevoke`.
+   */
+  noReloadOnRevoke?: boolean;
+}
+
+const DEFAULT_LABELS: Record<OptionalConsentCategory, string> = {
+  analytics: 'Analytics — how the site is used, so we can improve it',
+  marketing: 'Marketing — measuring which campaigns bring people here',
+  preferences: 'Preferences — remembering choices you make on the site',
+};
+
+const {
+  categories = head.consentCategories ?? ['analytics'],
+  policyUrl = head.consentPolicyUrl ?? undefined,
+  policyLabel = 'Cookie notice',
+  heading = 'Cookies on this site',
+  acceptLabel = 'Accept',
+  rejectLabel = 'Reject',
+  saveLabel = 'Save choices',
+  labels = {},
+  noReloadOnRevoke = false,
+} = Astro.props;
+
+const wording = { ...DEFAULT_LABELS, ...labels };
+// One category is a yes/no question; checkboxes for it would be a form standing in
+// for two buttons that already say the same thing.
+const choose = categories.length > 1;
+---
+
+<wc-consent hidden {...noReloadOnRevoke ? { 'reload-on-revoke': 'false' } : {}}>
+  {/*
+    Shown in the top layer. A plain fixed banner resolves against the nearest
+    containing block, and `body { container-type: inline-size }` — ordinary in a
+    framework whose breakpoints are container queries — makes body one, trapping
+    the banner mid-page. `manual`, not `auto`: light dismiss would let a stray
+    click count as a decision.
+  */}
+  <form class="consent" popover="manual" aria-label={heading}>
+    <div class="consent__body">
+      <slot>
+        <p>
+          We use cookies to understand how this site is used. You can decline without
+          losing any functionality.
+        </p>
+      </slot>
+      {policyUrl && <a class="link" href={policyUrl}>{policyLabel}</a>}
+    </div>
+
+    {choose && (
+      <div class="consent__options">
+        {categories.map((category) => (
+          <label>
+            <input type="checkbox" name={category} />
+            {wording[category]}
+          </label>
+        ))}
+      </div>
+    )}
+
+    <div class="consent__actions">
+      <button type="button" class="btn" data-consent-reject>{rejectLabel}</button>
+      {choose && <button type="button" class="btn" data-consent-save>{saveLabel}</button>}
+      <button type="button" class="cta" data-consent-accept>{acceptLabel}</button>
+    </div>
+  </form>
+</wc-consent>

package/src/components/Details.astro

@@ -1,5 +1,5 @@
 ---
-import { Icon } from 'astro-icon/components';
+import Icon from './Icon.astro';
 
 interface Item {
   label: string;
@@ -12,8 +12,14 @@ interface Props {
   icon?: string;
   items: Item[];
   class?: string;
-  /** Resolve semantic icon names to fully-qualified astro-icon names.
-   *  Defaults to pass-through (expects already-qualified names like 'fa7-solid:chevron-down'). */
+  /**
+   * Map a semantic name onto a fully-qualified one before rendering.
+   *
+   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * the site's set is configured once instead of threaded through every call
+   * site. Left in place because removing it would break consumers passing one;
+   * when omitted, `<Icon />` resolves through the site config.
+   */
   iconResolver?: (name: string) => string;
 }
 
@@ -28,7 +34,7 @@ const {
 <details class={`details-collapse ${className || ''}`}>
   <summary class="details-trigger"><slot>
     {label}
-    <Icon name={iconResolver('expand-more')} class="details-icon" /></slot>
+    <Icon name={iconResolver('chevron-down')} class="details-icon" /></slot>
   </summary>
   <slot name="content" />
 </details>

package/src/components/Drawer.astro

@@ -1,5 +1,5 @@
 ---
-import { Icon } from 'astro-icon/components';
+import Icon from './Icon.astro';
 
 type Attrs = Record<string, string | number | boolean>;
 
@@ -16,8 +16,14 @@ interface Props {
   class?: string;
   maxWidth?: string;
   maxHeight?: string;
-  /** Resolve semantic icon names to fully-qualified astro-icon names.
-   *  Defaults to pass-through (expects already-qualified names like 'fa7-solid:bars'). */
+  /**
+   * Map a semantic name onto a fully-qualified one before rendering.
+   *
+   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * the site's set is configured once instead of threaded through every call
+   * site. Left in place because removing it would break consumers passing one;
+   * when omitted, `<Icon />` resolves through the site config.
+   */
   iconResolver?: (name: string) => string;
 }
 

package/src/components/Head.astro

@@ -4,22 +4,28 @@
  * layout's <head>. Requires the getvitops() integration (it provides the
  * `virtual:getvitops/head` config + copies the assets into public/).
  *
- * Renders: favicon + PWA manifest tags, and the web-component runtime scripts in
+ * Renders: favicon + PWA manifest tags, the webfont <Font /> tags for families
+ * declared via getvitops({ fonts }), and the web-component runtime scripts in
  * canonical order/priority. It does NOT emit a stylesheet <link> — the CSS is
  * imported into Astro's graph by the integration and Astro emits that link.
  */
 // @ts-ignore — virtual module provided by the getvitops() integration at build time
 import head from 'virtual:getvitops/head';
+// @ts-ignore — `Font` is provided by Astro's Fonts API (astro >= 7)
+import { Font } from 'astro:assets';
 
 interface Props {
   favicons?: boolean;
   webComponents?: boolean;
   editor?: boolean;
+  /** Emit `<Font />` for the declared families (default true when any were declared). */
+  fonts?: boolean;
 }
 const {
   favicons = head.favicons,
   webComponents = head.webComponents,
   editor = head.editor,
+  fonts = true,
 } = Astro.props;
 const wc = head.wcBase;
 
@@ -34,6 +40,19 @@ const THEME_SCRIPT =
   `try{var s=localStorage.getItem('vitops-color-scheme');` +
   `if(s==='light'||s==='dark'){document.documentElement.dataset.theme=s;` +
   `document.documentElement.style.colorScheme=s+' only'}}catch(e){}`;
+
+/*
+ * No `<html>` class flips here on purpose. `animation.css` used to need `no-js`
+ * and `.no-scroll-timeline` set before first paint; it now asks the platform
+ * directly — `@media (scripting: enabled)` and `@supports not
+ * (animation-timeline: view())` — so there is nothing to inject.
+ *
+ * That is not a simplification for its own sake: a class-based switch could only
+ * ever reach pages that render this component, so a Bricks site or a consumer
+ * with their own `<head>` stayed broken, and `no-js` in particular had to be
+ * written into an `<html>` tag Astro does not own. The CSS version is correct for
+ * every consumer of the stylesheet, including the ones that never load any JS.
+ */
 ---
 
 {favicons && head.faviconLinks.map((l: { rel: string; href: string; type?: string; sizes?: string }) => (
@@ -41,6 +60,23 @@ const THEME_SCRIPT =
 ))}
 {favicons && head.themeColor && <meta name="theme-color" content={head.themeColor} />}
 
+{/*
+  Webfonts declared via getvitops({ fonts }). Astro's `fonts:` config resolves and
+  optimises the files; this component is what actually puts the @font-face on the page,
+  so without it the config is inert and every --font-* token falls through to its
+  fallback stack.
+
+  Only families this integration registered — <Font /> throws on a cssVariable Astro
+  cannot resolve, so a family from a user-level `fonts:` or another integration is
+  deliberately not listed here; render <Font /> for those yourself.
+
+  `preload` comes from the declaration, so which faces get a preload link is a property
+  of the font, not something re-decided in every layout.
+*/}
+{fonts && head.fonts.map((f: { cssVariable: string; preload: boolean | object[] }) => (
+  <Font cssVariable={f.cssVariable} preload={f.preload} />
+))}
+
 {/* Set by getvitops({ sitemap }); null when no sitemap was registered. */}
 {head.sitemap && <link rel="sitemap" type="application/xml" href={head.sitemap} />}
 
@@ -66,6 +102,15 @@ const THEME_SCRIPT =
   </>
 )}
 
+{/*
+  The consent gate + <wc-consent> — its own Lit-free bundle, loaded whenever the
+  gate is on or a tag needs scheduling. Deliberately NOT inside the
+  `webComponents` block: this module decides whether third-party tags run at all,
+  so it must not be switched off along with the element runtime, and it must be
+  free to load ahead of the deferred Lit bundle rather than behind it.
+*/}
+{head.consentRuntime && <script is:inline type="module" src={`${wc}/consent.js`}></script>}
+
 {/*
   The live theme editor — a separate, opt-in bundle (getvitops({ editor: true })).
   It is tooling, not part of the runtime, so it stays out of elements.js and off