@warpgogol/werkstatt-shared 0.2.0

package/src/share/semantic/block-extractors/index.ts

@@ -0,0 +1,502 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0208: block text extractor implementations for all known block types. Registers extractors into the global BLOCK_EXTRACTORS registry.</purpose>
+<non-goals>
+  <item>Do not handle block types that contain no text-bearing props.</item>
+  <item>Do not resolve content references — extraction is shallow and deterministic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0208: registered extractors for warpgogol-com block types.</item>
+  <item>RFC-0372: added video-section, donation-card, credits, passport no-op extractors; people extractor now extracts heading; all extractors return heading (possibly empty) for unified SemanticBlock.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { BLOCK_EXTRACTORS } from "../block-extraction.ts";
+
+function safeGet(obj: unknown, path: string): unknown {
+  return path.split(".").reduce((acc: unknown, key: string) => {
+    if (acc && typeof acc === "object") return (acc as Record<string, unknown>)[key];
+    return undefined;
+  }, obj);
+}
+
+function safeString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function safeArray<T>(v: unknown, mapper: (item: unknown) => T | undefined): T[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const result = v.map(mapper).filter((x): x is T => x !== undefined);
+  return result.length > 0 ? result : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// hero-decision-card
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "hero-decision-card",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const lead =
+      safeString(safeGet(props, "header.subheading")) ?? safeString(safeGet(props, "tagline"));
+    const items = safeArray(safeGet(props, "decisionCard.items"), (item) => {
+      const label = safeString(safeGet(item, "label"));
+      const value = safeString(safeGet(item, "value"));
+      if (!label) return undefined;
+      return { title: `${label}: ${value ?? ""}` };
+    });
+    const ctaItems: Array<{ title: string; description?: string }> = [];
+    const primaryLabel = safeString(safeGet(props, "primaryCta.label"));
+    const secondaryLabel = safeString(safeGet(props, "secondaryCta.label"));
+    if (primaryLabel) ctaItems.push({ title: `CTA: ${primaryLabel}` });
+    if (secondaryLabel) ctaItems.push({ title: `CTA: ${secondaryLabel}` });
+    return { heading, lead, items: items?.length ? [...items, ...ctaItems] : ctaItems };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// audience-cards (guarantees, included-features, price-economics, growth-modules, referral-club, growth-timeline, etc.)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "audience-cards",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const lead = safeString(safeGet(props, "header.subheading"));
+    const cards = safeArray(safeGet(props, "body.cards"), (card) => {
+      const title = safeString(safeGet(card, "title"));
+      const description = safeString(safeGet(card, "description"));
+      if (!title) return undefined;
+      return { title, description };
+    });
+    return { heading, lead, items: cards };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// comparison-cards
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "comparison-cards",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const _labels = safeGet(props, "labels") as Record<string, string> | undefined;
+    const rows = safeArray(safeGet(props, "rows"), (row) => {
+      const left = safeString(safeGet(row, "left"));
+      const right = safeString(safeGet(row, "right"));
+      if (!left || !right) return undefined;
+      return { title: `${left} → ${right}` };
+    });
+    return { heading, items: rows };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// price-card
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "price-card",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const monthly = safeString(safeGet(props, "monthly"));
+    const yearly = safeString(safeGet(props, "yearly"));
+    const setup = safeString(safeGet(props, "setup"));
+    const includes = safeArray(safeGet(props, "includes"), (item) => {
+      const text = safeString(safeGet(item, "text"));
+      if (!text) return undefined;
+      return { title: text };
+    });
+    const priceItems: Array<{ title: string; description?: string }> = [];
+    if (monthly) priceItems.push({ title: `Monatlich: ${monthly}` });
+    if (yearly) priceItems.push({ title: `Jährlich: ${yearly}` });
+    if (setup) priceItems.push({ title: `Einrichtung: ${setup}` });
+    return { heading, items: includes?.length ? [...priceItems, ...includes] : priceItems };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// ownership-block
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "ownership-block",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const items = safeArray(safeGet(props, "body.items"), (item) => {
+      const text = safeString(safeGet(item, "text"));
+      if (!text) return undefined;
+      return { title: text };
+    });
+    return { heading, items };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// controlled-responsibility-block
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "controlled-responsibility-block",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const lead = safeString(safeGet(props, "header.subheading"));
+    const primaryLabel = safeString(safeGet(props, "labels.primary"));
+    const secondaryLabel = safeString(safeGet(props, "labels.secondary"));
+    const primaryItems = safeArray(safeGet(props, "primaryItems"), (item) => {
+      const text = safeString(safeGet(item, "text"));
+      if (!text) return undefined;
+      return { title: `${primaryLabel ?? ""}: ${text}`.replace(/^:\s*/, "") };
+    });
+    const secondaryItems = safeArray(safeGet(props, "secondaryItems"), (item) => {
+      const text = safeString(safeGet(item, "text"));
+      if (!text) return undefined;
+      return { title: `${secondaryLabel ?? ""}: ${text}`.replace(/^:\s*/, "") };
+    });
+    return { heading, lead, items: [...(primaryItems ?? []), ...(secondaryItems ?? [])] };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// notausgang-block
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "notausgang-block",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const items = safeArray(safeGet(props, "body.items"), (item) => {
+      const text = safeString(safeGet(item, "text"));
+      if (!text) return undefined;
+      return { title: text };
+    });
+    return { heading, items };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// faq-list — extracts heading only; FAQ entries come from business/faq via reader
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "faq-list",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    return { heading };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// final-cta
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "final-cta",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const paragraphs = safeArray(safeGet(props, "body.paragraphs"), (p) => {
+      const text = safeString(p);
+      if (!text) return undefined;
+      return { title: text };
+    });
+    const ctaItems = safeArray(safeGet(props, "ctaGroup.items"), (item) => {
+      const label = safeString(safeGet(item, "label"));
+      if (!label) return undefined;
+      return { title: `CTA: ${label}` };
+    });
+    const allItems = [...(paragraphs ?? []), ...(ctaItems ?? [])];
+    return { heading, items: allItems.length > 0 ? allItems : undefined };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// trust-strip
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "trust-strip",
+  extract(props) {
+    const items = safeArray(safeGet(props, "body.items"), (item) => {
+      const text = safeString(safeGet(item, "text"));
+      if (!text) return undefined;
+      return { title: text };
+    });
+    return { items };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// send-message
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "send-message",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const paragraphs = safeArray(safeGet(props, "body.paragraphs"), (p) => {
+      const text = safeString(p);
+      if (!text) return undefined;
+      return { title: text };
+    });
+    return { heading, items: paragraphs };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// chat-widget
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "chat-widget",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    return { heading };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// markdown (RFC-0325: Programmatic Surface Q&A/prose sections baked as repeated
+// `type: "markdown"` blocks — e.g. the Ratgeber FAQ items). The first markdown
+// block on a page is separately consumed for the page's prose `contentRef`
+// body (build-page.ts `extractMarkdownProps`); this extractor additionally
+// surfaces EVERY markdown block's heading/lead as a content block so repeated
+// Q&A-style sections are not silently dropped from Markdown twins.
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "markdown",
+  extract(props) {
+    const heading = safeString(safeGet(props, "heading"));
+    const lead = safeString(safeGet(props, "lead"));
+    return { heading, lead };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// hero (nicaragua-projekt home page)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "hero",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const lead =
+      safeString(safeGet(props, "header.subheading")) ?? safeString(safeGet(props, "tagline"));
+    const description = safeString(safeGet(props, "description"));
+    const stats = safeArray(safeGet(props, "stats"), (s) => {
+      const value = safeString(safeGet(s, "value"));
+      const label = safeString(safeGet(s, "label"));
+      if (!value || !label) return undefined;
+      return { title: `${value} ${label}` };
+    });
+    const ctaItems: Array<{ title: string }> = [];
+    const primary = safeString(safeGet(props, "ctaPrimaryLabel"));
+    const secondary = safeString(safeGet(props, "ctaSecondaryLabel"));
+    if (primary) ctaItems.push({ title: `CTA: ${primary}` });
+    if (secondary) ctaItems.push({ title: `CTA: ${secondary}` });
+    const allItems = [...(stats ?? []), ...ctaItems];
+    return {
+      heading,
+      lead: lead ?? description,
+      items: allItems.length > 0 ? allItems : undefined,
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// problem (nicaragua-projekt)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "problem",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const paragraphs = safeArray(safeGet(props, "body.paragraphs"), (p) => {
+      const text = safeString(p);
+      if (!text) return undefined;
+      return { title: text };
+    });
+    return { heading, items: paragraphs };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// approach (nicaragua-projekt)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "approach",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const cards = safeArray(safeGet(props, "body.cards"), (card) => {
+      const title = safeString(safeGet(card, "title"));
+      const description = safeString(safeGet(card, "description"));
+      if (!title) return undefined;
+      return { title, description };
+    });
+    return { heading, items: cards };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// impact (nicaragua-projekt)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "impact",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const stats = safeArray(safeGet(props, "body.stats"), (s) => {
+      const value = safeString(safeGet(s, "value"));
+      const label = safeString(safeGet(s, "label"));
+      if (!value || !label) return undefined;
+      return { title: `${value} ${label}` };
+    });
+    return { heading, items: stats };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// social-proof (nicaragua-projekt)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "social-proof",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const paragraphs = safeArray(safeGet(props, "body.paragraphs"), (p) => {
+      const text = safeString(p);
+      if (!text) return undefined;
+      return { title: text };
+    });
+    const note = safeString(safeGet(props, "registrationNote"));
+    const items = [...(paragraphs ?? [])];
+    if (note) items.push({ title: note });
+    return { heading, items: items.length > 0 ? items : undefined };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// donation-use (nicaragua-projekt)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "donation-use",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const cards = safeArray(safeGet(props, "body.cards"), (card) => {
+      const number = safeString(safeGet(card, "number"));
+      const title = safeString(safeGet(card, "title"));
+      if (!title) return undefined;
+      return { title: number ? `${number}. ${title}` : title };
+    });
+    return { heading, items: cards };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// women (nicaragua-projekt)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "women",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const paragraphs = safeArray(safeGet(props, "body.paragraphs"), (p) => {
+      const text = safeString(p);
+      if (!text) return undefined;
+      return { title: text };
+    });
+    return { heading, items: paragraphs };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// transparency (nicaragua-projekt)
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "transparency",
+  extract(props) {
+    const rawHeading = safeGet(props, "header.heading");
+    let heading: string | undefined;
+    if (Array.isArray(rawHeading)) {
+      heading = rawHeading
+        .map((h: unknown) => {
+          if (h && typeof h === "object") {
+            const text = (h as Record<string, unknown>)["text"];
+            return typeof text === "string" ? text : "";
+          }
+          return "";
+        })
+        .filter(Boolean)
+        .join(" ");
+    } else {
+      heading = safeString(rawHeading);
+    }
+    const note = safeString(safeGet(props, "body.note"));
+    const items = safeArray(safeGet(props, "body.items"), (item) => {
+      const text = safeString(safeGet(item, "text"));
+      if (!text) return undefined;
+      return { title: text };
+    });
+    const reportLink = safeString(safeGet(props, "reportLinkLabel"));
+    const allItems = [...(items ?? [])];
+    if (note) allItems.unshift({ title: note });
+    if (reportLink) allItems.push({ title: reportLink });
+    return { heading: heading || undefined, items: allItems.length > 0 ? allItems : undefined };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// people (nicaragua-projekt, warpgogol-com) — extracts heading from header;
+// people content itself is sourced from business/people enrichment, not block props.
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "people",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    return { heading };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// video-section (warpgogol-com) — extracts heading and lead from header.
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "video-section",
+  extract(props) {
+    const heading = safeString(safeGet(props, "header.heading"));
+    const lead = safeString(safeGet(props, "header.subheading"));
+    return { heading, lead };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// donation-card (nicaragua-projekt) — extracts heading from labels.title.
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "donation-card",
+  extract(props) {
+    const heading = safeString(safeGet(props, "labels.title"));
+    return { heading };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// credits (nicaragua-projekt, warpgogol-com) — extracts heading and lead.
+// ---------------------------------------------------------------------------
+BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+  blockType: "credits",
+  extract(props) {
+    const heading = safeString(safeGet(props, "heading"));
+    const lead = safeString(safeGet(props, "lead"));
+    return { heading, lead };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// RFC-0372: Passport-reserved moon no-op extractors. These block types render
+// visual components (passport-header, pulsar, passport-score-grid,
+// passport-provenance, passport-star-map) with no text content to project into
+// the semantic layer. They must be registered so page.blocks.extract.validate
+// does not fail, but they return empty headings.
+// ---------------------------------------------------------------------------
+const PASSPORT_NOOP_TYPES = [
+  "passport-header",
+  "pulsar",
+  "passport-score-grid",
+  "passport-provenance",
+  "passport-star-map",
+] as const;
+
+for (const blockType of PASSPORT_NOOP_TYPES) {
+  BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+    blockType,
+    extract() {
+      return { heading: "" };
+    },
+  });
+}

package/src/share/semantic/breadcrumbs.ts

@@ -0,0 +1,120 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0229] The canonical breadcrumb trail builder — the single source of truth for both the
+  rendered breadcrumbs section and the BreadcrumbList JSON-LD on every page of every site.
+  Framework-agnostic and pure: ancestor discovery is injected via a BreadcrumbAncestorResolver
+  seam so each route source (authored pages, Programmatic Surface) contributes its own hierarchy.
+</purpose>
+<non-goals>
+  <item>Do not read files, the route registry, or the surface artifact — that is the resolver's job.</item>
+  <item>Do not render markup or emit JSON-LD — callers project the trail into both.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0229: initial canonical trail builder + resolver seam.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { SemanticBreadcrumb } from "./models.ts";
+
+/** One crumb in a breadcrumb trail. URLs are absolute so the trail feeds JSON-LD directly. */
+export type BreadcrumbCrumb = SemanticBreadcrumb & { pageId?: string };
+
+/** An ordered breadcrumb trail: Home first, the current page last. */
+export type BreadcrumbTrail = BreadcrumbCrumb[];
+
+/**
+ * The injected ancestor-discovery seam. Returns the ordered ancestors that sit *between* Home and
+ * the current page (exclusive of both), nearest-root first. Each route source implements this over
+ * its own hierarchy (authored: parentPageId chain; Programmatic Surface: the depth/tuple chain).
+ * Non-live ancestors (noindex / redirect / missing) MUST be skipped so the trail stays clickable.
+ */
+export interface BreadcrumbAncestorResolver {
+  resolveAncestors(input: {
+    pageId: string;
+    lang: string;
+    defaultLang: string;
+  }): Promise<BreadcrumbCrumb[]>;
+}
+
+/**
+ * Strip a site-name suffix from an SEO title. Pages often use "Page Name | Site Name" for the
+ * <title>; a breadcrumb should show only the page-name portion.
+ */
+export function stripSiteNameFromTitle(title: string): string {
+  const separatorIndex = title.lastIndexOf(" | ");
+  return separatorIndex > 0 ? title.slice(0, separatorIndex).trim() : title.trim();
+}
+
+/**
+ * The ordered ancestor pageIds of a Programmatic Surface page, derived purely from its synthetic
+ * pageId, nearest-root first and exclusive of the page itself.
+ *
+ * A surface pageId encodes its axis tuple as `<surfaceId>:<v1>:<v2>:…` (and the depth-0 landing as
+ * `<surfaceId>:_root`), so the hierarchy is recoverable without the Blueprint: the depth-0 landing
+ * plus every shallower tuple. Returns `[]` for the root landing and for any non-surface pageId.
+ *
+ * This is the single source of the surface hierarchy shape — shared by the render-time ancestor
+ * resolver (which maps these ids to live crumbs) and `breadcrumb.trail.validate` (which checks the
+ * ancestors resolve to routes). Keep both on this one function so they cannot drift.
+ */
+export function surfaceAncestorPageIds(pageId: string): string[] {
+  const parts = pageId.split(":");
+  if (parts.length < 2) return [];
+  const surfaceId = parts[0]!;
+  const values = parts.slice(1);
+  // The depth-0 landing (`<surfaceId>:_root`) has no ancestors between it and Home.
+  if (values.length === 1 && values[0] === "_root") return [];
+
+  const ids: string[] = [`${surfaceId}:_root`];
+  for (let depth = 1; depth < values.length; depth += 1) {
+    ids.push(`${surfaceId}:${values.slice(0, depth).join(":")}`);
+  }
+  return ids;
+}
+
+/** Normalize a URL for dedupe: drop a trailing slash (but keep a bare-root "/"). */
+function dedupeKey(url: string): string {
+  if (url === "/") return "/";
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * Assemble the canonical breadcrumb trail for one page:
+ *
+ *   [ Home, …live ancestors (root-first)…, current page ]
+ *
+ * The same trail is projected into the visible breadcrumbs section AND the BreadcrumbList JSON-LD,
+ * so the two can never drift. The home page itself yields a single-node trail (Home === self), which
+ * callers suppress per schema.org guidance.
+ */
+export async function buildBreadcrumbTrail(input: {
+  pageId: string;
+  pageTitle: string;
+  selfUrl: string;
+  homeLabel: string;
+  homeUrl: string;
+  lang: string;
+  defaultLang: string;
+  resolver: BreadcrumbAncestorResolver;
+}): Promise<BreadcrumbTrail> {
+  const { pageId, pageTitle, selfUrl, homeLabel, homeUrl, lang, defaultLang, resolver } = input;
+
+  const ancestors = await resolver.resolveAncestors({ pageId, lang, defaultLang });
+
+  const home: BreadcrumbCrumb = { name: homeLabel, url: homeUrl };
+  const self: BreadcrumbCrumb = { name: stripSiteNameFromTitle(pageTitle), url: selfUrl, pageId };
+
+  const trail: BreadcrumbTrail = [home];
+  const seen = new Set<string>([dedupeKey(homeUrl), dedupeKey(selfUrl)]);
+  for (const crumb of ancestors) {
+    const key = dedupeKey(crumb.url);
+    // Drop ancestors that collapse onto Home or self, or repeat an earlier ancestor.
+    if (seen.has(key) || !crumb.name.trim()) continue;
+    seen.add(key);
+    trail.push({ ...crumb, name: stripSiteNameFromTitle(crumb.name) });
+  }
+  trail.push(self);
+  return trail;
+}