@sarimarcus/content-sites-ui 0.16.0 → 0.18.0

package/src/editorial/ArticlesListingPage.astro

@@ -0,0 +1,40 @@
+---
+/**
+ * ArticlesListingPage — the shell of an article listing (index, topic hub, their paginated pages): breadcrumb band,
+ * a header (eyebrow, heading, accent rule, lede) and <main>. The route keeps Layout, schema, paging and image maps,
+ * passes the breadcrumb in `breadcrumb`, an optional line under the lede in `header-extra`, and the main content
+ * (its own Containers) as default-slot children.
+ */
+import BreadcrumbBand from '../layout/BreadcrumbBand.astro';
+import Container from '../layout/Container.astro';
+
+interface Props {
+  eyebrow: string;
+  heading: string;
+  lede: string;
+  /** Mark <main> as the Pagefind body. */
+  pagefindBody?: boolean;
+}
+
+const { eyebrow, heading, lede, pagefindBody = false } = Astro.props;
+---
+
+<BreadcrumbBand>
+  <slot name="breadcrumb" />
+</BreadcrumbBand>
+
+<header class="bg-muted/30 border-b border-border pt-12 pb-10">
+  <Container size="measure">
+    <p class="text-sm font-semibold uppercase tracking-[0.18em] text-primary mb-3">{eyebrow}</p>
+    <h1 class="text-3xl sm:text-4xl font-normal font-display text-foreground leading-tight text-balance">
+      {heading}
+    </h1>
+    <div class="mt-4 flex"><span class="block h-0.5 w-16 rounded-full bg-accent"></span></div>
+    <p class="mt-5 text-lg text-muted-foreground leading-relaxed">{lede}</p>
+    <slot name="header-extra" />
+  </Container>
+</header>
+
+<main class="py-14" data-pagefind-body={pagefindBody ? '' : undefined}>
+  <slot />
+</main>

package/src/editorial/NotFoundPage.astro

@@ -0,0 +1,98 @@
+---
+/**
+ * NotFoundPage — the 404 body: a decorative arch-and-zellige backdrop, the large "404", a message, a home button, a
+ * search link and a short list of section links. The route keeps Layout (with `noindex`), passes every string and
+ * imports `@sarimarcus/content-sites-ui/not-found.css`.
+ */
+import Button from '../primitives/Button.astro';
+import LinkArrow from '../primitives/LinkArrow.astro';
+import Icon from '../primitives/Icon.astro';
+
+interface Props {
+  tagline: string;
+  lede: string;
+  homeHref: string;
+  homeLabel: string;
+  searchHref: string;
+  searchLabel: string;
+  searchAriaLabel: string;
+  exploreLabel: string;
+  /** Accessible name of the section links. */
+  exploreAriaLabel?: string;
+  links: { href: string; label: string }[];
+}
+
+const { tagline, lede, homeHref, homeLabel, searchHref, searchLabel, searchAriaLabel, exploreLabel, exploreAriaLabel = 'Explore sections', links } = Astro.props;
+---
+
+<main class="relative min-h-[80vh] flex items-center justify-center overflow-hidden bg-muted">
+  {/* Geometric zellige-inspired background pattern — pure CSS */}
+  <div class="absolute inset-0 opacity-[0.04] pointer-events-none" aria-hidden="true">
+    <div class="not-found-zellige-grid"></div>
+  </div>
+
+  {/* Decorative horseshoe arches — layered behind content */}
+  <div class="absolute inset-0 flex items-end justify-center pointer-events-none" aria-hidden="true">
+    <div class="not-found-arch-row">
+      <div class="not-found-arch not-found-arch--left"></div>
+      <div class="not-found-arch not-found-arch--center"></div>
+      <div class="not-found-arch not-found-arch--right"></div>
+    </div>
+  </div>
+
+  <div class="relative z-10 max-w-deck mx-auto px-6 py-20 text-center">
+    {/* Decorative star motif */}
+    <div class="flex justify-center mb-6" aria-hidden="true">
+      <div class="not-found-islamic-star"></div>
+    </div>
+
+    {/* The 404 number — large and decorative */}
+    <h1 class="text-accent text-[8rem] sm:text-[10rem] md:text-[12rem] leading-none font-display tracking-tight select-none not-found-fade-in-up">
+      404
+    </h1>
+
+    {/* Thin accent separator */}
+    <div class="mx-auto w-24 h-px bg-gradient-to-r from-transparent via-accent to-transparent my-6 not-found-fade-in-up not-found-delay-1" aria-hidden="true"></div>
+
+    {/* Message */}
+    <h2 class="font-display text-2xl sm:text-3xl text-foreground mb-4 not-found-fade-in-up not-found-delay-1">
+      {tagline}
+    </h2>
+    <p class="text-muted-foreground text-lg sm:text-xl leading-relaxed max-w-lg mx-auto mb-10 not-found-fade-in-up not-found-delay-2">
+      {lede}
+    </p>
+
+    {/* Primary CTA */}
+    <div class="mb-6 not-found-fade-in-up not-found-delay-2">
+      <Button href={homeHref} variant="primary">
+        {homeLabel}
+      </Button>
+    </div>
+
+    {/* Search prompt */}
+    <div class="mb-12 not-found-fade-in-up not-found-delay-3">
+      <a
+        href={searchHref}
+        data-search-trigger
+        class="group flex items-center gap-3 w-full max-w-sm mx-auto px-4 py-3 rounded-xl border border-foreground/20 bg-white/60 backdrop-blur-sm text-left hover:border-primary/40 hover:bg-white/80 transition-all no-underline"
+        aria-label={searchAriaLabel}
+      >
+        <Icon name="search" class="w-4 h-4 text-muted-foreground shrink-0" />
+        <span class="text-muted-foreground text-sm flex-1">{searchLabel}</span>
+        <kbd class="hidden sm:inline-flex items-center px-1.5 py-0.5 rounded text-xs font-mono border border-border text-muted-foreground/60 bg-muted/50">⌘K</kbd>
+      </a>
+    </div>
+
+    {/* Explore sections */}
+    <div class="not-found-fade-in-up not-found-delay-4">
+      <p class="text-sm uppercase tracking-widest text-muted-foreground/60 mb-5 font-medium">
+        {exploreLabel}
+      </p>
+      <nav aria-label={exploreAriaLabel} class="flex flex-wrap justify-center gap-x-6 gap-y-3">
+        {links.map((link, i) => (
+          <LinkArrow href={link.href} color={i % 2 === 0 ? 'secondary' : 'primary'} size="base">{link.label}</LinkArrow>
+        ))}
+      </nav>
+    </div>
+  </div>
+</main>

package/src/editorial/StaticProsePage.astro

@@ -0,0 +1,48 @@
+---
+/**
+ * StaticProsePage — the shell of a legal or site-information page (privacy, terms, contact, editorial standards,
+ * agents). The route keeps Layout, schema and the prose itself (default slot), so copy and links stay in site source.
+ * Not Pagefind-indexed: it carries no body marker.
+ */
+import Container from '../layout/Container.astro';
+import Button from '../primitives/Button.astro';
+
+interface CtaLink {
+  href: string;
+  label: string;
+}
+
+interface Props {
+  heading: string;
+  /** Small uppercase line above the heading ("Site policy"). */
+  eyebrow?: string;
+  /** Closing box under the prose: a short line and secondary buttons. */
+  cta?: { text: string; links: CtaLink[] };
+}
+
+const { heading, eyebrow, cta } = Astro.props;
+---
+
+<main class="py-16 lg:py-24">
+  <Container size="measure">
+    {eyebrow && <p class="text-sm font-semibold uppercase tracking-[0.18em] text-primary mb-3">{eyebrow}</p>}
+    <h1 class="text-3xl sm:text-4xl font-medium font-display mb-8">{heading}</h1>
+
+    <div class="prose prose-stone max-w-none">
+      <slot />
+    </div>
+
+    <slot name="after" />
+
+    {cta && (
+      <div class="not-prose mt-12 rounded-2xl border border-border bg-muted/40 p-6">
+        <p class="text-sm text-muted-foreground mb-4">
+          {cta.text}
+        </p>
+        <div class="flex flex-wrap gap-3">
+          {cta.links.map((link) => <Button href={link.href} variant="secondary">{link.label}</Button>)}
+        </div>
+      </div>
+    )}
+  </Container>
+</main>

package/src/editorial/index.ts

@@ -3,4 +3,8 @@ export { default as EditorialGuidePage } from './EditorialGuidePage.astro';
 export { default as EventPage } from './EventPage.astro';
 export { default as BeforeYouGo } from './BeforeYouGo.astro';
 export { default as NumberedStep } from './NumberedStep.astro';
+export { default as StaticProsePage } from './StaticProsePage.astro';
+export { default as NotFoundPage } from './NotFoundPage.astro';
+export { default as ArticlesListingPage } from './ArticlesListingPage.astro';
+export { default as ArticleFeatureCard } from './ArticleFeatureCard.astro';
 export type { EventInfoRow, EventInfoIcon } from './event';

package/src/layout/ConsentAnalytics.astro

@@ -0,0 +1,121 @@
+---
+/**
+ * Google Tag Manager behind Consent Mode v2, with the Silktide consent manager. Production only. Deferred to the first
+ * interaction, or to idle after load (8 s timeout keeps GTM outside the Lighthouse TBT window). Inline on purpose:
+ * the consent default must be pushed before the gtm.js event in one synchronous step, which a deferred module cannot
+ * guarantee. Defines `window.openCookiePreferences`, which the footer's cookie-preferences button calls.
+ * The `<noscript>` iframe goes at the start of `<body>`: render with `part="noscript"` there and `part="script"` at
+ * the end of `<body>`.
+ */
+import { GTM_ORIGIN, SILKTIDE_BASE } from './resources.ts';
+
+export interface ConsentType {
+  id: string;
+  label: string;
+  description: string;
+  required?: boolean;
+  defaultValue?: boolean;
+  /** The Consent Mode v2 storage key(s) this category grants. */
+  gtag?: string | string[];
+}
+
+interface Props {
+  gtmId: string;
+  part: 'noscript' | 'script';
+  /** The banner's prompt text. */
+  prompt?: string;
+  consentTypes?: ConsentType[];
+}
+
+const { gtmId, part, prompt = '', consentTypes = [] } = Astro.props;
+const isProd = import.meta.env.PROD;
+const gtmOrigin = GTM_ORIGIN;
+const silktideScript = `${SILKTIDE_BASE}/silktide-consent-manager.js`;
+const silktideConfig = { text: { prompt: { description: prompt } }, consentTypes };
+---
+
+{isProd && part === 'noscript' && (
+  <noscript set:html={`<iframe src="${gtmOrigin}/ns.html?id=${gtmId}" height="0" width="0" style="display:none;visibility:hidden"></iframe>`} />
+)}
+{isProd && part === 'script' && (
+  <script is:inline define:vars={{ gtmId, gtmOrigin, silktideScript, silktideConfig }}>
+    (function () {
+      let thirdPartyLoaded = false;
+
+      function loadThirdPartyScripts() {
+        if (thirdPartyLoaded) return;
+        thirdPartyLoaded = true;
+
+        window.dataLayer = window.dataLayer || [];
+
+        // GTM treats a dataLayer entry as a consent command only when it is an `arguments` object; a plain array is
+        // ignored, which leaves analytics_storage unset and blocks tags with an additional consent check.
+        function gtag() { window.dataLayer.push(arguments); }
+        gtag('consent', 'default', {
+          ad_storage: 'denied',
+          ad_user_data: 'denied',
+          ad_personalization: 'denied',
+          analytics_storage: 'granted',
+        });
+
+        window.dataLayer.push({
+          'gtm.start': new Date().getTime(),
+          event: 'gtm.js',
+        });
+
+        // On the main thread: Partytown race-dropped the initial page_view (SLA-2661).
+        var gtmScript = document.createElement('script');
+        gtmScript.async = true;
+        gtmScript.src = gtmOrigin + '/gtm.js?id=' + gtmId;
+        document.head.appendChild(gtmScript);
+
+        var consentScript = document.createElement('script');
+        consentScript.src = silktideScript;
+        consentScript.async = true;
+        consentScript.onload = function () {
+          if (!window.silktideConsentManager) return;
+          window.silktideConsentManager.init(silktideConfig);
+        };
+        document.head.appendChild(consentScript);
+      }
+
+      var evtOpts = { once: true, passive: true, capture: true };
+      ['pointerdown', 'keydown', 'touchstart', 'scroll'].forEach(function (evt) {
+        window.addEventListener(evt, loadThirdPartyScripts, evtOpts);
+      });
+
+      function scheduleThirdPartyScripts() {
+        if ('requestIdleCallback' in window) {
+          window.requestIdleCallback(loadThirdPartyScripts, { timeout: 8000 });
+        } else {
+          setTimeout(loadThirdPartyScripts, 6000);
+        }
+      }
+
+      if (document.readyState === 'complete') {
+        scheduleThirdPartyScripts();
+      } else {
+        window.addEventListener('load', scheduleThirdPartyScripts, { once: true });
+      }
+
+      // Silktide is lazy-loaded: if this click is the first interaction, load it and poll briefly (about 4 s).
+      window.openCookiePreferences = function () {
+        if (window.silktideConsentManager) {
+          window.silktideConsentManager.getInstance().toggleModal(true);
+          return;
+        }
+        loadThirdPartyScripts();
+        var attempts = 0;
+        var poll = setInterval(function () {
+          attempts++;
+          if (window.silktideConsentManager) {
+            clearInterval(poll);
+            window.silktideConsentManager.getInstance().toggleModal(true);
+          } else if (attempts > 40) {
+            clearInterval(poll);
+          }
+        }, 100);
+      };
+    })();
+  </script>
+)}

package/src/layout/DocumentShell.astro

@@ -0,0 +1,171 @@
+---
+/**
+ * The HTML document every site page renders into: head metadata (description, robots, canonical, Open Graph, article,
+ * Twitter, title), RSS and favicons, non-critical stylesheets, consent-gated analytics, the Travelpayouts Emerald
+ * loader, the skip link and the landmarks (navigation and footer wrapped out of the Pagefind index, `#main-content`).
+ * The site's thin Layout supplies identity, theme, fonts, chrome and policy; it keeps its own stylesheet import and
+ * its single `<script>` so bundle names stay the site's.
+ *
+ * Slots: `head-start` (after robots: preconnects), `fonts` (font-face block and preloads), `head` (page additions,
+ * JSON-LD), `body-start` (decorative layers), `nav`, `footer`, default (page content).
+ */
+import { normalizePagePath, normalizeSiteUrl, toAbsoluteSiteUrl } from '@sarimarcus/content-sites-core/url';
+import { OgImageMeta } from '../seo/index.ts';
+import EmeraldLoader from '../affiliate/EmeraldLoader.astro';
+import AsyncStylesheet from './AsyncStylesheet.astro';
+import ConsentAnalytics, { type ConsentType } from './ConsentAnalytics.astro';
+import { SILKTIDE_STYLESHEET } from './resources.ts';
+
+interface Props {
+  title: string;
+  description: string;
+  siteName: string;
+  /** Absolute origin, e.g. `https://www.example.com`. */
+  siteUrl: string;
+  canonicalUrl?: string;
+  ogImage?: string;
+  ogImageAlt?: string;
+  ogType?: string;
+  ogLocale?: string;
+  articleAuthor?: string;
+  /** Absolute URL of the author's profile page, resolved by the site. */
+  articleAuthorUrl?: string;
+  articlePublishedTime?: string;
+  articleModifiedTime?: string;
+  articleSection?: string;
+  noindex?: boolean;
+  preloadImage?: string;
+  twitterHandle?: string;
+  themeColor: string;
+  lang?: string;
+  rssTitle?: string;
+  /** Non-critical stylesheet URLs (`?url` imports), loaded after the title in this order. */
+  stylesheets?: string[];
+  gtmId: string;
+  consentPrompt: string;
+  consentTypes: ConsentType[];
+  /** Travelpayouts id for the Emerald loader; omit to leave it out. */
+  travelpayoutsTrs?: string;
+  skipLinkLabel: string;
+  mainClass?: string;
+  footerClass?: string;
+}
+
+const {
+  title,
+  description,
+  siteName,
+  siteUrl,
+  canonicalUrl: providedCanonicalUrl,
+  ogImage = '/og-default.jpg',
+  ogImageAlt,
+  ogType,
+  ogLocale = 'en',
+  articleAuthor,
+  articleAuthorUrl,
+  articlePublishedTime,
+  articleModifiedTime,
+  articleSection,
+  noindex = false,
+  preloadImage,
+  twitterHandle,
+  themeColor,
+  lang = 'en',
+  rssTitle = siteName,
+  stylesheets = [],
+  gtmId,
+  consentPrompt,
+  consentTypes,
+  travelpayoutsTrs,
+  skipLinkLabel,
+  mainClass,
+  footerClass,
+} = Astro.props;
+
+const baseUrl = import.meta.env.BASE_URL.replace(/\/$/, '');
+const canonicalUrl = providedCanonicalUrl
+  ? normalizeSiteUrl(providedCanonicalUrl, siteUrl, baseUrl)
+  : toAbsoluteSiteUrl(normalizePagePath(Astro.url.pathname, baseUrl), siteUrl, baseUrl);
+const imageAlt = ogImageAlt ?? `${title} - ${siteName}`;
+
+function normalizeArticleTime(dateStr: string | undefined): string | undefined {
+  if (!dateStr) return undefined;
+  if (dateStr.includes('T')) return dateStr;
+  const date = new Date(`${dateStr}T00:00:00Z`);
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+
+const publishedTime = normalizeArticleTime(articlePublishedTime);
+const modifiedTime = normalizeArticleTime(articleModifiedTime);
+const isArticleMeta = Boolean(articleAuthorUrl || publishedTime || modifiedTime || articleSection);
+---
+
+<!doctype html>
+<html lang={lang}>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content={themeColor} />
+    <meta name="description" content={description} />
+    <meta name="robots" content={noindex ? 'noindex, follow' : 'index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1'} />
+    <slot name="head-start" />
+
+    <slot name="fonts" />
+
+    <link rel="canonical" href={canonicalUrl} />
+    <link rel="alternate" type="application/rss+xml" title={rssTitle} href={`${baseUrl}/rss.xml`} />
+    <link rel="icon" type="image/svg+xml" href={`${baseUrl}/favicon.svg`} />
+    <link rel="icon" type="image/x-icon" href={`${baseUrl}/favicon.ico`} />
+
+    <AsyncStylesheet href={SILKTIDE_STYLESHEET} />
+
+    {preloadImage && <link rel="preload" as="image" href={preloadImage} fetchpriority="high" />}
+
+    <meta property="og:type" content={ogType ?? (isArticleMeta ? 'article' : 'website')} />
+    <meta property="og:url" content={canonicalUrl} />
+    <meta property="og:title" content={title} />
+    <meta property="og:description" content={description} />
+    <OgImageMeta image={ogImage} alt={imageAlt} siteUrl={siteUrl} baseUrl={baseUrl} />
+    <meta property="og:site_name" content={siteName} />
+    <meta property="og:locale" content={ogLocale} />
+    {articleAuthor && <meta name="author" content={articleAuthor} />}
+    {articleAuthorUrl && <meta property="article:author" content={articleAuthorUrl} />}
+    {publishedTime && <meta property="article:published_time" content={publishedTime} />}
+    {modifiedTime && <meta property="article:modified_time" content={modifiedTime} />}
+    {articleSection && <meta property="article:section" content={articleSection} />}
+
+    <meta name="twitter:card" content="summary_large_image" />
+    {twitterHandle && <meta name="twitter:site" content={twitterHandle} />}
+    {twitterHandle && <meta name="twitter:creator" content={twitterHandle} />}
+    <meta name="twitter:title" content={title} />
+    <meta name="twitter:description" content={description} />
+
+    <title>{title}</title>
+
+    {stylesheets.map((href) => <AsyncStylesheet href={href} />)}
+
+    {travelpayoutsTrs && <EmeraldLoader trs={travelpayoutsTrs} />}
+
+    <slot name="head" />
+  </head>
+  <body class="min-h-screen bg-background flex flex-col">
+    <ConsentAnalytics gtmId={gtmId} part="noscript" />
+    <slot name="body-start" />
+    <a
+      href="#main-content"
+      class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-[100] focus:px-4 focus:py-2 focus:bg-primary focus:text-primary-foreground focus:rounded-lg focus:outline-none focus:ring-2 focus:ring-accent"
+    >
+      {skipLinkLabel}
+    </a>
+
+    {Astro.slots.has('nav') && <div data-pagefind-ignore><slot name="nav" /></div>}
+
+    <div id="main-content" class:list={[mainClass, 'flex-1']}>
+      <slot />
+    </div>
+
+    {Astro.slots.has('footer') && <div data-pagefind-ignore class={footerClass}><slot name="footer" /></div>}
+
+    <ConsentAnalytics gtmId={gtmId} part="script" prompt={consentPrompt} consentTypes={consentTypes} />
+  </body>
+</html>

package/src/layout/ListingShell.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * ListingShell — the frame of a listing hub: breadcrumb band, hero, optional full-width bands, <main> with a
+ * Container, and trailing bands, all inside one Pagefind-ignore wrapper (listings are not indexed). The route keeps
+ * Layout and passes StructuredData to Layout directly, so its JSON-LD lands in <head>; everything else comes in by slot.
+ */
+import BreadcrumbBand from './BreadcrumbBand.astro';
+import Container from './Container.astro';
+
+interface Props {
+  mainClass?: string;
+}
+
+const { mainClass = 'py-12 lg:py-20' } = Astro.props;
+---
+
+<div data-pagefind-ignore>
+  <BreadcrumbBand ignore={false}>
+    <slot name="breadcrumb" />
+  </BreadcrumbBand>
+
+  <slot name="hero" />
+  <slot name="before-main" />
+
+  <main class={mainClass}>
+    <Container>
+      <slot />
+    </Container>
+  </main>
+
+  <slot name="after-main" />
+</div>

package/src/layout/analytics.ts

@@ -0,0 +1,151 @@
+// Pushes custom events to the GTM dataLayer.
+// GTM consent mode (Silktide analytics_storage) governs whether GA4 receives each event.
+
+declare global {
+  interface Window {
+    dataLayer: Record<string, unknown>[];
+    silktideConsentManager?: { hasConsent(id: string): boolean };
+    track?: (eventName: string, params?: Record<string, unknown>) => void;
+  }
+}
+
+function hasAnalyticsConsent(): boolean {
+  const mgr = window.silktideConsentManager;
+  if (!mgr) return true; // not yet loaded — GTM consent mode enforces at send time
+  return typeof mgr.hasConsent === 'function' ? mgr.hasConsent('analytics') : true;
+}
+
+export function track(eventName: string, params: Record<string, unknown> = {}): void {
+  if (!hasAnalyticsConsent()) return;
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({ event: eventName, page_path: window.location.pathname, ...params });
+}
+
+/**
+ * Page type: the first path segment, 'home' at the root.
+ *
+ * The single definition behind both the GA4 `page_type` param (runtime pathname, '/plan/x') and a site's GYG `cmp`
+ * segment (BUILD-time `Astro.url.pathname`, '/index.html' under build.format 'file'). The `.html`/`index`
+ * normalisation is what makes the two agree.
+ */
+export function pageTypeOf(pathname: string): string {
+  const first = pathname.split('/').filter(Boolean)[0];
+  if (!first) return 'home';
+  const bare = first.replace(/\.html$/, '');
+  return bare === 'index' || bare === '' ? 'home' : bare;
+}
+
+// Param key derived from the data-track-* attribute name where the
+// event-specific prefix (e.g. 'cta_', 'affiliate_', 'link_') has been stripped.
+const HREF_DESTINATION_KEYS: Record<string, string> = {
+  outbound_click: 'link_destination',
+  cta_click: 'cta_destination',
+  internal_link_click: 'link_destination',
+};
+
+// Reads data-track-* attributes from the clicked element and fires track().
+// Handles affiliate_click, cta_click, outbound_click, internal_link_click.
+export function setupDelegatedTracking(): void {
+  // MPA — pathname is stable for the page's lifetime; compute once.
+  const pageType = pageTypeOf(window.location.pathname);
+
+  document.addEventListener('click', (e: MouseEvent) => {
+    const target = e.target;
+    if (!(target instanceof Element)) return;
+    const el = target.closest<HTMLElement>('[data-track-event]');
+    if (!el) return;
+    const eventName = el.dataset.trackEvent;
+    if (!eventName) return;
+
+    const params: Record<string, unknown> = { page_type: pageType };
+
+    for (const key of Object.keys(el.dataset)) {
+      if (key === 'trackEvent' || !key.startsWith('track')) continue;
+      const param = key
+        .slice('track'.length)
+        .replace(/([A-Z])/g, '_$1')
+        .toLowerCase()
+        .replace(/^_/, '');
+      params[param] = el.dataset[key];
+    }
+
+    // Fall back to href for the destination param when the markup didn't set it
+    // — saves repeating the URL on every CTA/link.
+    const destKey = HREF_DESTINATION_KEYS[eventName];
+    if (destKey && !params[destKey] && el instanceof HTMLAnchorElement) {
+      params[destKey] = el.href;
+    }
+
+    track(eventName, params);
+  });
+}
+
+// Fires faq_expand on <details data-faq-track> open. Uses capture because toggle doesn't bubble.
+export function setupFaqTracking(): void {
+  document.addEventListener(
+    'toggle',
+    (e: Event) => {
+      const details = e.target as HTMLDetailsElement;
+      if (!details.hasAttribute('data-faq-track') || !details.open) return;
+      const question = details.querySelector('summary h3')?.textContent?.trim() ?? '';
+      track('faq_expand', { question });
+    },
+    true,
+  );
+}
+
+// Fires scroll_depth at 25/50/75/100% — deduped per page view, removed after 100%.
+// Reads layout-triggering geometry (scrollHeight) inside a rAF-throttled tick
+// so rapid scroll events coalesce to one measurement per frame.
+export function setupScrollDepthTracking(): void {
+  const thresholds = [25, 50, 75, 100];
+  const fired = new Set<number>();
+  let frameQueued = false;
+
+  function measure() {
+    frameQueued = false;
+    const total = document.documentElement.scrollHeight;
+    if (total <= window.innerHeight) return;
+    const pct = Math.round(((window.scrollY + window.innerHeight) / total) * 100);
+    for (const d of thresholds) {
+      if (pct >= d && !fired.has(d)) {
+        fired.add(d);
+        track('scroll_depth', { percent: d });
+      }
+    }
+    if (fired.size === thresholds.length) {
+      window.removeEventListener('scroll', onScroll);
+    }
+  }
+
+  function onScroll() {
+    if (frameQueued) return;
+    frameQueued = true;
+    requestAnimationFrame(measure);
+  }
+
+  window.addEventListener('scroll', onScroll, { passive: true });
+}
+
+export interface AnalyticsOptions {
+  /** Pages that get scroll-depth tracking, tested against `location.pathname`. Omitted or false: none; true: every page. */
+  scrollDepth?: boolean | RegExp | ((pathname: string) => boolean);
+  /** Track `<details data-faq-track>` opens. */
+  faq?: boolean;
+}
+
+let installed = false;
+
+/** Sets `window.track` and binds delegated click, FAQ and scroll-depth tracking. A second call is a no-op. */
+export function setupAnalytics(options: AnalyticsOptions = {}): void {
+  if (installed) return;
+  installed = true;
+  window.track = track;
+  setupDelegatedTracking();
+  if (options.faq) setupFaqTracking();
+  const { scrollDepth } = options;
+  const path = window.location.pathname;
+  const wantsScroll =
+    scrollDepth instanceof RegExp ? scrollDepth.test(path) : typeof scrollDepth === 'function' ? scrollDepth(path) : scrollDepth === true;
+  if (wantsScroll) setupScrollDepthTracking();
+}