@janga/norna 0.7.27 → 0.7.29

package/scripts/lib/site-structure.mjs

@@ -1,16 +1,15 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
 import { access, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { categorySchema } from './schema-definitions.mjs';
 import { parsePageDirectoryPath } from './page-model.mjs';
+import { comparePageOrder, parsePageOrder } from './page-order.mjs';
+import { assertSiteSourceFormat } from './site-source-format.mjs';
+import { parseContentFrontmatter, splitSiteFile } from './site-content.mjs';
 import {
 	homePageDirectory,
-	siteContentLabel,
-	siteDir,
-	siteDirLabel,
-	sitePagesDir,
-	sitePagesLabel,
+	siteDir as defaultSiteDir,
+	siteDirLabel as defaultSiteDirLabel,
 } from './site-paths.mjs';
-import { parseYamlConfig } from './yaml-config.mjs';
 
 const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
 
@@ -19,30 +18,15 @@ const readDirectory = async (directory) => readdir(directory, { withFileTypes: t
 	throw error;
 });
 
-const compareNodeMetadata = (left, right) => (
-	left.pageOrder - right.pageOrder
-	|| left.pageId.localeCompare(right.pageId, 'en')
-);
-
-const assertLegacyStructureIsAbsent = async () => {
-	const legacyContentPath = path.join(siteDir, 'content.md');
-	const legacyImagesPath = path.join(siteDir, 'images');
-	const legacyPaths = [];
-	if (await fileExists(legacyContentPath)) legacyPaths.push(`${siteDirLabel}/content.md`);
-	if (await fileExists(legacyImagesPath)) legacyPaths.push(`${siteDirLabel}/images`);
-	if (legacyPaths.length > 0) {
-		throw new Error([
-			`The old root-page structure is no longer supported: ${legacyPaths.join(', ')}.`,
-			`Move the homepage content to ${sitePagesLabel}/${homePageDirectory}/content.md and its images to ${sitePagesLabel}/${homePageDirectory}/images/.`,
-		].join('\n'));
-	}
-
-	if (await fileExists(path.join(siteDir, 'routes'))) {
-		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
+const assertLegacyStructureIsAbsent = async ({ siteDir, siteDirLabel }) => {
+	for (const name of ['content.md', 'theme.yaml', 'images', 'pages', 'routes']) {
+		if (await fileExists(path.join(siteDir, name))) {
+			throw new Error(`${siteDirLabel}/${name} uses the former page layout. Put the homepage content.md, tree-theme.yaml, optional page-theme.yaml, images/ and pages/ inside ${siteDirLabel}/root/. Keep site-config/ and public/ at the site level. Stop the development server before moving files.`);
+		}
 	}
 };
 
-const assertUniqueSiblings = (nodes, pagesLabel) => {
+const assertUniqueSiblings = (nodes, pagesLabel, warnings) => {
 	const byId = new Map();
 	const byOrder = new Map();
 
@@ -57,25 +41,40 @@ const assertUniqueSiblings = (nodes, pagesLabel) => {
 		}
 		byId.set(node.pageId, node);
 
+		if (node.pageOrder === null) continue;
 		const existingOrder = byOrder.get(node.pageOrder);
 		if (existingOrder) {
-			throw new Error([
-				`${pagesLabel} contains duplicate sibling order "${String(node.pageOrder).padStart(3, '0')}".`,
-				`- ${existingOrder.nodeLabel}`,
-				`- ${node.nodeLabel}`,
-			].join('\n'));
+			const message = `${pagesLabel} contains duplicate sibling navigation.order ${node.pageOrder}: ${existingOrder.pageId} and ${node.pageId}. Slug determines their order. Choose different values to set an explicit order.`;
+			for (const sibling of [existingOrder, node]) warnings.push({ code: 'duplicate-page-order', message, label: sibling.contentLabel, path: sibling.contentPath });
 		}
 		byOrder.set(node.pageOrder, node);
 	}
 };
 
-const readCategory = async (categoryPath, categorySourceLabel) => {
-	const source = await readFile(categoryPath, 'utf8');
-	return parseYamlConfig(source, categorySourceLabel, { schema: categorySchema });
-};
-
-export const getSiteStructure = async () => {
-	await assertLegacyStructureIsAbsent();
+// Editors can inspect several sites in one process and retain malformed nodes
+// for repair. Builds and mutation plans keep the strict default contract.
+export const getSiteStructure = async ({
+	siteRoot = defaultSiteDir,
+	tolerant = false,
+	readSource = (filePath) => readFile(filePath, 'utf8'),
+} = {}) => {
+	const siteDir = path.resolve(siteRoot);
+	const siteDirLabel = siteDir === defaultSiteDir ? defaultSiteDirLabel : siteDir;
+	const sitePagesDir = getSiteSourcePaths(siteDir).pages;
+	const sitePagesLabel = `${siteDirLabel}/root/pages`;
+	const siteContentLabel = `${siteDirLabel}/root/content.md`;
+	const problems = [];
+	const report = (error, node = null) => {
+		if (!tolerant) throw error;
+		problems.push({ message: error.message, path: node?.contentPath ?? node?.categoryPath ?? siteDir });
+		if (node) (node.problems ??= []).push(error.message);
+	};
+	try {
+		await assertLegacyStructureIsAbsent({ siteDir, siteDirLabel, sitePagesLabel });
+		await assertSiteSourceFormat(siteDir, readSource);
+	} catch (error) {
+		report(error);
+	}
 
 	const nodes = [];
 	const warnings = [];
@@ -98,90 +97,82 @@ export const getSiteStructure = async () => {
 				fileExists(contentPath),
 				fileExists(categoryPath),
 			]);
-			const metadata = parsePageDirectoryPath(pageDirectory, nodeLabel);
-
-			if (hasContent === hasCategory) {
-				const problem = hasContent
-					? 'contains both content.md and category.yaml'
-					: 'contains neither content.md nor category.yaml';
-				throw new Error(`${nodeLabel} ${problem}. Keep exactly one: content.md for a page, or category.yaml for a navigation category.`);
+			let metadata;
+			try {
+				metadata = parsePageDirectoryPath(pageDirectory, nodeLabel);
+			} catch (error) {
+				report(error);
+				continue;
 			}
 
-			const isHome = pageDirectory === homePageDirectory;
-			if (isHome && hasCategory) {
-				throw new Error(`${nodeLabel}/category.yaml is invalid. The homepage must be a page with content.md.`);
+			if (hasCategory) report(new Error(`${nodeLabel}/category.yaml is no longer supported. Create content.md with an H1 and page.listChildren: true instead.`));
+			if (!hasContent) {
+				report(new Error(`${nodeLabel} has no content.md. Every page directory needs a content.md file.`));
+				continue;
 			}
 
 			const node = {
 				...metadata,
-				isHome,
-				kind: hasCategory ? 'category' : 'page',
+				isHome: false,
+				kind: 'page',
 				nodeDir,
 				nodeLabel,
-				pagePath: isHome ? '' : metadata.pagePath,
-				parentPagePath: isHome ? null : metadata.parentPagePath,
+				pagePath: metadata.pagePath,
+				parentPagePath: metadata.parentPagePath,
 			};
 
-			if (hasCategory) {
-				if (await fileExists(path.join(nodeDir, 'images'))) {
-					throw new Error(`${nodeLabel} is a navigation category and cannot contain images/. Use content.md when the collection needs editorial content or images.`);
-				}
-				const category = await readCategory(categoryPath, `${nodeLabel}/category.yaml`);
-				Object.assign(node, {
-					categorySourceLabel: `${nodeLabel}/category.yaml`,
-					categoryPath,
-					label: category.label,
-				});
-			} else {
-				Object.assign(node, {
-					contentLabel: `${nodeLabel}/content.md`,
-					contentPath,
-					imagesDir: path.join(nodeDir, 'images'),
-					imagesLabel: `${nodeLabel}/images`,
-				});
-			}
-
+			Object.assign(node, {
+				contentLabel: `${nodeLabel}/content.md`,
+				contentPath,
+				imagesDir: path.join(nodeDir, 'images'),
+				imagesLabel: `${nodeLabel}/images`,
+			});
+
+			try {
+				const { frontmatterBody } = splitSiteFile(await readSource(contentPath), node.contentLabel);
+				node.pageOrder = parsePageOrder(parseContentFrontmatter(frontmatterBody, node.contentLabel).navigation?.order, `${node.contentLabel}: navigation.order`);
+			} catch (error) { report(error, node); }
 			siblingNodes.push(node);
 		}
 
-		assertUniqueSiblings(siblingNodes, pagesLabel);
+		try {
+			assertUniqueSiblings(siblingNodes, pagesLabel, warnings);
+		} catch (error) {
+			report(error);
+		}
 
-		for (const node of siblingNodes.sort(compareNodeMetadata)) {
+		for (const node of siblingNodes.sort(comparePageOrder)) {
 			nodes.push(node);
 			const childPagesDir = path.join(node.nodeDir, 'pages');
 			const childDirectories = (await readDirectory(childPagesDir)).filter((entry) => entry.isDirectory());
 
-			if (node.isHome && childDirectories.length > 0) {
-				throw new Error([
-					`${node.nodeLabel} is the homepage and cannot contain child pages.`,
-					`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
-					...childDirectories.map(({ name }) => `- ${node.nodeLabel}/pages/${name}`),
-				].join('\n'));
-			}
-
-			if (node.kind === 'category' && childDirectories.length === 0) {
-				warnings.push({
-					code: 'empty-category',
-					label: node.categorySourceLabel,
-					message: `${node.categorySourceLabel} defines an empty navigation category. Add at least one child page under ${node.nodeLabel}/pages/.`,
-				});
-			}
-
-			if (!node.isHome && childDirectories.length > 0) {
+			if (childDirectories.length > 0) {
 				await collectNodes(childPagesDir, `${node.nodeLabel}/pages`, node.pageDirectory);
 			}
 		}
 	};
 
-	await collectNodes(sitePagesDir, sitePagesLabel);
-	if (!nodes.some(({ isHome }) => isHome)) {
-		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
+	const rootContentPath = getSiteSourcePaths(siteDir).content;
+	if (await fileExists(path.join(getSiteSourcePaths(siteDir).root, 'category.yaml'))) {
+		report(new Error(`${siteDirLabel}/root/category.yaml is invalid. The site root must be a page with content.md.`));
 	}
+	if (await fileExists(rootContentPath)) {
+		nodes.push({
+			...parsePageDirectoryPath(homePageDirectory),
+			kind: 'page', isHome: true, nodeDir: getSiteSourcePaths(siteDir).root, nodeLabel: `${siteDirLabel}/root`,
+			contentPath: rootContentPath, contentLabel: siteContentLabel,
+			imagesDir: getSiteSourcePaths(siteDir).images, imagesLabel: `${siteDirLabel}/root/images`,
+		});
+	} else {
+		report(new Error(`Homepage content is missing. Create ${siteContentLabel}.`));
+	}
+	await collectNodes(sitePagesDir, sitePagesLabel);
 
 	return {
 		categories: nodes.filter(({ kind }) => kind === 'category'),
 		contentFiles: nodes.filter(({ kind }) => kind === 'page'),
 		nodes,
+		...(tolerant ? { problems } : {}),
 		warnings,
 	};
 };

package/scripts/lib/site-upgrade.mjs

@@ -0,0 +1,32 @@
+import { assertSiteSourceFormat } from './site-source-format.mjs';
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { readThemePackage } from './theme-packages.mjs';
+import { getSiteSourcePaths } from './site-conventions.mjs';
+
+const inspect = (filename) => lstat(filename).catch((error) => {
+	if (error.code === 'ENOENT') return null;
+	throw error;
+});
+
+// Keep the existing command without claiming the former layout is current.
+// Our maintained sites are converted directly; no general converter is needed.
+export const planSiteUpgrade = async (siteRoot) => {
+	siteRoot = path.resolve(siteRoot);
+	const source = getSiteSourcePaths(siteRoot);
+	if (!(await inspect(siteRoot))?.isDirectory()) throw new Error(`${siteRoot} must be a regular directory, not a symbolic link.`);
+	for (const name of ['content.md', 'theme.yaml', 'images', 'pages', 'routes', 'config.yaml', 'page-theme.yaml', 'sitewide-content.yaml', 'site-config/site-theme.yaml', 'root/theme.yaml']) {
+		if (await inspect(path.join(siteRoot, name))) {
+			throw new Error(`This site uses former source locations (${name}). Automatic conversion to root/ is not provided. Stop the development server and back up the site. Keep site-config/ and public/ at the site level; put the homepage content.md, images/ and pages/ in root/. Put the required tree-theme.yaml with an explicit preset in root/; optional page-theme.yaml affects one page only. Rename descendant theme.yaml to tree-theme.yaml to preserve inherited overrides. For older formats, follow the source-layout reference before moving files. Update relative source/schema links, then run norna check and norna build. No files changed.`);
+		}
+	}
+	for (const directory of [source.root, path.join(siteRoot, 'site-config')]) {
+		if (!(await inspect(directory))?.isDirectory()) throw new Error(`${directory} must be a regular directory, not a symbolic link.`);
+	}
+	for (const filename of [source.content, path.join(siteRoot, 'site-config', 'settings.yaml'), source.theme]) {
+		if (!(await inspect(filename))?.isFile()) throw new Error(`${filename} is required and must be a regular file.`);
+	}
+	await assertSiteSourceFormat(siteRoot);
+	await readThemePackage({ siteRoot, filename: source.theme });
+	return { siteRoot, moves: [] };
+};

package/scripts/lib/social-image-assets.mjs

@@ -1,3 +1,4 @@
+import { publicFilePublication } from './publication-paths.mjs';
 import { getPublicAssetInspection } from './logo-assets.mjs';
 import {
 	socialImageAssetDefinitions,
@@ -13,7 +14,7 @@ export const getSocialImageAssets = () => getPublicAssetInspection().socialImage
 	.map((filename) => ({
 		...definitionsByFilename.get(filename),
 		filename,
-		href: `/${filename}`,
+		href: publicFilePublication(filename).pathname,
 	}));
 
 export const getSocialImageAsset = () => {

package/scripts/lib/source-files.mjs

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { pageDirectoryPattern, parsePageDirectoryPath } from './page-model.mjs';
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { configSchema, rootThemeSchema, pageThemeSchema, siteSchema, sitewideSchema, themeVisualSchema } from './schema-definitions.mjs';
+
+// Also published in schemas/manifest.json for synchronous editor discovery.
+export const sourceFileDefinitions = [
+	{ name: 'settings.yaml', location: 'site-config', schemaKind: 'config', required: true, input: 'url', description: 'Required public URL and technical site settings.' },
+	{ name: 'shared-content.yaml', location: 'site-config', schemaKind: 'sitewideContent', text: 'banners: []\n', description: 'Shared notices and footer content for the complete site.', removalEffect: 'Shared notices, authored footer content and logo display settings in this file will be removed from the whole site.' },
+	{ name: 'content.md', location: 'page', schemaKind: 'contentFrontmatter', required: true, input: 'title', description: 'Required page content.' },
+	{ name: 'tree-theme.yaml', location: 'page', schemaKind: 'theme', rootSchemaKind: 'rootTheme', required: 'root', rootText: 'preset: documentation\n', text: '# Modify inherited settings. Add preset only to replace the complete base.\n{}\n', description: 'Visual settings for this page and its descendants. Without preset, modifies inherited values; preset selects a new base. Required on the root page.', removalEffect: 'This branch resumes the ancestor tree theme. Overrides on descendants remain; a descendant preset starts an independent base.' },
+	{ name: 'page-theme.yaml', location: 'page', schemaKind: 'pageTheme', text: '# Modify this page only. Add preset only to replace the complete base.\n{}\n', description: 'Visual settings for this page only. Without preset, modifies its tree theme; preset selects a new base. Descendants keep their tree theme.', removalEffect: 'This page will use its selected tree theme again. Other pages are unchanged.' },
+];
+export const sourcePageDirectoryPattern = pageDirectoryPattern.source;
+const schemas = { config: configSchema, contentFrontmatter: siteSchema, sitewideContent: sitewideSchema, theme: themeVisualSchema, rootTheme: rootThemeSchema, pageTheme: pageThemeSchema };
+
+export const getSourcePageLocation = (siteRoot, directory) => {
+	const relative = path.relative(getSiteSourcePaths(siteRoot).root, directory);
+	if (!relative) return { isHome: true, ...parsePageDirectoryPath('.') };
+	if (!relative.startsWith(`pages${path.sep}`)) return null;
+	try { return { ...parsePageDirectoryPath(relative.slice(6).split(path.sep).join('/')), isHome: false }; }
+	catch { return null; }
+};
+
+export const getSourceFileDefinition = (siteRoot, filename) => {
+	const relative = path.relative(siteRoot, filename).split(path.sep).join('/');
+	const location = getSourcePageLocation(siteRoot, path.dirname(filename));
+	const definition = sourceFileDefinitions.find((entry) => entry.location === 'page'
+		? location && path.basename(filename) === entry.name : relative === `${entry.location}/${entry.name}`);
+	if (!definition) return null;
+	const schemaKind = location?.isHome && definition.rootSchemaKind ? definition.rootSchemaKind : definition.schemaKind;
+	return { ...definition, schemaKind, text: location?.isHome && definition.rootText ? definition.rootText : definition.text, schema: schemaKind === 'contentFrontmatter' ? undefined : schemas[schemaKind],
+		required: definition.required === true || definition.required === 'root' && location?.isHome === true };
+};

package/scripts/lib/structured-blocks.mjs

@@ -1,5 +1,7 @@
 import { isAlias, isMap, isScalar, isSeq, LineCounter, parseDocument } from 'yaml';
 
+export const managedImageFilenamePattern = '^[a-zA-Z0-9][a-zA-Z0-9.-]*\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[sS][vV][gG])$(?![\\s\\S])';
+
 const stringSchema = (name, definition) => ({
 	type: 'string',
 	description: definition.description,
@@ -7,7 +9,7 @@ const stringSchema = (name, definition) => ({
 	...(definition.values ? { enum: Object.keys(definition.values) } : {}),
 	...(name === 'alt' ? {} : { minLength: 1 }),
 	pattern: name === 'image'
-		? '^[a-zA-Z0-9][a-zA-Z0-9.-]*\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[sS][vV][gG])$(?![\\s\\S])'
+		? managedImageFilenamePattern
 		: name === 'caption' || name === 'text'
 			? '^(?=[\\s\\S]*\\S)[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F-\\x9F]*$(?![\\s\\S])'
 			: name === 'alt'

package/scripts/lib/theme-config.mjs

@@ -1,77 +1,35 @@
-import { readFile, readdir } from 'node:fs/promises';
+import { readdir } from 'node:fs/promises';
 import path from 'node:path';
-import {
-	validatePageThemeYamlStructure,
-	validateThemeYamlStructure,
-} from './site-content.mjs';
-import {
-	sitePagesDir,
-	sitePagesLabel,
-	siteThemeLabel,
-	siteThemePath,
-} from './site-paths.mjs';
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { siteDir, siteThemePath } from './site-paths.mjs';
+import { readThemePackage } from './theme-packages.mjs';
+import { getSourcePageLocation } from './source-files.mjs';
 import { resolveThemePresentation } from './presentation.mjs';
-import { resolveThemeConfig } from './theme-presets.mjs';
-import { pageThemeSchema, themeVisualSchema } from './schema-definitions.mjs';
-import { parseYamlConfig } from './yaml-config.mjs';
 
 export const readThemeConfig = async () => {
-	const themeFile = await readFile(siteThemePath, 'utf8').catch((error) => {
-		if (error?.code === 'ENOENT') {
-			throw new Error(`${siteThemeLabel} is required. Create it before running Norna.`);
-		}
-
-		throw error;
-	});
-	const config = parseYamlConfig(themeFile, siteThemeLabel, {
-		schema: themeVisualSchema,
-		validateStructure: validateThemeYamlStructure,
-	});
-	resolveThemeConfig(config, siteThemeLabel);
-	resolveThemePresentation(config, siteThemeLabel);
-
-	return config;
-};
-
-const getPageThemeFiles = async (directory, relativeDirectory = '') => {
-	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
-		if (error?.code === 'ENOENT') return [];
-		throw error;
-	});
-	const files = [];
-
-	for (const entry of entries) {
-		const relativePath = path.join(relativeDirectory, entry.name);
-		const absolutePath = path.join(directory, entry.name);
-		if (entry.isDirectory()) {
-			files.push(...await getPageThemeFiles(absolutePath, relativePath));
-			continue;
-		}
-
-		if (entry.name === 'theme.yaml') {
-			files.push({
-				path: absolutePath,
-				label: `${sitePagesLabel}/${relativePath.split(path.sep).join('/')}`,
-			});
-		}
-	}
-
-	return files;
+	const theme = await readThemePackage({ siteRoot: siteDir, filename: siteThemePath });
+	resolveThemePresentation(theme.config, theme.label);
+	return theme.config;
 };
 
 export const validatePageThemeFiles = async () => {
-	const files = await getPageThemeFiles(sitePagesDir);
-	const configs = [];
-
-	for (const file of files) {
-		const source = await readFile(file.path, 'utf8');
-		const config = parseYamlConfig(source, file.label, {
-			schema: pageThemeSchema,
-			validateStructure: validatePageThemeYamlStructure,
+	const themes = [];
+	const visit = async (directory) => {
+		const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+			if (error.code === 'ENOENT') return [];
+			throw error;
 		});
-
-		configs.push({ ...file, config });
-	}
-
-	return configs;
+		for (const entry of entries) {
+			const filename = path.join(directory, entry.name);
+			if (entry.isDirectory()) { await visit(filename); continue; }
+			if (!['tree-theme.yaml', 'page-theme.yaml', 'theme.yaml'].includes(entry.name)) continue;
+			const location = getSourcePageLocation(siteDir, directory);
+			if (!location) continue;
+			if (entry.name === 'theme.yaml') throw new Error(`${filename} uses the former theme filename. Use page-theme.yaml for one page only or tree-theme.yaml for inherited branch settings.`);
+			if (filename === siteThemePath) continue;
+			themes.push({ ...await readThemePackage({ siteRoot: siteDir, filename }), pageDirectory: location.pageDirectory });
+		}
+	};
+	await visit(getSiteSourcePaths(siteDir).root);
+	return themes;
 };

package/scripts/lib/theme-packages.mjs

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getPageDirectoryAncestors, parsePageDirectoryPath } from './page-model.mjs';
+import { getPageSourceDirectory } from './site-conventions.mjs';
+import { getSourceFileDefinition } from './source-files.mjs';
+import { mergeThemeOverrides } from './theme-presets.mjs';
+import { resolveThemePresentation } from './presentation.mjs';
+import { validateThemeYamlStructure } from './site-content.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+
+export const readThemePackage = async ({ siteRoot, filename, sources = new Map() }) => {
+	const definition = getSourceFileDefinition(siteRoot, filename);
+	if (!definition || !['rootTheme', 'theme', 'pageTheme'].includes(definition.schemaKind)) throw new Error(`Not a permitted theme location: ${filename}.`);
+	const source = sources.has(filename) ? sources.get(filename) : await readFile(filename, 'utf8').catch((error) => {
+		if (error.code !== 'ENOENT') throw error;
+		if (definition.required) throw new Error(`${filename} is required. Create the root tree theme before running Norna.`);
+		return null;
+	});
+	if (source === null) return null;
+	return { path: filename, label: filename, config: parseYamlConfig(source, filename, { schema: definition.schema, validateStructure: validateThemeYamlStructure }) };
+};
+
+// Resolve authored overrides only; preset expansion stays in the shared visual
+// resolvers. A page-only file is never considered while walking ancestors.
+export const selectPageTheme = async ({ siteRoot, pageDirectory = '.', sources, includePageTheme = true }) => {
+	siteRoot = path.resolve(siteRoot);
+	parsePageDirectoryPath(pageDirectory);
+	const ancestors = pageDirectory === '.' ? ['.'] : ['.', ...getPageDirectoryAncestors(pageDirectory)];
+	let treeTheme;
+	const sourceFiles = [];
+	for (const ancestor of ancestors) {
+		const filename = path.join(siteRoot, getPageSourceDirectory(ancestor), 'tree-theme.yaml');
+		const candidate = await readThemePackage({ siteRoot, filename, sources });
+		if (candidate) {
+			treeTheme = { ...candidate, config: mergeThemeOverrides(treeTheme?.config, candidate.config) };
+			sourceFiles.push(candidate);
+		}
+	}
+	const pageTheme = includePageTheme
+		? await readThemePackage({ siteRoot, filename: path.join(siteRoot, getPageSourceDirectory(pageDirectory), 'page-theme.yaml'), sources })
+		: null;
+	const selected = pageTheme ? { ...pageTheme, config: mergeThemeOverrides(treeTheme.config, pageTheme.config) } : treeTheme;
+	if (pageTheme) sourceFiles.push(pageTheme);
+	resolveThemePresentation(treeTheme.config, treeTheme.label);
+	resolveThemePresentation(selected.config, selected.label);
+	return { treeTheme, pageTheme, selected, sourceFiles };
+};

package/scripts/lib/theme-presets.mjs

@@ -93,7 +93,7 @@ export const getThemePresetMetadata = (presetName) => {
 	};
 };
 
-export const getThemePreset = (presetName, sourceLabel = 'theme.yaml') => {
+export const getThemePreset = (presetName, sourceLabel = 'root/tree-theme.yaml') => {
 	const preset = themePresets[presetName];
 
 	if (!preset) {
@@ -103,62 +103,29 @@ export const getThemePreset = (presetName, sourceLabel = 'theme.yaml') => {
 	return structuredClone(preset);
 };
 
-export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.yaml') => {
-	const presetName = theme?.preset;
-	if (presetName === undefined) return structuredClone(theme ?? {});
+// Keep authored fields separate from preset defaults so navigation can distinguish
+// an explicit surface request from an adaptable preset default.
+export const mergeThemeOverrides = (base = {}, override = {}) => {
+	const merged = override.preset !== undefined ? structuredClone(override) : mergeDeep(base, override);
+	if (override.images?.presentation === 'prose-aligned' && override.images.maxAvailableHeightPercent === undefined) {
+		delete merged.images.maxAvailableHeightPercent;
+	}
+	return merged;
+};
 
+export const resolveThemeConfig = (theme = {}, sourceLabel = 'root/tree-theme.yaml') => {
+	const presetName = theme?.preset;
 	const overrides = structuredClone(theme ?? {});
-	delete overrides.preset;
-
-	const resolved = {
-		preset: presetName,
+	const resolved = presetName === undefined ? overrides : {
 		...mergeDeep(getThemePreset(presetName, sourceLabel), overrides),
 	};
-
-	if (
-		overrides.images?.presentation === 'prose-aligned'
-		&& overrides.images.maxAvailableHeightPercent === undefined
-	) {
+	if (overrides.images?.presentation === 'prose-aligned' && overrides.images.maxAvailableHeightPercent === undefined) {
 		delete resolved.images.maxAvailableHeightPercent;
 	}
-
-	return resolved;
-};
-
-const mergePageThemePart = (base, override, keys) => Object.fromEntries(keys
-	.filter((key) => override?.[key] !== undefined || base?.[key] !== undefined)
-	.map((key) => [key, override?.[key] ?? base?.[key]]));
-
-export const mergePageThemeConfig = (base = {}, override = {}) => {
-	const images = {
-		...(base.images ?? {}),
-		...mergePageThemePart(base.images, override.images, [
-			'presentation',
-			'width',
-			'maxAvailableWidthPercent',
-			'maxAvailableHeightPercent',
-		]),
-	};
-
-	if (
-		override.images?.presentation === 'prose-aligned'
-		&& override.images.maxAvailableHeightPercent === undefined
-	) {
-		delete images.maxAvailableHeightPercent;
+	if (resolved.images?.presentation === 'prose-aligned' && resolved.images.maxAvailableHeightPercent !== undefined) {
+		throw new Error(`images.maxAvailableHeightPercent cannot be used with images.presentation "prose-aligned" in ${sourceLabel}. Remove images.maxAvailableHeightPercent or set images.presentation to "centered-fit".`);
 	}
-
-	return {
-		...base,
-		layout: {
-			...(base.layout ?? {}),
-			...mergePageThemePart(base.layout, override.layout, ['contentSpacing', 'textWidth']),
-		},
-		images,
-		sections: {
-			...(base.sections ?? {}),
-			...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
-		},
-	};
+	return resolved;
 };
 
 const quote = (value) => JSON.stringify(value);
@@ -171,7 +138,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 	];
 };
 
-export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
+export const renderThemePresetReference = (presetName, sourceLabel = 'root/tree-theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
 	const { appearance, corners, layout, images, blocks, typography, palette, sections } = preset;
@@ -179,8 +146,8 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
 		`# ${metadata.description}`,
-		'# This is a reference file. Norna only loads theme.yaml.',
-		'# Keep the preset in theme.yaml and copy only the values you want to override.',
+		'# This is a reference file. Norna loads root/tree-theme.yaml for the shared theme.',
+		'# Keep the preset in root/tree-theme.yaml and copy only the values you want to override.',
 		`# Available theme presets: ${themePresetNames.join(', ')}.`,
 		`preset: ${presetName}`,
 		'',

package/scripts/lib/typography.mjs

@@ -152,7 +152,7 @@ const evaluateResponsiveSize = (value, viewportWidth) => {
 	return Math.min(parsed.maximumRem * 16, Math.max(parsed.minimumRem * 16, preferredPixels));
 };
 
-export const assertTypographyContract = (typography, sourceLabel = 'theme.yaml') => {
+export const assertTypographyContract = (typography, sourceLabel = 'root/tree-theme.yaml') => {
 	const values = typography?.values ?? typography;
 	if (!values?.headings || !values?.body || !values?.caption) {
 		throw new Error(`Incomplete typography configuration in ${sourceLabel}.`);
@@ -427,7 +427,7 @@ export const defaultTypography = {
 	rhythm: 'normal',
 };
 
-export const resolveTypographyConfig = (typography = defaultTypography, sourceLabel = 'theme.yaml') => {
+export const resolveTypographyConfig = (typography = defaultTypography, sourceLabel = 'root/tree-theme.yaml') => {
 	const profileName = typography?.profile ?? defaultTypography.profile;
 	const rhythmName = typography?.rhythm ?? defaultTypography.rhythm;
 	const profile = typographyProfiles[profileName];

package/scripts/lib/yaml-config.mjs

@@ -60,7 +60,7 @@ export const parseYamlConfig = (source, label, {
 	if (issues.length > 0) {
 		throw new Error([
 			`${label} has invalid YAML structure.`,
-			...issues.map((issue) => `- ${issue.message}`),
+			...issues.map((issue) => `- ${issue.message}${issue.fix ? ` ${issue.fix}` : ''}`),
 		].join('\n'));
 	}