@sarimarcus/content-sites-ui 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.14.0 (2026-10-01)
+
+- New `./seo`: `JsonLd` (safe JSON-LD renderer: escapes `</script`, `<!--` and U+2028/9), `OgImageMeta`, `Breadcrumb` (chevron or star separator, tap targets, copy as props), `ArticleMetadata` (resolved author in, no byline without one) and `AuthoritativeSources` (domain labels and outbound classification as props; competitor sources unlinked, affiliates `rel="noopener sponsored"`; optional disambiguation of domain-derived labels shared by different URLs). `scrollbar-hide` utility in `tailwind.css` (SLA-2737).
+
+## 0.13.0 (2026-10-01)
+
+- New `./editorial`: `EditorialGuidePage` (breadcrumb band, hero and body slots; owns the Pagefind markers, `pagefindType`, `breadcrumbIgnore`) and `EventPage` (back link, rendered body as `TrustedHtml`, highlights, practical information, price, official website and tags as props; `breadcrumb`, `hero`, `after-body`, `after-details` and `tail` slots), plus `BeforeYouGo` and `NumberedStep`. `./layout`: `BreadcrumbBand` (SLA-2819).
+
 ## 0.12.1 (2026-10-01)
 
 - No changes; lockstep release with tourism (SLA-2739).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Universal Astro UI components, layout shell and design tokens shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,6 @@
     "@lucide/astro": "^1.23.0",
     "astro": "^7.0.6",
     "tailwindcss": "^4.1.18",
-    "@sarimarcus/content-sites-core": "0.12.1"
+    "@sarimarcus/content-sites-core": "0.14.0"
   }
 }

package/src/editorial/BeforeYouGo.astro

@@ -0,0 +1,27 @@
+---
+/**
+ * BeforeYouGo — the boxed checklist that opens a planning guide: a heading with an info glyph and a list of
+ * `label` + `text` pairs. Labels carry their own punctuation.
+ */
+import Icon from '../primitives/Icon.astro';
+
+interface Props {
+  heading: string;
+  items: { label: string; text: string }[];
+  class?: string;
+}
+
+const { heading, items, class: className = 'mb-16' } = Astro.props;
+---
+
+<div class:list={['max-w-measure mx-auto', className]}>
+  <div class="p-6 bg-accent/10 border border-accent/20 rounded-xl">
+    <h2 class="font-semibold mb-3 flex items-center gap-2 font-display">
+      <Icon name="info" class="w-5 h-5 text-accent-strong" />
+      {heading}
+    </h2>
+    <ul class="text-sm text-muted-foreground space-y-2">
+      {items.map((item) => <li><strong>{item.label}</strong> {item.text}</li>)}
+    </ul>
+  </div>
+</div>

package/src/editorial/EditorialGuidePage.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * EditorialGuidePage — the shell of a long-form planning guide. The route keeps data, SEO and schema, and renders
+ * the site Layout around this template. It passes the site Breadcrumb in `breadcrumb`, its hero in `hero`, and the
+ * page body (byline, intro, sections, FAQ, sources, related blocks, each in its own Container) as default-slot
+ * children. The template owns the Pagefind markers: the hero and the body are indexed, the breadcrumb band is not.
+ */
+import BreadcrumbBand from '../layout/BreadcrumbBand.astro';
+
+interface Props {
+  /** Pagefind `type` meta on the hero. */
+  pagefindType?: string;
+  /** Keep the breadcrumb band out of the Pagefind body. */
+  breadcrumbIgnore?: boolean;
+}
+
+const { pagefindType = 'guide', breadcrumbIgnore = true } = Astro.props;
+---
+
+<BreadcrumbBand ignore={breadcrumbIgnore}>
+  <slot name="breadcrumb" />
+</BreadcrumbBand>
+
+<div data-pagefind-body data-pagefind-meta={`type:${pagefindType}`}>
+  <slot name="hero" />
+</div>
+
+<main class="py-12 lg:py-20">
+  <div data-pagefind-body>
+    <slot />
+  </div>
+</main>

package/src/editorial/EventPage.astro

@@ -0,0 +1,178 @@
+---
+/**
+ * EventPage — the shell and shared body of an event page. The route keeps paths, data, SEO and schema, and renders
+ * the site Layout around this template. Slots:
+ *   breadcrumb    — the site Breadcrumb, in the band under the header.
+ *   hero          — the site hero, inside the Pagefind body with `type:<pagefindType>` meta.
+ *   after-body    — site blocks between the description and the shared boxes.
+ *   after-details — site blocks after the tags, inside the measure column (affiliate, FAQ, onward links).
+ *   tail          — full-width blocks after the column (related events, related content).
+ * Every string arrives as a prop; the route renders markdown and passes it as TrustedHtml.
+ */
+import Container from '../layout/Container.astro';
+import Badge from '../primitives/Badge.astro';
+import BreadcrumbBand from '../layout/BreadcrumbBand.astro';
+import { newTab } from '../primitives/newTab';
+import type { TrustedHtml } from '../types';
+import type { EventInfoRow } from './event';
+
+interface Props {
+  bodyHtml: TrustedHtml;
+  /** Prose modifiers after `prose`, e.g. the site's prose theme and size. */
+  proseClass?: string;
+  backLink: { href: string; label: string };
+  highlights?: { heading: string; items: string[] };
+  practicalInfo?: { heading: string; rows: EventInfoRow[] };
+  price?: { label: string; value: string };
+  officialWebsite?: { href: string; label: string };
+  tags?: { heading: string; items: string[] };
+  pagefindType?: string;
+}
+
+const {
+  bodyHtml,
+  proseClass = 'prose-lg',
+  backLink,
+  highlights,
+  practicalInfo,
+  price,
+  officialWebsite,
+  tags,
+  pagefindType = 'event',
+} = Astro.props;
+
+const toneText = { primary: 'text-primary', secondary: 'text-secondary', accent: 'text-accent' };
+---
+
+<BreadcrumbBand>
+  <slot name="breadcrumb" />
+</BreadcrumbBand>
+
+<div data-pagefind-body data-pagefind-meta={`type:${pagefindType}`}>
+  <slot name="hero" />
+</div>
+
+<main class="pt-6 pb-12 lg:pt-8 lg:pb-20">
+  <Container size="measure">
+    <a
+      href={backLink.href}
+      class="inline-flex items-center gap-2 text-sm text-muted-foreground hover:text-primary transition-colors mb-8"
+    >
+      <svg class="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <path d="m12 19-7-7 7-7" /><path d="M19 12H5" />
+      </svg>
+      {backLink.label}
+    </a>
+
+    <article class={`prose ${proseClass} max-w-none`} data-pagefind-body>
+      <div set:html={bodyHtml} />
+    </article>
+
+    <slot name="after-body" />
+
+    {highlights && highlights.items.length > 0 && (
+      <div class="mt-12 p-6 bg-primary/5 rounded-xl border border-primary/20">
+        <h2
+          class="text-xl font-medium mb-6 flex items-center gap-2 font-display"
+        >
+          <svg class="w-5 h-5 shrink-0 text-primary" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="M12 2L15.09 8.26L22 9.27L17 14.14L18.18 21.02L12 17.77L5.82 21.02L7 14.14L2 9.27L8.91 8.26L12 2Z" />
+          </svg>
+          {highlights.heading}
+        </h2>
+        <ul class="space-y-3">
+          {highlights.items.map((highlight) => (
+            <li class="flex items-start gap-3">
+              <svg class="w-5 h-5 text-primary shrink-0 mt-0.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <polyline points="20 6 9 17 4 12" />
+              </svg>
+              <span class="text-foreground">{highlight}</span>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )}
+
+    {practicalInfo && (
+      <div class="mt-12 p-6 bg-muted/50 rounded-xl border border-border">
+        <h2
+          class="text-xl font-medium mb-6 flex items-center gap-2 font-display"
+        >
+          <svg class="w-5 h-5 shrink-0 text-primary" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <circle cx="12" cy="12" r="10" /><path d="M12 16v-4" /><path d="M12 8h.01" />
+          </svg>
+          {practicalInfo.heading}
+        </h2>
+
+        <div class="space-y-4">
+          {practicalInfo.rows.map((row) => (
+            <div class="flex items-start gap-3">
+              <div class="w-10 h-10 rounded-lg bg-background flex items-center justify-center shrink-0">
+                <svg class={`w-5 h-5 shrink-0 ${toneText[row.tone]}`} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                  {row.icon === 'clock' && <Fragment><circle cx="12" cy="12" r="10" /><polyline points="12 6 12 12 16 14" /></Fragment>}
+                  {row.icon === 'sun' && <Fragment><circle cx="12" cy="12" r="4" /><path d="M12 2v2" /><path d="M12 20v2" /><path d="m4.93 4.93 1.41 1.41" /><path d="m17.66 17.66 1.41 1.41" /><path d="M2 12h2" /><path d="M20 12h2" /><path d="m6.34 17.66-1.41 1.41" /><path d="m19.07 4.93-1.41 1.41" /></Fragment>}
+                  {row.icon === 'pen' && <Fragment><path d="M12 20h9" /><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z" /></Fragment>}
+                  {row.icon === 'bus' && <Fragment><path d="M8 6v6" /><path d="M15 6v6" /><path d="M2 12h19.6" /><path d="M18 18h3s.5-1.7.8-2.8c.1-.4.2-.8.2-1.2 0-.4-.1-.8-.2-1.2l-1.4-5C20.1 6.8 19.1 6 18 6H4a2 2 0 0 0-2 2v10h3" /><circle cx="7" cy="18" r="2" /><path d="M9 18h5" /><circle cx="16" cy="18" r="2" /></Fragment>}
+                </svg>
+              </div>
+              <div>
+                <span class="text-sm font-medium text-foreground">{row.label}</span>
+                {row.html !== undefined
+                  ? <div class="text-sm text-muted-foreground mt-0.5 whitespace-pre-line" set:html={row.html} />
+                  : <p class="text-sm text-muted-foreground mt-0.5">{row.text}</p>}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    )}
+
+    {price && (
+      <div class="mt-8 p-4 bg-accent/10 rounded-lg border border-accent/20">
+        <div class="flex items-center gap-3">
+          <svg class="w-6 h-6 text-accent" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="M4 10h12"/><path d="M4 14h9"/><path d="M19 6a7.7 7.7 0 0 0-5.2-2A7.9 7.9 0 0 0 6 12c0 4.4 3.5 8 7.8 8 2 0 3.8-.8 5.2-2"/>
+          </svg>
+          <div>
+            <span class="text-sm font-medium">{price.label}</span>
+            <p class="text-lg text-accent font-medium">{price.value}</p>
+          </div>
+        </div>
+      </div>
+    )}
+
+    {officialWebsite && (
+      <div class="mt-8">
+        <a
+          href={officialWebsite.href}
+          {...newTab(officialWebsite.href, '_blank')}
+          class="inline-flex items-center gap-2 px-6 py-3 bg-primary text-primary-foreground rounded-lg hover:bg-primary-strong transition-colors"
+        >
+          <svg class="w-5 h-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /><polyline points="15 3 21 3 21 9" /><line x1="10" y1="14" x2="21" y2="3" />
+          </svg>
+          {officialWebsite.label}
+        </a>
+      </div>
+    )}
+
+    {tags && tags.items.length > 0 && (
+      <div class="mt-8">
+        <h3 class="text-sm font-medium text-muted-foreground mb-3">
+          {tags.heading}
+        </h3>
+        <div class="flex flex-wrap gap-2">
+          {tags.items.map((tag) => (
+            <Badge tone="custom" toneClass="bg-muted text-muted-foreground" size="lg" lines={0} class="capitalize !py-1 ![font-weight:inherit]">
+              {tag}
+            </Badge>
+          ))}
+        </div>
+      </div>
+    )}
+
+    <slot name="after-details" />
+  </Container>
+
+  <slot name="tail" />
+</main>

package/src/editorial/NumberedStep.astro

@@ -0,0 +1,34 @@
+---
+/**
+ * NumberedStep — one stage of a multi-stage plan: a round marker, a title and a subtitle, then the stage's prose in
+ * a card (default slot). `tone` colours the marker and the card; the accent tone tints the card too.
+ */
+interface Props {
+  marker: string;
+  title: string;
+  subtitle: string;
+  tone?: 'primary' | 'accent' | 'secondary';
+}
+
+const { marker, title, subtitle, tone = 'primary' } = Astro.props;
+
+const [markerBg, markerText] = {
+  primary: ['bg-primary', 'text-primary-foreground'],
+  accent: ['bg-accent', 'text-accent-foreground'],
+  secondary: ['bg-secondary', 'text-secondary-foreground'],
+}[tone];
+const cardClass = tone === 'accent' ? 'bg-accent/10 rounded-xl border border-accent/20' : 'bg-card rounded-xl border border-border';
+---
+
+<div>
+  <div class="flex items-center gap-4 mb-4">
+    <div class={`w-14 h-14 rounded-full ${markerBg} flex items-center justify-center ${markerText} font-bold text-xl shrink-0`}>{marker}</div>
+    <div>
+      <h3 class="text-xl font-semibold font-display">{title}</h3>
+      <p class="text-muted-foreground text-sm">{subtitle}</p>
+    </div>
+  </div>
+  <div class={`p-6 ${cardClass}`}>
+    <slot />
+  </div>
+</div>

package/src/editorial/event.ts

@@ -0,0 +1,13 @@
+import type { TrustedHtml } from '../types';
+
+export type EventInfoIcon = 'clock' | 'sun' | 'pen' | 'bus';
+
+/** One row of an EventPage practical-information box. */
+export interface EventInfoRow {
+  icon: EventInfoIcon;
+  tone: 'primary' | 'secondary' | 'accent';
+  label: string;
+  /** Plain text, or `html` for rendered markdown. */
+  text?: string;
+  html?: TrustedHtml;
+}

package/src/editorial/index.ts

@@ -1,2 +1,6 @@
-// Public surface of @sarimarcus/content-sites-ui/editorial. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-ui/editorial.
+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 type { EventInfoRow, EventInfoIcon } from './event';

package/src/layout/BreadcrumbBand.astro

@@ -0,0 +1,19 @@
+---
+/**
+ * BreadcrumbBand — the muted strip under the fixed header that holds a page's breadcrumb trail (default slot).
+ * `ignore` keeps it out of the Pagefind body.
+ */
+import Container from './Container.astro';
+
+interface Props {
+  ignore?: boolean;
+}
+
+const { ignore = true } = Astro.props;
+---
+
+<div class="pt-16 bg-muted/50 border-b border-border" data-pagefind-ignore={ignore ? '' : undefined}>
+  <Container class="py-3">
+    <slot />
+  </Container>
+</div>

package/src/layout/index.ts

@@ -1,2 +1,3 @@
 // Public surface of @sarimarcus/content-sites-ui/layout.
 export { default as Container } from './Container.astro';
+export { default as BreadcrumbBand } from './BreadcrumbBand.astro';

package/src/seo/ArticleMetadata.astro

@@ -0,0 +1,144 @@
+---
+/**
+ * ArticleMetadata — byline and freshness dates (E-E-A-T).
+ *
+ * The author arrives resolved: the site looks the name up in its authors collection and passes the profile URL,
+ * the optimised portrait (or a photo URL) and the credentials. No author renders no byline and no avatar; a site
+ * that wants a brand byline passes it as an author.
+ *
+ * Dates: most callers pass a date-only value (only articles carry a real HH:MM), so a time is printed only when the
+ * input has one, in `timeZone`; a date-only value always prints its UTC calendar day. "Updated" leads when the two
+ * dates fall on different calendar days, since recency is what a reader and a crawler look for.
+ *
+ * The `\n`-prefixed labels and `bylineLead` reproduce the text nodes the sites' templates compile to, so adoption
+ * changes no byte.
+ */
+import { Image } from 'astro:assets';
+import type { ArticleAuthor } from './types';
+
+interface Props {
+  author?: ArticleAuthor | null;
+  datePublished?: string;
+  dateModified?: string;
+  /** Time zone for a value that carries a time. */
+  timeZone?: string;
+  locale?: string;
+  writtenByLabel?: string;
+  /** Portrait alt text, followed by the author's name. */
+  portraitLabel?: string;
+  updatedLabel?: string;
+  publishedLabel?: string;
+  ariaLabel?: string;
+  /** Classes of the round placeholder shown when the author has no portrait. */
+  placeholderClass?: string;
+  updatedIconClass?: string;
+  /** Whitespace compatibility only: 'grouped' compiles to the markup of a template that wraps the byline in a Fragment. */
+  bylineWhitespace?: 'flat' | 'grouped';
+}
+
+const {
+  author,
+  datePublished,
+  dateModified,
+  timeZone = 'UTC',
+  locale = 'en-GB',
+  writtenByLabel = 'Written by',
+  portraitLabel = 'Portrait of',
+  updatedLabel = 'Updated',
+  publishedLabel = 'Published',
+  ariaLabel = 'Article information',
+  placeholderClass = 'bg-gradient-to-br from-primary/20 to-accent/20',
+  updatedIconClass = 'text-primary',
+  bylineWhitespace = 'flat',
+} = Astro.props;
+
+function formatDate(dateStr: string | undefined): string {
+  if (!dateStr) return '';
+
+  const date = new Date(dateStr);
+  return dateStr.includes('T')
+    ? date.toLocaleString(locale, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        timeZone,
+      })
+    : date.toLocaleDateString(locale, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        timeZone: 'UTC',
+      });
+}
+
+const publishedFormatted = formatDate(datePublished);
+const modifiedFormatted = formatDate(dateModified);
+const showModified = !!dateModified && (!datePublished || dateModified.slice(0, 10) !== datePublished.slice(0, 10));
+
+const name = author?.name;
+const portraitAlt = `${portraitLabel} ${name}`;
+const credentials = author?.credentials ?? null;
+const grouped = bylineWhitespace === 'grouped';
+const bylineLead = author ? (grouped ? '  ' : ' ') : (grouped ? '' : ' ');
+---
+
+<address class="not-italic mb-5" role="contentinfo" aria-label={ariaLabel}>
+  <div class="flex items-start gap-3">
+    {author && (author.image ? (
+      <Image
+        src={author.image}
+        alt={portraitAlt}
+        width={96}
+        height={96}
+        class="w-12 h-12 rounded-full object-cover bg-muted shrink-0 mt-0.5"
+        loading="lazy"
+        decoding="async"
+      />
+    ) : author.photoUrl ? (
+      <img
+        src={author.photoUrl}
+        alt={portraitAlt}
+        width="48"
+        height="48"
+        class="w-12 h-12 rounded-full object-cover bg-muted shrink-0 mt-0.5"
+        loading="lazy"
+        decoding="async"
+      />
+    ) : (
+      <div class:list={['w-12 h-12 rounded-full', placeholderClass, 'shrink-0 mt-0.5']} aria-hidden="true" />
+    ))}
+
+    {/* name, credentials, dates */}
+    <div class="min-w-0">{bylineLead}{author && <div class="text-xs text-muted-foreground mb-0.5">{writtenByLabel}</div>}
+      {author && (author.href ? (
+        <a href={author.href} rel="author" class="font-semibold text-foreground hover:text-primary transition-colors hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary">
+          {name}
+        </a>
+      ) : (
+        <span class="font-semibold text-foreground">{name}</span>
+      ))}
+      {author && credentials && (
+        <p class="mt-1 text-sm text-muted-foreground leading-snug line-clamp-2">{credentials}</p>
+      )}
+      {/* freshness first */}
+      <div class="mt-2 flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+        {showModified && modifiedFormatted ? (
+          <span class="inline-flex items-center gap-1.5 text-sm font-medium text-foreground">
+            <svg class:list={['w-3.5 h-3.5 shrink-0', updatedIconClass]} 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>{`\n${updatedLabel}`} <time datetime={dateModified}>{modifiedFormatted}</time>
+          </span>
+        ) : publishedFormatted && (
+          <span class="text-sm font-medium text-foreground">{`\n${publishedLabel}`} <time datetime={datePublished}>{publishedFormatted}</time>
+          </span>
+        )}
+        {showModified && publishedFormatted && (
+          <span>{publishedLabel} <time datetime={datePublished}>{publishedFormatted}</time></span>
+        )}
+      </div>
+    </div>
+  </div>
+</address>

package/src/seo/AuthoritativeSources.astro

@@ -0,0 +1,190 @@
+---
+/**
+ * AuthoritativeSources — numbered, anchored references (E-E-A-T). Each item carries id="fn-{n}" so an inline `[^n]`
+ * footnote link jumps to it (validate-footnote-render relies on that), and the inline script opens the list when the
+ * page loads on, or navigates to, a `#fn-n` hash.
+ *
+ * A source is a URL string, labelled from `domainLabels` (by host, without `www.`) or else by its host, or an object
+ * { url, name?, description?, quote? }: `description` is a curated blurb, `quote` the verbatim cited sentence.
+ *
+ * Link policy (Rule 38), from `domainClass` (host → class, or a function of the URL): a competitor renders its label
+ * unlinked (the item stays, so footnote numbers hold), an affiliate link carries rel="noopener sponsored", any other
+ * rel="noopener".
+ *
+ * `disambiguate` suffixes domain-derived labels shared by different URLs with a fragment of their URL path
+ * ("Host — Prices"), so two pages of one domain stay distinguishable. Explicit names, repeat citations of one URL and
+ * domain-root URLs keep their label.
+ */
+import type { SourceInput, DomainClassifier } from './types';
+
+interface Props {
+  sources: SourceInput[];
+  title?: string;
+  class?: string;
+  eyebrow?: string;
+  eyebrowClass?: string;
+  domainLabels?: Record<string, string>;
+  domainClass?: DomainClassifier;
+  disambiguate?: boolean;
+  disambiguationSeparator?: string;
+  /** Follows the count: "12 references". */
+  countLabel?: string;
+  showLabel?: string;
+  hideLabel?: string;
+  newTabLabel?: string;
+  /** Size class of the Show/Hide toggle labels. */
+  toggleSizeClass?: string;
+}
+
+const {
+  sources,
+  title = 'Sources',
+  class: className = '',
+  eyebrow = 'Further reading',
+  eyebrowClass = 'text-xs font-semibold uppercase tracking-[0.18em] text-primary',
+  domainLabels = {},
+  domainClass = {},
+  disambiguate = false,
+  disambiguationSeparator = ' — ',
+  countLabel = 'references',
+  showLabel = 'Show',
+  hideLabel = 'Hide',
+  newTabLabel = '(opens in a new tab)',
+  toggleSizeClass = 'text-sm',
+} = Astro.props;
+
+if (!sources || sources.length === 0) return null;
+
+const hostKey = (host: string) => host.toLowerCase().replace(/^www\./, '');
+const classMap = typeof domainClass === 'function'
+  ? null
+  : new Map(Object.entries(domainClass).map(([d, c]) => [hostKey(d), c]));
+
+function classify(url: string): string {
+  if (typeof domainClass === 'function') return domainClass(url);
+  try {
+    return classMap?.get(hostKey(new URL(url).hostname)) ?? 'other';
+  } catch {
+    return 'other';
+  }
+}
+
+function domainLabel(url: string): string {
+  try {
+    const h = new URL(url).hostname.replace(/^www\./, '');
+    return domainLabels[h] ?? h;
+  } catch {
+    return url;
+  }
+}
+
+function humanizeSlug(slug: string): string {
+  const cleaned = slug
+    .replace(/\.(html?|php|aspx?)$/i, '')
+    .replace(/[-_]+/g, ' ')
+    .trim();
+  if (!cleaned) return '';
+  return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+
+function pathFragment(url: string): string | null {
+  try {
+    const segments = new URL(url).pathname.split('/').filter(Boolean);
+    if (segments.length === 0) return null;
+    const humanized = humanizeSlug(decodeURIComponent(segments[segments.length - 1]));
+    return humanized || null;
+  } catch {
+    return null;
+  }
+}
+
+const normalized: { name: string; url: string; description?: string; quote?: string; linkRel: string | null; fromDomain: boolean }[] = sources.map((s) => {
+  const entry =
+    typeof s === 'string'
+      ? { name: domainLabel(s), url: s, fromDomain: true }
+      : { url: s.url, name: s.name ?? domainLabel(s.url), description: s.description, quote: s.quote, fromDomain: !s.name };
+  const cls = classify(entry.url);
+  return {
+    ...entry,
+    linkRel: cls === 'competitor' ? null : cls === 'affiliate' ? 'noopener sponsored' : 'noopener',
+  };
+});
+
+if (disambiguate) {
+  const urlsByName = new Map<string, Set<string>>();
+  for (const n of normalized) if (n.fromDomain) urlsByName.set(n.name, (urlsByName.get(n.name) ?? new Set()).add(n.url));
+  for (const n of normalized) {
+    if (n.fromDomain && (urlsByName.get(n.name)?.size ?? 0) > 1) {
+      const frag = pathFragment(n.url);
+      if (frag) n.name = `${n.name}${disambiguationSeparator}${frag}`;
+    }
+  }
+}
+---
+
+<section class:list={["mt-12 pt-8 border-t border-border", className]} aria-labelledby="sources-heading">
+  <p class:list={[eyebrowClass, 'mb-2']}>{eyebrow}</p>
+  <h2 id="sources-heading" class="text-xl sm:text-2xl font-normal font-display text-foreground mb-3 tracking-tight">{title}</h2>
+  <details data-sources class="group">
+    <summary class="flex min-h-11 cursor-pointer list-none items-center justify-between gap-4 rounded-lg border border-border bg-muted/30 px-4 py-2.5 text-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary marker:content-none">
+      <span class="text-muted-foreground">{normalized.length} {countLabel}</span>
+      <span class:list={[toggleSizeClass, 'font-medium text-primary group-open:hidden']}>{showLabel}</span>
+      <span class:list={['hidden', toggleSizeClass, 'font-medium text-primary group-open:inline']}>{hideLabel}</span>
+    </summary>
+
+  <ol class="mt-5 space-y-2 list-none" role="list">
+    {normalized.map((source, i) => (
+      <li
+        id={`fn-${i + 1}`}
+        class="flex items-baseline gap-3 p-3 bg-muted/30 rounded-lg border border-border hover:border-primary/50 transition-colors scroll-mt-28"
+      >
+        <span class="font-mono text-sm text-primary min-w-[2rem] shrink-0 select-none" aria-hidden="true">
+          [{i + 1}]
+        </span>
+        <div class="flex-1 min-w-0">
+          {source.linkRel === null ? (
+            <span class="inline-flex items-baseline gap-1.5 font-medium text-sm text-foreground break-words">
+              <span>{source.name}</span>
+            </span>
+          ) : (
+            <a
+              href={source.url}
+              target="_blank"
+              rel={source.linkRel}
+              class="inline-flex items-baseline gap-1.5 font-medium text-sm text-foreground hover:text-primary transition-colors break-words"
+            >
+              <span>{source.name}</span>
+              <svg class="w-3.5 h-3.5 self-center text-muted-foreground shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <path d="M7 7h10v10" />
+                <path d="M7 17 17 7" />
+              </svg>
+              <span class="sr-only">{newTabLabel}</span>
+            </a>
+          )}
+          {source.description && (
+            <p class="text-sm text-muted-foreground mt-1 leading-relaxed">{source.description}</p>
+          )}
+          {source.quote && (
+            <p class="text-sm text-muted-foreground mt-1.5 leading-relaxed italic border-l-2 border-primary/30 pl-3">
+              &ldquo;{source.quote}&rdquo;
+            </p>
+          )}
+        </div>
+      </li>
+    ))}
+  </ol>
+  </details>
+</section>
+
+<script is:inline>
+  (() => {
+    const revealSource = () => {
+      if (!/^#fn-\d+$/.test(location.hash)) return;
+      const target = document.querySelector(location.hash);
+      const details = target?.closest('[data-sources]');
+      if (details) details.open = true;
+    };
+    revealSource();
+    addEventListener('hashchange', revealSource);
+  })();
+</script>

package/src/seo/Breadcrumb.astro

@@ -0,0 +1,80 @@
+---
+/**
+ * Breadcrumb — the visual trail, Home first. Renders no JSON-LD: the BreadcrumbList is the structured-data adapter's.
+ *
+ * Single line, always: the trail scrolls horizontally instead of wrapping, so a deep trail never pushes the page
+ * content down on mobile. `tapTargets`: py-1/-my-1 extends each link's hit area 4px beyond its row without moving
+ * layout; the nav's own py-1/-my-1 mirrors it so the overflow container never clips that hit area (28px meets
+ * WCAG 2.5.8 AA). `separator="star"` draws a filled star that fades with depth.
+ *
+ * `navLead` reproduces the text node the sites' templates emit before the list (two spaces with tap targets, one
+ * without), so adopting the package changes no byte.
+ */
+import { url } from '@sarimarcus/content-sites-core/url';
+import Icon from '../primitives/Icon.astro';
+import type { BreadcrumbItem } from './types';
+
+interface Props {
+  items: BreadcrumbItem[];
+  compactMobile?: boolean;
+  textColorClass?: string;
+  linkColorClass?: string;
+  separatorColorClass?: string;
+  separator?: 'chevron' | 'star';
+  tapTargets?: boolean;
+  homeLabel?: string;
+  homeHref?: string;
+  ariaLabel?: string;
+  basePath?: string;
+}
+
+const {
+  items,
+  textColorClass = 'text-muted-foreground',
+  linkColorClass = 'hover:text-primary',
+  separatorColorClass = 'text-border',
+  compactMobile = false,
+  separator = 'chevron',
+  tapTargets = true,
+  homeLabel = 'Home',
+  homeHref = '/',
+  ariaLabel = 'Breadcrumb navigation',
+  basePath = '/',
+} = Astro.props;
+
+const breadcrumbs = [
+  { name: homeLabel, url: homeHref },
+  ...items,
+];
+const navLead = tapTargets ? '  ' : ' ';
+---
+
+<nav aria-label={ariaLabel} class:list={[tapTargets ? 'text-sm py-1 -my-1 px-1 -mx-1' : 'text-sm', compactMobile ? 'overflow-hidden sm:overflow-x-auto' : 'overflow-x-auto scrollbar-hide', textColorClass]}>{navLead}<ol class:list={[tapTargets ? 'flex flex-nowrap items-center gap-x-1.5 whitespace-nowrap' : 'flex flex-nowrap items-center gap-1.5 whitespace-nowrap']}>
+    {breadcrumbs.map((item, index) => (
+      <li class:list={['flex items-center gap-1.5', compactMobile && index === breadcrumbs.length - 1 ? 'min-w-0 sm:shrink-0' : 'shrink-0']}>
+        {index > 0 && (separator === 'star' ? (
+          <Icon
+            name="star"
+            filled
+            class:list={['w-2.5 h-2.5 shrink-0', separatorColorClass]}
+            style={`opacity: ${Math.max(0.4, 1 - (index - 1) * 0.15)}`}
+          />
+        ) : (
+          <svg class:list={['w-3.5 h-3.5 shrink-0', separatorColorClass]} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="m9 18 6-6-6-6"/>
+          </svg>
+        ))}
+        {item.url && index < breadcrumbs.length - 1 ? (
+          <a
+            href={url(item.url, basePath)}
+            class:list={[tapTargets ? 'inline-flex items-center py-1 -my-1 px-1 -mx-1 transition-colors' : 'transition-colors', linkColorClass]}
+          >
+            {item.name}
+          </a>
+        ) : (
+          <span class:list={['font-medium', compactMobile && index === breadcrumbs.length - 1 ? 'truncate sm:overflow-visible' : '']}>{item.name}</span>
+        )}
+      </li>
+    ))}
+  </ol>
+</nav>

package/src/seo/JsonLd.astro

@@ -0,0 +1,20 @@
+---
+/**
+ * JsonLd — renders structured data as one <script type="application/ld+json">.
+ *
+ * Output is JSON.stringify(data) with the minimal escaping that keeps the block inside its script element while
+ * staying valid JSON: `</script` (any case) → `<\/script`, `<!--` → `<\u0021--`, U+2028/U+2029 → `\u2028`/`\u2029`.
+ * Any other input renders byte-identical to `set:html={JSON.stringify(data)}`. Values may carry markup (an FAQ answer
+ * with a link), so `<` is deliberately left as is.
+ */
+import { escapeJsonLd } from './jsonLd';
+
+interface Props {
+  data: object | object[];
+}
+
+const { data } = Astro.props;
+const json = escapeJsonLd(JSON.stringify(data));
+---
+
+<script type="application/ld+json" set:html={json} />

package/src/seo/OgImageMeta.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * OgImageMeta — Open Graph and Twitter image tags. A relative `image` (or the default) is made absolute against
+ * `siteUrl` + `baseUrl`; an `http…` image passes through. The 1200×675 default matches the OG generator
+ * (scripts/og-images/generate.mjs).
+ */
+interface Props {
+  image?: string;
+  alt: string;
+  siteUrl: string;
+  baseUrl: string;
+  defaultImage?: string;
+  width?: number;
+  height?: number;
+}
+
+const { image, alt, siteUrl, baseUrl, defaultImage = '/og-default.jpg', width = 1200, height = 675 } = Astro.props;
+const ogImagePath = image ?? defaultImage;
+const absoluteOgImage = ogImagePath.startsWith('http')
+  ? ogImagePath
+  : `${siteUrl}${baseUrl}${ogImagePath}`;
+---
+
+<meta property="og:image" content={absoluteOgImage} />
+<meta property="og:image:alt" content={alt} />
+<meta property="og:image:width" content={String(width)} />
+<meta property="og:image:height" content={String(height)} />
+<meta name="twitter:image" content={absoluteOgImage} />
+<meta name="twitter:image:alt" content={alt} />

package/src/seo/index.ts

@@ -1,2 +1,8 @@
-// Public surface of @sarimarcus/content-sites-ui/seo. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-ui/seo.
+export { default as JsonLd } from './JsonLd.astro';
+export { default as OgImageMeta } from './OgImageMeta.astro';
+export { default as Breadcrumb } from './Breadcrumb.astro';
+export { default as ArticleMetadata } from './ArticleMetadata.astro';
+export { default as AuthoritativeSources } from './AuthoritativeSources.astro';
+export { escapeJsonLd } from './jsonLd';
+export type { BreadcrumbItem, ArticleAuthor, SourceInput, DomainClassifier } from './types';

package/src/seo/jsonLd.ts

@@ -0,0 +1,11 @@
+/**
+ * Keep serialised JSON inside a <script> element without changing what it parses to. Every match sits inside a JSON
+ * string (none of these sequences can occur outside one), where `\/`, `\u0021` and `\u2028` are valid escapes.
+ */
+export function escapeJsonLd(json: string): string {
+  return json
+    .replace(/<\/(script)/gi, '<\\/$1')
+    .replace(/<!--/g, '<\\u0021--')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}

package/src/seo/types.ts

@@ -0,0 +1,20 @@
+import type { ImageMetadata } from 'astro';
+
+export interface BreadcrumbItem {
+  name: string;
+  url?: string;
+}
+
+/** An author already resolved by the site: profile URL, optimised portrait or photo URL, credentials. */
+export interface ArticleAuthor {
+  name: string;
+  href?: string | null;
+  image?: ImageMetadata | null;
+  photoUrl?: string | null;
+  credentials?: string | null;
+}
+
+export type SourceInput = string | { name?: string; url: string; description?: string; quote?: string };
+
+/** Host → outbound class (`competitor`, `affiliate`, …), or a function of the URL. */
+export type DomainClassifier = Record<string, string> | ((url: string) => string);

package/src/styles/tailwind.css

@@ -1,3 +1,12 @@
 /* Tailwind v4 skips node_modules during class detection. Consumers @import this file so the
    package's own templates are scanned: @import "@sarimarcus/content-sites-ui/tailwind.css"; */
 @source "..";
+
+/* Horizontal scrollers that keep scrolling but draw no scrollbar (Breadcrumb, TableOfContents). */
+@utility scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}