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

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 };
+}

package/core/seo-graph/register.js

@@ -0,0 +1,42 @@
+import { createLogger } from '../logging/index.js';
+import { getScope, memoize } from '../registry.js';
+import { createSeoNamespace } from './build.js';
+
+const SCOPE_NAME = 'core:seo-graph';
+const LOG_NAME = 'seo-graph';
+const COMPUTED_KEY = 'eleventyComputed._seoGraph';
+
+/**
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} coreContext
+ */
+export function registerSeoGraph(eleventyConfig, coreContext) {
+	const { state, runtime } = coreContext;
+	const { settings, options } = state;
+
+	const log = createLogger(LOG_NAME, { verbose: options.verbose });
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	const buildSeoNamespace = createSeoNamespace({ scope, settings, runtime, options, log });
+
+	function shouldSkip(data) {
+		if (data._internal) return true;
+		if (data.page?.outputFileExtension !== 'html') return true;
+		return false;
+	}
+
+	eleventyConfig.addGlobalData(COMPUTED_KEY, () => {
+		return (data) => {
+			if (shouldSkip(data)) return data._seoGraph ?? null;
+			return memoize(scope, data, buildSeoNamespace);
+		};
+	});
+
+	log.info('SEO graph registered');
+
+	return {
+		get: (data) => scope.cache.get(data),
+		getByKey: (key) => scope.values.get(key),
+		snapshot: () => Object.fromEntries(scope.values)
+	};
+}

package/core/seo-graph/schema.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+// Structural shape of the resolved `seo` namespace. Permissive on values;
+// strict only where a missing/wrong shape would break a downstream consumer.
+export const seoSchema = z
+	.object({
+		title: z.string().optional(),
+		description: z.string().optional(),
+		url: z.string().optional(),
+		ogImage: z.unknown().optional(),
+		locale: z.string().optional(),
+		openGraph: z.record(z.unknown()).optional(),
+		twitter: z.record(z.unknown()).optional(),
+		// The assembled JSON-LD @graph. Authored identity lives at
+		// `data.schema`; the resolved graph lives here. No `seo.schema` path.
+		graph: z.array(z.unknown()).optional()
+	})
+	.passthrough();

package/core/slug-index.js

@@ -35,7 +35,7 @@ const SCOPE_NAME = 'core:slug-index';
  *   page-context.buildPageContext → set() → registry scope → wikilinks getBySlug()
  *
  * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
- * @returns {{set: (slug: string, url: string, inputPath?: string) => void, getBySlug: (slug: string) => string | null, snapshot: () => Record<string, {url: string, inputPath?: string}>}}
+ * @returns {{set: (slug: string, url: string, inputPath?: string) => void, getBySlug: (slug: string) => string | undefined, snapshot: () => Record<string, {url: string, inputPath?: string}>}}
  */
 export function createSlugIndex(eleventyConfig) {
 	const scope = getScope(eleventyConfig, SCOPE_NAME);
@@ -52,7 +52,7 @@ export function createSlugIndex(eleventyConfig) {
 			setEntry(scope, slug, { url, inputPath });
 		},
 		getBySlug(slug) {
-			return getEntry(scope, slug)?.url ?? null;
+			return getEntry(scope, slug)?.url;
 		},
 		snapshot() {
 			return Object.fromEntries(scope.values);

package/core/state.js

@@ -0,0 +1,75 @@
+/**
+ * State derivation (composition root helper)
+ *
+ * Pure normalisation of user-supplied `settings` and `options` into the
+ * resolved `state` shape modules read from. No eleventyConfig, no
+ * environment reads beyond the `mode` argument, no side effects.
+ *
+ * Architecture layer:
+ *   composition root (pure helper)
+ *
+ * System role:
+ *   The single place that applies defaults, fallbacks, and feature
+ *   inference. Extracted from the entry point so it can be reasoned
+ *   about — and tested — without booting Eleventy.
+ *
+ * Why this exists:
+ *   Keeping defaults and feature derivation tangled with eleventyConfig
+ *   wiring made the entry point hard to scan. Pulling the pure half out
+ *   leaves the composition root as a list of registration steps.
+ *
+ * Scope:
+ *   Owns settings/options normalisation and the derived `features` map.
+ *   Does not own validation (see core/schema.js) or any runtime wiring.
+ *
+ * Data flow:
+ *   settings + options + { mode } → { settings, options, features }
+ *
+ * @param {import('./types.js').BaselineSettings} settings
+ * @param {import('./types.js').BaselineOptions} options
+ * @param {{ mode?: string }} [env]
+ * @returns {import('./types.js').BaselineState & { features: Readonly<Record<string, boolean>> }}
+ */
+export function deriveBaselineState(settings, options, { mode } = {}) {
+	const isDev = mode === 'development';
+
+	const resolvedSettings = {
+		title: settings.title,
+		tagline: settings.tagline,
+		url: settings.url,
+		noindex: settings.noindex ?? false,
+		defaultLanguage: settings.defaultLanguage,
+		defaultLocale: settings.defaultLocale,
+		languages: settings.languages,
+		head: settings.head,
+		seo: settings.seo
+	};
+
+	const resolvedOptions = {
+		verbose: options.verbose ?? true,
+		multilang: options.multilingual ?? false,
+		sitemap: options.sitemap ?? options.enableSitemapTemplate ?? true,
+		navigator: options.navigator ?? options.enableNavigatorTemplate ?? isDev,
+		head: {
+			titleSeparator: options.head?.titleSeparator,
+			showGenerator: options.head?.showGenerator
+		},
+		assets: {
+			esbuild: options.assets?.esbuild ?? options.assetsESBuild ?? {}
+		}
+	};
+
+	const features = Object.freeze({
+		multilang: Boolean(resolvedOptions.multilang),
+		sitemap: Boolean(resolvedOptions.sitemap),
+		navigator: Boolean(resolvedOptions.navigator),
+		head: true,
+		assets: true
+	});
+
+	return Object.freeze({
+		settings: Object.freeze(resolvedSettings),
+		options: Object.freeze(resolvedOptions),
+		features
+	});
+}

package/core/{shortcodes/image.js → surface/image-shortcode.js}

@@ -1,10 +1,10 @@
 import path from 'node:path';
 import Image from '@11ty/eleventy-img';
-import { createLogger } from '../logging.js';
+import { createLogger } from '../logging/index.js';
 
 // Module-level logger. Image shortcode only uses `.warn`, which emits regardless
 // of verbose, so we don't thread verbose through the shortcode signature.
-const log = createLogger('image');
+const log = createLogger('image-shortcode');
 
 const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 'auto'];
 const DEFAULT_FORMATS = ['avif', 'webp'];
@@ -68,7 +68,7 @@ export async function imageShortcode(options = {}) {
 
 	// --- Validation and normalization ---
 
-	if (!src) throw new Error(`imageShortcode: src is required (received ${JSON.stringify(src)})`);
+	if (!src) throw new Error(`[baseline/image-shortcode] src is required (received ${JSON.stringify(src)})`);
 	if (alt == null) {
 		log.warn('alt is required (use empty string for decorative images)');
 	}
@@ -106,7 +106,7 @@ export async function imageShortcode(options = {}) {
 		});
 	} catch (error) {
 		if (process.env.ELEVENTY_RUN_MODE === 'serve') {
-			log.warn(`transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
+			log.warn(`transformOnRequest failed for ${src}, retrying. ${error?.message || error}`);
 			metadata = await Image(resolvedSrc, imageOptions);
 		} else {
 			throw error;

package/core/surface/index.js

@@ -0,0 +1,22 @@
+/**
+ * Surface barrel
+ *
+ * Single entry point for everything Baseline registers against Eleventy that
+ * user templates can reach: filters, global functions, shortcodes.
+ */
+
+import { registerDateGlobal } from '../dates/index.js';
+
+// --- Filters ---
+export { markdownFilter } from '../markdown/markdownify.js';
+export { relatedPostsFilter } from './filters/related-posts.js';
+export { isStringFilter } from './filters/isString.js';
+
+// --- Shortcodes ---
+export { imageShortcode } from './image-shortcode.js';
+
+// --- Global functions (aggregator) ---
+/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
+export function registerGlobals(eleventyConfig) {
+	registerDateGlobal(eleventyConfig);
+}

package/core/types.js

@@ -14,6 +14,9 @@
  * @property {string} [url]
  * @property {boolean} [noindex]
  * @property {string} [defaultLanguage]
+ * Short language code; a writer-side alias for defaultLocale.
+ * @property {string} [defaultLocale]
+ * BCP 47 default locale; preferred when both are set.
  * @property {Record<string, unknown>} [languages]
  * @property {Object} [head]
  */