@sarimarcus/content-sites-core 0.13.0 → 0.14.0

package/dist/schema/types.d.ts

@@ -0,0 +1,77 @@
+/** A JSON-LD node as assembled. `undefined` values are dropped when the graph is serialised. */
+export type JsonLdNode = Record<string, any>;
+/** One `{ type, data }` entry a page hands to its StructuredData component. */
+export interface SchemaEntry<T extends string = string> {
+    type: T;
+    data: Record<string, any>;
+}
+export interface OpeningHoursSpecification {
+    '@type': 'OpeningHoursSpecification';
+    dayOfWeek: string | string[];
+    opens: string;
+    closes: string;
+}
+export interface IdRef {
+    '@id': string;
+}
+/** An author record as the site stores it; only these fields reach JSON-LD. */
+export interface SchemaAuthorProfile {
+    name: string;
+    slug?: string;
+    photo?: string;
+    socialLinks?: string[];
+}
+export interface ResolvedAuthor {
+    id: string;
+    name: string;
+    url: string;
+    image?: string;
+    sameAs?: string[];
+}
+/** Path segment per entity kind, e.g. `{ hotel: 'lodges' }`. A kind not listed uses its own name. */
+export type RouteMap = Partial<Record<string, string>>;
+export interface SchemaContextInput {
+    /** Site origin, with or without a trailing slash. */
+    siteUrl: string;
+    /** Base path without a trailing slash (`''` at the root). */
+    basePath: string;
+    /** The page's own pathname (`Astro.url.pathname`). */
+    pagePath: string;
+    /** Whether a file exists under the site's `public/` (path with a leading slash). Defaults to "no". */
+    fileExists?: (publicPath: string) => boolean;
+    /** An image path containing this marker is already an OG image. */
+    ogImageMarker?: string;
+    /** Author profile by display name. */
+    findAuthor?: (name: string) => SchemaAuthorProfile | undefined;
+    /** Markdown → plain text, for JSON-LD string values. */
+    plainText?: (markdown: string) => string;
+    /** `publisher` for a content item, given its author. Defaults to the Organization. */
+    publisher?: (authorName: string | undefined, ctx: SchemaContext) => IdRef;
+    /** Route segments per entity kind. */
+    routes?: RouteMap;
+    /** Clock for the future-date clamp and `defaultToNow`. */
+    now?: () => Date;
+}
+export interface SchemaContext {
+    siteUrl: string;
+    basePath: string;
+    siteBaseUrl: string;
+    pageUrl: string;
+    orgId: string;
+    websiteId: string;
+    /** `${siteUrl}${basePath}${path}` for a root-relative path. */
+    abs(path: string): string;
+    /** A root-relative path made absolute; an `http…` value passes through. */
+    absOrHttp(path: string): string;
+    /** Item URL for an entity kind: `${siteUrl}${basePath}/${segment}/${slug}`. */
+    route(kind: string, slug: string): string;
+    fileExists(publicPath: string): boolean;
+    resolveImageUrl(imagePath: string | undefined, slug?: string): string | undefined;
+    resolveAuthor(authorName: string | undefined): ResolvedAuthor | null;
+    formatDate(dateStr: string | undefined, defaultToNow?: boolean): string | undefined;
+    plainText(markdown: string): string;
+    publisherFor(authorName: string | undefined): IdRef;
+}
+/** Builds the node(s) for one schema entry; `null` emits nothing. */
+export type SchemaBuilder = (data: Record<string, any>, ctx: SchemaContext) => JsonLdNode | JsonLdNode[] | null;
+export type SchemaBuilders = Record<string, SchemaBuilder>;

package/dist/schema/types.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/values.d.ts

@@ -0,0 +1,42 @@
+import type { JsonLdNode } from './types.ts';
+/** First integer in a price string; any "free" reads as 0; null when there is no number. */
+export declare function parsePriceFromString(priceStr: string | undefined): number | null;
+/** Street and number only: drops postal code, city and country, and a second part that is a district or postcode. */
+export declare function cleanStreetAddress(fullAddress: string | undefined): string;
+/** A €-symbol range (`€`…`€€€€`) from a price string, inferred from `priceFrom` when given. */
+export declare function normalizePriceRange(priceStr: string | undefined, priceFrom?: number): string;
+/** A hotel range as `€120-€200` (from `120-200€`), else `€€€`. */
+export declare function normalizeHotelPriceRange(priceStr: string | undefined): string;
+/** `postalCode`, else the first 5-digit run in `address`. */
+export declare function postalCodeOf(data: {
+    postalCode?: string;
+    address?: string;
+}): string | undefined;
+/** How an entity's PostalAddress is filled: fixed city values or per-item fields. */
+export interface AddressPolicy {
+    locality(data: Record<string, any>): string | undefined;
+    region(data: Record<string, any>): string | undefined;
+    country(data: Record<string, any>): string | undefined;
+    /** Postal code used when the item has none. */
+    postalFallback?: string;
+    /** Drop an empty street (`""`) instead of emitting it. */
+    omitEmptyStreet?: boolean;
+}
+/** Address read from each item's own `city`, `region` and `country`; empty values are dropped. */
+export declare function dataAddressPolicy(): AddressPolicy;
+export interface PostalAddressParts {
+    /** Raw address to clean into `streetAddress`. Absent: no street key. */
+    street?: string;
+    /** Postal code before the policy fallback. Absent: no postal key. */
+    postalCode?: string;
+}
+/** A PostalAddress in the fixed key order: street, locality, region, postal code, country. */
+export declare function postalAddress(policy: AddressPolicy, data: Record<string, any>, parts?: PostalAddressParts): JsonLdNode;
+export declare function geoCoordinates(coordinates: {
+    lat: number;
+    lng: number;
+} | undefined): JsonLdNode | undefined;
+export declare function aggregateRating(data: {
+    rating?: number;
+    ratingCount?: number;
+}): JsonLdNode | undefined;

package/dist/schema/values.js

@@ -0,0 +1,86 @@
+/** First integer in a price string; any "free" reads as 0; null when there is no number. */
+export function parsePriceFromString(priceStr) {
+    if (!priceStr)
+        return null;
+    if (priceStr.toLowerCase().includes('free'))
+        return 0;
+    const match = priceStr.match(/(\d+)/);
+    return match ? parseFloat(match[1]) : null;
+}
+/** Street and number only: drops postal code, city and country, and a second part that is a district or postcode. */
+export function cleanStreetAddress(fullAddress) {
+    if (!fullAddress)
+        return '';
+    const parts = fullAddress.split(',').map((p) => p.trim());
+    const streetName = parts[0];
+    if (parts.length < 2)
+        return streetName;
+    const cleanedNumber = parts[1].replace(/º\s*/g, '').trim();
+    const isNeighbourhoodOrPostal = /^\d{5}/.test(cleanedNumber) || /^[A-ZÁÉÍÓÚÜÑ][a-záéíóúüñ]/.test(cleanedNumber);
+    return isNeighbourhoodOrPostal || !cleanedNumber ? streetName : `${streetName}, ${cleanedNumber}`;
+}
+/** A €-symbol range (`€`…`€€€€`) from a price string, inferred from `priceFrom` when given. */
+export function normalizePriceRange(priceStr, priceFrom) {
+    if (!priceStr)
+        return '€€';
+    if (/^€+$/.test(priceStr))
+        return priceStr;
+    const price = priceFrom || parsePriceFromString(priceStr) || 10;
+    if (price < 10)
+        return '€';
+    if (price < 20)
+        return '€€';
+    if (price < 40)
+        return '€€€';
+    return '€€€€';
+}
+/** A hotel range as `€120-€200` (from `120-200€`), else `€€€`. */
+export function normalizeHotelPriceRange(priceStr) {
+    if (!priceStr)
+        return '€€€';
+    if (/^€\d+-€\d+$/.test(priceStr))
+        return priceStr;
+    const match = priceStr.match(/(\d+)-(\d+)€?/);
+    if (match)
+        return `€${match[1]}-€${match[2]}`;
+    return '€€€';
+}
+/** `postalCode`, else the first 5-digit run in `address`. */
+export function postalCodeOf(data) {
+    return data.postalCode || data.address?.match(/(\d{5})/)?.[1];
+}
+/** Address read from each item's own `city`, `region` and `country`; empty values are dropped. */
+export function dataAddressPolicy() {
+    return {
+        locality: (d) => d.city || undefined,
+        region: (d) => d.region || undefined,
+        country: (d) => d.country || undefined,
+        omitEmptyStreet: true,
+    };
+}
+/** A PostalAddress in the fixed key order: street, locality, region, postal code, country. */
+export function postalAddress(policy, data, parts = {}) {
+    const node = { '@type': 'PostalAddress' };
+    if ('street' in parts) {
+        const street = cleanStreetAddress(parts.street);
+        node.streetAddress = policy.omitEmptyStreet ? street || undefined : street;
+    }
+    node.addressLocality = policy.locality(data);
+    node.addressRegion = policy.region(data);
+    if ('postalCode' in parts)
+        node.postalCode = parts.postalCode || policy.postalFallback;
+    node.addressCountry = policy.country(data);
+    return node;
+}
+export function geoCoordinates(coordinates) {
+    return coordinates ? { '@type': 'GeoCoordinates', latitude: coordinates.lat, longitude: coordinates.lng } : undefined;
+}
+export function aggregateRating(data) {
+    return data.rating ? {
+        '@type': 'AggregateRating',
+        ratingValue: data.rating,
+        bestRating: 5,
+        worstRating: 1,
+        reviewCount: data.ratingCount ?? 1,
+    } : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -57,6 +57,10 @@
     "./types": {
       "types": "./dist/types/index.d.ts",
       "default": "./dist/types/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "default": "./dist/schema/index.js"
     }
   },
   "dependencies": {

package/src/schema/context.ts

@@ -0,0 +1,96 @@
+import { normalizeSiteUrl, toAbsoluteSiteUrl } from '../url/index.ts';
+import { slugify } from '../text/index.ts';
+import type { JsonLdNode, ResolvedAuthor, SchemaContext, SchemaContextInput } from './types.ts';
+
+/** The site root with a trailing slash (either form) collapses to the bare base URL. */
+export function normalizeHomepageUrl(url: string, siteUrl: string, siteBaseUrl: string): string {
+  return (url === `${siteUrl}/` || url === `${siteBaseUrl}/`) ? siteBaseUrl : url;
+}
+
+/** Every string in a JSON-LD value through `normalizeSiteUrl` + `normalizeHomepageUrl`, keys in their order. */
+export function normalizeStructuredDataUrls<T>(value: T, siteUrl: string, basePath: string): T {
+  const siteBaseUrl = `${siteUrl}${basePath || ''}`;
+  const walk = (v: unknown): unknown => {
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object') {
+      return Object.fromEntries(Object.entries(v).map(([key, entryValue]) => [key, walk(entryValue)]));
+    }
+    if (typeof v === 'string') return normalizeHomepageUrl(normalizeSiteUrl(v, siteUrl, basePath), siteUrl, siteBaseUrl);
+    return v;
+  };
+  return walk(value) as T;
+}
+
+/** ISO 8601, never in the future: a date-only value becomes UTC midnight, a future one is clamped to `now`. */
+export function formatSchemaDate(dateStr: string | undefined, defaultToNow = false, now: () => Date = () => new Date()): string | undefined {
+  if (!dateStr) return defaultToNow ? now().toISOString() : undefined;
+  const isoDate = dateStr.includes('T') ? dateStr : `${dateStr}T00:00:00Z`;
+  const current = now();
+  if (new Date(isoDate) > current) return current.toISOString();
+  return isoDate;
+}
+
+export function createPersonSchema(author: ResolvedAuthor): JsonLdNode {
+  return {
+    '@type': 'Person',
+    '@id': author.id,
+    name: author.name,
+    url: author.url,
+    image: author.image,
+    sameAs: author.sameAs,
+  };
+}
+
+/** The node, preceded by its author's Person node when the author resolves. */
+export function withAuthorPersonSchema(ctx: SchemaContext, node: JsonLdNode, authorName: string | undefined): JsonLdNode | JsonLdNode[] {
+  const author = ctx.resolveAuthor(authorName);
+  return author ? [createPersonSchema(author), node] : node;
+}
+
+export function createSchemaContext(input: SchemaContextInput): SchemaContext {
+  const siteUrl = input.siteUrl.replace(/\/$/, '');
+  const basePath = input.basePath;
+  const siteBaseUrl = `${siteUrl}${basePath || ''}`;
+  const fileExists = input.fileExists ?? (() => false);
+  const marker = input.ogImageMarker ?? '/og/';
+  const routes = input.routes ?? {};
+  const now = input.now ?? (() => new Date());
+
+  const ctx: SchemaContext = {
+    siteUrl,
+    basePath,
+    siteBaseUrl,
+    pageUrl: toAbsoluteSiteUrl(input.pagePath, siteUrl, basePath),
+    orgId: `${siteBaseUrl}#organization`,
+    websiteId: `${siteBaseUrl}#website`,
+    abs: (path) => `${siteUrl}${basePath}${path}`,
+    absOrHttp: (path) => (path.startsWith('http') ? path : `${siteUrl}${basePath}${path}`),
+    route: (kind, slug) => `${siteUrl}${basePath}/${routes[kind] ?? kind}/${slug}`,
+    fileExists,
+    // /images/{type}/{name}.webp → /images/og/{type}/{name}.jpg, falling back to the slug's jpg (SLA-2817);
+    // omitted rather than pointing at a file that is not there.
+    resolveImageUrl(imagePath, slug) {
+      if (!imagePath) return undefined;
+      if (imagePath.startsWith('http')) return imagePath;
+      const ogPath = imagePath.includes(marker)
+        ? imagePath
+        : imagePath.replace(/^\/images\//, '/images/og/').replace(/\.(webp|png|jpeg)$/, '.jpg');
+      const slugOgPath = slug ? ogPath.replace(/[^/]+$/, `${slug}.jpg`) : undefined;
+      const resolved = [ogPath, slugOgPath].find((p) => p && fileExists(p));
+      return resolved ? `${siteUrl}${basePath}${resolved}` : undefined;
+    },
+    resolveAuthor(authorName) {
+      if (!authorName) return null;
+      const profile = input.findAuthor?.(authorName);
+      const url = `${siteUrl}${basePath}/author/${profile?.slug || slugify(authorName)}`;
+      const image = profile?.photo
+        ? (profile.photo.startsWith('http') ? profile.photo : `${siteUrl}${basePath}${profile.photo}`)
+        : undefined;
+      return { id: `${url}#person`, name: authorName, url, image, sameAs: profile?.socialLinks };
+    },
+    formatDate: (dateStr, defaultToNow = false) => formatSchemaDate(dateStr, defaultToNow, now),
+    plainText: input.plainText ?? ((markdown) => markdown),
+    publisherFor: (authorName) => (input.publisher ? input.publisher(authorName, ctx) : { '@id': ctx.orgId }),
+  };
+  return ctx;
+}

package/src/schema/events.ts

@@ -0,0 +1,175 @@
+import { createPersonSchema } from './context.ts';
+import { geoCoordinates, postalAddress, type AddressPolicy } from './values.ts';
+import type { JsonLdNode, SchemaBuilder, SchemaContext } from './types.ts';
+
+/** Where events take place and who runs them; every value is the site's. */
+export interface EventPolicy {
+  address: AddressPolicy;
+  /** Place name when the item has no `location`. Absent: such an item gets no `location`. */
+  defaultLocationName?: string;
+  /** Add `geo` from `coordinates` to the Place. */
+  geo?: boolean;
+  organizer(data: Record<string, any>): JsonLdNode;
+  performer(data: Record<string, any>): JsonLdNode | undefined;
+  currency?: string;
+}
+
+function eventPrice(data: Record<string, any>): { isFree: boolean | undefined; price: number | null } {
+  const isFree = data.tags?.includes('free') || data.price?.toLowerCase().includes('free');
+  const priceMatch = data.price?.match(/(\d+)/);
+  return { isFree, price: isFree ? 0 : (priceMatch ? parseFloat(priceMatch[1]) : null) };
+}
+
+// Offers open three months before the start date.
+function validFrom(startDate: string | undefined): string | null {
+  if (!startDate) return null;
+  const from = new Date(new Date(startDate));
+  from.setMonth(from.getMonth() - 3);
+  return from.toISOString();
+}
+
+function eventLocation(policy: EventPolicy, data: Record<string, any>): JsonLdNode | undefined {
+  const name = data.location || policy.defaultLocationName;
+  if (!name) return undefined;
+  const geo = policy.geo ? geoCoordinates(data.coordinates) : undefined;
+  return {
+    '@type': 'Place',
+    name,
+    address: postalAddress(policy.address, data),
+    ...(geo && { geo }),
+  };
+}
+
+const EVENT_STATUS = (rescheduled: unknown) => (rescheduled ? 'https://schema.org/EventRescheduled' : 'https://schema.org/EventScheduled');
+const OFFLINE = 'https://schema.org/OfflineEventAttendanceMode';
+
+export interface EventOptions extends EventPolicy {
+  /** Map `data.offers[]` to Offers when present (else one Offer from `price`). */
+  offersArray?: boolean;
+  /** Emit the Event node; when false only the companion Article is emitted. Default: always. */
+  emitEvent?: (data: Record<string, any>) => boolean;
+  articleSection?: string;
+  inLanguage?: string;
+}
+
+/** Event at route `event`, its author's Person first, and a companion Article (SLA-357). */
+export function eventBuilder(options: EventOptions): SchemaBuilder {
+  const { offersArray = false, emitEvent = () => true, articleSection = 'Events', inLanguage = 'en', currency = 'EUR' } = options;
+  return (data, ctx) => {
+    const { isFree, price } = eventPrice(data);
+    const from = validFrom(data.startDate);
+    const pageRoute = ctx.route('event', data.slug);
+    const singleOffer = price !== null ? {
+      '@type': 'Offer',
+      price,
+      priceCurrency: currency,
+      availability: 'https://schema.org/InStock',
+      url: data.officialWebsite || pageRoute,
+      validFrom: from,
+    } : undefined;
+
+    const event: JsonLdNode = {
+      '@type': 'Event',
+      name: data.name,
+      description: data.description,
+      image: ctx.resolveImageUrl(data.image, data.slug),
+      startDate: data.startDate || undefined,
+      endDate: data.endDate || undefined,
+      previousStartDate: data.previousStartDate || undefined,
+      eventStatus: EVENT_STATUS(data.previousStartDate),
+      eventAttendanceMode: OFFLINE,
+      isAccessibleForFree: isFree,
+      location: eventLocation(options, data),
+      organizer: options.organizer(data),
+      performer: options.performer(data),
+      offers: offersArray && (data.offers?.length ?? 0) > 0
+        ? data.offers.map((o: { price: number; priceCurrency?: string; url?: string; availability?: string }) => ({
+          '@type': 'Offer',
+          price: o.price,
+          priceCurrency: o.priceCurrency || currency,
+          availability: `https://schema.org/${o.availability || 'InStock'}`,
+          url: o.url || data.officialWebsite || pageRoute,
+          validFrom: from,
+        }))
+        : singleOffer,
+      mainEntityOfPage: { '@id': ctx.pageUrl },
+      url: pageRoute,
+    };
+
+    const author = ctx.resolveAuthor(data.author);
+    const article: JsonLdNode = {
+      '@type': 'Article',
+      '@id': `${pageRoute}#article`,
+      headline: data.name,
+      description: data.description,
+      image: ctx.resolveImageUrl(data.image, data.slug),
+      datePublished: ctx.formatDate(data.datePublished || data.dateModified),
+      dateModified: ctx.formatDate(data.dateModified),
+      author: author ? { '@id': author.id } : undefined,
+      publisher: ctx.publisherFor(data.author),
+      mainEntityOfPage: { '@id': ctx.pageUrl },
+      articleSection,
+      inLanguage,
+    };
+
+    const nodes = emitEvent(data) ? [event, article] : [article];
+    return author ? [createPersonSchema(author), ...nodes] : nodes;
+  };
+}
+
+export interface EventItemListOptions extends EventPolicy {
+  /** Organizer of a listed item (may differ from the event page's). */
+  itemOrganizer(item: Record<string, any>): JsonLdNode;
+  /** A listed item is an Event only when this holds (else a WebPage). Default: it has a `startDate`. */
+  isEvent?: (item: Record<string, any>) => boolean;
+}
+
+/** ItemList of events, each linked at its `url`; an item that cannot be a valid Event becomes a WebPage. */
+export function eventItemListBuilder(options: EventItemListOptions): SchemaBuilder {
+  const { isEvent = (item) => Boolean(item.startDate), currency = 'EUR' } = options;
+  return (data, ctx: SchemaContext) => ({
+    '@type': 'ItemList',
+    name: data.name,
+    numberOfItems: data.items?.length || 0,
+    itemListElement: data.items?.map((item: any) => {
+      const { isFree, price } = eventPrice(item);
+      const from = validFrom(item.startDate);
+      const performer = options.performer(item);
+      if (!isEvent(item)) {
+        return {
+          '@type': 'ListItem',
+          position: item.position,
+          item: { '@type': 'WebPage', name: item.name, description: item.description, url: ctx.abs(item.url) },
+        };
+      }
+      return {
+        '@type': 'ListItem',
+        position: item.position,
+        item: {
+          '@type': 'Event',
+          name: item.name,
+          description: item.description,
+          image: ctx.resolveImageUrl(item.image, item.slug),
+          url: ctx.abs(item.url),
+          startDate: item.startDate,
+          endDate: item.endDate,
+          previousStartDate: item.previousStartDate || undefined,
+          eventStatus: EVENT_STATUS(item.previousStartDate),
+          eventAttendanceMode: OFFLINE,
+          isAccessibleForFree: isFree,
+          location: eventLocation(options, item),
+          organizer: options.itemOrganizer(item),
+          performer,
+          offers: price !== null ? {
+            '@type': 'Offer',
+            price,
+            priceCurrency: currency,
+            availability: 'https://schema.org/InStock',
+            url: item.officialWebsite || ctx.route('event', item.slug),
+            validFrom: from,
+          } : undefined,
+        },
+      };
+    }),
+  });
+}

package/src/schema/graph.ts

@@ -0,0 +1,92 @@
+import { normalizeSiteUrl } from '../url/index.ts';
+import { normalizeHomepageUrl, normalizeStructuredDataUrls } from './context.ts';
+import type { JsonLdNode, SchemaBuilders, SchemaContext, SchemaEntry } from './types.ts';
+
+export interface BreadcrumbInput {
+  name: string;
+  url: string;
+}
+
+export function buildBreadcrumbList(ctx: SchemaContext, breadcrumbs: BreadcrumbInput[]): JsonLdNode {
+  return {
+    '@type': 'BreadcrumbList',
+    '@id': `${ctx.pageUrl}#breadcrumb`,
+    itemListElement: breadcrumbs.map((item, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: item.name,
+      item: normalizeHomepageUrl(normalizeSiteUrl(item.url, ctx.siteUrl, ctx.basePath), ctx.siteUrl, ctx.siteBaseUrl),
+    })),
+  };
+}
+
+export interface PageInput {
+  entries: SchemaEntry[];
+  breadcrumbs?: BreadcrumbInput[];
+  pageTitle?: string;
+  pageDescription?: string;
+  datePublished?: string;
+  dateModified?: string;
+}
+
+/** The page's WebPage node: name/description/dates fall back to the first entries that carry them. */
+export function buildWebPageNode(ctx: SchemaContext, page: PageInput, inLanguage = 'en'): JsonLdNode {
+  const { entries } = page;
+  return {
+    '@type': 'WebPage',
+    '@id': ctx.pageUrl,
+    url: ctx.pageUrl,
+    name: page.pageTitle || entries[0]?.data.name || entries[0]?.data.headline,
+    description: page.pageDescription || entries[0]?.data.description,
+    inLanguage,
+    datePublished: ctx.formatDate(page.datePublished
+      || entries.find((s) => s.data.datePublished)?.data.datePublished
+      || entries.find((s) => s.data.dateModified)?.data.dateModified),
+    dateModified: ctx.formatDate(page.dateModified || (() => {
+      const s = entries.find((e) => e.data.dateModified || e.data.datePublished);
+      return s?.data.dateModified || s?.data.datePublished;
+    })()),
+    isPartOf: { '@id': ctx.websiteId },
+    ...(page.breadcrumbs ? { breadcrumb: { '@id': `${ctx.pageUrl}#breadcrumb` } } : {}),
+  };
+}
+
+export interface AssembleOptions extends PageInput {
+  /** The site's Organization node (`@id` = `ctx.orgId`). */
+  organization: JsonLdNode;
+  /** The site's WebSite node (`@id` = `ctx.websiteId`). */
+  website: JsonLdNode;
+  builders: SchemaBuilders;
+  inLanguage?: string;
+  /** Runs after the base nodes and breadcrumb, before any entry. */
+  beforeEntries?: (graph: JsonLdNode[]) => void;
+  /** Runs once every entry is in the graph. */
+  afterEntries?: (graph: JsonLdNode[]) => void;
+}
+
+/**
+ * The page graph in emission order: Organization, WebSite, WebPage, BreadcrumbList (when breadcrumbs are given),
+ * then each entry's node(s) in call order. A type with no builder, or a builder returning null, emits nothing.
+ */
+export function assembleGraph(ctx: SchemaContext, options: AssembleOptions): JsonLdNode[] {
+  const graph: JsonLdNode[] = [options.organization, options.website, buildWebPageNode(ctx, options, options.inLanguage)];
+  if (options.breadcrumbs) graph.push(buildBreadcrumbList(ctx, options.breadcrumbs));
+  options.beforeEntries?.(graph);
+  for (const { type, data } of options.entries) {
+    const builder = options.builders[type];
+    const result = builder ? builder(data, ctx) : null;
+    if (result === null) continue;
+    if (Array.isArray(result)) graph.push(...result);
+    else graph.push(result);
+  }
+  options.afterEntries?.(graph);
+  return graph;
+}
+
+/** The serialisable JSON-LD document: `@context` plus the graph with every URL normalised. */
+export function finalizeGraph(ctx: SchemaContext, graph: JsonLdNode[]): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@graph': normalizeStructuredDataUrls(graph, ctx.siteUrl, ctx.basePath),
+  };
+}