@janga/norna 0.7.27 → 0.7.28

package/scripts/lib/page-move-apply.mjs

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getSiteLinkGraph } from './site-link-graph.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+
+const writeFileAtomically = async (filePath, source, mode) => {
+	const temporaryPath = path.join(
+		path.dirname(filePath),
+		`.${path.basename(filePath)}.norna-${process.pid}-${randomUUID()}.tmp`,
+	);
+	try {
+		await writeFile(temporaryPath, source, { mode: mode & 0o777 });
+		await rename(temporaryPath, filePath);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
+};
+
+const assertSourcesUnchanged = async (plan) => {
+	for (const file of plan.sourceFiles) {
+		const currentSource = await readFile(file.contentPath, 'utf8');
+		if (currentSource !== file.source) {
+			throw new Error([
+				`Page move stopped because ${file.contentLabel} changed after the plan was created.`,
+				'Run the command again to build a fresh plan. No file was changed.',
+			].join('\n'));
+		}
+	}
+};
+
+const assertFinalSite = async (siteRoot, generatedRoutes) => {
+	const structure = await getSiteStructure({ siteRoot });
+	const graph = await getSiteLinkGraph({ siteStructure: structure, publicDir: path.join(siteRoot, 'public'), generatedRoutes });
+	const errors = graph.diagnostics.filter(({ severity }) => severity === 'error');
+	if (errors.length === 0) return;
+	throw new Error([
+		'Post-move link validation failed.',
+		...errors.flatMap((diagnostic) => [
+			`- ${diagnostic.message}`,
+			...(diagnostic.fix ? [`  Fix: ${diagnostic.fix}`] : []),
+		]),
+	].join('\n'));
+};
+
+export const applyPageMovePlan = async (plan, { siteRoot, generatedRoutes, renameDirectory = rename }) => {
+	await assertSourcesUnchanged(plan);
+	let collectionCreated = false;
+	let directoryMoved = false;
+	let fileWritten = false;
+
+	try {
+		if (plan.mode === 'move') {
+			if (!plan.destinationCollectionExists) {
+				await mkdir(plan.destinationCollectionDirectory);
+				collectionCreated = true;
+			}
+			try {
+				await renameDirectory(plan.sourceDirectory, plan.destinationDirectory);
+				directoryMoved = true;
+			} catch (error) {
+				if (error?.code === 'EXDEV') {
+					throw new Error('Page directories must stay on one filesystem so Norna can move the complete subtree atomically.');
+				}
+				throw error;
+			}
+		}
+
+		for (const change of plan.fileChanges) {
+			await writeFileAtomically(change.finalPath, change.updatedSource, change.mode);
+			fileWritten = true;
+		}
+		await assertFinalSite(siteRoot, generatedRoutes);
+	} catch (error) {
+		const changesStarted = directoryMoved || fileWritten;
+		const rollbackErrors = [];
+		if (directoryMoved) {
+			try {
+				await renameDirectory(plan.destinationDirectory, plan.sourceDirectory);
+				directoryMoved = false;
+			} catch (rollbackError) {
+				rollbackErrors.push(`Could not restore the page directory: ${rollbackError.message}`);
+			}
+		}
+
+		for (const change of changesStarted ? plan.fileChanges : []) {
+			try {
+				const restorePath = directoryMoved && change.finalPath !== change.originalPath
+					? change.finalPath
+					: change.originalPath;
+				await writeFileAtomically(restorePath, change.originalSource, change.mode);
+			} catch (rollbackError) {
+				rollbackErrors.push(`Could not restore ${change.contentLabel}: ${rollbackError.message}`);
+			}
+		}
+
+		if (collectionCreated && !directoryMoved) {
+			try {
+				await rmdir(plan.destinationCollectionDirectory);
+			} catch (rollbackError) {
+				if (rollbackError?.code !== 'ENOENT' && rollbackError?.code !== 'ENOTEMPTY') {
+					rollbackErrors.push(`Could not remove the newly created pages directory: ${rollbackError.message}`);
+				}
+			}
+		}
+
+		throw new Error([
+			error instanceof Error ? error.message : String(error),
+			rollbackErrors.length === 0
+				? (changesStarted
+					? 'The original page directory and content files were restored.'
+					: 'No source file was changed.')
+				: 'Rollback was incomplete. Inspect these paths before running page:move again:',
+			...rollbackErrors.map((message) => `- ${message}`),
+		].join('\n'));
+	}
+};

package/scripts/lib/page-move-plan.mjs

@@ -11,6 +11,7 @@ import {
 	toPosixPath,
 } from './site-content.mjs';
 import { getSiteNodePathname } from './site-page-urls.mjs';
+import { changeYamlField } from './yaml-source-edit.mjs';
 
 const pagePathPattern = /^\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)+$/;
 
@@ -61,12 +62,6 @@ const applyReplacements = (source, replacements) => {
 	return updated;
 };
 
-const insertBeforeTrailingBlankLines = (lines, additions) => {
-	let index = lines.length;
-	while (index > 0 && !lines[index - 1].trim()) index -= 1;
-	lines.splice(index, 0, ...additions);
-};
-
 const addPageAliasToSource = (source, alias, label) => {
 	const eol = source.includes('\r\n') ? '\r\n' : '\n';
 	const { body, frontmatter, frontmatterBody } = splitSiteFile(source, label);
@@ -88,64 +83,31 @@ const addPageAliasToSource = (source, alias, label) => {
 		};
 	}
 
-	const lines = frontmatterBody.split(/\r?\n/);
-	const pageIndex = lines.findIndex((line) => /^page:\s*(?:#.*)?$/.test(line));
-	if (data.page && pageIndex < 0) {
-		throw new Error([
-			`Cannot add ${alias} to ${label} without rewriting its flow-style page metadata.`,
-			'Use block YAML beginning with "page:" on its own line, or rerun with --no-aliases.',
-		].join('\n'));
-	}
-
-	if (pageIndex < 0) {
-		insertBeforeTrailingBlankLines(lines, [
-			'page:',
-			'  aliases:',
-			`    - ${alias}`,
-		]);
-	} else {
-		let pageEnd = lines.length;
-		for (let index = pageIndex + 1; index < lines.length; index += 1) {
-			const line = lines[index];
-			if (!line.trim() || line.trimStart().startsWith('#')) continue;
-			if (!line.startsWith(' ')) {
-				pageEnd = index;
-				break;
-			}
-		}
-
-		const aliasesIndex = lines.findIndex((line, index) => (
-			index > pageIndex
-			&& index < pageEnd
-			&& /^ {2}aliases:\s*(?:#.*)?$/.test(line)
-		));
-		if (data.page?.aliases && aliasesIndex < 0) {
-			throw new Error([
-				`Cannot add ${alias} to ${label} without rewriting its flow-style aliases list.`,
-				'Use a block list below "  aliases:", or rerun with --no-aliases.',
-			].join('\n'));
-		}
-
-		if (aliasesIndex < 0) {
-			lines.splice(pageIndex + 1, 0, '  aliases:', `    - ${alias}`);
-		} else {
-			let lastAliasIndex = -1;
-			for (let index = aliasesIndex + 1; index < pageEnd; index += 1) {
-				if (/^ {4}-\s+/.test(lines[index])) lastAliasIndex = index;
-			}
-			if (lastAliasIndex < 0) {
-				throw new Error(`Cannot find the block-list entries below "aliases:" in ${label}.`);
-			}
-			lines.splice(lastAliasIndex + 1, 0, `    - ${alias}`);
-		}
+	let yaml;
+	try {
+		yaml = changeYamlField(frontmatterBody, ['page', 'aliases'], [...(data.page?.aliases ?? []), alias], eol);
+	} catch (error) {
+		throw Object.assign(new Error(`Cannot preserve ${alias} in ${label}. ${error.message}`), { sourcePath: label });
 	}
 
 	return {
 		changed: true,
-		source: `---${eol}${lines.join(eol)}${eol}---${eol}${body}`,
+		source: `---${eol}${yaml.replace(/\r?\n$/, '')}${eol}---${eol}${body}`,
 	};
 };
 
+const removePageAliasFromSource = (source, alias, label) => {
+	const { body, frontmatter, frontmatterBody } = splitSiteFile(source, label);
+	if (!frontmatter) return source;
+	const data = parseContentFrontmatter(frontmatterBody, label);
+	if (!data.page?.aliases?.includes(alias)) return source;
+	const eol = source.includes('\r\n') ? '\r\n' : '\n';
+	const remaining = data.page.aliases.filter((entry) => entry !== alias);
+	const yaml = changeYamlField(frontmatterBody, ['page', 'aliases'], remaining.length ? remaining : undefined, eol);
+	if (!yaml.trim()) return body.replace(/^\r?\n/, '');
+	return `---${eol}${yaml.replace(/\r?\n$/, '')}${eol}---${eol}${body}`;
+};
+
 const normalizeMovePathname = (value, optionName) => {
 	if (value === '/') return { pagePath: '', pathname: '/' };
 	if (typeof value !== 'string' || !pagePathPattern.test(value)) {
@@ -396,6 +358,7 @@ const formatGraphDiagnostics = (diagnostics) => diagnostics.flatMap((diagnostic)
 export const createPageMovePlan = async ({
 	from,
 	graph,
+	generatedRoutes,
 	order = null,
 	preserveAliases = true,
 	publicFiles,
@@ -559,6 +522,9 @@ export const createPageMovePlan = async ({
 		})));
 
 		const mapping = mappingByContentPath.get(contentPath);
+		if (mapping && page.aliases.includes(mapping.newPathname)) {
+			updatedSource = removePageAliasFromSource(updatedSource, mapping.newPathname, page.contentFile.contentLabel);
+		}
 		if (mapping && preserveAliases) {
 			const aliasResult = addPageAliasToSource(updatedSource, mapping.oldPathname, page.contentFile.contentLabel);
 			updatedSource = aliasResult.source;
@@ -614,11 +580,13 @@ export const createPageMovePlan = async ({
 		pageDocuments: virtualPageDocuments,
 		publicFiles,
 		siteStructure: virtualStructure,
+		generatedRoutes,
 	});
-	if (virtualGraph.diagnostics.length > 0) {
+	const errors = virtualGraph.diagnostics.filter(({ severity }) => severity === 'error');
+	if (errors.length > 0) {
 		throw new Error([
 			'Page move preflight failed. No file was changed.',
-			...formatGraphDiagnostics(virtualGraph.diagnostics),
+			...formatGraphDiagnostics(errors),
 		].join('\n'));
 	}
 

package/scripts/lib/presentation.mjs

@@ -453,7 +453,7 @@ export const getPresentationCssVariables = (presentation) => {
 	return variables;
 };
 
-const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'theme.yaml') => {
+const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'root/tree-theme.yaml') => {
 	const surfaces = sectionBackgroundPatterns[pattern];
 	if (!surfaces) {
 		throw new Error(`sections.backgroundPattern must be one of ${Object.keys(sectionBackgroundPatterns).join(', ')} in ${sourceLabel}.`);
@@ -462,7 +462,7 @@ const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'theme.yaml') =>
 	return surfaces;
 };
 
-export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
+export const resolveThemePresentation = (theme, sourceLabel = 'root/tree-theme.yaml') => {
 	const normalizedTheme = resolveThemeConfig(theme, sourceLabel);
 	const paletteName = normalizedTheme.palette ?? 'near-monochrome';
 	const palette = getPresentationPalette(paletteName);
@@ -509,7 +509,7 @@ export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 
 export const assertSectionBackgroundPatternCompatibility = (
 	theme,
-	sourceLabel = 'theme.yaml',
+	sourceLabel = 'root/tree-theme.yaml',
 	navigationMode = 'sections',
 ) => {
 	const requestedPattern = theme?.sections?.backgroundPattern;

package/scripts/lib/project-config.mjs

@@ -1,4 +1,6 @@
 import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import {
 	validateConfigYamlStructure,
 } from './site-content.mjs';
@@ -11,6 +13,7 @@ import { navigationModeNames } from './navigation-model.mjs';
 import {
 	siteConfigLabel,
 	siteConfigPath,
+	siteDir,
 	siteThemeLabel,
 } from './site-paths.mjs';
 import { localEditorNames, normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
@@ -20,6 +23,9 @@ import { resolveThemeConfig } from './theme-presets.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
 
 const readSiteConfig = async () => {
+	if (existsSync(path.join(siteDir, 'site-config/site-theme.yaml')) || existsSync(path.join(siteDir, 'root/theme.yaml')) || existsSync(path.join(siteDir, 'config.yaml')) || existsSync(path.join(siteDir, 'page-theme.yaml')) || existsSync(path.join(siteDir, 'sitewide-content.yaml'))) {
+		throw new Error('This site has configuration files in the former locations. Stop its development server and follow the source-layout reference to place technical settings in site-config/ and page files in root/. Move the shared theme to root/tree-theme.yaml with an explicit preset and homepage-only overrides to root/page-theme.yaml. Automatic historical conversion is not provided.');
+	}
 	const source = await readFile(siteConfigPath, 'utf8').catch((error) => {
 		if (error?.code === 'ENOENT') {
 			throw new Error(`${siteConfigLabel} is required. Create it before running Norna.`);
@@ -302,13 +308,6 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 		defaultImagePresentation,
 		sourceLabel,
 	);
-	if (imagePresentation === 'prose-aligned' && rawImagesConfig.maxAvailableHeightPercent !== undefined) {
-		throw new Error([
-			`images.maxAvailableHeightPercent cannot be used with images.presentation "prose-aligned" in ${sourceLabel}.`,
-			'Prose-aligned images follow available horizontal space instead of a viewport-height limit.',
-			'Remove images.maxAvailableHeightPercent or set images.presentation to "centered-fit".',
-		].join('\n'));
-	}
 
 	return Object.freeze({
 		layout: Object.freeze({
@@ -371,7 +370,7 @@ export const resolveNavigationConfig = (config, sourceLabel = siteConfigLabel) =
 	if (Object.hasOwn(rawNavigation, 'sectionTracking')) {
 		throw new Error([
 			`navigation.sectionTracking is no longer supported in ${sourceLabel}.`,
-			'Section tracking is automatic on pages with a contents rail.',
+			'Section tracking is automatic on tree-navigation pages with H2 headings.',
 			'Remove navigation.sectionTracking.',
 		].join('\n'));
 	}

package/scripts/lib/schema-definitions.mjs

@@ -167,13 +167,6 @@ const themeLayout = z.object({
 	gutter: responsiveCssLength.optional().describe('Horizontal page gutter as one value or separate desktop and mobile values.'),
 	spacing: themeLayoutSpacing.optional().describe('Fine-grained spacing overrides.'),
 }).strict().describe('Optional layout overrides applied after the preset.');
-const pageThemeLayout = z.object({
-	contentSpacing: contentSpacing.optional().describe('Page content spacing. Descendant pages inherit this value.'),
-	textWidth: textWidth.optional().describe('Body-text line length. Descendant pages inherit this value.'),
-}).strict().refine(
-	(value) => value.contentSpacing !== undefined || value.textWidth !== undefined,
-	'Specify contentSpacing, textWidth, or both.',
-).describe('Page-local layout settings inherited by descendant pages.');
 const themeImages = z.object({
 	presentation: imagePresentation.optional().describe('Managed-image presentation method. Omit this to keep the selected preset or inherited page setting.'),
 	width: visualCssLength.optional().describe('Maximum managed-image width. Omit this to keep the selected preset.'),
@@ -182,25 +175,19 @@ const themeImages = z.object({
 }).strict().describe('Optional defaults for placing managed images inside the page content area. Persistent navigation remains outside this area.');
 const themeCardList = z.object({
 	width: cardListWidth,
-}).strict().describe('Site-wide card-list defaults.');
+}).strict().describe('Card-list defaults.');
 const themeBlocks = z.object({
 	cardList: themeCardList.optional(),
 }).strict().refine(
 	(value) => value.cardList !== undefined,
 	'Specify cardList.',
-).describe('Optional site-wide defaults for structured Norna content blocks.');
+).describe('Optional defaults for structured Norna content blocks.');
 const configNavigation = z.object({
 	mode: navigationMode.optional().describe('How Norna presents the discovered page and heading hierarchy. Omit this to select automatic.'),
 }).strict().describe('Site-wide navigation behavior.');
 const themeSections = z.object({
 	backgroundPattern: backgroundPattern.optional().describe('Section background pattern. Alternating and accented create full-width bands with sections or top navigation; tree navigation requires uniform.'),
 }).strict().describe('Defaults for page section presentation.');
-const pageThemeSections = z.object({
-	backgroundPattern: backgroundPattern.optional().describe('Section background sequence inherited by descendant pages. Non-uniform patterns are invalid with tree navigation.'),
-}).strict().refine(
-	(value) => value.backgroundPattern !== undefined,
-	'Specify backgroundPattern.',
-).describe('Page-local section presentation inherited by descendant pages.');
 const pageNavigation = z.object({
 	listed: z.boolean().optional().default(true).describe('List this page in site navigation. The page remains public when false.'),
 }).strict();
@@ -210,6 +197,7 @@ const pageAlias = z.string().regex(
 ).describe('Previous site-relative URL that permanently identifies this page.');
 const pageMetadata = z.object({
 	description: z.string().min(1).optional().describe('Page description used in metadata, social previews and generated child-page lists.'),
+	listChildren: z.boolean().optional().describe('Append links to every listed direct child page after this page\'s authored content.'),
 	aliases: z.array(pageAlias)
 		.min(1)
 		.refine((values) => new Set(values).size === values.length, 'Page aliases must be unique within the page.')
@@ -251,9 +239,9 @@ const siteShape = {
 };
 
 const themeVisualShape = {
-	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
+	preset: themePreset.optional().describe('Select a new visual base, discarding all inherited theme values. Required in root/tree-theme.yaml; omit elsewhere to modify inherited values. Even the same preset starts a new base.'),
 	appearance: themeAppearance.optional(),
-	corners: cornerTreatment.optional().describe('Site-wide corner treatment. Omit this to use the selected preset.'),
+	corners: cornerTreatment.optional().describe('Corner treatment. Omit this to use the selected preset.'),
 	layout: themeLayout.optional(),
 	images: themeImages.optional(),
 	blocks: themeBlocks.optional(),
@@ -262,44 +250,29 @@ const themeVisualShape = {
 	sections: themeSections.optional(),
 };
 
-const pageThemeShape = {
-	layout: pageThemeLayout.optional(),
-	images: themeImages.optional(),
-	sections: pageThemeSections.optional(),
-};
-
 const sitewideShape = {
 	logo: sitewideLogo.optional(),
 	banners: banners.describe('Site-wide dismissible notices.'),
 	footer: sitewideFooter.optional().describe('Site-wide footer content.'),
 };
 
-const categoryShape = {
-	label: z.string().trim().min(1).describe('Navigation label for a group of child pages without an authored page body.'),
-};
-
 export const schemaTopLevelKeys = Object.freeze({
 	config: Object.freeze(Object.keys(configShape)),
-	category: Object.freeze(Object.keys(categoryShape)),
 	content: Object.freeze(Object.keys(siteShape)),
 	sitewide: Object.freeze(Object.keys(sitewideShape)),
 	theme: Object.freeze(Object.keys(themeVisualShape)),
-	pageTheme: Object.freeze(Object.keys(pageThemeShape)),
+	pageTheme: Object.freeze(Object.keys(themeVisualShape)),
 });
 
 export const configSchema = z.object(configShape).strict()
 	.describe('Technical settings for one Norna site. Additional pages cannot provide technical configuration.');
-export const categorySchema = z.object(categoryShape).strict()
-	.describe('A navigation group without an authored page body. Opening its URL redirects when its first listed direct child is a page; otherwise it shows a generated child list.');
 export const siteSchema = z.object(siteShape).strict()
 	.describe('Frontmatter for a homepage or additional page content.md file.');
 export const themeVisualSchema = z.object(themeVisualShape).strict()
-	.describe('Site-wide visual identity and default page presentation. Presets may be selected only in the root theme.');
-export const pageThemeSchema = z.object(pageThemeShape).strict()
-	.refine(
-		(value) => value.layout !== undefined || value.images !== undefined || value.sections !== undefined,
-		'Specify layout, images, sections, or a combination of them.',
-	)
-	.describe('Limited page presentation overrides inherited by descendant pages. Site colors, corners, typography, content-block defaults and navigation remain global.');
+	.describe('Visual settings for this page and its descendants. Omit preset to modify inherited values; an explicit preset replaces the complete inherited base, even when the preset name is unchanged.');
+export const rootThemeSchema = z.object({ ...themeVisualShape, preset: themePreset }).strict()
+	.describe('Required root/tree-theme.yaml. Select a preset for the site, then add the visual settings you want to override.');
+export const pageThemeSchema = z.object(themeVisualShape).strict()
+	.describe('Visual settings for this page only. Omit preset to modify the active tree theme; an explicit preset replaces that base. Descendants keep their tree theme.');
 export const sitewideSchema = z.object(sitewideShape).strict()
 	.describe('Editorial content and optional navigation logo display settings shared by every page.');

package/scripts/lib/schema-editor-metadata.mjs

@@ -151,7 +151,7 @@ const addSitewideLogoHelp = (jsonSchema) => {
 const addConfigHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
 		yamlExample('url: https://example.com/'),
-		'`config.yaml` contains the few technical settings shared by the complete site.',
+		'`site-config/settings.yaml` contains the few technical settings shared by the complete site.',
 		documentationLink('Configuration reference', 'configuration.md'),
 	].join('\n\n');
 	addHelp(jsonSchema, 'url', [
@@ -283,7 +283,7 @@ const addThemeHelp = (jsonSchema) => {
 	], presentationPaletteNames);
 	addHelp(jsonSchema, 'appearance', [
 		yamlExample('appearance:\n  default: system'),
-		'Selects the initial Appearance. The Appearance choice is always available in the site-wide Display panel. Omit this setting to follow the visitor\'s system preference.',
+		'Selects the initial Appearance. The Appearance choice is always available in the site-wide Display panel. Omit this setting to keep the inherited or preset value.',
 		documentationLink('Appearance', 'theme.md', 'appearance'),
 	]);
 	addFieldHelp(jsonSchema, 'appearance.default', 'appearance:\n  default: system', 'theme.md', 'appearance', ['system', 'light', 'dark']);
@@ -463,49 +463,10 @@ const addThemeHelp = (jsonSchema) => {
 	})]);
 };
 
-const addPageThemeHelp = (jsonSchema) => {
-	jsonSchema.markdownDescription = [
-		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
-		'A limited theme in a page or category directory may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Tree navigation requires a uniform section background. Site colors, corners, typography, content-block defaults and navigation stay consistent.',
-		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
-	].join('\n\n');
-	addHelp(jsonSchema, 'layout', [
-		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
-		'Adjusts body-text line length and vertical content spacing for pages below this directory.',
-		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
-	]);
-	addFieldHelp(jsonSchema, 'layout.textWidth', 'layout:\n  textWidth: narrow', 'theme.md', 'page-themes', ['narrow', 'normal', 'wide']);
-	addFieldHelp(jsonSchema, 'layout.contentSpacing', 'layout:\n  contentSpacing: compact', 'theme.md', 'page-themes', ['compact', 'normal', 'spacious']);
-	addHelp(jsonSchema, 'images', [
-		yamlExample('images:\n  presentation: prose-aligned\n  width: 900px'),
-		'Adjusts managed-image presentation and sizing inside the content area for pages below this directory. Persistent navigation remains outside this area.',
-		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
-	]);
-	const imageFields = [
-		['images.presentation', 'images:\n  presentation: prose-aligned'],
-		['images.width', 'images:\n  width: 900px'],
-		['images.maxAvailableWidthPercent', 'images:\n  maxAvailableWidthPercent:\n    desktop: 100\n    mobile: 100'],
-		['images.maxAvailableWidthPercent.desktop', 'images:\n  maxAvailableWidthPercent:\n    desktop: 100'],
-		['images.maxAvailableWidthPercent.mobile', 'images:\n  maxAvailableWidthPercent:\n    mobile: 100'],
-		['images.maxAvailableHeightPercent', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74\n    mobile: 68'],
-		['images.maxAvailableHeightPercent.desktop', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74'],
-		['images.maxAvailableHeightPercent.mobile', 'images:\n  maxAvailableHeightPercent:\n    mobile: 68'],
-	];
-	for (const [propertyPath, example] of imageFields) {
-		addFieldHelp(jsonSchema, propertyPath, example, 'theme.md', 'image-sizing');
-	}
-	addHelp(jsonSchema, 'sections', [
-		yamlExample('sections:\n  backgroundPattern: alternating'),
-		'Adjusts the H2 section background pattern for pages below this directory. Alternating and accented create full-width bands but are invalid when navigation resolves to tree.',
-		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
-	]);
-	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'page-themes', ['uniform', 'alternating', 'accented']);
-};
-
 const addSitewideHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
 		yamlExample('footer:\n  copyrightMessage: Copyright Example Owner.'),
-		'`sitewide-content.yaml` optionally defines banners, footer content, and logo display settings shared by every page.',
+		'`site-config/shared-content.yaml` optionally defines banners, footer content, and logo display settings shared by every page.',
 		documentationLink('Site-wide content reference', 'sitewide-content.md'),
 	].join('\n\n');
 	addSitewideLogoHelp(jsonSchema);
@@ -583,9 +544,10 @@ const addContentHelp = (jsonSchema) => {
 	]);
 	addHelp(jsonSchema, 'page.description', [
 		yamlExample('page:\n  description: About this project.'),
-		'A page-specific description used in metadata and social previews. Generated child-page and category lists can show it beside the page title; it is not inserted into the page body.',
+		'A page-specific description used in metadata and social previews. Generated child-page lists can show it beside the page title; it is not inserted into the page body.',
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	], ['About this project.']);
+	addFieldHelp(jsonSchema, 'page.listChildren', 'page:\n  listChildren: true', 'pages.md', 'list-child-pages', [true, false]);
 	addHelp(jsonSchema, 'page.aliases', [
 		yamlExample('page:\n  aliases:\n    - /old-about/'),
 		'Lists previous site-relative URLs that permanently identify this page. The page containing the list is always the target. Paths omit the configured base path and are excluded from the sitemap.',
@@ -604,28 +566,19 @@ const addContentHelp = (jsonSchema) => {
 	addFieldHelp(jsonSchema, 'navigation.listed', 'navigation:\n  listed: false', 'pages.md', 'navigation', [true, false]);
 };
 
-const addCategoryHelp = (jsonSchema) => {
-	jsonSchema.markdownDescription = [
-		yamlExample('label: Guides'),
-		'`category.yaml` groups child pages without editorial content. Its URL opens the first listed direct page, or a generated child list when the first child is a category.',
-		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
-	].join('\n\n');
-	addHelp(jsonSchema, 'label', [
-		yamlExample('label: Guides'),
-		'The category label shown in global navigation, tree navigation, mobile navigation, and breadcrumbs.',
-		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
-	]);
-};
-
 export const applySchemaEditorMetadata = (filename, jsonSchema) => {
 	addValueDescriptions(jsonSchema);
-	if (filename === 'category.schema.json') addCategoryHelp(jsonSchema);
 	if (filename === 'config.schema.json') {
 		addLanguageSuggestions(jsonSchema);
 		addConfigHelp(jsonSchema);
 	}
-	if (filename === 'theme.schema.json') addThemeHelp(jsonSchema);
-	if (filename === 'page-theme.schema.json') addPageThemeHelp(jsonSchema);
+	if (['root-theme.schema.json', 'theme.schema.json', 'page-theme.schema.json'].includes(filename)) {
+		addThemeHelp(jsonSchema);
+		jsonSchema.markdownDescription = [yamlExample(filename === 'root-theme.schema.json' ? 'preset: documentation' : 'layout:\n  textWidth: wide'), jsonSchema.description, documentationLink('Theme inheritance', 'theme.md', 'page-themes')].join('\n\n');
+		addHelp(jsonSchema, 'preset', [yamlExample('preset: documentation'),
+			'Selects a new base and discards inherited theme values, even when the preset name is unchanged. Required in root/tree-theme.yaml. Omit in other theme files to modify inherited values.',
+			documentationLink('Theme inheritance', 'theme.md', 'page-themes'), documentationLink('Preset reference', 'theme.md', 'theme-presets')]);
+	}
 	if (filename === 'sitewide-content.schema.json') addSitewideHelp(jsonSchema);
 	if (filename === 'content-frontmatter.schema.json') addContentHelp(jsonSchema);
 	return jsonSchema;

package/scripts/lib/schema-value-definitions.mjs

@@ -26,7 +26,7 @@ export const schemaValueDefinitions = Object.freeze([
 		automatic: option('Automatic', 'Choose one site-wide navigation presentation from the listed page hierarchy. This is the default.'),
 		sections: option('Sections', 'Keep a one-page site title and its H2 sections in sticky page navigation.'),
 		top: option('Top', 'Keep top-level pages in the global row and give the current page section navigation when needed.'),
-		tree: option('Tree', 'Keep top-level areas global and add a persistent left page tree. Deep branches can add a right H2/H3 contents rail.'),
+		tree: option('Tree', 'Group destinations in menus and show the selected group’s pages and H2 links in a left tree.'),
 	}),
 	definition(['vscode'], {
 		vscode: option('Visual Studio Code', 'Open the current page source in the locally installed Visual Studio Code application.'),

package/scripts/lib/site-content.mjs

@@ -22,9 +22,6 @@ const frontmatterDelimiterRegex = /^---\s*$/;
 const knownConfigTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.config);
 const knownContentTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.content);
 const knownThemeTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.theme);
-const knownPageThemeTopLevelFrontmatterKeys = new Set(
-	schemaTopLevelKeys.pageTheme,
-);
 const knownSitewideTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.sitewide);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
@@ -57,6 +54,7 @@ const knownNestedFrontmatterKeys = new Set([
 	'listed',
 	'logo',
 	'lineHeight',
+	'listChildren',
 	'maxAvailableHeightPercent',
 	'maxAvailableWidthPercent',
 	'mobile',
@@ -154,28 +152,19 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		} else if (fileKind === 'content' && key === 'images') {
 			fix = 'Put local image references in image-stack or image-carousel blocks in the Markdown body.';
 		} else if (fileKind === 'content' && knownThemeTopLevelFrontmatterKeys.has(key)) {
-			fix = `Move "${key}:" to theme.yaml. Visual settings do not belong in content frontmatter.`;
+			fix = `Move "${key}:" to site-config/site-theme.yaml. Visual settings do not belong in content frontmatter.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {
-			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in config.yaml.`;
-			fix = 'Set the navigation mode under "navigation:" in config.yaml.';
+			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in site-config/settings.yaml.`;
+			fix = 'Set the navigation mode under "navigation:" in site-config/settings.yaml.';
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'shape') {
-			message = fileKind === 'page theme'
-				? `Frontmatter line ${lineNumber}: "shape" was replaced by the site-wide "corners" setting, which page themes cannot override.`
-				: `Frontmatter line ${lineNumber}: "shape" was replaced by "corners". Use "square" or replace the old "soft" value with "rounded".`;
-			fix = fileKind === 'page theme'
-				? 'Remove "shape:" from this page theme. Set "corners: square" or "corners: rounded" in the root theme.yaml when an override is needed.'
-				: 'Replace "shape:" with "corners:". Use "square" or replace the old "soft" value with "rounded".';
+			message = `Frontmatter line ${lineNumber}: "shape" was replaced by "corners".`;
+			fix = 'Use "corners: square" or "corners: rounded"; replace the old "soft" value with "rounded".';
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'colorMode') {
 			message = `Frontmatter line ${lineNumber}: Theme setting "colorMode" was replaced by "appearance".`;
-			fix = fileKind === 'page theme'
-				? 'Remove "colorMode:" from this page theme. Set "appearance:" in the root theme.yaml when an override is needed.'
-				: 'Replace "colorMode:" with "appearance:".';
+			fix = 'Replace "colorMode:" with "appearance:".';
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'readerControls') {
 			message = `Frontmatter line ${lineNumber}: Theme setting "readerControls" was removed. Appearance and reading width are always available; Focus reading follows tree navigation.`;
 			fix = 'Remove "readerControls:". Use "appearance.default" for the initial Appearance; reading width is always available and tree navigation provides Focus reading.';
-		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'corners', 'palette', 'typography'].includes(key)) {
-			message = `Frontmatter line ${lineNumber}: page themes may not define site-wide visual identity through "${key}".`;
-			fix = `Move "${key}:" to the root theme.yaml. Page themes may set only layout.textWidth, layout.contentSpacing, images, and sections.backgroundPattern.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && ['logo', 'site'].includes(key)) {
 			message = `Frontmatter line ${lineNumber}: ${fileKind} may not define navigation logo settings. Optional logo display settings belong under "logo:" in ${sitewideContentLabel}.`;
 			fix = `Move only the logo display settings under "logo:" in ${sitewideContentLabel}; the homepage Markdown H1 supplies navigation text and logo alternative text.`;
@@ -223,12 +212,6 @@ export const validateThemeYamlStructure = (frontmatter, addIssue) =>
 		fileKind: 'theme',
 	});
 
-export const validatePageThemeYamlStructure = (frontmatter, addIssue) =>
-	validateFrontmatterStructure(frontmatter, addIssue, {
-		knownTopLevelFrontmatterKeys: knownPageThemeTopLevelFrontmatterKeys,
-		fileKind: 'page theme',
-	});
-
 export const validateSitewideYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownSitewideTopLevelFrontmatterKeys,