@janga/norna 0.7.16 → 0.7.18

package/scripts/lib/page-model.mjs

@@ -0,0 +1,102 @@
+import { homePageDirectory } from './site-conventions.mjs';
+
+export const pageDirectoryPattern = /^(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+const pageEntryPathSeparator = '--';
+
+export const parsePageDirectory = (pageDirectory, label = 'page directory') => {
+	const match = pageDirectory.match(pageDirectoryPattern);
+
+	if (!match) {
+		throw new Error(
+			`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}.`);
+	}
+
+	return {
+		pageDirectory,
+		pageOrder: Number.parseInt(match[1], 10),
+		pageId: match[2],
+	};
+};
+
+const normalizePageDirectoryPath = (pageDirectoryPath) => pageDirectoryPath.replaceAll('\\', '/');
+
+export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page directory path') => {
+	const normalizedPath = normalizePageDirectoryPath(pageDirectoryPath);
+	const segments = normalizedPath.split('/').filter(Boolean);
+
+	if (!normalizedPath || normalizedPath.startsWith('/') || normalizedPath.endsWith('/') || segments.length % 2 === 0) {
+		throw new Error(
+			`Invalid ${label} "${pageDirectoryPath}". Nested pages must use the form NNN-page-id/pages/NNN-child-id.`,
+		);
+	}
+
+	const pageDirectories = [];
+	for (const [index, segment] of segments.entries()) {
+		if (index % 2 === 1) {
+			if (segment !== 'pages') {
+				throw new Error(
+					`Invalid ${label} "${pageDirectoryPath}". Use a pages directory between nested page directories.`,
+				);
+			}
+			continue;
+		}
+
+		pageDirectories.push(parsePageDirectory(segment, `${label} segment ${segment}`));
+	}
+
+	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,
+		pageOrder: currentPage.pageOrder,
+		pageOrders: logicalPageOrders,
+		pagePath: logicalPageIds.join('/'),
+		parentPagePath: logicalPageIds.length > 1
+			? logicalPageIds.slice(0, -1).join('/')
+			: null,
+		depth: pageDirectories.length,
+	};
+};
+
+export const encodePageDirectoryPath = (pageDirectoryPath) => {
+	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
+	return pageDirectories.join(pageEntryPathSeparator);
+};
+
+export const decodePageDirectoryPath = (pageEntryPath, label = 'page entry path') => {
+	const pageDirectories = pageEntryPath.split(pageEntryPathSeparator);
+	if (pageDirectories.some((pageDirectory) => !pageDirectory)) {
+		throw new Error(`Invalid ${label} "${pageEntryPath}".`);
+	}
+
+	return pageDirectories.join('/pages/');
+};
+
+export const getPageDirectoryAncestors = (pageDirectoryPath) => {
+	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
+	return pageDirectories.map((_, index) => (
+		pageDirectories.slice(0, index + 1).join('/pages/')
+	));
+};

package/scripts/lib/presentation.mjs

@@ -5,7 +5,11 @@ import {
 import { resolveThemeConfig } from './theme-presets.mjs';
 
 export const presentationPaletteNames = ['dark', 'light', 'paper'];
-const sectionSurfaceNames = ['base', 'soft', 'emphasis'];
+const sectionBackgroundPatterns = Object.freeze({
+	uniform: ['base'],
+	alternating: ['base', 'soft'],
+	cycling: ['base', 'soft', 'emphasis'],
+});
 
 const presentationPalettes = Object.freeze({
 	dark: {
@@ -92,34 +96,30 @@ export const getPresentationCssVariables = (presentation) => {
 	};
 };
 
-const getSectionSurfaces = (value = ['base'], sourceLabel = 'theme.yaml') => {
-	if (!Array.isArray(value) || value.length < 1 || value.length > 3) {
-		throw new Error(`sectionSurfaces must contain one to three values in ${sourceLabel}.`);
-	}
-
-	for (const surface of value) {
-		if (!sectionSurfaceNames.includes(surface)) {
-			throw new Error(`Unknown section surface "${surface}" in ${sourceLabel}. Use one of: ${sectionSurfaceNames.join(', ')}.`);
-		}
-	}
-
-	if (new Set(value).size !== value.length) {
-		throw new Error(`Each section surface may appear only once in ${sourceLabel}.`);
+const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'theme.yaml') => {
+	const surfaces = sectionBackgroundPatterns[pattern];
+	if (!surfaces) {
+		throw new Error(`sections.backgroundPattern must be one of ${Object.keys(sectionBackgroundPatterns).join(', ')} in ${sourceLabel}.`);
 	}
 
-	return value;
+	return surfaces;
 };
 
 export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 	const normalizedTheme = resolveThemeConfig(theme, sourceLabel);
 	const paletteName = normalizedTheme.palette ?? 'dark';
 	const palette = getPresentationPalette(paletteName);
+	const typography = resolveTypographyConfig(normalizedTheme.typography ?? defaultTypography);
+	const textWidth = normalizedTheme.layout?.textWidth;
+	if (textWidth !== undefined) {
+		typography.values.body.width = textWidth;
+	}
 
 	return {
 		paletteName,
 		palette,
-		sectionSurfaces: getSectionSurfaces(normalizedTheme.sectionSurfaces, sourceLabel),
-		typography: resolveTypographyConfig(normalizedTheme.typography ?? defaultTypography),
+		sectionSurfaces: getSectionSurfaces(normalizedTheme.sections?.backgroundPattern, sourceLabel),
+		typography,
 	};
 };
 
@@ -129,6 +129,14 @@ export const resolvePagePresentation = (theme, sourceLabel) => {
 	return resolvedThemePresentation;
 };
 
+const textWidthCssValues = Object.freeze({
+	narrow: 'min(60ch, var(--text-width))',
+	normal: 'min(72ch, var(--text-width))',
+	wide: 'min(72ch, var(--image-layout-width))',
+});
+
+export const getTextWidthCssValue = (textWidth) => textWidthCssValues[textWidth];
+
 export const resolveSectionSurface = (pagePresentation, sectionIndex) => {
 	const surfaceName = pagePresentation.sectionSurfaces[sectionIndex % pagePresentation.sectionSurfaces.length];
 

package/scripts/lib/project-config.mjs

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import {
 	validateConfigYamlStructure,
 } from './site-content.mjs';
+import { navigationModeNames } from './navigation-model.mjs';
 import {
 	siteConfigLabel,
 	siteConfigPath,
@@ -182,19 +183,27 @@ const readSiteUrl = (config) => {
 
 const localeLabels = Object.freeze({
 	en: Object.freeze({
+		breadcrumb: 'Breadcrumb',
 		dismissBanner: 'Dismiss notice',
+		built: 'Built',
 		images: 'Images',
+		navigationChildren: 'Child pages',
+		navigationMenu: 'Menu',
 		note: 'Note',
-		pageNavigation: 'On this page',
+		pageNavigation: 'Page contents',
 		siteBanners: 'Site notices',
 		siteNavigation: 'Pages',
 		skipToContent: 'Skip to content',
 	}),
 	sv: Object.freeze({
+		breadcrumb: 'Brödsmulor',
 		dismissBanner: 'Stäng meddelande',
+		built: 'Byggd',
 		images: 'Bilder',
+		navigationChildren: 'Undersidor',
+		navigationMenu: 'Meny',
 		note: 'Not',
-		pageNavigation: 'På den här sidan',
+		pageNavigation: 'Sidinnehåll',
 		siteBanners: 'Meddelanden',
 		siteNavigation: 'Sidor',
 		skipToContent: 'Hoppa till innehållet',
@@ -228,8 +237,8 @@ const siteUrl = readSiteUrl(rawConfig);
 const scrollBehaviorNames = ['instant', 'smooth'];
 
 const defaultFontFamily = "Arial, 'Helvetica Neue', Helvetica, sans-serif";
-const layoutDensityNames = ['compact', 'normal', 'airy'];
-const layoutDensityProfiles = Object.freeze({
+const contentSpacingNames = ['compact', 'normal', 'spacious'];
+const contentSpacingProfiles = Object.freeze({
 	compact: Object.freeze({
 		blockGap: Object.freeze({
 			desktop: '1.25em',
@@ -282,7 +291,7 @@ const layoutDensityProfiles = Object.freeze({
 			mobile: '1.5rem',
 		}),
 	}),
-	airy: Object.freeze({
+	spacious: Object.freeze({
 		blockGap: Object.freeze({
 			desktop: '1.75em',
 			mobile: '1.5em',
@@ -315,12 +324,19 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 	const rawLayoutSpacingConfig = assertObject(rawLayoutConfig.spacing ?? {}, 'layout.spacing', sourceLabel);
 	const rawImagesConfig = assertObject(rawThemeConfig.images ?? {}, 'images', sourceLabel);
 	const rawTypographyConfig = assertObject(rawThemeConfig.typography ?? {}, 'typography', sourceLabel);
-	const resolvedLayoutDensity = readEnum(rawLayoutConfig, 'density', 'layout', layoutDensityNames, 'normal', sourceLabel);
-	const resolvedLayoutSpacingDefaults = layoutDensityProfiles[resolvedLayoutDensity];
+	const resolvedContentSpacing = readEnum(rawLayoutConfig, 'contentSpacing', 'layout', contentSpacingNames, 'normal', sourceLabel);
+	const resolvedLayoutSpacingDefaults = contentSpacingProfiles[resolvedContentSpacing];
+	const shape = readEnum(rawThemeConfig, 'shape', 'theme', ['square', 'soft'], 'soft', sourceLabel);
 
 	return Object.freeze({
 		layout: Object.freeze({
-			density: resolvedLayoutDensity,
+			contentSpacing: resolvedContentSpacing,
+			textWidth: readEnum(rawLayoutConfig, 'textWidth', 'layout', ['narrow', 'normal', 'wide'], 'normal', sourceLabel),
+			localNavigationGap: readCssLengthValue(
+				rawLayoutConfig.localNavigationGap ?? 'clamp(1.5rem, 3vw, 3rem)',
+				'layout.localNavigationGap',
+				sourceLabel,
+			),
 			gutter: readResponsiveCssLength(rawLayoutConfig, 'gutter', 'layout', Object.freeze({
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -349,6 +365,27 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 		typography: Object.freeze({
 			fontFamily: readFontFamily(rawTypographyConfig, 'fontFamily', 'typography', defaultFontFamily, sourceLabel),
 		}),
+		shape: Object.freeze({
+			name: shape,
+			radiusSmall: shape === 'square' ? '0' : '2px',
+			radiusMedium: shape === 'square' ? '0' : '6px',
+			radiusLarge: shape === 'square' ? '0' : '8px',
+		}),
+	});
+};
+
+export const resolveNavigationConfig = (config, sourceLabel = siteConfigLabel) => {
+	const rawNavigation = assertObject(config.navigation ?? {}, 'navigation', sourceLabel);
+
+	return Object.freeze({
+		mode: readEnum(
+			rawNavigation,
+			'mode',
+			'navigation',
+			navigationModeNames,
+			'automatic',
+			sourceLabel,
+		),
 	});
 };
 
@@ -359,6 +396,7 @@ export const projectConfig = Object.freeze({
 	}),
 	...resolveThemeVisualConfig(rawTheme, siteThemeLabel),
 	navigation: Object.freeze({
+		...resolveNavigationConfig(rawConfig, siteConfigLabel),
 		scrollBehavior: readEnum(
 			rawConfig,
 			'scrollBehavior',

package/scripts/lib/schema-definitions.mjs

@@ -1,4 +1,5 @@
 import { z } from 'astro/zod';
+import { navigationModeNames } from './navigation-model.mjs';
 import { themePresetNames } from './theme-presets.mjs';
 
 const isDateOnly = (value) => {
@@ -10,13 +11,16 @@ const isDateOnly = (value) => {
 
 const textAlign = z.enum(['left', 'center', 'right']).describe('Text alignment. Omit an override to keep the active typography profile.');
 const textSize = z.enum(['small', 'medium', 'large', 'xlarge']).describe('Text size from the active typography system. Omit an override to keep the profile value.');
-const textWidth = z.enum(['narrow', 'normal', 'wide']).describe('Maximum width of body text. Omit an override to keep the profile value.');
+const textWidth = z.enum(['narrow', 'normal', 'wide']).describe('Maximum width of body text. Omit this to keep the inherited page setting.');
 const headingWeight = z.union([z.literal(400), z.literal(500), z.literal(600), z.literal(700)]).describe('CSS font weight.');
 const typographyProfile = z.enum(['restrained', 'dense', 'reading', 'statement']).describe('Coordinated typography defaults. Omit this to use the selected preset.');
 const themePreset = z.enum(themePresetNames).describe('Complete Norna visual preset. Start here and add overrides only when needed.');
 const presentationPalette = z.enum(['dark', 'light', 'paper']).describe('Coordinated site color palette. Omit this to use the selected preset.');
-const sectionSurface = z.enum(['base', 'soft', 'emphasis']).describe('Semantic section surface from the active palette.');
 const spacingDensity = z.enum(['compact', 'normal', 'airy']).describe('Coordinated spacing density. Omit this to use the selected preset.');
+const contentSpacing = z.enum(['compact', 'normal', 'spacious']).describe('Vertical spacing between page sections and structured content blocks.');
+const backgroundPattern = z.enum(['uniform', 'alternating', 'cycling']).describe('How sections cycle through the active palette surfaces.');
+const shapeProfile = z.enum(['square', 'soft']).describe('Site-wide corner treatment for interface and content surfaces.');
+const navigationMode = z.enum(navigationModeNames).describe('Site-wide navigation model. Automatic selects from the site structure.');
 const lineHeight = z.number()
 	.min(1, 'Use a unitless line height of at least 1.')
 	.max(3, 'Use a unitless line height of at most 3.')
@@ -71,7 +75,6 @@ const headingLevelsPresentationOverride = z.object({
 }).strict().describe('Heading overrides by Markdown level.');
 const bodyPresentationOverride = z.object({
 	...commonTextPresentationOverride,
-	width: textWidth.optional().describe('Maximum body-text line length.'),
 	paragraphSpacing: cssLength.optional().describe('Vertical space between body paragraphs.'),
 }).strict().describe('Focused overrides for body text.');
 const captionPresentationOverride = z.object({
@@ -119,95 +122,115 @@ const themeLayoutSpacing = z.object({
 	sectionGap: responsiveCssLength.optional().describe('Vertical separation between page sections.'),
 }).strict().describe('Fine-grained spacing overrides applied after layout density.');
 const themeLayout = z.object({
-	density: spacingDensity.optional().describe('Overall spacing density. Omit this to keep the selected preset.'),
+	contentSpacing: contentSpacing.optional().describe('Page content spacing. Omit this to keep the selected preset or inherited page setting.'),
+	textWidth: textWidth.optional().describe('Body-text line length. Omit this to keep the selected preset or inherited page setting.'),
 	pageWidth: visualCssLength.optional().describe('Maximum width of the site layout. Omit this to keep the selected preset.'),
 	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({
 	width: visualCssLength.optional().describe('Maximum managed-image width. Omit this to keep the selected preset.'),
 	maxAvailableWidthPercent: responsivePercent.optional().describe('Maximum percentage of available horizontal space used by managed images.'),
 	maxAvailableHeightPercent: responsivePercent.optional().describe('Maximum percentage of viewport height used by managed images.'),
 }).strict().describe('Optional defaults for managed image presentation.');
-const sectionSurfaces = z.array(sectionSurface).min(1).max(3).refine(
-	(value) => new Set(value).size === value.length,
-	'Each section surface may appear only once.',
-).describe('Surface sequence cycled across page sections.');
+const configNavigation = z.object({
+	mode: navigationMode.optional().describe('Navigation model. Omit this to let Norna choose from the site structure.'),
+}).strict().describe('Site-wide navigation behavior.');
+const themeSections = z.object({
+	backgroundPattern: backgroundPattern.optional().describe('Section background sequence. Omit this to keep the selected preset or inherited page setting.'),
+}).strict().describe('Defaults for page section presentation.');
+const pageThemeSections = z.object({
+	backgroundPattern: backgroundPattern.optional().describe('Section background sequence inherited by descendant pages.'),
+}).strict().refine(
+	(value) => value.backgroundPattern !== undefined,
+	'Specify backgroundPattern.',
+).describe('Page-local section presentation inherited by descendant pages.');
 const pageNavigation = z.object({
-	include: z.boolean().optional().describe('Include this page in site navigation. Pages are included when omitted.'),
-	label: z.string().optional().describe('Navigation label when it should differ from the page title.'),
+	listed: z.boolean().optional().default(true).describe('List this page in site navigation. The page remains public when false.'),
 }).strict();
-const sitewideNavigation = z.object({
-	label: z.string().min(1).optional().describe('Accessible site label used for navigation text and logo alternative text.'),
-	logo: z.object({
-		height: visualCssLength.optional().describe('Displayed logo height. Width follows the intrinsic aspect ratio.'),
-	}).strict().optional().describe('Optional display settings for a convention-based navigation logo.'),
-}).strict().describe('Site-wide identity shown in navigation.');
+const pageMetadata = z.object({
+	description: z.string().min(1).optional().describe('Optional page-specific meta description.'),
+}).strict().describe('Optional metadata for this homepage or additional page. The Markdown H1 supplies the page title.');
+const sitewideLogo = z.object({
+	height: visualCssLength.optional().describe('Displayed logo height. Width follows the intrinsic aspect ratio.'),
+}).strict().describe('Optional display settings for a convention-based navigation logo.');
 
-const sectionMetadata = z.object({
-	visible: visibilityWindow.optional().describe('Optional date window for this section.'),
-}).strict().describe('Metadata keyed by the explicit Markdown section id. Markdown order remains authoritative.');
 const banner = z.object({
 	id: z.string().regex(/^[a-z0-9-]+$/).describe('Stable banner identifier used for dismissal state.'),
 	tone: z.enum(['warning']).default('warning').describe('Semantic banner tone.'),
 	visible: visibilityWindow.optional().describe('Optional date window for the banner.'),
 	title: z.string().min(1).describe('Short banner heading.'),
 	text: z.string().min(1).describe('Concise banner message.'),
-}).strict().describe('Dismissible, site-wide one-line notice.');
+}).strict().describe('Dismissible site-wide warning shown above page content for important temporary information.');
 const banners = z.array(banner).optional().default([]).refine(
 	(values) => new Set(values.map((value) => value.id)).size === values.length,
 	'Banner ids must be unique.',
 );
-const dateTimeFormat = z.object({
-	locale: z.string().min(1).describe('Intl locale such as en-GB or sv-SE.'),
-	timeZone: z.string().min(1).describe('IANA time zone such as Europe/Stockholm.'),
-	dateStyle: z.enum(['short', 'medium', 'long', 'full']).describe('Intl dateStyle for the build timestamp.'),
-	timeStyle: z.enum(['short', 'medium', 'long', 'full']).describe('Intl timeStyle for the build timestamp.'),
-}).strict().refine((value) => {
-	try {
-		new Intl.DateTimeFormat(value.locale, {
-			dateStyle: value.dateStyle,
-			timeStyle: value.timeStyle,
-			timeZone: value.timeZone,
-		});
-		return true;
-	} catch {
-		return false;
-	}
-}, 'Use a valid Intl.DateTimeFormat configuration.');
 const sitewideFooter = z.object({
 	copyrightMessage: z.string().min(1).optional().describe('Copyright or ownership text shown in the site footer.'),
-	buildInfo: z.object({
-		enabled: z.boolean().default(true).describe('Show generated build information in the footer.'),
-		text: z.string().min(1).describe('Label shown before the generated build timestamp.'),
-		dateTimeFormat: dateTimeFormat.describe('Formatting used for the generated build timestamp.'),
-	}).strict().optional().describe('Optional generated build timestamp.'),
+	buildInfo: z.boolean().optional().default(false).describe('Show a localized generated build timestamp in the footer.'),
 }).strict().describe('Site-wide footer content.');
 
-export const configSchema = z.object({
+const configShape = {
 	url: z.string().url().describe('Absolute public URL for the built site.'),
 	language: z.string().regex(/^(?:en|sv)(?:-[a-zA-Z0-9]+)*$/).optional().describe('Site language tag using Norna\'s English or Swedish interface text; the default is en.'),
+	navigation: configNavigation.optional(),
 	scrollBehavior: z.enum(['instant', 'smooth']).optional().default('instant').describe('Use instant anchors by default or the browser\'s native smooth scrolling.'),
-}).strict().describe('Technical settings for one Norna site. Routes cannot provide technical configuration.');
+};
 
-export const siteSchema = z.object({
-	title: z.string().describe('Page title used in metadata and route navigation.'),
-	description: z.string().describe('Page description used in metadata.'),
+const siteShape = {
+	page: pageMetadata.optional(),
 	navigation: pageNavigation.optional().describe('Optional navigation metadata for this page.'),
-	sections: z.record(z.string().regex(/^[a-z0-9-]+$/), sectionMetadata).optional().default({}).describe('Optional metadata keyed by Markdown section id. Do not duplicate section order here.'),
-}).strict().describe('Frontmatter for a homepage or route content.md file.');
+};
 
-export const themeVisualSchema = z.object({
+const themeVisualShape = {
 	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
+	shape: shapeProfile.optional().describe('Site-wide shape profile. Omit this to use the selected preset.'),
 	layout: themeLayout.optional(),
 	images: themeImages.optional(),
 	typography: themeTypography.optional(),
 	palette: presentationPalette.optional(),
-	sectionSurfaces: sectionSurfaces.optional().describe('Surface sequence cycled through page sections. Omit this to keep the selected preset.'),
-}).strict().describe('Visual settings for a site or route. A route theme replaces the inherited visual theme; site identity remains site-wide.');
+	sections: themeSections.optional(),
+};
 
-export const sitewideSchema = z.object({
-	navigation: sitewideNavigation.optional().describe('Site-wide navigation identity.'),
+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.'),
-}).strict().describe('Editorial content and identity shared by every page.');
+};
+
+export const schemaTopLevelKeys = Object.freeze({
+	config: Object.freeze(Object.keys(configShape)),
+	content: Object.freeze(Object.keys(siteShape)),
+	sitewide: Object.freeze(Object.keys(sitewideShape)),
+	theme: Object.freeze(Object.keys(themeVisualShape)),
+	pageTheme: Object.freeze(Object.keys(pageThemeShape)),
+});
+
+export const configSchema = z.object(configShape).strict()
+	.describe('Technical settings for one Norna site. Additional pages cannot provide technical configuration.');
+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, shapes, typography and navigation remain global.');
+export const sitewideSchema = z.object(sitewideShape).strict()
+	.describe('Editorial content and optional navigation logo display settings shared by every page.');