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

package/modules/head/drivers/posthtml-head-elements.js

@@ -27,32 +27,43 @@ import { dedupeMeta, dedupeLink } from '../utils/dedupe.js';
  *
  * Scope:
  *   Owns node emission, dedupe orchestration, capo sort, and placeholder
- *   replacement.
- *   Does not own seed shape (page context), hreflang building
- *   (head/utils/alternates.js), or capo's element weights (capo.js).
+ *   replacement. Owns the og:/twitter: vocabulary: the seo substrate hands
+ *   over short structured keys, this driver maps them to <meta>/<script>.
+ *   Does not own seed shape (page context), the seo projection
+ *   (core/seo-graph), hreflang building (head/utils/alternates.js), or capo's
+ *   element weights (capo.js).
  *
  * Data flow:
- *   seeds + alternates + options → emit → dedupe → capo-sort → PostHTML
+ *   seeds + seo + alternates + options → emit → dedupe → capo-sort → PostHTML
  *   tree mutation
  *
  * @param {Object} args
  * @param {Object} args.seeds - Page context for the current page.
+ * @param {Object} [args.seo] - Resolved _seoGraph namespace (url, schema, openGraph, twitter).
  * @param {Array<Object>} args.alternates - hreflang link descriptors.
  * @param {Object} args.options - Head options (titleSeparator, showGenerator).
  * @param {string} args.placeholderTag - Placeholder element to replace.
  * @param {string} args.eol - End-of-line separator interleaved between nodes.
- * @param {Object} args.log - Scoped logger.
  * @returns {(tree: Object) => Object} PostHTML plugin function.
  */
-export function renderHead({ seeds, alternates, options, placeholderTag, eol, log }) {
-	const defaults = emitMeta(seeds.meta, seeds.render, options);
+export function renderHead({ seeds, seo, alternates, options, placeholderTag, eol }) {
+	// seo.url is the canonical source, resolved at cascade-time. It is undefined
+	// on noindex / no-settings.url pages, where the seo layer deliberately drops
+	// the canonical — emitMeta's guard then emits nothing, which is correct. The
+	// seo handle is present whenever a head renders (same skip set as page
+	// context), so there is no absent-handle case to fall back for.
+	const canonical = seo?.url;
+	const defaults = emitMeta(seeds.meta, seeds.render, options, canonical);
 	const extras = emitExtras(seeds.head, alternates);
+	const { meta: seoMeta, multi: seoMulti, scripts: seoScripts } = emitSeo(seo);
 
-	const deduped = dedupeAll([...defaults, ...extras]);
-	const sorted = capoSort(deduped);
+	// seo emits last so the substrate wins a property collision with settings.head.
+	// Multi-valued tags and JSON-LD bypass dedupe (property-keyed last-wins would
+	// collapse repeated og:locale:alternate / article:author to one).
+	const deduped = dedupeAll([...defaults, ...extras, ...seoMeta]);
+	const sorted = capoSort([...deduped, ...seoMulti, ...seoScripts]);
 
 	return function rendererPlugin(tree) {
-		// log.info('injecting head for', seeds.page.inputPath || seeds.page.url);
 		tree.match({ tag: placeholderTag }, () => ({
 			tag: 'head',
 			content: interleaveEOL(sorted, eol)
@@ -61,14 +72,14 @@ export function renderHead({ seeds, alternates, options, placeholderTag, eol, lo
 	};
 }
 
-function emitMeta(meta, render, options) {
+function emitMeta(meta, render, options, canonical) {
 	const nodes = [];
 	nodes.push(mkMeta({ charset: 'UTF-8' }));
 	nodes.push(mkMeta({ name: 'viewport', content: 'width=device-width, initial-scale=1.0' }));
 	if (meta.title) nodes.push({ tag: 'title', content: [meta.title] });
 	if (meta.description) nodes.push(mkMeta({ name: 'description', content: meta.description }));
 	nodes.push(mkMeta({ name: 'robots', content: meta.robots }));
-	if (meta.canonical) nodes.push(mkLink({ rel: 'canonical', href: meta.canonical }));
+	if (canonical) nodes.push(mkLink({ rel: 'canonical', href: canonical }));
 	if (options.showGenerator && render.generator) {
 		nodes.push(mkMeta({ name: 'generator', content: render.generator }));
 	}
@@ -76,6 +87,75 @@ function emitMeta(meta, render, options) {
 	return nodes;
 }
 
+/**
+ * Map the resolved seo projection to head nodes. The substrate hands over short
+ * structured keys; this driver owns the og:/twitter: vocabulary. Single-valued
+ * tags ride the deduped meta flow; multi-valued ones (og:locale:alternate,
+ * repeated article:author / article:tag) go in `multi` to skip the property-keyed dedupe.
+ * The JSON-LD graph rides `scripts` (the adapter returns a bare @graph array,
+ * wrapped in its @context envelope here).
+ *
+ * @param {Object} [seo] - Resolved seo namespace (graph, openGraph, twitter).
+ * @returns {{ meta: Array<Object>, multi: Array<Object>, scripts: Array<Object> }}
+ */
+function emitSeo(seo) {
+	const meta = [];
+	const multi = [];
+	const scripts = [];
+	if (!seo) return { meta, multi, scripts };
+
+	const og = seo.openGraph ?? {};
+	const tw = seo.twitter ?? {};
+
+	const prop = (property, content) => {
+		if (content !== undefined && content !== null && content !== '') meta.push(mkMeta({ property, content }));
+	};
+	const name = (key, content) => {
+		if (content !== undefined && content !== null && content !== '') meta.push(mkMeta({ name: key, content }));
+	};
+
+	prop('og:title', og.title);
+	prop('og:type', og.type);
+	prop('og:description', og.description);
+	prop('og:url', og.url);
+	prop('og:site_name', og.siteName);
+	prop('og:locale', og.locale);
+	prop('og:image', og.image);
+	prop('og:image:alt', og.imageAlt);
+	if (og.imageWidth !== undefined) prop('og:image:width', String(og.imageWidth));
+	if (og.imageHeight !== undefined) prop('og:image:height', String(og.imageHeight));
+
+	for (const loc of asArray(og.localeAlternate)) {
+		if (loc) multi.push(mkMeta({ property: 'og:locale:alternate', content: loc }));
+	}
+
+	if (og.article) {
+		prop('article:published_time', og.article.publishedTime);
+		prop('article:modified_time', og.article.modifiedTime);
+		prop('article:section', og.article.section);
+		for (const author of asArray(og.article.authors)) {
+			if (author) multi.push(mkMeta({ property: 'article:author', content: author }));
+		}
+		for (const tag of asArray(og.article.tags)) {
+			if (tag) multi.push(mkMeta({ property: 'article:tag', content: tag }));
+		}
+	}
+
+	name('twitter:card', tw.card);
+	name('twitter:site', tw.site);
+	name('twitter:creator', tw.creator);
+	name('twitter:title', tw.title);
+	name('twitter:description', tw.description);
+	name('twitter:image', tw.image);
+
+	if (seo.schema?.length) {
+		const content = JSON.stringify({ '@context': 'https://schema.org', '@graph': seo.schema });
+		scripts.push(mkScript({ type: 'application/ld+json', content }));
+	}
+
+	return { meta, multi, scripts };
+}
+
 function emitExtras(head, alternates = []) {
 	const nodes = [];
 	for (const m of asArray(head?.meta)) nodes.push(mkMeta(m));

package/modules/head/index.js

@@ -2,6 +2,8 @@ import { renderHead } from './drivers/posthtml-head-elements.js';
 import { buildAlternates } from './utils/alternates.js';
 import { optionsSchema } from './schema.js';
 
+import chalk from 'kleur';
+
 // Internal constants — not user-facing.
 const PLACEHOLDER_TAG = 'baseline-head';
 const EOL = '\n';
@@ -31,15 +33,16 @@ const EOL = '\n';
  *   every field the composer needs from cascade-time into transform-time.
  *
  * Scope:
- *   Owns transform-time composition and placeholder replacement.
- *   Pass 1 covers bucket 1 only: charset, viewport, title, description,
- *   robots, canonical, optional generator, plus user extras from
- *   settings.head and hreflang alternates. SEO and JSON-LD are later passes.
- *   Does not own seed shape (page context) or driver internals.
+ *   Owns transform-time composition and placeholder replacement. Emits
+ *   charset, viewport, title, description, robots, canonical, optional
+ *   generator, user extras from settings.head, hreflang alternates, plus the
+ *   seo substrate's OG/Twitter projections and JSON-LD graph.
+ *   Does not own seed shape (page context), the seo projection
+ *   (core/seo-graph), or driver internals.
  *
  * Data flow:
- *   page context + translation-map store + settings.head → driver →
- *   PostHTML tree mutation (replaces <baseline-head>)
+ *   page context + seo handle + translation-map store + settings.head →
+ *   driver → PostHTML tree mutation (replaces <baseline-head>)
  *
  * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
  * @param {Object} moduleContext
@@ -52,11 +55,12 @@ export function headCore(eleventyConfig, moduleContext) {
 	const parsed = optionsSchema.safeParse(options.head);
 	if (!parsed.success) {
 		for (const issue of parsed.error.issues) {
-			log.info('options:', `${issue.path.join('.')} — ${issue.message}`);
+			log.info('options:', `${issue.path.join('.')}, ${issue.message}`);
 		}
 	}
 
 	const pageContextRegistry = moduleContext.resolvePageContext;
+	const seoGraphRegistry = moduleContext.resolveSeoGraph;
 
 	// Resolved plugin options with defaults.
 	const headOptions = {
@@ -68,39 +72,39 @@ export function headCore(eleventyConfig, moduleContext) {
 	const headStats = { pages: new Set() };
 
 	eleventyConfig.on('eleventy.after', () => {
-		log.info({
-			message: 'Head injection summary',
-			totalPages: headStats.pages.size,
-			sample: Array.from(headStats.pages).slice(0, 10)
-		});
+		log.info(chalk.green(`Head injected into ${headStats.pages.size} pages`));
 		headStats.pages.clear();
 	});
 
 	// --- Transform-time: compose and inject. ---
-	log.info('Injecting heads to pages');
+	log.info('Injecting heads');
 	eleventyConfig.htmlTransformer.addPosthtmlPlugin('html', function (context) {
 		headStats.pages.add(context?.page?.inputPath || context?.outputPath);
 
 		const key = context?.page?.url ?? context?.page?.inputPath;
 		const seeds = pageContextRegistry?.getByKey(key);
 		if (!seeds) {
-			log.warn('no head seeds for', context?.page?.inputPath || context?.outputPath);
+			log.warn('No head seeds for', context?.page?.inputPath || context?.outputPath);
 			return (tree) => tree;
 		}
 
-		const translationKey = seeds.page?.locale?.translationKey;
+		// Peer substrate, read by the same key as the page context above. Carries
+		// the resolved canonical, OG/Twitter projections, and the JSON-LD graph.
+		const seo = seoGraphRegistry?.getByKey(key);
+
+		const translationKey = seeds.page?.translationKey;
 
 		const alternates = translationKey
-			? buildAlternates(seeds.page?.locale?.translationKey, runtime.translationMap.get(), seeds.site?.url)
+			? buildAlternates(translationKey, runtime.translationMap.get(), seeds.site?.url)
 			: [];
 
 		return renderHead({
 			seeds,
+			seo,
 			alternates,
 			options: headOptions,
 			placeholderTag: PLACEHOLDER_TAG,
-			eol: EOL,
-			log
+			eol: EOL
 		});
 	});
 }

package/modules/head/schema.js

@@ -6,6 +6,7 @@ import * as z from 'zod';
 // `options.head` slice: render-behaviour knobs.
 export const optionsSchema = z.looseObject({
 	titleSeparator: z.string().optional(),
+	titleTemplate: z.string().optional(),
 	showGenerator: z.boolean().optional()
 });
 
@@ -17,10 +18,13 @@ export const settingsHeadSchema = z.looseObject({
 	style: z.array(z.looseObject({})).optional()
 });
 
-// `settings.seo` site-default SEO scalars, page-overridable.
+// `settings.seo` site-default SEO config: canonical policy, default share
+// image, and OG/Twitter defaults. Structural only; values stay permissive.
 export const settingsSeoSchema = z.looseObject({
-	ogImage: z.string().optional(),
-	twitterSite: z.string().optional()
+	preserveQueryParams: z.boolean().optional(),
+	ogImage: z.unknown().optional(),
+	openGraph: z.looseObject({}).optional(),
+	twitter: z.looseObject({}).optional()
 });
 
 // Page-level `seo:` block. Same scalar set as bare front matter, namespaced.

package/modules/multilang/filters/i18n-default-translation.js

@@ -5,10 +5,8 @@
  * @returns {object|null}
  */
 export default function i18nDefaultTranslation(page, collection) {
-	if (!page?.locale?.translationKey) return null;
+	if (!page?.translationKey) return null;
 	return (
-		collection.find(
-			(p) => p.locale && p.locale.translationKey === page.locale.translationKey && p.locale.isDefaultLang
-		) || null
+		collection.find((p) => p.translationKey === page.translationKey && p.isDefaultLang) || null
 	);
 }

package/modules/multilang/filters/i18n-translation-in.js

@@ -6,11 +6,11 @@
  * @returns {object|null}
  */
 export default function i18nTranslationIn(page, collection, lang) {
-	if (!page?.locale?.translationKey) return null;
+	if (!page?.translationKey) return null;
 
 	return (
 		collection.find(
-			(p) => p.locale && p.locale.translationKey === page.locale.translationKey && p.locale.lang === lang
+			(p) => p.translationKey === page.translationKey && p.lang === lang
 		) || null
 	);
 }

package/modules/multilang/filters/i18n-translations-for.js

@@ -5,6 +5,6 @@
  * @returns {Array<object>}
  */
 export default function i18nTranslationsFor(page, collection) {
-	if (!page?.locale?.translationKey) return [];
-	return collection.filter((p) => p.locale && p.locale.translationKey === page.locale.translationKey);
+	if (!page?.translationKey) return [];
+	return collection.filter((p) => p.translationKey === page.translationKey);
 }

package/modules/multilang/index.js

@@ -1,6 +1,12 @@
 import { I18nPlugin } from '@11ty/eleventy';
 import { DeepCopy } from '@11ty/eleventy-utils';
-import { normalizeLanguages } from '../../core/utils/helpers.js';
+import {
+	normalizeLang,
+	normalizeLocale,
+	deriveLang,
+	resolveDefault
+} from '../../core/locale/index.js';
+import { normalizeLanguageMap } from '../../core/utils/normalize-language-map.js';
 import i18nTranslationsFor from './filters/i18n-translations-for.js';
 import i18nTranslationIn from './filters/i18n-translation-in.js';
 import i18nDefaultTranslation from './filters/i18n-default-translation.js';
@@ -9,10 +15,10 @@ import i18nDefaultTranslation from './filters/i18n-default-translation.js';
  * Multilang (module)
  *
  * Language infrastructure. Normalises language config, builds translation
- * relationships, attaches per-page locale data, and exposes cross-language
- * lookup filters. Active only when options.multilingual is true and both
- * defaultLanguage and at least one languages entry are set; otherwise the
- * module exits early.
+ * relationships, attaches per-page lang / locale / translationKey /
+ * isDefaultLang fields, and exposes cross-language lookup filters. Active
+ * only when options.multilingual is true and both defaultLanguage and at
+ * least one languages entry are set; otherwise the module exits early.
  *
  * Architecture layer:
  *   module
@@ -24,7 +30,8 @@ import i18nDefaultTranslation from './filters/i18n-default-translation.js';
  *
  * Lifecycle:
  *   build-time   → normalise languages, attach I18nPlugin, register filters
- *                  and computed page.locale
+ *                  and computed page.lang / page.locale / page.translationKey
+ *                  / page.isDefaultLang
  *   cascade-time → translationsMap and translations collections build the
  *                  per-translationKey map and write it to the store
  *
@@ -35,15 +42,16 @@ import i18nDefaultTranslation from './filters/i18n-default-translation.js';
  *   lifecycle boundary.
  *
  * Scope:
- *   Owns language normalisation, page.locale computation, the translations
- *   and translationsMap collections, and the i18n filters
- *   (i18nTranslationsFor, i18nTranslationIn, i18nDefaultTranslation).
- *   Does not own URL routing (I18nPlugin) or hreflang rendering (head).
+ *   Owns language normalisation, per-page flat locale fields (lang, locale,
+ *   translationKey, isDefaultLang), the translations and translationsMap
+ *   collections, and the i18n filters (i18nTranslationsFor,
+ *   i18nTranslationIn, i18nDefaultTranslation). Does not own URL routing
+ *   (I18nPlugin) or hreflang rendering (head).
  *
  * Data flow:
- *   settings.languages + page.lang/translationKey → normalisation +
- *   I18nPlugin → collections + computed page.locale + translation-map
- *   store → head, sitemap
+ *   settings.languages + page.lang/locale/translationKey → normalisation
+ *   + I18nPlugin → collections + flat computed page fields +
+ *   translation-map store → head, sitemap
  *
  * @param {import("@11ty/eleventy/src/UserConfig.js").default} eleventyConfig
  * @param {Object} moduleContext
@@ -52,45 +60,73 @@ export function multilangCore(eleventyConfig, moduleContext) {
 	const { state, runtime, log } = moduleContext;
 	const { settings, options } = state;
 
-	// --- Language normalization ---
-	// Accept languages as array or object; normalize to object map.
-	// Drives collection building, locale data, and sitemap-core language config.
-	const normalizeLanguageCode = (lang) => (lang || '').toLowerCase().trim();
-	const defaultLanguage = normalizeLanguageCode(settings.defaultLanguage);
-	const languages = normalizeLanguages(settings, log);
+	// --- Default resolution ---
+	// resolveDefault returns { lang, locale } from settings.defaultLocale (preferred)
+	// or settings.defaultLanguage (cosmetic alias; locale derived via Intl.Locale,
+	// returning the bare language subtag when no region is given).
+	const { lang: defaultLanguage, locale: defaultLocale } = resolveDefault(settings);
+	const languages = normalizeLanguageMap(settings, log);
 	const hasLanguages = languages && Object.keys(languages).length > 0;
 
 	const isMultilingual = options.multilang === true && defaultLanguage && hasLanguages;
 
 	if (!isMultilingual) {
-		log.info('inactive: requires options.multilingual + settings.defaultLanguage + languages');
+		log.info('Multilang inactive, needs options.multilang, settings.defaultLanguage or defaultLocale, and languages');
 		return;
 	}
 
+	log.info(`Multilang active: ${Object.keys(languages).join('/')} (default: ${defaultLanguage})`);
+
 	// Register Eleventy's built-in I18nPlugin for locale-aware URL resolution.
 	eleventyConfig.addPlugin(I18nPlugin, {
 		defaultLanguage: defaultLanguage,
 		errorMode: 'allow-fallback'
 	});
 
-	// Computed locale data: every page gets a page.locale object with its
-	// resolved lang, translationKey, and whether it's the default language.
-	eleventyConfig.addGlobalData('eleventyComputed.page.locale', () => {
-		return (data) => {
-			const translationKey = data.translationKey;
-			const lang = normalizeLanguageCode(data.lang || data.language || defaultLanguage);
-			const isDefaultLang = lang === defaultLanguage;
+	// --- Per-page resolvers ---
+	// Shared between the four flat eleventyComputed registrations below and
+	// the buildTranslations collection iterator. Closes over defaults and
+	// the languages map.
+	//
+	// Accept `language` as a writer-side alias for `lang`. Cheap, forgiving,
+	// and means existing front matter using either spelling keeps working.
+	// Also derives lang from data.locale when neither is set.
+	function resolvePageLang(data) {
+		return (
+			normalizeLang(data.lang || data.language || deriveLang(data.locale)) || defaultLanguage
+		);
+	}
 
-			return {
-				translationKey,
-				lang,
-				isDefaultLang
-			};
-		};
-	});
+	function resolvePageLocale(data) {
+		if (data.locale) return normalizeLocale(data.locale);
+		const lang = resolvePageLang(data);
+		return normalizeLocale(languages?.[lang]?.locale) ?? defaultLocale;
+	}
+
+	// --- Computed per-page fields ---
+	// Four independent registrations merge cleanly at the leaves (validated
+	// 2026-05-25 via temp/workbench/multilang-glow-up/eleventy-probe/).
+	// Replaces the historical single-bag page.locale object with flat
+	// siblings on page.
+	eleventyConfig.addGlobalData(
+		'eleventyComputed.page.lang',
+		() => (data) => resolvePageLang(data)
+	);
+	eleventyConfig.addGlobalData(
+		'eleventyComputed.page.locale',
+		() => (data) => resolvePageLocale(data)
+	);
+	eleventyConfig.addGlobalData(
+		'eleventyComputed.page.translationKey',
+		() => (data) => data.translationKey
+	);
+	eleventyConfig.addGlobalData(
+		'eleventyComputed.page.isDefaultLang',
+		() => (data) => resolvePageLang(data) === defaultLanguage
+	);
 
 	// Build a set of allowed language codes for validation during collection building.
-	const allowedLanguages = new Set(Object.keys(languages).map(normalizeLanguageCode));
+	const allowedLanguages = new Set(Object.keys(languages).map(normalizeLang));
 
 	// Build both the map (keyed by translationKey → lang) and the flat list.
 	// Shared logic for both collections — called once per collection registration.
@@ -102,7 +138,7 @@ export function multilangCore(eleventyConfig, moduleContext) {
 			const translationKey = page.data.translationKey;
 			if (!translationKey) continue;
 
-			const lang = page.data.lang || page.data.language || defaultLanguage;
+			const lang = resolvePageLang(page.data);
 			if (!lang) continue;
 
 			if (allowedLanguages.size && !allowedLanguages.has(lang)) {
@@ -110,8 +146,13 @@ export function multilangCore(eleventyConfig, moduleContext) {
 				continue;
 			}
 
-			const locale = { locale: { translationKey, lang, isDefaultLang: lang === defaultLanguage } };
-			const safeCopy = DeepCopy(page, locale);
+			const isDefaultLang = lang === defaultLanguage;
+			const locale = resolvePageLocale(page.data);
+
+			// Attach flat per-page fields. Mirrors the eleventyComputed shape
+			// so collection consumers read item.lang / item.locale /
+			// item.translationKey / item.isDefaultLang directly.
+			const safeCopy = DeepCopy(page, { lang, locale, translationKey, isDefaultLang });
 			list.push(safeCopy);
 
 			if (!map[translationKey]) map[translationKey] = {};
@@ -119,7 +160,7 @@ export function multilangCore(eleventyConfig, moduleContext) {
 				title: page.data.title,
 				url: page.url,
 				lang,
-				isDefaultLang: lang === defaultLanguage,
+				isDefaultLang,
 				data: page.data
 			};
 		}

package/modules/navigator/index.js

@@ -10,39 +10,42 @@ const __dirname = path.dirname(__filename);
 /**
  * Navigator (module)
  *
- * Debug surface. Exposes Eleventy and Baseline runtime state to templates so
- * developers can inspect data shape, scope contents, and lifecycle output
- * without leaving the page.
+ * Two roles, one module: the public read surface for plugin-produced
+ * cross-page data (the content graph and its enriched backlinks), and the
+ * debug surface for inspecting Eleventy and Baseline runtime state.
  *
  * Architecture layer:
  *   module
  *
  * System role:
- *   Read-only window into the runtime substrate. Pulls snapshots from the
- *   page-context registry and content-map store via the module context;
- *   does not write back.
+ *   Read-only window over the runtime substrate. Surfaces the content graph
+ *   for templates that need cross-page reads, and snapshots from the
+ *   page-context registry and content-map store for debugging. Writes
+ *   nothing back.
  *
  * Lifecycle:
- *   build-time   → register Nunjucks globals, debug filters, and the
- *                  optional virtual debug page
- *   cascade-time → eleventyComputed `_snapshot` resolves contentMap and
- *                  pageContext on each page
+ *   build-time   → register `_navigator` ({ nodes, edges, backlinks }),
+ *                  debug globals, filters, and the optional virtual debug page
+ *   cascade-time → eleventyComputed `_snapshot` resolves contentMap,
+ *                  pageContext, and seoGraph on each page
  *
  * Why this exists:
- *   Render-time inspection of cascade state has no built-in surface.
- *   Centralising globals and filters under a debug-only module keeps the
- *   inspection vocabulary stable and out of feature modules.
+ *   Templates need an addressable cross-page surface for graph reads, and
+ *   render-time inspection of cascade state has no built-in equivalent.
+ *   One module owns both vocabularies so feature modules stay narrow.
  *
  * Scope:
- *   Owns the `_runtime` and `_ctx` Nunjucks globals, computed `_snapshot`,
+ *   Owns the `_navigator` global (`{ nodes, edges, backlinks }`, the public
+ *   read surface), the debug globals `_runtime` and `_ctx`, computed `_snapshot`,
  *   debug filters (`_inspect`, `_json`, `_keys`), and the optional virtual
  *   page at /navigator-core.html.
- *   Does not own the data it surfaces (page-context registry, content-map
- *   store).
+ *   Does not own the data it surfaces (content graph, page-context registry,
+ *   content-map store).
  *
  * Data flow:
- *   snapshots (contentMap, pageContext) + this.ctx → globals + computed
- *   `_snapshot` + virtual page → developer
+ *   runtime.contentGraph + snapshots + this.ctx → `_navigator` + debug
+ *   globals + computed `_snapshot` + virtual page → templates and
+ *   developers
  *
  * Note: `_snapshot.contentMap` is null on the navigator template itself
  * because it renders before `eleventy.contentMap` fires. Read `_snapshot`
@@ -51,32 +54,43 @@ const __dirname = path.dirname(__filename);
  * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
  * @param {Object} moduleContext
  * @param {Object} moduleContext.state - Resolved plugin state.
- * @param {Object} moduleContext.snapshots - Thunks: { contentMap, pageContext }.
+ * @param {Object} moduleContext.runtime - Lazy access layer; reads contentGraph.
+ * @param {Object} moduleContext.snapshots - Thunks: { contentMap, pageContext, seoGraph }.
  */
 export function navigatorCore(eleventyConfig, moduleContext) {
-	const { state, snapshots, log, env } = moduleContext;
-	const { settings, options } = state;
+	const { state, runtime, snapshots, log, env } = moduleContext;
+	const { options } = state;
 
 	// Structural-only options check: log on mismatch, do not throw.
 	const parsed = optionsSchema.safeParse(options.navigator);
 	if (!parsed.success) {
 		for (const issue of parsed.error.issues) {
-			log.info('options:', `${issue.path.join('.')} — ${issue.message}`);
+			log.info('options:', `${issue.path.join('.')}, ${issue.message}`);
 		}
 	}
 
 	// Boolean shorthand activates the virtual page; object form lets users tune.
 	const navigatorOpts = options.navigator && typeof options.navigator === 'object' ? options.navigator : {};
-	const renderTemplate = env.mode === 'development' ?? navigatorOpts.template ?? Boolean(options.navigator);
+	const renderTemplate =
+		navigatorOpts.template ?? (typeof options.navigator === 'boolean' ? options.navigator : env.mode === 'development');
 	const inspectorDepth = navigatorOpts.inspectorDepth ?? 4;
 
 	eleventyConfig.addGlobalData('eleventyComputed._snapshot', () => {
 		return () => ({
 			contentMap: snapshots.contentMap(),
-			pageContext: snapshots.pageContext()
+			pageContext: snapshots.pageContext(),
+			seoGraph: snapshots.seoGraph()
 		});
 	});
 
+	// Public read surface for plugin-produced cross-page data. Templates can
+	// paginate over `_navigator.backlinks` or read `_navigator.graph` directly.
+	eleventyConfig.addGlobalData('_navigator', () => ({
+		nodes: runtime.contentGraph?.nodes ?? {},
+		edges: runtime.contentGraph?.edges ?? {},
+		backlinks: runtime.contentGraph?.backlinks ?? {}
+	}));
+
 	/**
 	 * Nunjucks Global: _runtime
 	 *
@@ -125,7 +139,7 @@ export function navigatorCore(eleventyConfig, moduleContext) {
 			inspectorDepth
 		});
 
-		log.info('Navigator template registered at /navigator-core.html');
+		log.info('Navigator mounted at /navigator-core.html');
 	}
 
 	/**

package/modules/navigator/templates/navigator-core.html

@@ -41,7 +41,7 @@ permalink: /navigator-core.html
 			<details>
 				<summary><strong>Page Context</strong></summary>
 				<pre>
-					{{- _snapshot.pageContext | _inspect({ depth: null }) -}}
+					{{- _pageContext | _inspect({ depth: null }) -}}
 				</pre>
 			</details>
 			{% for key, value in _runtime() %}