@apleasantview/eleventy-plugin-baseline 0.1.0-next.41 → 0.1.0-next.42

package/core/page-context/build.js

@@ -1,9 +1,90 @@
 import { setEntry } from '../registry.js';
 import { slugify } from '../utils/slugify.js';
+import { titleCaseSlug } from '../utils/title-case-slug.js';
 import { uniqueBy } from '../utils/unique-by.js';
 import { resolveField } from '../utils/resolve-field.js';
 import { extractFirstParagraph, normalizeCanonical } from './seo-helpers.js';
 
+/**
+ * Apply a title template, replacing tokens with resolved values. Tokens:
+ * `%s` (page title), `%siteTitle%`, `%tagline%`. One regex with the longer
+ * tokens first so `%s` does not eat the `%s` inside `%siteTitle%`.
+ * Replacement is literal: an empty value leaves the surrounding template
+ * text as the author wrote it.
+ *
+ * @param {string} template
+ * @param {{ title?: string, siteTitle?: string, tagline?: string }} tokens
+ * @returns {string}
+ */
+export function applyTitleTemplate(template, { title, siteTitle, tagline }) {
+	const values = { '%s': title, '%siteTitle%': siteTitle, '%tagline%': tagline };
+	return template.replace(/%siteTitle%|%tagline%|%s/g, (token) => values[token] ?? '');
+}
+
+/**
+ * Resolve the final `<title>` text.
+ *
+ * Precedence: per-page bare opt-out (`titleTemplate: null`) → per-page
+ * template → titleless home (baked-in `siteTitle` + `tagline`) → global
+ * template → default (`page – site`, guarded so a page named like the site
+ * stays bare). With no template set anywhere this reproduces the legacy
+ * separator composition exactly.
+ *
+ * @returns {string}
+ */
+export function resolveTitle({ data, isHome, pageTitle, siteTitle, tagline, separator, globalTemplate }) {
+	const pageTemplate = data?.titleTemplate;
+	const base = pageTitle ?? siteTitle;
+	const tokens = { title: pageTitle, siteTitle, tagline };
+
+	if (pageTemplate === null) return base;
+	if (typeof pageTemplate === 'string') return applyTitleTemplate(pageTemplate, tokens);
+	if (isHome && !data?.seo?.title) return tagline ? `${siteTitle}${separator}${tagline}` : base;
+	if (typeof globalTemplate === 'string') return applyTitleTemplate(globalTemplate, tokens);
+	if (!isHome && pageTitle && siteTitle && pageTitle !== siteTitle) return `${pageTitle}${separator}${siteTitle}`;
+	return base;
+}
+
+/**
+ * Resolve a breadcrumb trail from the page's ancestor section path.
+ *
+ * `section` is the containing-directory chain, not a path that ends at the
+ * page: a leaf (/docs/module/head/) and its section index (/docs/module/)
+ * share the same section. The tell is the URL. When the page IS its section
+ * index, the last segment names it (relabelled with the page title); otherwise
+ * the page is a leaf and gets appended as its own crumb. The final crumb keeps
+ * its URL so the schema renderer can wire its @id, and is flagged `current` so
+ * the visible renderer knows not to link it. In multilang, a deliberately
+ * non-default language prefixes every URL with `/{lang}`.
+ *
+ * @param {{ section?: string[], url?: string, title?: string, lang?: string, isDefaultLang?: boolean }} input
+ * @returns {Array<{ label: string, url: string, current?: boolean }>}
+ */
+export function buildBreadcrumbs({ section = [], url, title, lang, isDefaultLang } = {}) {
+	if (!section?.length || !url) return [];
+
+	// Only a deliberately non-default language prefixes the path; absence
+	// (no multilang) keeps the root, never a spurious `/{lang}`.
+	const base = isDefaultLang === false && lang ? `/${lang}` : '';
+
+	const crumbs = [{ label: 'Home', url: `${base}/` }];
+	let acc = base;
+	for (const seg of section) {
+		acc += `/${seg}`;
+		crumbs.push({ label: titleCaseSlug(seg), url: `${acc}/` });
+	}
+
+	const sectionUrl = `${base}/${section.join('/')}/`;
+	if (url === sectionUrl) {
+		crumbs[crumbs.length - 1].label = title ?? crumbs[crumbs.length - 1].label;
+	} else {
+		crumbs.push({ label: title ?? titleCaseSlug(section[section.length - 1]), url });
+	}
+
+	crumbs[crumbs.length - 1].current = true;
+	return crumbs;
+}
+
 /**
  * Page context — builder factory
  *
@@ -56,6 +137,8 @@ export function createPageContext({ scope, slugIndex, settings, runtime, options
 			outputPath: pageInput?.outputPath,
 			lang: pageInput?.lang,
 			locale: pageInput?.locale,
+			translationKey: pageInput?.translationKey,
+			isDefaultLang: pageInput?.isDefaultLang,
 			sitemap: pageInput?.sitemap
 		};
 	}
@@ -90,7 +173,14 @@ export function createPageContext({ scope, slugIndex, settings, runtime, options
 			slug: slugify(rawSlug),
 			section,
 			type: data?.type,
-			head: data?.head
+			head: data?.head,
+			breadcrumbs: buildBreadcrumbs({
+				section,
+				url: data?.page?.url,
+				title: data?.seo?.title ?? data?.title,
+				lang: data?.page?.lang,
+				isDefaultLang: data?.page?.isDefaultLang
+			})
 		};
 	}
 
@@ -116,18 +206,6 @@ export function createPageContext({ scope, slugIndex, settings, runtime, options
 		const pageTitle = data?.seo?.title ?? data?.title ?? siteTitle;
 		const pageDescription = data?.seo?.description ?? data?.description ?? data?.excerpt ?? extractFirstParagraph(data);
 
-		function enhance(value) {
-			if (query.isHome && !data?.seo?.title && tagline) {
-				return `${siteTitle}${separator}${tagline}`;
-			}
-
-			if (!query.isHome && pageTitle && siteTitle && pageTitle !== siteTitle) {
-				return `${pageTitle}${separator}${siteTitle}`;
-			}
-
-			return value;
-		}
-
 		// ---- DESCRIPTION ----
 		const description = resolveField({
 			pageValue: pageDescription,
@@ -136,13 +214,16 @@ export function createPageContext({ scope, slugIndex, settings, runtime, options
 		});
 
 		// ---- TITLE ----
-		const base = resolveField({
-			pageValue: pageTitle,
-			siteValue: siteTitle
+		const title = resolveTitle({
+			data,
+			isHome: query.isHome,
+			pageTitle,
+			siteTitle,
+			tagline,
+			separator,
+			globalTemplate: options.head?.titleTemplate
 		});
 
-		const title = enhance(base);
-
 		// ---- CANONICAL ----
 		let canonical;
 
@@ -173,22 +254,38 @@ export function createPageContext({ scope, slugIndex, settings, runtime, options
 		const userHead = userSettings.head ?? {};
 		const pageHead = data?.head ?? {};
 
+		// Keys must distinguish tags that legitimately differ: links by rel + href
+		// (so preconnect and dns-prefetch to one host both survive), metas by their
+		// identifying attribute (name / property / charset / http-equiv) so og:*
+		// property tags are not collapsed. The head driver runs the authoritative
+		// final pass; this just merges settings + front-matter without losing tags.
+		// Links key on rel + href so tags that share a host but differ in rel
+		// (preconnect vs dns-prefetch) are not collapsed. Metas key on their
+		// identifying attribute so two tags with the same key (e.g. a repeated
+		// og:title) collapse to the last, matching the driver's authoritative
+		// pass instead of leaning on uniqueBy's by-shape fallback.
 		const link = uniqueBy([...(userHead.link ?? []), ...(pageHead.link ?? [])], (item) => {
 			if (item?.rel === 'canonical') {
 				try {
-					return normalizeCanonical(item.href, siteUrl);
+					return `canonical|${normalizeCanonical(item.href, siteUrl)}`;
 				} catch {
-					return item?.href;
+					return `canonical|${item?.href}`;
 				}
 			}
-			return item?.href;
+			return item?.href ? `${item.rel ?? ''}|${item.href}` : undefined;
 		});
 
 		const script = uniqueBy([...(userHead.script ?? []), ...(pageHead.script ?? [])], 'src');
 
 		const style = uniqueBy([...(userHead.style ?? []), ...(pageHead.style ?? [])], 'href');
 
-		const meta = uniqueBy([...(userHead.meta ?? []), ...(pageHead.meta ?? [])], 'name');
+		const meta = uniqueBy([...(userHead.meta ?? []), ...(pageHead.meta ?? [])], (item) => {
+			if (item?.charset) return 'charset';
+			if (item?.name) return `name:${item.name}`;
+			if (item?.property) return `prop:${item.property}`;
+			if (item?.['http-equiv']) return `http:${item['http-equiv']}`;
+			return undefined;
+		});
 
 		return {
 			link,
@@ -228,7 +325,7 @@ export function createPageContext({ scope, slugIndex, settings, runtime, options
 		if (inspectionKey) setEntry(scope, inspectionKey, context);
 
 		if (slugIndex && entry.slug && page.url) {
-			const eligible = page.locale?.isDefaultLang === true;
+			const eligible = page.isDefaultLang === true;
 			if (eligible) {
 				slugIndex.set(entry.slug, page.url, page.inputPath);
 			}

package/core/schema.js

@@ -58,6 +58,7 @@ export const settingsSchema = z.object({
 	url: z.string().optional(),
 	noindex: z.boolean().optional(),
 	defaultLanguage: z.string().optional(),
+	defaultLocale: z.string().optional(),
 	languages: z
 		.unknown()
 		.optional()
@@ -84,5 +85,6 @@ export const settingsSchema = z.object({
 			meta: z.array(z.looseObject({})).optional(),
 			style: z.array(z.looseObject({})).optional()
 		})
-		.optional()
+		.optional(),
+	seo: z.looseObject({}).optional()
 });

package/core/seo-graph/adapter.js

@@ -0,0 +1,246 @@
+// Adapter to @jdevalk/seo-graph-core.
+//
+// Translates Baseline's cascade (settings, schema identity, navigator nodes,
+// dates) into seo-graph-core's piece builders, assembles the JSON-LD @graph,
+// and returns it for storage under data._seoGraph.schema. Auto-builds a generic spine
+// (WebSite, Organization/Person, WebPage, Article, BreadcrumbList, image and
+// translation refs); domain shapes ride in untouched via the schema.pieces seam.
+
+import {
+	makeIds,
+	assembleGraph,
+	buildPiece,
+	buildWebSite,
+	buildWebPage,
+	buildArticle,
+	buildBreadcrumbList,
+	buildImageObject
+} from '@jdevalk/seo-graph-core';
+import { resolveDates } from '../dates/index.js';
+import { resolveLocale } from '../locale/index.js';
+import { slugify } from '../utils/slugify.js';
+
+/** Recursively strip null/undefined; `_data/schema.js` uses null as "not set". */
+function dropNulls(value) {
+	if (Array.isArray(value)) {
+		const cleaned = value.map(dropNulls).filter((v) => v !== null && v !== undefined);
+		return cleaned.length ? cleaned : null;
+	}
+	if (value && typeof value === 'object') {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) {
+			const cleaned = dropNulls(v);
+			if (cleaned !== null && cleaned !== undefined) out[k] = cleaned;
+		}
+		return Object.keys(out).length ? out : null;
+	}
+	return value;
+}
+
+/** Stable within-site slug for an Organization @id. */
+function orgSlug(name) {
+	return slugify(name) || 'organization';
+}
+
+/**
+ * Build an ImageObject node, or null when pixel dimensions are unknown. The
+ * two-tier degrade: no node without width+height (the builder throws), and the
+ * OG projection still emits a url-only og:image in that case.
+ *
+ * @param {{ url?: string, width?: number, height?: number, alt?: string } | undefined} image
+ * @param {{ id: string } | { pageUrl: string }} target  Site-wide id (logo) or page primary image.
+ * @param {import('@jdevalk/seo-graph-core').IdFactory} ids
+ * @returns {object | null}
+ */
+function buildImage(image, target, ids) {
+	if (!image?.url || !image.width || !image.height) return null;
+	return buildImageObject(
+		{ ...target, url: image.url, width: image.width, height: image.height, caption: image.alt },
+		ids
+	);
+}
+
+/**
+ * Inline WebPage refs for sibling translations, keyed off a shared
+ * translationKey on the navigator nodes. Emitted as nested entities (carrying
+ * @type) rather than bare @id refs, so they resolve within this page's graph.
+ *
+ * @returns {Array<object>}
+ */
+function buildWorkTranslations(nodes, translationKey, currentUrl, siteRoot, ids) {
+	if (!nodes || !translationKey) return [];
+	const refs = [];
+	for (const n of Object.values(nodes)) {
+		if (n.translationKey !== translationKey || n.url === currentUrl) continue;
+		const absUrl = `${siteRoot}${n.url}`;
+		refs.push({ '@type': 'WebPage', '@id': ids.webPage(absUrl), url: absUrl, inLanguage: n.locale || n.lang });
+	}
+	return refs;
+}
+
+/**
+ * Assemble the resolved JSON-LD @graph for a single page from the cascade.
+ *
+ * Pure function over the full Eleventy `data` bag: reads `data.schema`
+ * (identity + pieces), `data.settings`, `data.page`, and the navigator nodes.
+ * Identity is tidied (drop-null) and stamped; everything in `schema.pieces`
+ * passes through `buildPiece` untouched. Returns the bare `@graph` array.
+ *
+ * @param {Record<string, any>} data  The Eleventy cascade data bag.
+ * @returns {Array<unknown>}
+ */
+export function assembleSchemaGraph(data) {
+	const settings = data.settings;
+	const schema = data.schema;
+	const pageUrl = data.page?.url;
+
+	// Eleventy's dependency-discovery proxy can call this with siblings undefined.
+	if (!settings?.url || !pageUrl) return [];
+
+	const siteUrl = settings.url;
+	const siteRoot = siteUrl.replace(/\/+$/, '');
+	const canonical = `${siteRoot}${pageUrl}`;
+
+	const navigatorNodes = data._navigator?.nodes;
+	const node = navigatorNodes?.[pageUrl];
+
+	const lang = node?.lang || data.page?.lang || data.lang || settings.defaultLanguage;
+	const locale = resolveLocale(node, data, settings, lang);
+	const siteName = settings.languages?.[lang]?.title || settings.title;
+	const multilang = data._baseline?.features?.multilang;
+
+	const personUrl = schema?.person?.url || siteUrl;
+	const ids = makeIds({ siteUrl, personUrl });
+
+	// --- Identity: build only what's configured; tidy null sentinels. ---
+	const orgConfig = schema?.organization ? dropNulls(schema.organization) : null;
+	const personConfig = schema?.person ? dropNulls(schema.person) : null;
+
+	let orgNode = null;
+	let logoNode = null;
+	if (orgConfig) {
+		const { logo, ...rest } = orgConfig;
+		logoNode = buildImage(logo, { id: `${siteRoot}/#logo` }, ids);
+		orgNode = buildPiece({
+			'@type': 'Organization',
+			...rest,
+			'@id': ids.organization(orgSlug(orgConfig.name)),
+			...(logoNode ? { logo: { '@id': logoNode['@id'] }, image: { '@id': logoNode['@id'] } } : {})
+		});
+	}
+
+	let personNode = null;
+	if (personConfig) {
+		personNode = buildPiece({ '@type': 'Person', ...personConfig, '@id': ids.person });
+	}
+
+	// Primary entity: Organization, else Person, else a synthesised floor org so
+	// a zero-config site still emits a valid publisher.
+	let primaryRef;
+	if (orgNode) {
+		primaryRef = { '@id': orgNode['@id'] };
+	} else if (personNode) {
+		primaryRef = { '@id': personNode['@id'] };
+	} else {
+		orgNode = buildPiece(
+			dropNulls({
+				'@type': 'Organization',
+				'@id': ids.organization(orgSlug(settings.title)),
+				name: settings.title,
+				url: siteUrl
+			})
+		);
+		primaryRef = { '@id': orgNode['@id'] };
+	}
+
+	const website = buildWebSite(
+		{
+			url: siteUrl,
+			name: siteName,
+			publisher: primaryRef,
+			inLanguage: multilang && settings.languages ? Object.keys(settings.languages) : undefined
+		},
+		ids
+	);
+
+	const ogImageRaw = data.ogImage ?? data.seo?.ogImage ?? settings.seo?.ogImage;
+	const ogImage = typeof ogImageRaw === 'string' ? { url: ogImageRaw } : ogImageRaw;
+	const primaryImageNode = buildImage(ogImage, { pageUrl: canonical }, ids);
+
+	// Trail is resolved once in page-context, carried onto the graph node by the
+	// prepass (the adapter's only cross-pass channel — _pageContext is not in
+	// scope here). We just absolutise the root-relative URLs. The last crumb's
+	// URL is the page's canonical, so buildBreadcrumbList resolves it to the
+	// WebPage @id.
+	const crumbs = node?.breadcrumbs || [];
+	const breadcrumbNode = crumbs.length
+		? buildBreadcrumbList(
+				{
+					url: canonical,
+					items: crumbs.map((crumb) => ({
+						name: crumb.label,
+						url: crumb.url ? `${siteRoot}${crumb.url}` : canonical
+					}))
+				},
+				ids
+			)
+		: null;
+
+	const translationKey = node?.translationKey || data.page?.translationKey || data.translationKey;
+	const workTranslation = buildWorkTranslations(navigatorNodes, translationKey, pageUrl, siteRoot, ids);
+
+	const dates = resolveDates(data);
+
+	// schema.org keywords from the `topics` front-matter convention; native `tags` untouched.
+	const keywords = data.topics?.length ? data.topics : undefined;
+
+	const webPage = buildWebPage(
+		{
+			url: canonical,
+			name: node?.title || data.title,
+			isPartOf: { '@id': ids.website },
+			description: node?.description || data.description || node?.excerpt,
+			inLanguage: locale,
+			datePublished: dates.datePublished,
+			dateModified: dates.dateModified,
+			breadcrumb: breadcrumbNode ? { '@id': breadcrumbNode['@id'] } : undefined,
+			primaryImage: primaryImageNode ? { '@id': primaryImageNode['@id'] } : undefined,
+			workTranslation: workTranslation.length ? workTranslation : undefined,
+			keywords
+		},
+		ids,
+		data.pageType || 'WebPage'
+	);
+
+	const entryType = data.type || node?.type;
+	const articleNode =
+		entryType === 'article'
+			? buildArticle(
+					{
+						url: canonical,
+						isPartOf: { '@id': ids.webPage(canonical) },
+						author: personNode ? { '@id': personNode['@id'] } : primaryRef,
+						publisher: primaryRef,
+						headline: node?.title || data.title,
+						description: node?.description || data.description || node?.excerpt,
+						inLanguage: locale,
+						datePublished: dates.datePublished,
+						dateModified: dates.dateModified,
+						articleSection: data.sectionLabel,
+						keywords
+					},
+					ids,
+					data.articleType || 'Article'
+				)
+			: null;
+
+	const spine = [website, orgNode, personNode, logoNode, primaryImageNode, webPage, articleNode, breadcrumbNode].filter(
+		Boolean
+	);
+
+	// The extension seam: author-supplied nodes, concat-merged across the cascade,
+	// passed through untouched.
+	const authored = Array.isArray(schema?.pieces) ? schema.pieces.map((p) => buildPiece(p)) : [];
+
+	return assembleGraph([...spine, ...authored])['@graph'];
+}

package/core/seo-graph/build.js

@@ -0,0 +1,87 @@
+import { setEntry } from '../registry.js';
+import { assembleSchemaGraph } from './adapter.js';
+import { buildSocialProjections } from './open-graph.js';
+
+/**
+ * Resolve the canonical URL for the `seo` namespace.
+ *
+ * Strip-all by default: the entire query string and fragment are removed.
+ * Opt-out is a boolean carried at page level (`preserveQueryParams` in
+ * front matter) or site level (`settings.seo.preserveQueryParams`); page-level wins.
+ * The fragment is always stripped regardless.
+ *
+ * Returns `undefined` when the page or site is noindex, when `settings.url`
+ * is missing, or when no resolvable canonical input exists.
+ *
+ * @param {{ seo?: any, data?: any, settings?: any, page?: any }} input
+ * @returns {string | undefined}
+ */
+export function resolveCanonicalUrl({ seo, data, settings, page }) {
+	if (!settings?.url) return undefined;
+	if (settings.noindex === true || data?.noindex === true) return undefined;
+
+	const raw = seo?.canonical ?? data?.canonical ?? page?.url;
+	if (!raw) return undefined;
+
+	let url;
+	try {
+		url = new URL(raw, settings.url);
+	} catch {
+		return undefined;
+	}
+
+	url.hash = '';
+
+	const pagePref = data?.preserveQueryParams;
+	const sitePref = settings.seo?.preserveQueryParams;
+	const preserveQueryParams = pagePref ?? sitePref ?? false;
+
+	if (!preserveQueryParams) {
+		url.search = '';
+	}
+
+	return url.href;
+}
+
+/**
+ * SEO namespace builder factory.
+ *
+ * Returns `buildSeoNamespace(data)` which normalises the cascade into a
+ * resolved `_seoGraph` object: canonical fields, OG/Twitter projections, and the
+ * assembled JSON-LD graph at `_seoGraph.schema`.
+ *
+ * @param {{
+ *   scope: { values: Map },
+ *   settings: import('../types.js').BaselineSettings,
+ *   runtime: any,
+ *   options: import('../types.js').BaselineOptions,
+ *   log?: { warn: (...args: unknown[]) => void }
+ * }} deps
+ */
+export function createSeoNamespace({ scope, settings, runtime, options, log }) {
+	return function buildSeoNamespace(data) {
+		const seoIn = data.seo ?? {};
+		const userSettings = data.settings ?? settings;
+
+		const seoOut = { ...seoIn };
+
+		const url = resolveCanonicalUrl({
+			seo: seoIn,
+			data,
+			settings: userSettings,
+			page: data.page
+		});
+		if (url) seoOut.url = url;
+
+		seoOut.schema = assembleSchemaGraph(data);
+
+		const social = buildSocialProjections(data, url);
+		seoOut.openGraph = social.openGraph;
+		seoOut.twitter = social.twitter;
+
+		const inspectionKey = data.page?.url ?? data.page?.inputPath;
+		if (inspectionKey) setEntry(scope, inspectionKey, seoOut);
+
+		return seoOut;
+	};
+}

package/core/seo-graph/index.js

@@ -0,0 +1 @@
+export { registerSeoGraph } from './register.js';

package/core/seo-graph/open-graph.js

@@ -0,0 +1,130 @@
+// OG and Twitter projections.
+//
+// Render-ready normalisation of the social tags: short structured keys, every
+// value resolved against defaults and coerced (locale to OG underscore form,
+// dates to ISO). This module owns the decisions; the head driver owns the
+// og:/twitter: vocabulary and the per-tag emit. Shape and split follow the
+// prior art that productises this — Yoast's presentation-object + per-tag
+// presenters, mirrored by Joost's buildSeoContext (seo-context.ts) + Seo.astro
+// — written fresh against Baseline's namespace.
+
+import { resolveDates } from '../dates/index.js';
+import { resolveLocale, toOpenGraphLocale } from '../locale/index.js';
+
+/**
+ * Sibling-locale alternates in OG underscore form, excluding the page's own
+ * locale and de-duped. Derived from navigator nodes sharing the translationKey
+ * (the same set the graph adapter's workTranslation refs draw from).
+ *
+ * @returns {string[]}
+ */
+function localeAlternates(nodes, translationKey, currentUrl, primaryLocale) {
+	if (!nodes || !translationKey) return [];
+	const seen = new Set([primaryLocale]);
+	const out = [];
+	for (const n of Object.values(nodes)) {
+		if (n.translationKey !== translationKey || n.url === currentUrl) continue;
+		const loc = toOpenGraphLocale(n.locale || n.lang);
+		if (!loc || seen.has(loc)) continue;
+		seen.add(loc);
+		out.push(loc);
+	}
+	return out;
+}
+
+/**
+ * Build the OG and Twitter projections for a single page.
+ *
+ * Pure over the cascade `data` bag plus the resolved canonical URL (computed
+ * upstream in `build.js`; `undefined` on noindex). Returns render-ready
+ * projections with short keys — the head driver maps them to `<meta property>`
+ * / `<meta name>` tags. Empty projections when `settings.url` or `page.url` is
+ * absent (the dependency-discovery proxy pass).
+ *
+ * Rules beyond the old `buildSeoMeta`'s six fields: og:url falls back to the
+ * page URL on noindex; og:type follows an editorial `article`; image dimensions
+ * and alt gate on being known; article:* gate on the article type; locale
+ * alternates derive from sibling translations; Twitter carries only the
+ * overrides that differ from their OG counterpart (it inherits the rest).
+ *
+ * @param {Record<string, any>} data  The Eleventy cascade data bag.
+ * @param {string | undefined} canonicalUrl  The resolved canonical (`seo.url`).
+ * @returns {{ openGraph: Record<string, unknown>, twitter: Record<string, unknown> }}
+ */
+export function buildSocialProjections(data, canonicalUrl) {
+	const settings = data.settings;
+	const pageUrl = data.page?.url;
+	if (!settings?.url || !pageUrl) return { openGraph: {}, twitter: {} };
+
+	const seo = data.seo ?? {};
+	const schema = data.schema ?? {};
+	const nodes = data._navigator?.nodes;
+	const node = nodes?.[pageUrl];
+
+	const lang = node?.lang || data.page?.lang || data.lang || settings.defaultLanguage;
+	const locale = toOpenGraphLocale(resolveLocale(node, data, settings, lang)) ?? '';
+	const siteRoot = settings.url.replace(/\/+$/, '');
+
+	const title = seo.ogTitle ?? node?.title ?? data.title;
+	const description = seo.ogDescription ?? node?.description ?? data.description ?? node?.excerpt;
+
+	// Editorial `article` projects og:type article (and unlocks article:*);
+	// an explicit seo.ogType wins, then the site default, then 'website'.
+	const entryType = data.type || node?.type;
+	const type = seo.ogType ?? (entryType === 'article' ? 'article' : (settings.seo?.openGraph?.type ?? 'website'));
+
+	// og:url falls back to the absolute page URL when canonical is omitted
+	// (noindex), so share previews stay stable.
+	const url = canonicalUrl ?? `${siteRoot}${pageUrl}`;
+
+	const og = { title, type, url };
+	if (locale) og.locale = locale;
+	if (description) og.description = description;
+	const siteName = settings.languages?.[lang]?.title || settings.title;
+	if (siteName) og.siteName = siteName;
+
+	const translationKey = node?.translationKey || data.page?.translationKey || data.translationKey;
+	const localeAlt = localeAlternates(nodes, translationKey, pageUrl, locale);
+	if (localeAlt.length) og.localeAlternate = localeAlt;
+
+	// Image gating: a URL emits og:image; dimensions and alt ride only when
+	// known — the two-tier degrade the graph adapter follows for the ImageObject.
+	const ogImageRaw = data.ogImage ?? seo.ogImage ?? settings.seo?.ogImage;
+	const ogImage = typeof ogImageRaw === 'string' ? { url: ogImageRaw } : ogImageRaw;
+	if (ogImage?.url) {
+		og.image = ogImage.url;
+		if (ogImage.alt) og.imageAlt = ogImage.alt;
+		if (ogImage.width) og.imageWidth = ogImage.width;
+		if (ogImage.height) og.imageHeight = ogImage.height;
+	}
+
+	// article:* only when the page projects as an article. Author chain mirrors
+	// the graph adapter's: the Person, else the primary entity (Organization).
+	if (type === 'article') {
+		const dates = resolveDates(data);
+		const article = {};
+		if (dates.datePublished) article.publishedTime = dates.datePublished.toISOString();
+		if (dates.dateModified) article.modifiedTime = dates.dateModified.toISOString();
+		if (data.sectionLabel) article.section = data.sectionLabel;
+		// article:tag mirrors the `topics` convention (the same value the graph emits
+		// as schema.org keywords); always an array, OG tags are repeated tags.
+		if (data.topics?.length) article.tags = Array.isArray(data.topics) ? data.topics : [data.topics];
+		const author = schema.person?.name ?? schema.organization?.name;
+		if (author) article.authors = [author];
+		og.article = article;
+	}
+
+	// Twitter inherits from OG automatically, so default the card and carry only
+	// the overrides that differ from their OG counterpart (emitting a duplicate
+	// is noise).
+	const twitter = { card: seo.twitterCard ?? settings.seo?.twitter?.card ?? 'summary_large_image' };
+	const twitterSite = seo.twitterSite ?? settings.seo?.twitter?.site;
+	if (twitterSite) twitter.site = twitterSite;
+	const twitterCreator = settings.seo?.twitter?.creator;
+	if (twitterCreator) twitter.creator = twitterCreator;
+	if (seo.twitterTitle && seo.twitterTitle !== title) twitter.title = seo.twitterTitle;
+	if (seo.twitterDescription && seo.twitterDescription !== description) twitter.description = seo.twitterDescription;
+	if (seo.twitterImage && seo.twitterImage !== og.image) twitter.image = seo.twitterImage;
+
+	return { openGraph: og, twitter };
+}