@sarimarcus/content-sites-ui 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.17.0 (2026-10-01)
+
+- New `DocumentShell` (`./layout`): the whole HTML document a site page renders into: description, robots (`noindex, follow` when noindex), canonical from the page path, RSS and favicons, Open Graph / article / Twitter (handle optional), title, non-critical stylesheets, the Emerald loader, the skip link, navigation and footer wrapped out of the Pagefind index, `#main-content`, and consent-gated analytics. Slots `head-start`, `fonts`, `head`, `body-start`, `nav`, `footer`. It imports no stylesheet and emits no bundled script, so a site's thin Layout keeps its bundle names (SLA-2741).
+- New `ConsentAnalytics` (`./layout`): the inline GTM + Consent Mode v2 + Silktide bootstrap (consent default before the gtm.js event in one synchronous step; `window.openCookiePreferences`), production only, plus the `<noscript>` GTM iframe. `layout/resources.ts` declares the hosts it loads (SLA-2741).
+- New `EmeraldLoader` (`./affiliate`): the Travelpayouts Emerald script from the site's trs; `emeraldResources` declares its host (SLA-2741).
+- New entry points `./analytics` (`setupAnalytics`, `track`, `pageTypeOf`, delegated, FAQ and scroll-depth tracking) and `./travelpayouts-styler` (`setupTravelpayoutsStyler`, palette, fonts and copy as options), moved from the sites. FAQ tracking now fires: it tested `dataset.faqTrack`, which is empty on the bare `data-faq-track` attribute ui `FAQ` renders (SLA-2741).
+
 ## 0.16.0 (2026-10-01)
 
 - New `./navigation`: `SiteHeader` (fixed header, labelled main `<nav>`, logo/desktop/actions/mobile slots, mobile toggle, mobile panel after the header with `data-pagefind-ignore`, `surfaceClass`, Ctrl/Cmd+K → `searchPath?focus=1`), `NavDropdown` (click, hover with a 150 ms close delay, ArrowDown/ArrowUp/Escape, outside click, focus leaving; a click on a hover-opened dropdown keeps it open), `MobileNavSection` (single-open accordion, `aria-controls`), `NavMenuLink` / `MobileNavLink` (panel rows by `NavTone`), `SiteFooter` (sections, `<nav aria-label="Legal">`, cookie-preferences button through `data-cookie-preferences`, no inline handler), `isActivePath`, and the `SiteIdentity` / `NavLink` / `NavGroup` / `FooterSection` / `NavTone` contracts. One bundled controller, idempotent on `astro:page-load`, any number of headers per page; the toggle and chevron icons now switch state (SLA-2735).

package/README.md

@@ -1,7 +1,8 @@
 # @sarimarcus/content-sites-ui
 
 Universal Astro UI shared by every content site. Named entry points, one per folder: `primitives`,
-`composed`, `editorial`, `affiliate`, `seo`, `layout`, `navigation`, `search` and `types`. For example,
+`composed`, `editorial`, `affiliate`, `seo`, `layout`, `navigation`, `search` and `types`, plus the script
+entry points `analytics` and `travelpayouts-styler`. For example,
 `import { Container } from '@sarimarcus/content-sites-ui/layout'`. `src/internal` is never exported,
 and `src/styles` holds the Tailwind entry.
 
@@ -75,6 +76,34 @@ state and one bundled controller (idempotent on `astro:page-load`, any number of
 - `appendResults` renders Pagefind result cards from the site's type taxonomy; `SearchSuggestions` renders the
   empty-state chips. The search page, its copy and its index stay in the site.
 
+## Document shell
+
+```astro
+---
+import { DocumentShell } from '@sarimarcus/content-sites-ui/layout';
+---
+<DocumentShell title={title} description={description} siteName={site.siteName} siteUrl={site.url} themeColor="#FAFAF8"
+  gtmId={site.analytics.gtmId} consentPrompt="…" consentTypes={consentTypes} skipLinkLabel="Skip to main content">
+  <Fragment slot="fonts">…</Fragment>
+  <Navigation slot="nav" />
+  <slot />
+  <Footer slot="footer" />
+</DocumentShell>
+```
+
+`DocumentShell` renders the whole document: description, robots (`noindex, follow` when `noindex`), canonical (from
+the page path unless `canonicalUrl`), RSS and favicons, Open Graph / article / Twitter (`twitterHandle` optional),
+title, non-critical `stylesheets`, the Emerald loader (`travelpayoutsTrs`), the skip link, the navigation and footer
+wrapped in `data-pagefind-ignore`, `#main-content` and `ConsentAnalytics`. Slots: `head-start`, `fonts`, `head`,
+`body-start`, `nav`, `footer`, default. It imports no stylesheet and emits no bundled script, so the site's thin
+Layout keeps both (and with them its bundle names).
+
+`ConsentAnalytics` is inline on purpose: the Consent Mode default must reach the dataLayer before the `gtm.js` event
+in one synchronous step. It defines `window.openCookiePreferences` for the footer button. `./analytics`
+(`setupAnalytics`, `track`, `pageTypeOf`) and `./travelpayouts-styler` (`setupTravelpayoutsStyler`) are their own
+entry points so a client `<script>` imports no Astro component. The hosts the shell loads are declared in
+`layout/resources.ts`; `scripts/validate-csp-coverage.mjs` checks every site's CSP against them.
+
 ## Search and consent styles
 
 `@sarimarcus/content-sites-ui/search.css` styles the search page markup (`appendResults`, `SearchSuggestions` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Universal Astro UI components, layout shell and design tokens shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -30,8 +30,10 @@
     "./composed": "./src/composed/index.ts",
     "./editorial": "./src/editorial/index.ts",
     "./affiliate": "./src/affiliate/index.ts",
+    "./travelpayouts-styler": "./src/affiliate/travelpayoutsStyler.ts",
     "./seo": "./src/seo/index.ts",
     "./layout": "./src/layout/index.ts",
+    "./analytics": "./src/layout/analytics.ts",
     "./navigation": "./src/navigation/index.ts",
     "./search": "./src/search/index.ts",
     "./types": "./src/types/index.ts",
@@ -45,6 +47,6 @@
     "@lucide/astro": "^1.23.0",
     "astro": "^7.0.6",
     "tailwindcss": "^4.1.18",
-    "@sarimarcus/content-sites-core": "0.16.0"
+    "@sarimarcus/content-sites-core": "0.17.0"
   }
 }

package/src/affiliate/EmeraldLoader.astro

@@ -0,0 +1,40 @@
+---
+/**
+ * The Travelpayouts Emerald script that turns the site's affiliate links into tracked ones. Deferred off the critical
+ * path: it loads on the first interaction, or once the page is idle after load. `trs` is the site's Travelpayouts id.
+ */
+import { EMERALD_ORIGIN } from './resources.ts';
+
+interface Props {
+  trs: string;
+}
+
+const { trs } = Astro.props;
+const emeraldOrigin = EMERALD_ORIGIN;
+---
+
+<script is:inline define:vars={{ trs, emeraldOrigin }}>
+  (function () {
+    if (!/^\d+$/.test(trs)) return;
+    var loaded = false;
+    function loadAffiliate() {
+      if (loaded) return;
+      loaded = true;
+      var script = document.createElement('script');
+      script.async = 1;
+      script.src = emeraldOrigin + '/' + btoa(trs) + '.js?t=' + trs;
+      document.head.appendChild(script);
+    }
+    var opts = { once: true, passive: true, capture: true };
+    ['pointerdown', 'keydown', 'touchstart', 'scroll'].forEach(function (evt) {
+      window.addEventListener(evt, loadAffiliate, opts);
+    });
+    window.addEventListener('load', function () {
+      if ('requestIdleCallback' in window) {
+        requestIdleCallback(loadAffiliate, { timeout: 5000 });
+      } else {
+        setTimeout(loadAffiliate, 4000);
+      }
+    });
+  })();
+</script>

package/src/affiliate/index.ts

@@ -11,7 +11,10 @@ export { default as AffiliateCardSection } from './AffiliateCardSection.astro';
 export { default as AffiliateCarousel } from './AffiliateCarousel.astro';
 export { default as AffiliateComparisonTable } from './AffiliateComparisonTable.astro';
 export { default as HotelAffiliateCTA } from './HotelAffiliateCTA.astro';
-export { externalResources } from './resources';
+export { externalResources, emeraldResources, EMERALD_ORIGIN } from './resources';
 export type { WidgetKind, CspDirective, WidgetResources } from './resources';
 export type { AffiliateCardLabels, AffiliateCardItem, HotelCtaLabels, ComparisonRow, ComparisonTableLabels } from './types';
 export { selectActivities, type SelectableActivity, type SelectOptions } from './select';
+export { default as EmeraldLoader } from './EmeraldLoader.astro';
+export { setupTravelpayoutsStyler } from './travelpayoutsStyler.ts';
+export type { TravelpayoutsStylerOptions, TravelpayoutsStylerColors } from './travelpayoutsStyler.ts';

package/src/affiliate/resources.ts

@@ -28,3 +28,10 @@ export const externalResources: Record<WidgetKind, WidgetResources> = {
   },
 };
 
+
+/** The Travelpayouts Emerald loader every page carries (EmeraldLoader): https://emrldtp.com/<base64 trs>.js?t=<trs>. */
+export const EMERALD_ORIGIN = 'https://emrldtp.com';
+
+export const emeraldResources: Partial<Record<CspDirective, readonly string[]>> = {
+  'script-src': [EMERALD_ORIGIN],
+};

package/src/affiliate/travelpayoutsStyler.ts

@@ -0,0 +1,557 @@
+// TravelPayouts / Emerald contextual widgets render inside shadow DOM, so
+// external CSS cannot reach them. This module injects the site's tokens
+// directly into every .emerald-block shadow root, rewrites titles that read
+// as ad copy, strips characters whose glyph isn't in the site fonts, and
+// hides redundant CTAs per widget variant.
+//
+// Variants discovered in production (2026-05):
+//   - emerald-block__hotels         (top hotels list)
+//   - emerald-block__recommendation (3-card Booking/Viator/Discover Cars block)
+//   - emerald-block__highlights     (last-minute tours/experiences list)
+
+/** CSS colour values, by role. Any CSS colour syntax; the site owns the palette. */
+export interface TravelpayoutsStylerColors {
+  /** Links, button background, focus ring. */
+  accent: string;
+  /** Link and button hover/focus. */
+  accentHover: string;
+  /** Text on a button filled with the accent colour. */
+  onAccent: string;
+  /** Headings, card titles, disclosure text. */
+  foreground: string;
+  /** Descriptors, card body, metric labels. */
+  mutedForeground: string;
+  /** Card, info-box and disclosure background. */
+  surface: string;
+  /** Dividers and card/container borders. */
+  border: string;
+  /** Recommendation-card border on hover. */
+  borderHover: string;
+  /** Score/rating text and hotel rating labels. */
+  rating: string;
+  /** Affiliate-disclosure border. */
+  disclosureBorder: string;
+}
+
+export interface TravelpayoutsStylerOptions {
+  colors: TravelpayoutsStylerColors;
+  /** CSS font-family stacks. */
+  fonts: { body: string; heading: string };
+  /** Weight of widget section titles and generic headings. */
+  headingWeight: number;
+  /** Weight of recommendation-card titles. */
+  cardTitleWeight: number;
+  /** Border radii: `control` for buttons and the disclosure, `card` for cards and the hotels container. */
+  radius: { control: string; card: string };
+  /** Editorial replacements for the widget's ad-copy titles. */
+  titles: {
+    /** Replaces a highlights title mentioning "last minute". */
+    highlights: string;
+    /** Replaces a recommendation title carrying both "?" and "!". */
+    recommendation: string;
+  };
+}
+
+interface VariantConfig {
+  /** Replace the widget's H1–H4 title text. Receives the cleaned text, returns the new text. */
+  rewriteTitle?: (text: string) => string;
+  /** Selectors (run inside the shadow root) to hide via display:none. */
+  hide?: string[];
+}
+
+type Variants = Record<string, VariantConfig>;
+
+// Web fonts rarely ship emoji or geometric-shape glyphs, so anything
+// outside the BMP letterforms renders as a tofu rectangle. Strip:
+//   - all Extended_Pictographic (emoji)
+//   - misc symbols U+2600–26FF (★ ☆ ⛅ etc.)
+//   - geometric shapes U+25A0–25FF (■ □ ▲ etc.)
+//   - misc symbols & arrows U+2B00–2BFF (⬜ ⬛ ⭐ etc.)
+//   - variation selectors U+FE00–FE0F that follow them
+const TOFU_RE = /[\p{Extended_Pictographic}☀-⛿■-◿⬀-⯿]️?/gu;
+
+export function buildCss(o: TravelpayoutsStylerOptions): string {
+  const c = o.colors;
+  return [
+    // Host stays block-level and contained — NO !important on max-width so the
+    // site's light-DOM .emerald-block rule can size the host to the article column.
+    ":host { display: block; max-width: 100%; overflow: hidden; box-sizing: border-box; background: transparent; }",
+    ".wrapper,.hotels,.container { max-width: 100% !important; box-sizing: border-box !important; }",
+    `* { font-family: ${o.fonts.body}; }`,
+    "h1,h2,h3,h4,.title,[class*='heading'],[class*='title'] {",
+    `  font-family: ${o.fonts.heading};`,
+    `  font-weight: ${o.headingWeight};`,
+    "  letter-spacing: -0.01em;",
+    "}",
+    // Link color — exclude buttons so the .button color rule below wins on <a class='button'>.
+    // Without :not(), `a:link` (specificity 0,0,1,1) would override `.button` (0,0,1,0).
+    `a:not(.button):not([class*='button']),a:not(.button):not([class*='button']):link,a:not(.button):not([class*='button']):visited { color: ${c.accent} !important; text-decoration: none; }`,
+    `a:not(.button):not([class*='button']):hover,a:not(.button):not([class*='button']):focus { color: ${c.accentHover} !important; text-decoration: underline; }`,
+    ".button,[class*='button'],button {",
+    `  background-color: ${c.accent} !important;`,
+    `  color: ${c.onAccent} !important;`,
+    "  border: none !important;",
+    `  border-radius: ${o.radius.control} !important;`,
+    `  font-family: ${o.fonts.body} !important;`,
+    "  font-weight: 500 !important;",
+    "  font-size: 0.875rem !important;",
+    "  line-height: 1.5 !important;",
+    "  cursor: pointer;",
+    "  transition: background-color 0.15s ease;",
+    "  display: inline-flex !important;",
+    "  align-items: center !important;",
+    "  gap: 0.5rem !important;",
+    "  padding: 0.5rem 1rem !important;",
+    "  text-indent: 0 !important;",
+    "  text-decoration: none !important;",
+    "  visibility: visible !important;",
+    "  opacity: 1 !important;",
+    "}",
+    `.button { color: ${c.onAccent} !important; }`,
+    `.button *,[class*='button'] * { color: ${c.onAccent} !important; visibility: visible !important; opacity: 1 !important; }`,
+    `.button span,.button a,.button p,[class*='button'] span,[class*='button'] a,[class*='button'] p,button span,button a,button p { color: ${c.onAccent} !important; }`,
+    `button { color: ${c.onAccent} !important; }`,
+    ".button:hover,.button:focus,[class*='button']:hover,[class*='button']:focus,button:hover,button:focus {",
+    `  background-color: ${c.accentHover} !important;`,
+    "}",
+    // Keyboard focus ring in the accent colour.
+    ".button:focus-visible,[class*='button']:focus-visible,button:focus-visible {",
+    `  outline: 2px solid ${c.accent} !important;`,
+    "  outline-offset: 2px !important;",
+    "}",
+    "[class*='score'],[class*='rating'],[class*='grade'],[class*='stars'] {",
+    `  color: ${c.rating};`,
+    "  font-weight: 600;",
+    "}",
+    // Highlights variant: editorial list style — dividers, no cards.
+    ".highlights { background-color: transparent !important; }",
+    ".highlight {",
+    "  background-color: transparent !important;",
+    "  border: none !important;",
+    `  border-bottom: 1px solid ${c.border} !important;`,
+    "  padding: 0.875rem 0 !important;",
+    "  margin: 0 !important;",
+    "}",
+    ".highlight:last-child { border-bottom: none !important; }",
+    // Descriptor on its own line, link on next line as the focal point.
+    ".highlight__title {",
+    "  display: block !important;",
+    "  font-size: 0.95rem !important;",
+    "  line-height: 1.55 !important;",
+    `  color: ${c.mutedForeground} !important;`,
+    "}",
+    ".highlight__title > a {",
+    "  display: inline-block !important;",
+    "  margin-top: 0.25rem !important;",
+    "  font-weight: 500 !important;",
+    "  font-size: 1rem !important;",
+    "}",
+    // Hide broken-glyph emoji icons the widget injects — fonts don't include them.
+    ".highlight__icon { display: none !important; }",
+    // Widget section title: matches the H2-in-prose convention (clamp 1.5→1.875rem).
+    // .wrapper prefix for specificity
+    // (0,1,1,1) to beat widget's own h3.title rules (0,0,1,1) injected after our style.
+    ".wrapper h1.title, .wrapper h2.title, .wrapper h3.title, .wrapper h4.title {",
+    "  background-color: transparent !important;",
+    "  background: none !important;",
+    "  border: none !important;",
+    "  border-bottom: none !important;",
+    "  padding: 0 0 0.5rem !important;",
+    "  margin-bottom: 0.75rem !important;",
+    "  font-size: clamp(1.5rem, 2.5vw + 0.5rem, 1.875rem) !important;",
+    `  font-weight: ${o.headingWeight} !important;`,
+    "  line-height: 1.3 !important;",
+    `  color: ${c.foreground} !important;`,
+    `  font-family: ${o.fonts.heading} !important;`,
+    "  text-align: left !important;",
+    "}",
+    // Metric/quality badge — "Good", "Excellent" etc. — styled for non-highlights variants.
+    "[class*='metric'] {",
+    "  display: block !important;",
+    "  font-size: 0.6875rem !important;",
+    `  color: ${c.mutedForeground} !important;`,
+    "  font-weight: 500 !important;",
+    "  text-transform: uppercase !important;",
+    "  letter-spacing: 0.06em !important;",
+    `  font-family: ${o.fonts.body} !important;`,
+    "  margin-top: 0.125rem !important;",
+    "}",
+    // Highlights metric "Good"/"Excellent" adds no signal without numeric context — hide.
+    // Must come AFTER [class*='metric'] { display: block } above: same specificity + !important
+    // means later declaration wins, so the hide rule must be last.
+    ".highlight__metric, .highlight__metrics { display: none !important; }",
+    // Wrapper + hotels: transparent — no blue containers.
+    ".wrapper, .hotels { background-color: transparent !important; }",
+    // Override blue backgrounds in widget info boxes (div only, not headings).
+    "div.title,.container,[class*='info'],[class*='fact'],[class*='note'],[class*='tip'],[class*='callout'],.bg-blue-50,[style*='blue'],[style*='rgb(219, 234, 254)'] {",
+    `  background-color: ${c.surface} !important;`,
+    `  border-color: ${c.border} !important;`,
+    "}",
+    // Buttons inside div.title already get the on-accent colour from the base rule above — no override needed.
+    // Affiliate disclosure styling — disclosure border, surface background, foreground text.
+    "[class*='affiliate'],[class*='disclosure'],[class*='commission'],[class*='disclaimer'] {",
+    `  border: 1px solid ${c.disclosureBorder} !important;`,
+    "  border-opacity: 0.4 !important;",
+    `  background-color: ${c.surface} !important;`,
+    "  padding: 0.5rem 0.75rem !important;",
+    `  border-radius: ${o.radius.control} !important;`,
+    `  color: ${c.foreground} !important;`,
+    "}",
+
+    // ── Recommendation widget (3-card affiliate block) ──
+    // Cards: surface background, tinted border, generous padding, full-bleed buttons.
+    // Subtle border-color shift on hover signals interactivity without faking
+    // whole-card clickability (only the button is the action).
+    ".item, .item_large {",
+    `  background-color: ${c.surface} !important;`,
+    `  border: 1px solid ${c.border} !important;`,
+    `  border-radius: ${o.radius.card} !important;`,
+    "  padding: 1.25rem !important;",
+    "  box-sizing: border-box !important;",
+    "  display: flex !important;",
+    "  flex-direction: column !important;",
+    "  gap: 0.625rem !important;",
+    "  transition: border-color 0.15s ease !important;",
+    "}",
+    ".item:hover, .item_large:hover {",
+    `  border-color: ${c.borderHover} !important;`,
+    "}",
+    // Card title: text-lg. white-space: normal
+    // overrides widget's nowrap which otherwise forces column min-widths to text width,
+    // breaking the 3-equal-column grid.
+    ".item_title {",
+    `  font-family: ${o.fonts.heading} !important;`,
+    "  font-size: 1.125rem !important;",
+    `  font-weight: ${o.cardTitleWeight} !important;`,
+    "  line-height: 1.3 !important;",
+    "  letter-spacing: -0.01em !important;",
+    `  color: ${c.foreground} !important;`,
+    "  margin: 0 !important;",
+    "  white-space: normal !important;",
+    "  overflow: visible !important;",
+    "  text-overflow: clip !important;",
+    "}",
+    // Card body: body font, comfortable reading height, muted foreground.
+    ".item_content {",
+    `  font-family: ${o.fonts.body} !important;`,
+    "  font-size: 0.875rem !important;",
+    "  line-height: 1.55 !important;",
+    `  color: ${c.mutedForeground} !important;`,
+    "  margin: 0 !important;",
+    "  flex: 1 !important;",
+    "}",
+    // Card CTA: full-width, pushed to card bottom via auto-margin.
+    // align-self: stretch overrides widget's align-self: end on .item_large_button,
+    // which otherwise shrinks the button to its text width and right-aligns it.
+    // display: flex overrides base inline-flex so width: 100% fills the full card width.
+    ".item_button, .item_large_button {",
+    "  display: flex !important;",
+    "  align-self: stretch !important;",
+    "  box-sizing: border-box !important;",
+    "  width: 100% !important;",
+    "  justify-content: center !important;",
+    "  margin-top: auto !important;",
+    "  padding: 0.625rem 1rem !important;",
+    "  white-space: normal !important;",
+    "}",
+    // Recommendation grid: widget fixes grid-template-columns to a single pixel
+    // value that never expands to 3 columns within our max-w-measure container.
+    // Override to a responsive 3-up grid above 600px viewport width.
+    "@media (min-width: 600px) {",
+    "  .recommendation {",
+    "    grid-template-columns: repeat(3, 1fr) !important;",
+    "    gap: 1rem !important;",
+    "    align-items: stretch !important;",
+    "  }",
+    "}",
+
+    // ── Hotels widget (top-3 list) ──
+    // Widget structure: div.hotels > div.title + div.container > ul > li > a + span(stars) + span(rating)
+    // Title row: heading + inline "Explore all" CTA side-by-side.
+    // div.title (not h3) is the actual element — target .hotels .title.
+    ".hotels .title {",
+    "  display: flex !important;",
+    "  align-items: baseline !important;",
+    "  justify-content: space-between !important;",
+    "  gap: 1rem !important;",
+    "  flex-wrap: wrap !important;",
+    `  font-family: ${o.fonts.heading} !important;`,
+    "  font-size: clamp(1.5rem, 2.5vw + 0.5rem, 1.875rem) !important;",
+    `  font-weight: ${o.headingWeight} !important;`,
+    "  line-height: 1.3 !important;",
+    "  letter-spacing: -0.01em !important;",
+    `  color: ${c.foreground} !important;`,
+    "  background-color: transparent !important;",
+    "  background: none !important;",
+    "  border: none !important;",
+    "  padding: 0 0 0.5rem !important;",
+    "  margin-bottom: 0.75rem !important;",
+    "}",
+    // Title-row CTA: compact secondary button, not full primary size.
+    // Desktop rule — mobile override at max-width:639.98px below.
+    ".hotels a.button.title-button {",
+    "  font-size: 0.8125rem !important;",
+    "  padding: 0.375rem 0.875rem !important;",
+    "  align-self: center !important;",
+    "}",
+    // Hide the redundant full-width bottom CTA via CSS (more reliable than JS
+    // inline style, which can be overridden by widget's own stylesheet cascade).
+    ".hotels a.button.content-button { display: none !important; }",
+    // Hotels container: cards-style padding inside the surface.
+    ".hotels .container {",
+    "  padding: 0.5rem 1rem !important;",
+    `  border-radius: ${o.radius.card} !important;`,
+    `  border: 1px solid ${c.border} !important;`,
+    "}",
+    // Reset default ul/li list styling inside the container.
+    // gap: 0 overrides widget's gap:16px which otherwise puts dead space after each border-bottom divider.
+    ".hotels .container ul { list-style: none !important; margin: 0 !important; padding: 0 !important; gap: 0 !important; }",
+    // Divider lives on li (not on the link) so it closes the full row: name + rating together.
+    // padding-bottom creates breathing room between the rating label and the rule.
+    `.hotels .container li { margin: 0 !important; padding: 0 0 0.5rem 0 !important; border-bottom: 1px solid ${c.border} !important; }`,
+    ".hotels .container li:last-child { border-bottom: none !important; padding-bottom: 0 !important; }",
+    // Each hotel link: block, comfortable reading size. No border here — divider is on li.
+    // Actual DOM: ul > li > a (not direct children of .container).
+    ".hotels .container li a:not(.button) {",
+    "  display: block !important;",
+    "  padding: 0.75rem 0 0 !important;",
+    `  font-family: ${o.fonts.body} !important;`,
+    "  font-size: 0.9375rem !important;",
+    "  line-height: 1.45 !important;",
+    "}",
+    // Star-glyph spans: TOFU_RE strips ★ glyphs, leaving an empty span — hide it.
+    // Rating-text spans: "Rating 9" etc. have no class so [class*='rating'] misses them.
+    // Style as a small label in the rating colour.
+    ".hotels .container li > span:empty { display: none !important; }",
+    ".hotels .container li > span:not(:empty) {",
+    "  display: block !important;",
+    "  font-size: 0.625rem !important;",
+    "  font-weight: 600 !important;",
+    `  color: ${c.rating} !important;`,
+    "  text-transform: uppercase !important;",
+    "  letter-spacing: 0.06em !important;",
+    `  font-family: ${o.fonts.body} !important;`,
+    "  margin-top: 0.125rem !important;",
+    "}",
+
+    // Respect users who opt out of motion.
+    "@media (prefers-reduced-motion: reduce) {",
+    "  .button, [class*='button'], button, .item, .item_large {",
+    "    transition: none !important;",
+    "  }",
+    "}",
+
+    // ── Narrow viewports (<640px) ──
+    // Cards: tighter padding + smaller body text so 3-up grid doesn't suffocate
+    // when it collapses to a stacked single column.
+    // Hotels list: tighter row padding, slightly smaller link text.
+    // Title row: stack heading above CTA (still flex-wrap'd but with extra gap).
+    "@media (max-width: 639.98px) {",
+    "  .item, .item_large {",
+    "    padding: 1rem !important;",
+    "    gap: 0.5rem !important;",
+    "  }",
+    "  .item_title { font-size: 1rem !important; }",
+    "  .item_content { font-size: 0.8125rem !important; }",
+    "  .hotels .container { padding: 0.25rem 0.875rem !important; }",
+    "  .hotels .container li a:not(.button) {",
+    "    padding: 0.625rem 0 0 !important;",
+    "    font-size: 0.875rem !important;",
+    "  }",
+    // On narrow viewports, stack the title text above the CTA instead of
+    // side-by-side (which causes the 3-line title to collide with the button).
+    // font-size intentionally omitted — clamp(1.5rem,…,1.875rem) resolves to
+    // its 1.5rem minimum at narrow viewports, which is already mobile-appropriate.
+    "  .hotels .title {",
+    "    flex-direction: column !important;",
+    "    align-items: flex-start !important;",
+    "    gap: 0.375rem !important;",
+    "  }",
+    "  .hotels a.button.title-button {",
+    "    font-size: 0.8125rem !important;",
+    "    padding: 0.375rem 0.75rem !important;",
+    "  }",
+    "}",
+  ].join("\n");
+}
+
+function buildVariants(titles: TravelpayoutsStylerOptions["titles"]): Variants {
+  return {
+    highlights: {
+      rewriteTitle: (text) =>
+        /last\s*minute/i.test(text) ? titles.highlights : text,
+    },
+    recommendation: {
+      // Widget rotates ad copy ("Ready for <place>? These sites…!", "<place> in
+      // your plans? Your adventure…!"). Any title carrying both ? and ! is the
+      // tell — replace with editorial copy.
+      rewriteTitle: (text) =>
+        /\?/.test(text) && /!/.test(text) ? titles.recommendation : text,
+    },
+    hotels: {},
+  };
+}
+
+function getVariant(host: HTMLElement): string | null {
+  const cls = Array.from(host.classList).find((c) => c.startsWith("emerald-block__"));
+  return cls ? cls.replace("emerald-block__", "") : null;
+}
+
+function injectStyle(root: ShadowRoot, css: string): void {
+  if (root.querySelector("[data-ec]")) return;
+  const style = document.createElement("style");
+  style.setAttribute("data-ec", "1");
+  style.textContent = css;
+  root.prepend(style);
+}
+
+function rewriteTitles(root: ShadowRoot, variant: string | null, variants: Variants): void {
+  const config = variant ? variants[variant] : null;
+  root.querySelectorAll("h1.title, h2.title, h3.title, h4.title").forEach((h) => {
+    const original = h.textContent ?? "";
+    let cleaned = original.replace(TOFU_RE, "").replace(/\s+/g, " ").trim();
+    if (config?.rewriteTitle) cleaned = config.rewriteTitle(cleaned);
+    if (cleaned !== original) h.textContent = cleaned;
+  });
+}
+
+// Strip tofu chars from every text node. Hotel name links and rating labels
+// embed star emoji that the site fonts can't render, leaving ⬜ rectangles
+// — kill them at the level of each text node.
+function stripTofuFromTextNodes(root: ShadowRoot): void {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  const updates: Array<[Text, string]> = [];
+  let node: Node | null;
+  while ((node = walker.nextNode())) {
+    const text = node as Text;
+    const original = text.nodeValue ?? "";
+    if (!TOFU_RE.test(original)) continue;
+    // Reset lastIndex — TOFU_RE has /g flag so it's stateful across .test() calls.
+    TOFU_RE.lastIndex = 0;
+    const cleaned = original.replace(TOFU_RE, "").replace(/[ \t]+/g, " ");
+    if (cleaned !== original) updates.push([text, cleaned]);
+  }
+  for (const [text, cleaned] of updates) text.nodeValue = cleaned;
+}
+
+function hideElements(root: ShadowRoot, variant: string | null, variants: Variants): void {
+  const config = variant ? variants[variant] : null;
+  if (!config?.hide) return;
+  for (const selector of config.hide) {
+    root.querySelectorAll<HTMLElement>(selector).forEach((el) => {
+      // The injected CSS sets `.button { display: inline-flex !important }`, so plain
+      // inline `display: none` loses. Mark our hide as !important too.
+      el.style.setProperty("display", "none", "important");
+    });
+  }
+}
+
+// After this many ms, give up waiting for shadow content and release the
+// CLS reservation slot so a blocked/failing widget doesn't leave a permanent
+// reserved void. Late-arriving content (>10s) will still be styled when it
+// appears — only the visual reservation is dropped.
+const FAILURE_TIMEOUT_MS = 10_000;
+
+// Tracks hosts with a pending failure timeout so we don't schedule duplicates.
+const watchedHosts = new WeakSet<HTMLElement>();
+
+// True iff the shadow root has any element children other than the <style>
+// we injected ourselves. The widget script populates the root with the
+// `.wrapper` element (and descendants) once data arrives — until then, the
+// only child is our [data-ec] style tag.
+function hasRealContent(root: ShadowRoot): boolean {
+  for (const child of Array.from(root.children)) {
+    const isOurStyle =
+      child.tagName === "STYLE" &&
+      (child as HTMLElement).dataset.ec === "1";
+    if (!isOurStyle) return true;
+  }
+  return false;
+}
+
+function applyContentTransforms(root: ShadowRoot, variant: string | null, variants: Variants): void {
+  rewriteTitles(root, variant, variants);
+  stripTofuFromTextNodes(root);
+  hideElements(root, variant, variants);
+}
+
+// Release the site's CLS reservation on the host (keyed on data-loaded). Done either when the
+// widget has real content (normal path) or when the failure timeout fires.
+function markLoaded(host: HTMLElement): void {
+  (host as HTMLElement).dataset.loaded = "true";
+}
+
+function processHost(host: HTMLElement, css: string, variants: Variants): void {
+  const root = host.shadowRoot;
+  if (!root) return;
+  const variant = getVariant(host);
+  injectStyle(root, css);
+
+  if (hasRealContent(root)) {
+    applyContentTransforms(root, variant, variants);
+    markLoaded(host);
+    return;
+  }
+
+  // Shadow root exists but the widget hasn't injected its content yet.
+  // Two race conditions to handle:
+  //   1. Content arrives inside shadow DOM later. The light-DOM
+  //      MutationObserver in setupTravelpayoutsStyler() can't see this
+  //      (shadow boundaries hide it), so attach a dedicated observer to
+  //      THIS shadow root that fires when the widget populates.
+  //   2. Content never arrives (script blocked, adblock, error). After
+  //      FAILURE_TIMEOUT_MS, release the CLS slot anyway so users don't
+  //      stare at a permanent reserved void blocking the page below.
+  if (watchedHosts.has(host)) return;
+  watchedHosts.add(host);
+
+  const shadowObserver = new MutationObserver(() => {
+    if (host.dataset.loaded === "true") return;
+    if (!hasRealContent(root)) return;
+    applyContentTransforms(root, getVariant(host), variants);
+    markLoaded(host);
+    shadowObserver.disconnect();
+  });
+  shadowObserver.observe(root, { childList: true, subtree: true });
+
+  window.setTimeout(() => {
+    if (host.dataset.loaded === "true") return;
+    if (hasRealContent(root)) applyContentTransforms(root, getVariant(host), variants);
+    markLoaded(host);
+    shadowObserver.disconnect();
+  }, FAILURE_TIMEOUT_MS);
+}
+
+let installed = false;
+
+export function setupTravelpayoutsStyler(options: TravelpayoutsStylerOptions): void {
+  if (installed) return;
+  installed = true;
+  const css = buildCss(options);
+  const variants = buildVariants(options.titles);
+  const process = (host: HTMLElement) => processHost(host, css, variants);
+  const scanAll = () => document.querySelectorAll<HTMLElement>(".emerald-block").forEach(process);
+
+  // The TravelPayouts script mounts widgets asynchronously and re-renders
+  // their internals on data fetch. We watch the document tree for new hosts
+  // AND poll for the first 5 seconds to catch hosts whose shadow root mounts
+  // after the host element itself was added.
+  scanAll();
+
+  let ticks = 0;
+  const interval = window.setInterval(() => {
+    scanAll();
+    if (++ticks >= 20) window.clearInterval(interval);
+  }, 250);
+
+  new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      mutation.addedNodes.forEach((node) => {
+        if (node.nodeType !== 1) return;
+        const el = node as HTMLElement;
+        if (el.classList?.contains("emerald-block")) process(el);
+        el.querySelectorAll?.<HTMLElement>(".emerald-block").forEach(process);
+      });
+    }
+  }).observe(document.documentElement, { childList: true, subtree: true });
+}

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/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();
+}

package/src/layout/index.ts

@@ -2,3 +2,9 @@
 export { default as Container } from './Container.astro';
 export { default as BreadcrumbBand } from './BreadcrumbBand.astro';
 export { default as AsyncStylesheet } from './AsyncStylesheet.astro';
+export { default as DocumentShell } from './DocumentShell.astro';
+export { default as ConsentAnalytics } from './ConsentAnalytics.astro';
+export type { ConsentType } from './ConsentAnalytics.astro';
+export { shellResources, GTM_ORIGIN, SILKTIDE_BASE, SILKTIDE_STYLESHEET } from './resources.ts';
+export { track, pageTypeOf, setupDelegatedTracking, setupFaqTracking, setupScrollDepthTracking, setupAnalytics } from './analytics.ts';
+export type { AnalyticsOptions } from './analytics.ts';

package/src/layout/resources.ts

@@ -0,0 +1,19 @@
+// The third-party hosts the document shell loads, per CSP directive. Every site renders the shell, so every site's
+// Content-Security-Policy must allow these (scripts/validate-csp-coverage.mjs checks each site's _headers against this
+// list). Plain data and erasable types only: the gate imports this file under Node.
+
+import type { CspDirective } from '../affiliate/resources.ts';
+
+/** Google Tag Manager: gtm.js and, for visitors without JavaScript, the ns.html iframe. */
+export const GTM_ORIGIN = 'https://www.googletagmanager.com';
+/** Silktide Consent Manager, pinned. */
+export const SILKTIDE_BASE = 'https://cdn.jsdelivr.net/gh/silktide/consent-manager@v2.0.0';
+/** The consent manager's stylesheet; the CSP gate recognises a shell page by it. */
+export const SILKTIDE_STYLESHEET = `${SILKTIDE_BASE}/silktide-consent-manager.css`;
+const SILKTIDE_ORIGIN = new URL(SILKTIDE_BASE).origin;
+
+export const shellResources: Partial<Record<CspDirective, readonly string[]>> = {
+  'script-src': [GTM_ORIGIN, SILKTIDE_ORIGIN],
+  'style-src': [SILKTIDE_ORIGIN],
+  'frame-src': [GTM_ORIGIN],
+};