@sarimarcus/content-sites-ui 0.16.0 → 0.18.0

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/composed/ArrowLinkGrid.astro

@@ -0,0 +1,36 @@
+---
+import Icon from '../primitives/Icon.astro';
+
+/** ArrowLinkGrid — a grid of bordered link tiles (title, short subtitle, trailing arrow) tinted on hover. */
+interface Item {
+  href: string;
+  title: string;
+  subtitle: string;
+}
+
+interface Props {
+  items: Item[];
+  tone?: 'primary' | 'secondary';
+  columns?: 3 | 4;
+}
+
+const { items, tone = 'primary', columns = 4 } = Astro.props;
+const TONES = {
+  primary: { border: 'hover:border-primary/50', text: 'group-hover:text-primary' },
+  secondary: { border: 'hover:border-secondary/50', text: 'group-hover:text-secondary' },
+} as const;
+const GRID = { 3: 'grid sm:grid-cols-2 lg:grid-cols-3 gap-3', 4: 'grid sm:grid-cols-2 lg:grid-cols-4 gap-3' } as const;
+const t = TONES[tone];
+---
+
+<div class={GRID[columns]}>
+  {items.map((item) => (
+    <a href={item.href} class={`group flex items-center justify-between gap-3 px-4 py-3 rounded-lg border border-border ${t.border} bg-card transition-all`}>
+      <div>
+        <p class={`text-sm font-medium text-foreground ${t.text} transition-colors`}>{item.title}</p>
+        <p class="text-xs text-muted-foreground mt-0.5">{item.subtitle}</p>
+      </div>
+      <Icon name="arrow-right" class={`w-4 h-4 text-muted-foreground shrink-0 ${t.text} group-hover:translate-x-0.5 transition-all`} />
+    </a>
+  ))}
+</div>

package/src/composed/index.ts

@@ -6,3 +6,4 @@ export { default as FAQ } from './FAQ.astro';
 export { default as InlineImage } from './InlineImage.astro';
 export { default as Pagination } from './Pagination.astro';
 export { default as EntityCard } from './EntityCard.astro';
+export { default as ArrowLinkGrid } from './ArrowLinkGrid.astro';

package/src/editorial/ArticleFeatureCard.astro

@@ -0,0 +1,77 @@
+---
+/**
+ * ArticleFeatureCard — the wide lead card above an article grid: image left, label, title, byline with the
+ * published or "Updated" date, description and a read link. Dates arrive formatted; the image is the route's import.
+ */
+import { Picture } from 'astro:assets';
+import type { ImageMetadata } from 'astro';
+import Badge from '../primitives/Badge.astro';
+import Icon from '../primitives/Icon.astro';
+
+interface Props {
+  href: string;
+  title: string;
+  description: string;
+  author: string;
+  /** "Featured" or "Latest". */
+  label: string;
+  image?: ImageMetadata;
+  imageAlt?: string;
+  /** The date shown: the modified one when `updated`, else the published one. */
+  dateTime: string;
+  dateLabel: string;
+  updated?: boolean;
+  readLabel?: string;
+  updatedLabel?: string;
+}
+
+const { href, title, description, author, label, image, imageAlt = '', dateTime, dateLabel, updated = false, readLabel = 'Read article', updatedLabel = 'Updated' } = Astro.props;
+---
+
+<a href={href} class="group block mb-12 rounded-xl border border-border bg-card overflow-hidden hover:border-primary transition-colors focus:outline-none focus:ring-2 focus:ring-primary/50">
+  <div class="grid sm:grid-cols-[1.2fr_1fr] gap-0">
+    {image ? (
+      <div class="aspect-[4/3] sm:aspect-auto overflow-hidden">
+        <Picture
+          src={image}
+          alt={imageAlt}
+          widths={[480, 768, 1024]}
+          sizes="(max-width: 640px) 100vw, 50vw"
+          formats={['avif', 'webp']}
+          fallbackFormat="webp"
+          class="w-full h-full object-cover motion-safe:transition-transform motion-safe:duration-500 motion-safe:group-hover:scale-105"
+          loading="eager"
+          fetchpriority="high"
+        />
+      </div>
+    ) : (
+      <div class="aspect-[4/3] sm:aspect-auto bg-muted/40"></div>
+    )}
+    <div class="p-6 sm:p-8 flex flex-col justify-center">
+      <p class="text-xs font-semibold uppercase tracking-[0.18em] text-primary mb-2">{label}</p>
+      <h2 class="text-xl sm:text-2xl font-semibold font-display text-foreground leading-snug group-hover:text-primary transition-colors text-balance">
+        {title}
+      </h2>
+      <p class="mt-2 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
+        <span>{author}</span>
+        <span aria-hidden="true">·</span>
+        {updated ? (
+          <Badge tone="custom" toneClass="bg-muted" size="sm" lines={0} class="![font-size:inherit] ![line-height:inherit] ![font-weight:inherit] !gap-1">
+            <svg class="w-3 h-3 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+              <polyline points="23 4 23 10 17 10" />
+              <path d="M20.49 15a9 9 0 1 1-2.12-9.36L23 10" />
+            </svg>
+            {updatedLabel}{' '}<time datetime={dateTime}>{dateLabel}</time>
+          </Badge>
+        ) : (
+          <time datetime={dateTime}>{dateLabel}</time>
+        )}
+      </p>
+      <p class="mt-3 text-sm text-muted-foreground leading-relaxed line-clamp-3">{description}</p>
+      <span class="inline-flex items-center gap-1 mt-5 text-sm font-medium text-primary">
+        {readLabel}
+        <Icon name="arrow-right" class="w-3.5 h-3.5 motion-safe:transition-transform motion-safe:group-hover:translate-x-0.5" />
+      </span>
+    </div>
+  </div>
+</a>