@janga/norna 0.7.16 → 0.7.18

package/scripts/lib/site-content.mjs

@@ -2,28 +2,31 @@ import { access, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	siteContentLabel,
-	siteContentPath,
 	siteDir,
-	siteImagesDir,
+	siteDirLabel,
+	homePageDirectory,
 	siteImagesLabel,
-	siteRoutesDir,
-	siteRoutesLabel,
+	sitePagesDir,
+	sitePagesLabel,
+	sitewideContentLabel,
 } from './site-paths.mjs';
-import { parseRouteDirectory } from './route-model.mjs';
+import { parsePageDirectoryPath } from './page-model.mjs';
+import { getMarkdownHeadings } from './heading-ids.mjs';
+import { schemaTopLevelKeys } from './schema-definitions.mjs';
 
 export const rasterImageExtensions = new Set(['.jpg', '.jpeg', '.png']);
 export const staticImageExtensions = new Set(['.svg']);
 export const supportedImageExtensions = new Set([...rasterImageExtensions, ...staticImageExtensions]);
 
-const h2Regex = /^##\s+.*$/gm;
-const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
 const deprecatedInlineStyleReferenceRegex = /\[[^\]\n]+\]\{\.([a-z][a-z0-9-]*)\}/g;
 const frontmatterDelimiterRegex = /^---\s*$/;
-const knownConfigTopLevelFrontmatterKeys = new Set(['url', 'language', 'scrollBehavior']);
-const knownContentTopLevelFrontmatterKeys = new Set(['title', 'description', 'navigation', 'sections']);
-const knownThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'images', 'typography', 'palette', 'sectionSurfaces']);
-const knownRouteThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'images', 'typography', 'palette', 'sectionSurfaces']);
-const knownSitewideTopLevelFrontmatterKeys = new Set(['navigation', 'banners', 'footer']);
+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',
 	'alt',
@@ -31,7 +34,7 @@ const knownNestedFrontmatterKeys = new Set([
 	'blockGap',
 	'caption',
 	'carousel',
-	'density',
+	'contentSpacing',
 	'desktop',
 	'fontFamily',
 	'from',
@@ -45,11 +48,10 @@ const knownNestedFrontmatterKeys = new Set([
 	'heading',
 	'headings',
 	'id',
-	'include',
 	'image',
 	'imageGap',
 	'images',
-	'label',
+	'listed',
 	'logo',
 	'lineHeight',
 	'maxAvailableHeightPercent',
@@ -63,13 +65,15 @@ const knownNestedFrontmatterKeys = new Set([
 	'preset',
 	'profile',
 	'rhythm',
-	'sections',
 	'sectionGap',
-	'sectionSurfaces',
+	'backgroundPattern',
+	'sections',
+	'shape',
 	'size',
 	'spacingAfter',
 	'spacingBefore',
 	'theme',
+	'textWidth',
 	'typography',
 	'until',
 	'visible',
@@ -81,45 +85,99 @@ export const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
 
 export const getContentFiles = async () => {
-	const contentFiles = [{
-		contentLabel: siteContentLabel,
-		contentPath: siteContentPath,
-		imagesDir: siteImagesDir,
-		imagesLabel: siteImagesLabel,
-		isHome: true,
-		routeDirectory: null,
-		routeId: null,
-		routeOrder: 0,
-	}];
-	const routeEntries = await readdir(siteRoutesDir, { withFileTypes: true }).catch((error) => {
-		if (error?.code === 'ENOENT') {
-			return [];
-		}
+	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'));
+	}
 
+	const legacyRoutesDir = path.join(siteDir, 'routes');
+	const legacyRoutes = await readdir(legacyRoutesDir).catch((error) => {
+		if (error?.code === 'ENOENT') return null;
 		throw error;
 	});
+	if (legacyRoutes !== null) {
+		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
+	}
 
-	for (const entry of routeEntries) {
-		if (!entry.isDirectory()) continue;
+	const contentFiles = [];
+	const collectPageContentFiles = async (pagesDir, pagesLabel, parentPageDirectory = '') => {
+		const pageEntries = await readdir(pagesDir, { withFileTypes: true }).catch((error) => {
+		if (error?.code === 'ENOENT') {
+			return [];
+		}
 
-		const routeDirectory = entry.name;
-		const routeDir = path.join(siteRoutesDir, routeDirectory);
-		const routeContentPath = path.join(routeDir, 'content.md');
+		throw error;
+		});
 
-		if (!(await fileExists(routeContentPath))) continue;
+		for (const entry of pageEntries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+			if (!entry.isDirectory()) continue;
+
+			const pageDirectory = parentPageDirectory
+				? `${parentPageDirectory}/pages/${entry.name}`
+				: entry.name;
+			const pageLabel = `${pagesLabel}/${entry.name}`;
+			const pageDir = path.join(pagesDir, entry.name);
+			const pageContentPath = path.join(pageDir, 'content.md');
+
+			if (!(await fileExists(pageContentPath))) {
+				const childPageEntries = await readdir(path.join(pageDir, 'pages'), { withFileTypes: true }).catch((error) => {
+					if (error?.code === 'ENOENT') return [];
+					throw error;
+				});
+				if (childPageEntries.some((childEntry) => childEntry.isDirectory())) {
+					throw new Error(`${pageLabel} contains nested pages but has no content.md of its own.`);
+				}
+				continue;
+			}
+			const pageMetadata = parsePageDirectoryPath(pageDirectory, pageLabel);
+			const isHome = pageDirectory === homePageDirectory;
+
+			contentFiles.push({
+				contentLabel: `${pageLabel}/content.md`,
+				contentPath: pageContentPath,
+				imagesDir: path.join(pageDir, 'images'),
+				imagesLabel: `${pageLabel}/images`,
+				isHome,
+				...pageMetadata,
+				pagePath: isHome ? '' : pageMetadata.pagePath,
+				parentPagePath: isHome ? null : pageMetadata.parentPagePath,
+			});
 
-		const { routeId, routeOrder } = parseRouteDirectory(routeDirectory, `${siteRoutesLabel}/${routeDirectory}`);
+			if (isHome) {
+				const homePagesDir = path.join(pageDir, 'pages');
+				const homeChildEntries = await readdir(homePagesDir, { withFileTypes: true }).catch((error) => {
+					if (error?.code === 'ENOENT') return [];
+					throw error;
+				});
+				const homeChildDirectories = homeChildEntries.filter((childEntry) => childEntry.isDirectory());
+				if (homeChildDirectories.length > 0) {
+					throw new Error([
+						`${pageLabel} is the homepage and cannot contain child pages.`,
+						`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
+						...homeChildDirectories.map(({ name }) => `- ${pageLabel}/pages/${name}`),
+					].join('\n'));
+				}
+				continue;
+			}
+
+			await collectPageContentFiles(
+				path.join(pageDir, 'pages'),
+				`${pageLabel}/pages`,
+				pageDirectory,
+			);
+		}
+	};
 
-		contentFiles.push({
-			contentLabel: `${siteRoutesLabel}/${routeDirectory}/content.md`,
-			contentPath: routeContentPath,
-			imagesDir: path.join(routeDir, 'images'),
-			imagesLabel: `${siteRoutesLabel}/${routeDirectory}/images`,
-			isHome: false,
-			routeDirectory,
-			routeId,
-			routeOrder,
-		});
+	await collectPageContentFiles(sitePagesDir, sitePagesLabel);
+	if (!contentFiles.some(({ isHome }) => isHome)) {
+		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
 	}
 
 	return contentFiles;
@@ -129,7 +187,15 @@ export const splitSiteFile = (source, label = siteContentLabel) => {
 	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
 
 	if (!match) {
-		throw new Error(`${label} is missing frontmatter delimited by ---.`);
+		if (/^---(?:\r?\n|$)/.test(source)) {
+			throw new Error(`${label} starts YAML frontmatter with ---, but no closing --- delimiter was found.`);
+		}
+
+		return {
+			frontmatter: '',
+			frontmatterBody: '',
+			body: source,
+		};
 	}
 
 	return {
@@ -250,10 +316,27 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		if (knownTopLevelFrontmatterKeys.has(key)) continue;
 
 		let fix;
-		if (fileKind === 'content' && key === 'images') {
+		let message = `Frontmatter line ${lineNumber} defines "${key}" at the top level, but it is not a valid top-level ${fileKind} field.`;
+		if (fileKind === 'content' && key === 'title') {
+			fix = 'Remove "title:" and write the page title as the single Markdown H1 after frontmatter, for example "# About".';
+		} else if (fileKind === 'content' && key === 'description') {
+			fix = 'Indent "description:" under "page:". The optional meta description belongs in the page object.';
+		} else if (fileKind === 'content' && key === 'images') {
 			fix = 'Put local image references in norna-image-stack or norna-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.`;
+		} 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.';
+		} else if (fileKind === 'page theme' && ['preset', 'shape', '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.`;
+		} else if (fileKind === 'sitewide content' && (key === 'navigation' || key === 'site')) {
+			message = `Frontmatter line ${lineNumber}: "${key}:" no longer defines site identity.`;
+			fix = 'Use the homepage Markdown H1 for navigation text and logo alternative text. Move only an optional logo height to top-level "logo:".';
 		} else if (knownNestedFrontmatterKeys.has(key)) {
 			fix = `Indent "${key}:" under the object it belongs to.`;
 		} else {
@@ -262,7 +345,7 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 
 		addIssue({
 			severity: 'error',
-			message: `Frontmatter line ${lineNumber} defines "${key}" at the top level, but it is not a valid top-level ${fileKind} field.`,
+			message,
 			fix,
 		});
 	}
@@ -286,10 +369,10 @@ export const validateThemeYamlStructure = (frontmatter, addIssue) =>
 		fileKind: 'theme',
 	});
 
-export const validateRouteThemeYamlStructure = (frontmatter, addIssue) =>
+export const validatePageThemeYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
-		knownTopLevelFrontmatterKeys: knownRouteThemeTopLevelFrontmatterKeys,
-		fileKind: 'route theme',
+		knownTopLevelFrontmatterKeys: knownPageThemeTopLevelFrontmatterKeys,
+		fileKind: 'page theme',
 	});
 
 export const validateSitewideYamlStructure = (frontmatter, addIssue) =>
@@ -303,53 +386,32 @@ export const readThemeFile = async (sitePath) => {
 	return { frontmatter: source, frontmatterBody: source, body: '' };
 };
 
-export const getFrontmatterSections = (frontmatter) => {
-	const sections = [];
-	const lines = frontmatter.split(/\r?\n/);
-	let inSections = false;
-
-	for (const [index, line] of lines.entries()) {
-		if (/^sections:\s*$/.test(line)) {
-			inSections = true;
-			continue;
-		}
-
-		if (!inSections) continue;
-		if (/^[a-zA-Z0-9_-]+:/.test(line)) break;
-
-		const sectionMatch = line.match(/^\s{2}([a-z0-9-]+):(?:\s+.*)?\s*$/);
-		if (sectionMatch) {
-			sections.push({ id: sectionMatch[1], line: index + 1 });
-		}
-	}
-
-	return sections;
-};
-
-export const getHeadingId = (heading) => heading.match(explicitHeadingIdRegex)?.[1];
-
 export const getDeprecatedInlineStyleReferences = (body) => Array.from(body.matchAll(deprecatedInlineStyleReferenceRegex))
 	.map((match) => match[1]);
 
-export const getBodySections = (body) => {
-	const matches = Array.from(body.matchAll(h2Regex));
-	const prelude = matches.length > 0 ? body.slice(0, matches[0].index) : body;
-	const sections = [];
-
-	for (let index = 0; index < matches.length; index += 1) {
-		const match = matches[index];
-		const start = match.index ?? 0;
-		const next = matches[index + 1];
-		const end = next?.index ?? body.length;
-		const text = body.slice(start, end).trimEnd();
-		const heading = match[0];
-		const id = getHeadingId(heading);
-		const line = body.slice(0, start).split(/\r?\n/).length;
-
-		sections.push({ id, heading, line, text });
-	}
+export const getBodySections = async (body) => {
+	const { headings, source } = await getMarkdownHeadings(body);
+	const structuralHeadings = headings.filter((heading) => heading.depth <= 2);
+	const prelude = structuralHeadings.length > 0 ? source.slice(0, structuralHeadings[0].index) : source;
+	const sections = structuralHeadings.map((heading, index) => {
+		const next = structuralHeadings[index + 1];
+		const end = next?.index ?? source.length;
+
+		return {
+			...heading,
+			heading: heading.source,
+			isPageTitle: heading.depth === 1,
+			level: heading.depth,
+			text: source.slice(heading.index, end).trimEnd(),
+		};
+	});
 
-	return { prelude, sections };
+	return {
+		headings,
+		pageHeadings: sections.filter((section) => section.isPageTitle),
+		prelude,
+		sections,
+	};
 };
 
 export const getImageFiles = async (directory) => {

package/scripts/lib/site-conventions.mjs

@@ -0,0 +1 @@
+export const homePageDirectory = '000-home';

package/scripts/lib/site-paths.mjs

@@ -1,10 +1,12 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { homePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
 const defaultSiteDirectory = 'site';
+export { homePageDirectory };
 
 const currentFile = fileURLToPath(import.meta.url);
 const currentDirectory = path.dirname(currentFile);
@@ -23,7 +25,10 @@ export const invocationRoot = configuredInvocationRoot
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
 		existsSync(path.join(siteDir, 'config.yaml'))
-		&& existsSync(path.join(siteDir, 'content.md'))
+		&& (
+			existsSync(path.join(siteDir, 'pages', homePageDirectory, 'content.md'))
+			|| existsSync(path.join(siteDir, 'content.md'))
+		)
 	);
 };
 
@@ -116,10 +121,11 @@ const getPathLabel = (filePath) => {
 export const siteDir = resolvedSitePaths.siteDir;
 export const siteConfigPath = path.join(siteDir, 'config.yaml');
 export const siteThemePath = path.join(siteDir, 'theme.yaml');
-export const siteContentPath = path.join(siteDir, 'content.md');
 export const sitewideContentPath = path.join(siteDir, 'sitewide-content.yaml');
-export const siteImagesDir = path.join(siteDir, 'images');
-export const siteRoutesDir = path.join(siteDir, 'routes');
+export const sitePagesDir = path.join(siteDir, 'pages');
+export const siteHomePageDir = path.join(sitePagesDir, homePageDirectory);
+export const siteContentPath = path.join(siteHomePageDir, 'content.md');
+export const siteImagesDir = path.join(siteHomePageDir, 'images');
 export const sitePublicDir = path.join(siteDir, 'public');
 export const siteStateDir = path.join(siteDir, '.norna');
 export const astroPublicDir = path.join(siteStateDir, 'public');
@@ -138,7 +144,7 @@ export const siteThemeLabel = getPathLabel(siteThemePath);
 export const siteContentLabel = getPathLabel(siteContentPath);
 export const sitewideContentLabel = getPathLabel(sitewideContentPath);
 export const siteImagesLabel = getPathLabel(siteImagesDir);
-export const siteRoutesLabel = getPathLabel(siteRoutesDir);
+export const sitePagesLabel = getPathLabel(sitePagesDir);
 export const sitePublicLabel = getPathLabel(sitePublicDir);
 export const astroPublicLabel = getPathLabel(astroPublicDir);
 export const generatedImagesManifestLabel = getPathLabel(generatedImagesManifestPath);

package/scripts/lib/theme-config.mjs

@@ -1,18 +1,18 @@
 import { readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import {
-	validateRouteThemeYamlStructure,
+	validatePageThemeYamlStructure,
 	validateThemeYamlStructure,
 } from './site-content.mjs';
 import {
-	siteRoutesDir,
-	siteRoutesLabel,
+	sitePagesDir,
+	sitePagesLabel,
 	siteThemeLabel,
 	siteThemePath,
-	sitewideContentLabel,
 } from './site-paths.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 () => {
@@ -24,18 +24,16 @@ export const readThemeConfig = async () => {
 		throw error;
 	});
 	const config = parseYamlConfig(themeFile, siteThemeLabel, {
+		schema: themeVisualSchema,
 		validateStructure: validateThemeYamlStructure,
 	});
-	if (Object.hasOwn(config, 'navigation')) {
-		throw new Error(`${siteThemeLabel} may not define navigation. The site label and logo settings belong in ${sitewideContentLabel}.`);
-	}
 	resolveThemeConfig(config, siteThemeLabel);
 	resolveThemePresentation(config, siteThemeLabel);
 
 	return config;
 };
 
-const getRouteThemeFiles = async (directory, relativeDirectory = '') => {
+const getPageThemeFiles = async (directory, relativeDirectory = '') => {
 	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') return [];
 		throw error;
@@ -46,14 +44,14 @@ const getRouteThemeFiles = async (directory, relativeDirectory = '') => {
 		const relativePath = path.join(relativeDirectory, entry.name);
 		const absolutePath = path.join(directory, entry.name);
 		if (entry.isDirectory()) {
-			files.push(...await getRouteThemeFiles(absolutePath, relativePath));
+			files.push(...await getPageThemeFiles(absolutePath, relativePath));
 			continue;
 		}
 
 		if (entry.name === 'theme.yaml') {
 			files.push({
 				path: absolutePath,
-				label: `${siteRoutesLabel}/${relativePath.split(path.sep).join('/')}`,
+				label: `${sitePagesLabel}/${relativePath.split(path.sep).join('/')}`,
 			});
 		}
 	}
@@ -61,20 +59,16 @@ const getRouteThemeFiles = async (directory, relativeDirectory = '') => {
 	return files;
 };
 
-export const validateRouteThemeFiles = async () => {
-	const files = await getRouteThemeFiles(siteRoutesDir);
+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, {
-			validateStructure: validateRouteThemeYamlStructure,
+			schema: pageThemeSchema,
+			validateStructure: validatePageThemeYamlStructure,
 		});
-		if (Object.hasOwn(config, 'navigation')) {
-			throw new Error(`${file.label} may not define navigation. The site label and logo settings belong in ${sitewideContentLabel}.`);
-		}
-		resolveThemeConfig(config, file.label);
-		resolveThemePresentation(config, file.label);
 
 		configs.push({ ...file, config });
 	}

package/scripts/lib/theme-presets.mjs

@@ -2,9 +2,12 @@ import { mergeDeep } from './typography.mjs';
 
 const themePresetConfigurations = Object.freeze({
 	portfolio: Object.freeze({
+		shape: 'square',
 		layout: {
-			density: 'normal',
+			contentSpacing: 'normal',
+			textWidth: 'wide',
 			pageWidth: '1240px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -21,12 +24,15 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'normal',
 		},
 		palette: 'dark',
-		sectionSurfaces: ['base'],
+		sections: { backgroundPattern: 'uniform' },
 	}),
 	documentation: Object.freeze({
+		shape: 'soft',
 		layout: {
-			density: 'compact',
+			contentSpacing: 'compact',
+			textWidth: 'narrow',
 			pageWidth: '1240px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -43,12 +49,15 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'compact',
 		},
 		palette: 'paper',
-		sectionSurfaces: ['base', 'soft'],
+		sections: { backgroundPattern: 'alternating' },
 	}),
 	project: Object.freeze({
+		shape: 'soft',
 		layout: {
-			density: 'compact',
+			contentSpacing: 'compact',
+			textWidth: 'normal',
 			pageWidth: '1120px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -65,12 +74,15 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'compact',
 		},
 		palette: 'light',
-		sectionSurfaces: ['base', 'soft'],
+		sections: { backgroundPattern: 'alternating' },
 	}),
 	statement: Object.freeze({
+		shape: 'square',
 		layout: {
-			density: 'airy',
+			contentSpacing: 'spacious',
+			textWidth: 'normal',
 			pageWidth: '1280px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.5rem, 5vw, 4rem)',
 				mobile: '1rem',
@@ -87,7 +99,7 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'airy',
 		},
 		palette: 'paper',
-		sectionSurfaces: ['base', 'emphasis'],
+		sections: { backgroundPattern: 'cycling' },
 	}),
 });
 
@@ -154,6 +166,30 @@ export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.yaml') => {
 	};
 };
 
+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 = {}) => ({
+	...base,
+	layout: {
+		...(base.layout ?? {}),
+		...mergePageThemePart(base.layout, override.layout, ['contentSpacing', 'textWidth']),
+	},
+	images: {
+		...(base.images ?? {}),
+		...mergePageThemePart(base.images, override.images, [
+			'width',
+			'maxAvailableWidthPercent',
+			'maxAvailableHeightPercent',
+		]),
+	},
+	sections: {
+		...(base.sections ?? {}),
+		...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
+	},
+});
+
 const quote = (value) => JSON.stringify(value);
 const responsiveValueLines = (label, value, indent = 2) => {
 	const prefix = ' '.repeat(indent);
@@ -167,7 +203,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
-	const { layout, images, typography, palette, sectionSurfaces } = preset;
+	const { shape, layout, images, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -177,9 +213,14 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		`# Available theme presets: ${themePresetNames.join(', ')}.`,
 		`preset: ${presetName}`,
 		'',
+		'# Alternatives: square, soft.',
+		`shape: ${shape}`,
+		'',
 		'layout:',
-		'  # Alternatives: compact, normal, airy.',
-		`  density: ${layout.density}`,
+		'  # Alternatives: compact, normal, spacious.',
+		`  contentSpacing: ${layout.contentSpacing}`,
+		'  # Alternatives: narrow, normal, wide.',
+		`  textWidth: ${layout.textWidth}`,
 		'  # Any positive CSS length, including px, rem, em, %, or clamp(...).',
 		`  pageWidth: ${layout.pageWidth}`,
 		'  gutter:',
@@ -211,9 +252,9 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'',
 		'# Alternatives: dark, light, paper.',
 		`palette: ${palette}`,
-		'# One value keeps every section on the same surface; multiple values cycle.',
-		'# Use one to three unique values from: base, soft, emphasis.',
-		`sectionSurfaces: [${sectionSurfaces.join(', ')}]`,
+		'sections:',
+		'  # Alternatives: uniform, alternating, cycling.',
+		`  backgroundPattern: ${sections.backgroundPattern}`,
 		'',
 	].join('\n');
 };

package/scripts/release.mjs

@@ -129,7 +129,7 @@ if (showHelp || !releaseType) {
 		await run('git', ['add', ...releasePaths]);
 		await run('git', ['commit', '-m', `Release ${releaseTag}`]);
 		releaseCommitCreated = true;
-		await run('git', ['tag', releaseTag]);
+		await run('git', ['tag', '-a', releaseTag, '-m', `Release ${releaseTag}`]);
 		releaseTagCreated = true;
 		await run(npmBin, ['run', 'release:publish']);
 		await run('git', ['push', '--follow-tags']);