@janga/norna 0.7.27 → 0.7.28

package/scripts/lib/editor-site-tree.mjs

@@ -0,0 +1,151 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getMarkdownHeadings, slugifyAsciiIdentifier } from './heading-ids.mjs';
+import { parsePageDirectoryPath } from './page-model.mjs';
+import { splitPageMarkdownSource } from './page-markdown.mjs';
+import { siteSchema } from './schema-definitions.mjs';
+import { getSiteSourcePaths, homePageDirectory } from './site-conventions.mjs';
+import { createSiteNode, escapeMarkdownHeading, planSiteNodeCreation } from './site-node-create.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+import { changeYamlField } from './yaml-source-edit.mjs';
+import { readEditorLinkState } from './editor-site-links.mjs';
+import { readSiteEditingTree } from './editor-site-editing-tree.mjs';
+
+// Optional capability: older engines keep IntelliSense without exposing writes
+// through a site-tree API whose contract they do not implement.
+export const siteTreeApiVersion = 1;
+export const siteFileTreeApiVersion = 1;
+export const sitePageFormApiVersion = 1;
+export { siteTreeEditingApiVersion, getEditorSourceFileChoices, planEditorSourceFileCreation, createEditorSourceFile } from './editor-source-files.mjs';
+export { createSiteNode, planSiteNodeCreation, slugifyAsciiIdentifier };
+export { siteFileOperationsApiVersion, siteRemovalApiVersion, planEditorImageCopy, planEditorRemoval, getEditorImageUsage, createEditorImageAppend, createEditorImageBatchAppend } from './editor-site-files.mjs';
+export { getEditorIncomingLinks } from './editor-site-links.mjs';
+export { siteAddressApiVersion, getEditorPageAddresses, planEditorPageAddress, applyEditorPageAddress } from './editor-page-addresses.mjs';
+export { sitePagePlacementApiVersion, planEditorPagePlacement, applyEditorPagePlacement } from './editor-page-placement.mjs';
+
+const sourceParts = (source, kind) => {
+	const split = splitPageMarkdownSource(source);
+	if (split.frontmatterUnclosed) throw new Error('Close the YAML frontmatter with --- before editing page information.');
+	const lines = source.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+	const bodyLine = split.lineOffset;
+	return {
+		yaml: bodyLine ? lines.slice(1, bodyLine - 1).join('') : '',
+		offset: bodyLine ? lines[0].length : 0,
+		body: split.body,
+		bodyLine,
+	};
+};
+
+const parseInformation = async ({ source, kind, isHome, sourcePath }) => {
+	const parts = sourceParts(source, kind);
+	const data = parseYamlConfig(parts.yaml, sourcePath, { schema: siteSchema });
+	const { headings } = await getMarkdownHeadings(parts.body);
+	const titles = headings.filter(({ depth }) => depth === 1);
+	if (titles.length !== 1) throw new Error('Keep exactly one Markdown H1 title in this page before editing its information.');
+	if (isHome && data.navigation?.listed === false) throw new Error('Home must remain listed. Remove navigation.listed: false.');
+	return {
+		title: titles[0].title,
+		description: data.page?.description ?? '',
+		listed: data.navigation?.listed !== false,
+		aliases: data.page?.aliases ?? [],
+		listChildren: data.page?.listChildren === true,
+		titleLine: parts.bodyLine + titles[0].line - 1,
+		titleLineCount: titles[0].source.split('\n').length,
+	};
+};
+
+export const getSiteNodeInformation = async (input) => {
+	try {
+		return { ...await parseInformation(input), problem: null };
+	} catch (error) {
+		return { title: input.fallbackTitle ?? path.basename(path.dirname(input.sourcePath)),
+			description: '', listed: true, aliases: [], problem: error.message };
+	}
+};
+
+export const readSiteTree = async ({ siteRoot, sources = new Map(), cache = new Map() }) => {
+	const readSource = (filename) => sources.has(filename) ? sources.get(filename) : readFile(filename, 'utf8');
+	const structure = await getSiteStructure({ siteRoot, tolerant: true, readSource });
+	const nodes = [];
+	const used = new Set();
+	for (const node of structure.nodes) {
+		const sourcePath = node.contentPath ?? node.categoryPath;
+		used.add(sourcePath);
+		let information;
+		try {
+			const source = await readSource(sourcePath);
+			const previous = cache.get(sourcePath);
+			information = previous?.source === source ? previous.information : await getSiteNodeInformation({
+				kind: node.kind, isHome: node.isHome, source, sourcePath, fallbackTitle: node.label ?? node.pageId,
+			});
+			cache.set(sourcePath, { source, information });
+		} catch (error) {
+			information = { title: node.label ?? node.pageId, listed: true, aliases: [], problem: error.message };
+		}
+		nodes.push({ ...node, ...information, sourcePath, url: node.isHome ? '/' : `/${node.pagePath}/`,
+			problem: information.problem ?? node.problems?.[0] ?? null });
+	}
+	for (const filename of cache.keys()) if (!used.has(filename)) cache.delete(filename);
+	return { nodes, problems: structure.problems };
+};
+
+// One physical projection preserves resources and repairable entries even when
+// the logical structure cannot be read. The logical page API remains separate.
+export const readSiteFileTree = async (options) => {
+	const siteRoot = path.resolve(options.siteRoot);
+	const snapshot = await readSiteTree({ ...options, siteRoot }).catch((error) => ({
+		nodes: [], problems: [{ path: siteRoot, message: error.message }],
+	}));
+	return readSiteEditingTree({ ...options, siteRoot, snapshot, getInformation: getSiteNodeInformation });
+};
+
+export const editSiteNodeInformation = async ({ siteRoot, sourcePath, source, field, value, sources = new Map() }) => {
+	const relative = path.relative(getSiteSourcePaths(siteRoot).pages, sourcePath).split(path.sep).join('/');
+	const filename = path.posix.basename(relative);
+	if (filename !== 'content.md') throw new Error('Choose a page content.md source file.');
+	const pageDirectory = path.resolve(sourcePath) === getSiteSourcePaths(path.resolve(siteRoot)).content
+		? homePageDirectory : path.posix.dirname(relative);
+	parsePageDirectoryPath(pageDirectory);
+	const kind = 'page';
+	const isHome = pageDirectory === homePageDirectory;
+	const info = await parseInformation({ source, kind, isHome, sourcePath });
+	const allowed = ['title', 'description', 'listed', 'aliases', 'listChildren'];
+	if (!allowed.includes(field)) throw new Error('This information field is read-only.');
+	if (field === 'aliases') {
+		if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) throw new Error('Enter additional addresses as site-relative paths, such as /old-guide/.');
+	} else if (field === 'listed' || field === 'listChildren') {
+		if (typeof value !== 'boolean') throw new Error(field === 'listed' ? 'Choose whether this page is listed in navigation.' : 'Choose whether to append the list of child pages.');
+		if (field === 'listed' && isHome && !value) throw new Error('Home must remain listed.');
+	} else {
+		if (typeof value !== 'string' || /[\r\n]/.test(value)) throw new Error('Use a single line of text.');
+		value = value.trim();
+		if (field === 'title' && !value) throw new Error('Enter a title.');
+	}
+	if (info[field] === value) return [];
+	const eol = source.includes('\r\n') ? '\r\n' : '\n';
+	if (field === 'title') {
+		const lines = source.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+		const start = lines.slice(0, info.titleLine).join('').length;
+		const original = lines.slice(info.titleLine, info.titleLine + info.titleLineCount).join('');
+		return [{ start, end: start + original.replace(/\r?\n$/, '').length, text: `# ${escapeMarkdownHeading(value)}` }];
+	}
+	const parts = sourceParts(source, kind);
+	const keys = field === 'listed' ? ['navigation', 'listed'] : ['page', field === 'aliases' ? 'aliases' : field === 'listChildren' ? 'listChildren' : 'description'];
+	const yaml = changeYamlField(parts.yaml, keys, (field === 'description' && !value) || (field === 'aliases' && !value.length) || (field === 'listChildren' && !value) ? undefined : value, eol);
+	const next = parts.bodyLine ? !yaml.trim() ? source.slice(parts.offset + parts.yaml.length).replace(/^---[ \t]*(?:\r?\n|$)/, '')
+			: source.slice(0, parts.offset) + yaml + source.slice(parts.offset + parts.yaml.length)
+			: `---${eol}${yaml}---${eol}${eol}${source}`;
+	// Validate the complete result before offering it to the editor.
+	await parseInformation({ source: next, kind, isHome, sourcePath });
+	if (field === 'aliases') {
+		const state = await readEditorLinkState({ siteRoot, sources: new Map([...sources, [sourcePath, next]]) });
+		if (state.incomplete.length) throw new Error(`Additional addresses could not be checked. ${state.incomplete.join('\n')}`);
+	}
+	let start = 0;
+	while (start < source.length && start < next.length && source[start] === next[start]) start++;
+	let end = source.length;
+	let nextEnd = next.length;
+	while (end > start && nextEnd > start && source[end - 1] === next[nextEnd - 1]) { end--; nextEnd--; }
+	return [{ start, end, text: next.slice(start, nextEnd) }];
+};

package/scripts/lib/editor-source-files.mjs

@@ -0,0 +1,87 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { lstat, mkdir, open, rmdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { getSourcePageLocation, getSourceFileDefinition, sourceFileDefinitions } from './source-files.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+import { checkedPath } from './editor-site-files.mjs';
+import { escapeMarkdownHeading } from './site-node-create.mjs';
+
+export const siteTreeEditingApiVersion = 1;
+const stat = (filename) => lstat(filename).catch((error) => {
+	if (error.code === 'ENOENT') return null;
+	throw error;
+});
+
+export const editorPageLocation = getSourcePageLocation;
+export const editorSourceDefinition = getSourceFileDefinition;
+
+export const getEditorSourceFileChoices = async ({ siteRoot, directory }) => {
+	siteRoot = path.resolve(siteRoot);
+	directory = await checkedPath(siteRoot, directory);
+	const location = editorPageLocation(siteRoot, directory);
+	const directoryInfo = await stat(directory);
+	if ((!location && directory !== siteRoot) || (!directoryInfo?.isDirectory() && !(location?.isHome && !directoryInfo))) {
+		throw new Error('Select an existing page directory at a permitted location in this site.');
+	}
+	const content = await stat(path.join(directory, 'content.md'));
+	const names = location ? sourceFileDefinitions.filter((entry) => entry.location === 'page' && (entry.input === 'title' ? !content : content?.isFile() || location.isHome)).map((entry) => entry.name) : [];
+	if (directory === siteRoot || location?.isHome) {
+		names.push(...sourceFileDefinitions.filter((entry) => entry.location === 'site-config').map((entry) => `site-config/${entry.name}`));
+	}
+	if (directory === siteRoot) names.push('root/content.md', 'root/tree-theme.yaml');
+	const choices = [];
+	for (const name of names) {
+		const filename = path.join(name.startsWith('site-config/') || name.startsWith('root/') ? siteRoot : directory, name);
+		if (await stat(filename)) continue;
+		// A file or symlink occupying site-config must be repaired, not replaced.
+		const parent = await stat(path.dirname(filename));
+		if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) continue;
+		const definition = editorSourceDefinition(siteRoot, filename);
+		choices.push({ filename, name, description: definition.description, input: definition.input,
+			required: Boolean(definition.required), effect: definition.description });
+	}
+	return choices;
+};
+
+export const planEditorSourceFileCreation = async ({ siteRoot, directory, filename, value }) => {
+	siteRoot = path.resolve(siteRoot);
+	const choices = await getEditorSourceFileChoices({ siteRoot, directory });
+	const choice = choices.find((entry) => entry.filename === filename);
+	if (!choice) throw new Error('This file already exists or is not allowed here. Refresh Site Tree and review Add again.');
+	await checkedPath(siteRoot, filename);
+	const definition = editorSourceDefinition(siteRoot, filename);
+	let text = definition.text;
+	if (definition.input) {
+		if (typeof value !== 'string' || !value.trim() || /[\r\n]/.test(value)) throw new Error('Enter a non-empty, single line of text.');
+		text = definition.input === 'title' ? `# ${escapeMarkdownHeading(value.trim())}\n`
+			: `${definition.input}: ${JSON.stringify(value.trim())}\n`;
+	}
+	if (definition.schema) parseYamlConfig(text, filename, { schema: definition.schema });
+	const identity = async (location) => { const entry = await stat(location); return entry ? [entry.dev, entry.ino] : null; };
+	return { siteRoot, directory: path.resolve(directory), filename, value, text,
+		fingerprint: JSON.stringify([await identity(siteRoot), await identity(directory), filename, text]) };
+};
+
+export const createEditorSourceFile = async (plan) => {
+	const current = await planEditorSourceFileCreation(plan);
+	if (plan.fingerprint !== current.fingerprint) throw new Error('The selected directory changed. Review Add again.');
+	const parent = path.dirname(current.filename);
+	let createdDirectory = false;
+	let handle;
+	try {
+		if (!await stat(parent)) { await mkdir(parent); createdDirectory = true; }
+		await checkedPath(current.siteRoot, current.filename);
+		handle = await open(current.filename, 'wx');
+		await handle.writeFile(current.text, 'utf8');
+	} catch (error) {
+		if (handle) {
+			const owned = await handle.stat();
+			await handle.close(); handle = null;
+			const existing = await stat(current.filename);
+			if (existing?.ino === owned.ino && existing?.dev === owned.dev) await unlink(current.filename);
+		}
+		if (createdDirectory) await rmdir(parent).catch(() => {});
+		throw error;
+	} finally { await handle?.close(); }
+	return { sourcePath: current.filename };
+};

package/scripts/lib/editor-theme-help.mjs

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import { getSourcePageLocation } from './source-files.mjs';
+import { selectPageTheme } from './theme-packages.mjs';
+
+const presetHelp = (siteRoot, selection) => {
+	const origin = selection.sourceFiles.findLast((file) => file.config.preset !== undefined);
+	return `Preset: ${selection.selected.config.preset}\nPreset source: ${path.relative(siteRoot, origin.path)}`;
+};
+
+// Cache only within one tree read: dirty buffers and external changes must be
+// reflected on the next refresh. The engine resolver owns all inheritance rules.
+export const createEditorThemeHelp = ({ siteRoot, sources }) => {
+	const selections = new Map();
+	return async (directory, filename) => {
+		const includePageTheme = !filename || path.basename(filename) === 'page-theme.yaml';
+		const key = JSON.stringify([directory, includePageTheme]);
+		if (!selections.has(key)) selections.set(key, selectPageTheme({ siteRoot, sources,
+			pageDirectory: getSourcePageLocation(siteRoot, directory).pageDirectory, includePageTheme })
+			.catch(() => null));
+		const selection = await selections.get(key);
+		if (!selection) return 'Preset unavailable. Check the theme diagnostics.';
+		const file = filename && selection.sourceFiles.find((entry) => entry.path === filename);
+		const mode = !file ? '' : file.config.preset === undefined
+			? 'Modifies inherited settings. Add preset to replace the base.'
+			: getSourcePageLocation(siteRoot, directory).isHome && !includePageTheme
+				? 'Required base for the site. Its preset cannot be omitted.'
+				: 'Replaces inherited settings, even with the same preset name. Remove preset to resume inheritance.';
+		return [presetHelp(siteRoot, selection), mode].filter(Boolean).join('\n');
+	};
+};
+
+export const getEditorThemeRemovalHelp = async ({ siteRoot, filename, sources }) => {
+	const afterRemoval = new Map(sources);
+	afterRemoval.set(filename, null);
+	try {
+		const selection = await selectPageTheme({ siteRoot, sources: afterRemoval,
+			pageDirectory: getSourcePageLocation(siteRoot, path.dirname(filename)).pageDirectory,
+			includePageTheme: false });
+		return `After removal, the inherited tree theme is ${path.relative(siteRoot, selection.treeTheme.path)}.\n${presetHelp(siteRoot, selection)}`;
+	} catch {
+		return 'The inherited preset cannot be determined until the remaining theme errors are repaired.';
+	}
+};

package/scripts/lib/locale-registry.mjs

@@ -562,7 +562,7 @@ const normalizeLanguageTag = (value) => {
 
 const formatSupportedLanguages = () => supportedLocaleTags.join(', ');
 
-export const resolveLocale = (configuredLanguage = 'en', sourceLabel = 'site/config.yaml') => {
+export const resolveLocale = (configuredLanguage = 'en', sourceLabel = 'site/site-config/settings.yaml') => {
 	let parsed;
 	try {
 		parsed = normalizeLanguageTag(configuredLanguage);

package/scripts/lib/locales/en.mjs

@@ -61,7 +61,7 @@ export default Object.freeze({
 	pageSections: 'Sections',
 	previousImage: 'Previous image',
 	previousPage: 'Previous page',
-	returnHome: 'Go to the homepage',
+	returnHome: 'Home',
 	searchReturn: 'Back to {page}',
 	search: 'Search',
 	searchDescription: 'Search the published content on this site.',

package/scripts/lib/navigation-model.mjs

@@ -17,24 +17,11 @@ const getListedNodes = (nodes) => nodes.filter((node) => node.isHome || node.lis
 
 const getNodeDepth = (node) => node.depth ?? 1;
 
-const getTopLevelPagePath = (pagePath) => pagePath?.split('/')[0] ?? '';
-
-const getActiveBranchNodes = (nodes, currentPage) => {
-	if (!currentPage) return [];
-	if (currentPage.isHome) return nodes.filter((node) => node.isHome);
-
-	const rootPath = getTopLevelPagePath(currentPage.pagePath);
-	return nodes.filter((node) => (
-		node.pagePath === rootPath
-		|| node.pagePath?.startsWith(`${rootPath}/`)
-	));
-};
-
 export const getAutomaticNavigationMode = (nodes) => {
 	const listedNodes = getListedNodes(nodes);
 	if (listedNodes.length <= 1) return 'sections';
 
-	return listedNodes.some((node) => node.kind === 'category' || getNodeDepth(node) > 1)
+	return listedNodes.some((node) => getNodeDepth(node) > 1)
 		? 'tree'
 		: 'top';
 };
@@ -42,10 +29,6 @@ export const getAutomaticNavigationMode = (nodes) => {
 export const resolveNavigationModel = ({ mode = 'automatic', nodes }) => {
 	const requestedMode = assertNavigationMode(mode);
 	const listedNodes = getListedNodes(nodes);
-	const hasCategories = listedNodes.some((node) => node.kind === 'category');
-	if (hasCategories && requestedMode !== 'automatic' && requestedMode !== 'tree') {
-		throw new Error(`Navigation categories require tree navigation. Remove navigation.mode: ${requestedMode}, or set navigation.mode: tree.`);
-	}
 	const maximumDepth = listedNodes.reduce((maximum, node) => (
 		Math.max(maximum, getNodeDepth(node))
 	), 1);
@@ -57,33 +40,8 @@ export const resolveNavigationModel = ({ mode = 'automatic', nodes }) => {
 			: requestedMode,
 		requestedMode,
 		listedNodeCount: listedNodes.length,
-		hasCategories,
+		hasCategories: false,
 		hasNestedPages,
 		maximumDepth,
 	});
 };
-
-export const resolvePageContentsPlacement = ({
-	navigationMode,
-	nodes,
-	currentPage,
-	headingCount,
-}) => {
-	const listedNodes = getListedNodes(nodes);
-	const activeBranchNodes = getActiveBranchNodes(listedNodes, currentPage);
-	const activeBranchDepth = activeBranchNodes.reduce((maximum, node) => (
-		Math.max(maximum, getNodeDepth(node))
-	), 0);
-	const hasPageContents = headingCount >= 2;
-	const placement = currentPage?.isHome || navigationMode !== 'tree' || !hasPageContents
-		? 'none'
-		: activeBranchDepth <= 2
-			? 'page-tree'
-			: 'contents-rail';
-
-	return Object.freeze({
-		activeBranchDepth,
-		hasPageContents,
-		placement,
-	});
-};

package/scripts/lib/navigation-review.mjs

@@ -26,12 +26,11 @@ const getTreeMetrics = (root) => {
 	const nodes = flattenSiteNavigationTree([root]);
 	const rootDepth = root.node.depth;
 	return {
-		categoryCount: nodes.filter(({ node }) => node.kind === 'category').length,
 		maximumLevels: nodes.reduce((maximum, { node }) => (
 			Math.max(maximum, node.depth - rootDepth + 1)
 		), 1),
 		nodeCount: nodes.length,
-		pageCount: nodes.filter(({ node }) => node.kind === 'page').length,
+		pageCount: nodes.length,
 	};
 };
 
@@ -58,7 +57,7 @@ const getSiblingGroups = (roots) => {
 	return groups;
 };
 
-const toGraphError = (diagnostic) => ({
+const toGraphFinding = (diagnostic) => ({
 	code: diagnostic.code,
 	...(diagnostic.fix ? { fix: diagnostic.fix } : {}),
 	...(diagnostic.reference?.line ? { line: diagnostic.reference.line } : {}),
@@ -85,10 +84,8 @@ const getNavigationEntries = (siteStructure, linkGraph) => {
 	]));
 
 	return siteStructure.nodes.map((siteNode) => {
-		const page = siteNode.kind === 'page'
-			? pagesByDirectory.get(siteNode.pageDirectory)
-			: null;
-		if (siteNode.kind === 'page' && !page) {
+		const page = pagesByDirectory.get(siteNode.pageDirectory);
+		if (!page) {
 			throw new Error(`Navigation review could not find parsed content for ${siteNode.contentLabel}.`);
 		}
 
@@ -99,8 +96,8 @@ const getNavigationEntries = (siteStructure, linkGraph) => {
 				navigation: {
 					listed: siteNode.isHome || (page?.navigation.listed ?? true),
 				},
-				pathname: siteNode.kind === 'page' ? page.pathname : null,
-				title: siteNode.kind === 'page' ? page.title : siteNode.label,
+				pathname: page.pathname,
+				title: page.title,
 			},
 			page,
 			sections: [],
@@ -121,7 +118,7 @@ const getNavigationModes = ({ entries, listedEntries, requestedNavigationMode })
 	const modes = new Map();
 	const seenErrors = new Set();
 
-	for (const entry of entries.filter(({ node }) => node.kind === 'page')) {
+	for (const entry of entries) {
 		try {
 			const model = resolveNavigationModel({
 				currentPage: {
@@ -173,9 +170,7 @@ export const createNavigationReview = ({
 		requestedNavigationMode,
 	});
 
-	const pages = completeEntries
-		.filter(({ node }) => node.kind === 'page')
-		.map(({ headings, node, page }) => {
+	const pages = completeEntries.map(({ headings, node, page }) => {
 			const incomingPageLinkCount = resolvedPageReferences.filter(({ resolution }) => (
 				resolution.page.pathname === page.pathname
 			)).length;
@@ -200,21 +195,6 @@ export const createNavigationReview = ({
 			};
 		});
 
-	const categories = completeEntries
-		.filter(({ node }) => node.kind === 'category')
-		.map(({ children, node }) => ({
-			childCount: children.length,
-			depth: node.depth,
-			listed: listedPaths.has(node.pagePath),
-			listedChildCount: listedPaths.has(node.pagePath)
-				? (listedEntries.find(({ node: listedNode }) => listedNode.pagePath === node.pagePath)?.children.length ?? 0)
-				: 0,
-			parentPath: node.parentPagePath === null ? null : `/${node.parentPagePath}/`,
-			path: logicalPathname(node),
-			source: node.categorySourceLabel,
-			title: node.title,
-		}));
-
 	const branches = listedTree.map((root) => {
 		const metrics = getTreeMetrics(root);
 		const branchPaths = new Set(flattenSiteNavigationTree([root]).map(({ node }) => node.pagePath));
@@ -235,7 +215,8 @@ export const createNavigationReview = ({
 	const siblingGroups = getSiblingGroups(listedTree);
 	const widestSiblingCount = siblingGroups.reduce((maximum, group) => Math.max(maximum, group.count), 0);
 	const observations = [
-		...siteStructure.warnings.map(toStructureObservation),
+		...siteStructure.warnings.filter(({ code }) => code !== 'empty-category').map(toStructureObservation),
+		...linkGraph.diagnostics.filter(({ severity }) => severity === 'warning').map(toGraphFinding),
 	];
 	const unlistedPages = pages.filter(({ listed }) => !listed);
 	if (unlistedPages.length > 0) {
@@ -246,13 +227,6 @@ export const createNavigationReview = ({
 	}
 
 	const recommendations = [];
-	for (const category of categories.filter(({ listed, listedChildCount }) => listed && listedChildCount === 1)) {
-		recommendations.push({
-			code: 'single-child-category',
-			message: `${category.title} (${category.path}) has one listed child. Keep the category when its label adds useful orientation; otherwise consider moving the child to the category's parent.`,
-			path: category.path,
-		});
-	}
 	for (const branch of branches.filter(({ maximumLevels }) => maximumLevels >= thresholds.deepBranchLevels)) {
 		recommendations.push({
 			code: 'deep-branch',
@@ -279,7 +253,7 @@ export const createNavigationReview = ({
 
 	return {
 		command: 'navigation:review',
-		schemaVersion: 1,
+		schemaVersion: 2,
 		thresholds: {
 			deepBranchLevels: thresholds.deepBranchLevels,
 			sectionCount: thresholds.sectionCount,
@@ -287,10 +261,8 @@ export const createNavigationReview = ({
 		},
 		site: {
 			branchCount: branches.length,
-			categoryCount: categories.length,
 			effectiveNavigationModes,
 			internalReferenceCount: linkGraph.references.length,
-			listedCategoryCount: categories.filter(({ listed }) => listed).length,
 			listedPageCount: pages.filter(({ listed }) => listed).length,
 			maximumDepth: listedEntries.reduce((maximum, { node }) => Math.max(maximum, node.depth), 0),
 			pageCount: pages.length,
@@ -301,9 +273,8 @@ export const createNavigationReview = ({
 		branches,
 		siblingGroups,
 		pages,
-		categories,
 		errors: [
-			...linkGraph.diagnostics.map(toGraphError),
+			...linkGraph.diagnostics.filter(({ severity }) => severity === 'error').map(toGraphFinding),
 			...navigationErrors,
 		],
 		observations,
@@ -330,13 +301,13 @@ export const formatNavigationReviewText = (review) => {
 		'',
 		'Site',
 		`- Navigation: ${review.site.requestedNavigationMode} configured; ${review.site.effectiveNavigationModes.join(', ') || 'unresolved'} effective`,
-		`- Content: ${plural(review.site.pageCount, 'page')} (${review.site.listedPageCount} listed), ${plural(review.site.categoryCount, 'category', 'categories')} (${review.site.listedCategoryCount} listed)`,
+		`- Content: ${plural(review.site.pageCount, 'page')} (${review.site.listedPageCount} listed)`,
 		`- Structure: ${plural(review.site.branchCount, 'top-level branch', 'top-level branches')}, ${review.site.maximumDepth} listed ${review.site.maximumDepth === 1 ? 'level' : 'levels'}, widest sibling group ${review.site.widestSiblingCount}`,
 		`- Links: ${plural(review.site.internalReferenceCount, 'internal reference')}, ${review.site.resolvedPageLinkCount} resolved to pages`,
 		'',
 		'Branches',
 		...review.branches.map((branch) => (
-			`- ${branch.title} (${branch.path}; ${branch.kind}): ${plural(branch.pageCount, 'page')}, ${plural(branch.categoryCount, 'category', 'categories')}, ${plural(branch.maximumLevels, 'visible level')}; navigation ${branch.navigationModes.join(', ') || 'unresolved'}`
+			`- ${branch.title} (${branch.path}; ${branch.kind}): ${plural(branch.pageCount, 'page')}, ${plural(branch.maximumLevels, 'visible level')}; navigation ${branch.navigationModes.join(', ') || 'unresolved'}`
 		)),
 		'',
 		'Pages',
@@ -344,13 +315,6 @@ export const formatNavigationReviewText = (review) => {
 			`- ${page.title} (${page.pathname}; ${page.listed ? 'listed' : 'not listed'}): H2 ${page.h2Count}, H3 ${page.h3Count}; page links ${page.outgoingPageLinkCount} out / ${page.incomingPageLinkCount} in; navigation ${page.navigationMode ?? 'unresolved'}`
 		)),
 		'',
-		'Categories',
-		...(review.categories.length === 0
-			? ['- None.']
-			: review.categories.map((category) => (
-				`- ${category.title} (${category.path}; ${category.listed ? 'listed' : 'not listed'}): ${category.listedChildCount} listed of ${plural(category.childCount, 'direct child', 'direct children')}`
-			))),
-		'',
 		...formatFindingSection('Errors', review.errors),
 		'',
 		...formatFindingSection('Observations', review.observations),

package/scripts/lib/norna-markdown-blocks.mjs

@@ -56,7 +56,7 @@ export const nornaMarkdownBlockDefinitions = Object.freeze({
 					xl: value('Extra large', 'Use the largest card and image size.'),
 				}),
 			}),
-			width: field('Override the root theme\'s maximum width for this card list.', {
+			width: field('Override the shared theme\'s maximum width for this card list.', {
 				values: Object.freeze({
 					text: value('Text', 'Match the active body-text width, including a reader-selected reading width.'),
 					narrow: value('Narrow', 'Limit the complete card list to at most 48rem.'),

package/scripts/lib/page-aliases.mjs

@@ -154,7 +154,9 @@ export const createPageAliasModel = ({
 					contentFile,
 					fix: conflict.kind === 'page-alias'
 						? 'Keep the old URL on exactly one current page.'
-						: 'Remove or change the alias. A public URL can identify only one site resource.',
+						: conflict.kind === 'page'
+							? `Rename the page at ${conflict.label}, or remove ${pathname} from the previous addresses in ${contentLabel}. Removing it may break old links.`
+							: 'Remove or change the alias. A public URL can identify only one site resource.',
 					message: `Page alias "${pathname}" in ${contentLabel} conflicts with ${describeIdentity(conflict)}.`,
 					severity: 'error',
 				});

package/scripts/lib/page-model.mjs

@@ -12,8 +12,8 @@ export const parsePageDirectory = (pageDirectory, label = 'page directory') => {
 			`Invalid ${label} "${pageDirectory}". Page directories must use the form NNN-page-id, for example 010-getting-started. Page ids may contain only lowercase letters, numbers, and single hyphens.`,
 		);
 	}
-	if (match[1] === '000' && pageDirectory !== homePageDirectory) {
-		throw new Error(`Invalid ${label} "${pageDirectory}". The 000 prefix is reserved for ${homePageDirectory}.`);
+	if (match[1] === '000') {
+		throw new Error(`Invalid ${label} "${pageDirectory}". Child page orders must be 001–999. The homepage is root/content.md in the site container.`);
 	}
 
 	return {
@@ -27,6 +27,13 @@ const normalizePageDirectoryPath = (pageDirectoryPath) => pageDirectoryPath.repl
 
 export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page directory path') => {
 	const normalizedPath = normalizePageDirectoryPath(pageDirectoryPath);
+	if (normalizedPath === homePageDirectory) {
+		return {
+			pageDirectory: homePageDirectory, pageDirectories: [], pageId: 'home',
+			pageIds: [], pageOrder: 0, pageOrders: [], pagePath: '',
+			parentPagePath: null, depth: 0,
+		};
+	}
 	const segments = normalizedPath.split('/').filter(Boolean);
 
 	if (!normalizedPath || normalizedPath.startsWith('/') || normalizedPath.endsWith('/') || segments.length % 2 === 0) {
@@ -52,29 +59,18 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 	const pageIds = pageDirectories.map(({ pageId }) => pageId);
 	const pageOrders = pageDirectories.map(({ pageOrder }) => pageOrder);
 	const currentPage = pageDirectories.at(-1);
-	const homeIndex = pageDirectories.findIndex(({ pageDirectory }) => pageDirectory === homePageDirectory);
-	if (homeIndex > 0) {
-		throw new Error(`Invalid ${label} "${pageDirectoryPath}". ${homePageDirectory} is allowed only as a top-level page.`);
-	}
-	if (homeIndex === 0 && pageDirectories.length > 1) {
-		throw new Error(
-			`Invalid ${label} "${pageDirectoryPath}". ${homePageDirectory} is the homepage and cannot contain child pages. Place the page beside it under site/pages/, or below another non-home page.`,
-		);
-	}
-	const isHome = homeIndex === 0;
-	const logicalPageIds = isHome ? [] : pageIds;
-	const logicalPageOrders = isHome ? [] : pageOrders;
 
 	return {
 		pageDirectory: normalizedPath,
 		pageDirectories: pageDirectories.map(({ pageDirectory }) => pageDirectory),
 		pageId: currentPage.pageId,
-		pageIds: logicalPageIds,
+		pageIds,
 		pageOrder: currentPage.pageOrder,
-		pageOrders: logicalPageOrders,
-		pagePath: logicalPageIds.join('/'),
-		parentPagePath: logicalPageIds.length > 1
-			? logicalPageIds.slice(0, -1).join('/')
+		pageOrders,
+		pagePath: pageIds.join('/'),
+		// Navigation projects the root's children as top-level entries.
+		parentPagePath: pageIds.length > 1
+			? pageIds.slice(0, -1).join('/')
 			: null,
 		depth: pageDirectories.length,
 	};
@@ -82,10 +78,11 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 
 export const encodePageDirectoryPath = (pageDirectoryPath) => {
 	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
-	return pageDirectories.join(pageEntryPathSeparator);
+	return pageDirectories.length ? pageDirectories.join(pageEntryPathSeparator) : 'root';
 };
 
 export const decodePageDirectoryPath = (pageEntryPath, label = 'page entry path') => {
+	if (pageEntryPath === 'root') return homePageDirectory;
 	const pageDirectories = pageEntryPath.split(pageEntryPathSeparator);
 	if (pageDirectories.some((pageDirectory) => !pageDirectory)) {
 		throw new Error(`Invalid ${label} "${pageEntryPath}".`);