@janga/norna 0.7.13 → 0.7.15

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

@@ -1,6 +1,84 @@
 import { Buffer } from 'node:buffer';
+import { documentationLink } from './documentation-links.mjs';
+
+const field = (description, options = {}) => Object.freeze({ description, ...options });
+const value = (title, description) => Object.freeze({ title, description });
+const nornaBlocksDocumentation = documentationLink('Norna blocks reference', 'content.md', 'norna-blocks');
+
+export const nornaMarkdownBlockDefinitions = Object.freeze({
+	'norna-image-stack': Object.freeze({
+		description: 'Display one or more managed images in a vertical stack.',
+		documentation: nornaBlocksDocumentation,
+		item: Object.freeze({
+			start: field('Start another managed image.', { key: 'image', prefix: '- ' }),
+			fields: Object.freeze({
+				alt: field('Optional alternative text for the image.'),
+				caption: field('Optional visible caption below the image.'),
+			}),
+		}),
+	}),
+	'norna-image-carousel': Object.freeze({
+		description: 'Display two or more managed images in an interactive carousel.',
+		documentation: nornaBlocksDocumentation,
+		item: Object.freeze({
+			start: field('Start another managed carousel image.', { key: 'image', prefix: '- ' }),
+			fields: Object.freeze({
+				alt: field('Optional alternative text for the image.'),
+				caption: field('Optional visible caption for the image.'),
+			}),
+		}),
+	}),
+	'norna-card-list': Object.freeze({
+		description: 'Display a structured list of cards.',
+		documentation: nornaBlocksDocumentation,
+		options: Object.freeze({
+			layout: field('Place each card image above, left, or right of its text. Defaults to image-top.', {
+				default: 'image-top',
+				values: Object.freeze({
+					'image-top': value('Image above', 'Place the image above the card text.'),
+					'image-left': value('Image left', 'Place the image to the left of the card text.'),
+					'image-right': value('Image right', 'Place the image to the right of the card text.'),
+				}),
+			}),
+			flow: field('Arrange cards as a responsive grid or a vertical stack. Defaults to grid.', {
+				default: 'grid',
+				values: Object.freeze({
+					grid: value('Grid', 'Arrange cards in a responsive grid.'),
+					stack: value('Stack', 'Arrange cards in one vertical column.'),
+				}),
+			}),
+			size: field('Set the coordinated card and image size. Defaults to m.', {
+				default: 'm',
+				values: Object.freeze({
+					s: value('Small', 'Use compact cards and images.'),
+					m: value('Medium', 'Use the balanced default card size.'),
+					l: value('Large', 'Use larger cards and images.'),
+					xl: value('Extra large', 'Use the largest card and image size.'),
+				}),
+			}),
+			width: field('Limit the width of the complete card list. Defaults to normal.', {
+				default: 'normal',
+				values: Object.freeze({
+					text: value('Text', 'Match the active body-text width.'),
+					narrow: value('Narrow', 'Use a narrow card-list width.'),
+					normal: value('Normal', 'Use the balanced default card-list width.'),
+					wide: value('Wide', 'Allow the card list to use more horizontal space.'),
+				}),
+			}),
+		}),
+		item: Object.freeze({
+			start: field('Start another card. Every card requires a title.', { key: 'title', prefix: '- ' }),
+			fields: Object.freeze({
+				text: field('Optional card text.'),
+				image: field('Optional managed image filename.'),
+				link: field('Optional URL opened when the card is activated.'),
+				'badge-text': field('Optional short badge displayed on the card.'),
+			}),
+		}),
+	}),
+});
 
-export const nornaBlockTypes = new Set(['norna-image-stack', 'norna-image-carousel', 'norna-card-list']);
+export const nornaBlockTypes = new Set(Object.keys(nornaMarkdownBlockDefinitions));
 
 const blockTypeLabels = {
 	'norna-image-stack': 'norna-image-stack',
@@ -10,7 +88,7 @@ const blockTypeLabels = {
 
 const knownBlockTypeList = Array.from(nornaBlockTypes).join(', ');
 const imageNameRegex = /^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$/i;
-const markerTagName = 'norna-media-block';
+const markerTagName = 'norna-block';
 const imageStackExample = [
 	'```norna-image-stack',
 	'- image: filename.jpg',
@@ -30,10 +108,11 @@ const cardListExample = [
 	'  badge-text: Recommended',
 	'```',
 ].join('\n');
-const cardListLayouts = new Set(['image-top', 'image-left', 'image-right']);
-const cardListFlows = new Set(['grid', 'stack']);
-const cardListSizes = new Set(['s', 'm', 'l', 'xl']);
-const cardListWidths = new Set(['text', 'narrow', 'normal', 'wide']);
+const cardListDefinition = nornaMarkdownBlockDefinitions['norna-card-list'];
+const cardListLayouts = new Set(Object.keys(cardListDefinition.options.layout.values));
+const cardListFlows = new Set(Object.keys(cardListDefinition.options.flow.values));
+const cardListSizes = new Set(Object.keys(cardListDefinition.options.size.values));
+const cardListWidths = new Set(Object.keys(cardListDefinition.options.width.values));
 
 const formatLocation = ({ label, line } = {}) => [
 	label,
@@ -294,10 +373,10 @@ const parseImageListBlock = (source, options = {}) => {
 const parseCardListBlock = (source, options = {}) => {
 	const cards = [];
 	const allowedKeys = new Set(['text', 'image', 'link', 'badge-text']);
-	let layout = 'image-top';
-	let flow = 'grid';
-	let size = 'm';
-	let width = 'normal';
+	let layout = cardListDefinition.options.layout.default;
+	let flow = cardListDefinition.options.flow.default;
+	let size = cardListDefinition.options.size.default;
+	let width = cardListDefinition.options.width.default;
 	let current = null;
 
 	for (const [index, line] of normalizeLines(source).entries()) {
@@ -551,7 +630,7 @@ export const createNornaMarkdownBlockMarker = (type, source) => {
 
 export const splitNornaMarkdownBlockMarkers = (html, options = {}) => {
 	const blocks = [];
-	const markerRegex = /<norna-media-block\s+data-type="([^"]+)"\s+data-source="([^"]*)"\s*><\/norna-media-block>|<pre\b([^>]*)>\s*<code\b([^>]*)>([\s\S]*?)<\/code>\s*<\/pre>/g;
+	const markerRegex = /<norna-block\s+data-type="([^"]+)"\s+data-source="([^"]*)"\s*><\/norna-block>|<pre\b([^>]*)>\s*<code\b([^>]*)>([\s\S]*?)<\/code>\s*<\/pre>/g;
 	let cursor = 0;
 
 	for (const match of html.matchAll(markerRegex)) {

package/scripts/lib/presentation.mjs

@@ -5,6 +5,7 @@ import {
 import { resolveThemeConfig } from './theme-presets.mjs';
 
 export const presentationPaletteNames = ['dark', 'light', 'paper'];
+const sectionSurfaceNames = ['base', 'soft', 'emphasis'];
 
 const presentationPalettes = Object.freeze({
 	dark: {
@@ -66,8 +67,6 @@ const presentationPalettes = Object.freeze({
 	},
 });
 
-const normalizePresentation = (presentation) => presentation ?? {};
-
 export const getPresentationPalette = (paletteName = 'dark') => {
 	const palette = presentationPalettes[paletteName];
 	if (!palette) {
@@ -93,19 +92,33 @@ export const getPresentationCssVariables = (presentation) => {
 	};
 };
 
-export const resolveThemePresentation = (theme, sourceLabel = 'theme.md') => {
+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}.`);
+	}
+
+	return value;
+};
+
+export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 	const normalizedTheme = resolveThemeConfig(theme, sourceLabel);
-	const normalizedThemePresentation = normalizePresentation(normalizedTheme.presentation);
-	const paletteName = normalizedThemePresentation.palette ?? 'dark';
+	const paletteName = normalizedTheme.palette ?? 'dark';
 	const palette = getPresentationPalette(paletteName);
 
 	return {
 		paletteName,
 		palette,
-		sectionSurfaces: {
-			mode: normalizedThemePresentation.sectionSurfaces?.mode ?? 'none',
-			sequence: normalizedThemePresentation.sectionSurfaces?.sequence ?? ['base', 'soft', 'emphasis'],
-		},
+		sectionSurfaces: getSectionSurfaces(normalizedTheme.sectionSurfaces, sourceLabel),
 		typography: resolveTypographyConfig(normalizedTheme.typography ?? defaultTypography),
 	};
 };
@@ -117,9 +130,7 @@ export const resolvePagePresentation = (theme, sourceLabel) => {
 };
 
 export const resolveSectionSurface = (pagePresentation, sectionIndex) => {
-	const surfaceName = pagePresentation.sectionSurfaces.mode === 'cycle'
-			? pagePresentation.sectionSurfaces.sequence[sectionIndex % pagePresentation.sectionSurfaces.sequence.length]
-			: 'base';
+	const surfaceName = pagePresentation.sectionSurfaces[sectionIndex % pagePresentation.sectionSurfaces.length];
 
 	return {
 		name: surfaceName,

package/scripts/lib/project-config.mjs

@@ -1,52 +1,28 @@
-import { access, readFile } from 'node:fs/promises';
-import { parseYamlMapping } from './frontmatter-yaml.mjs';
+import { readFile } from 'node:fs/promises';
 import {
-	splitSiteFile,
-	validateConfigFrontmatterStructure,
-	validateFrontmatterIndentation,
+	validateConfigYamlStructure,
 } from './site-content.mjs';
 import {
-	legacySiteConfigPath,
 	siteConfigLabel,
 	siteConfigPath,
 	siteThemeLabel,
 } from './site-paths.mjs';
 import { readThemeConfig } from './theme-config.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
 
-const fileExists = (filePath) => access(filePath).then(() => true, () => false);
 const readSiteConfig = async () => {
-	const source = await readFile(siteConfigPath, 'utf8').catch(async (error) => {
-		if (error?.code === 'ENOENT' && await fileExists(legacySiteConfigPath)) {
-			throw new Error(`${siteConfigLabel} is required. Replace the obsolete config.mjs with a frontmatter-only config.md file.`);
-		}
-
+	const source = await readFile(siteConfigPath, 'utf8').catch((error) => {
 		if (error?.code === 'ENOENT') {
 			throw new Error(`${siteConfigLabel} is required. Create it before running Norna.`);
 		}
 
 		throw error;
 	});
-	const { body, frontmatter, frontmatterBody } = splitSiteFile(source, siteConfigLabel);
-	const issues = [];
-
-	validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
-	validateConfigFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
 
-	if (body.trim()) {
-		issues.push({
-			message: `${siteConfigLabel} may contain YAML frontmatter only. Remove the Markdown body.`,
-		});
-	}
-
-	if (issues.length > 0) {
-		throw new Error([
-			`${siteConfigLabel} has invalid frontmatter.`,
-			...issues.map((issue) => `- ${issue.message}`),
-		].join('\n'));
-	}
-
-	return parseYamlMapping(frontmatterBody);
+	return parseYamlConfig(source, siteConfigLabel, {
+		validateStructure: validateConfigYamlStructure,
+	});
 };
 
 const siteConfig = await readSiteConfig();
@@ -207,7 +183,7 @@ const readSiteUrl = (config) => {
 const localeLabels = Object.freeze({
 	en: Object.freeze({
 		dismissBanner: 'Dismiss notice',
-		gallery: 'Images',
+		images: 'Images',
 		note: 'Note',
 		pageNavigation: 'On this page',
 		siteBanners: 'Site notices',
@@ -216,7 +192,7 @@ const localeLabels = Object.freeze({
 	}),
 	sv: Object.freeze({
 		dismissBanner: 'Stäng meddelande',
-		gallery: 'Bilder',
+		images: 'Bilder',
 		note: 'Not',
 		pageNavigation: 'På den här sidan',
 		siteBanners: 'Meddelanden',
@@ -246,10 +222,10 @@ const readLocale = (config) => {
 	});
 };
 
-const rawConfig = assertObject(siteConfig, 'config frontmatter');
-const rawTheme = assertObject(themeConfig, 'theme frontmatter', siteThemeLabel);
+const rawConfig = assertObject(siteConfig, 'config YAML');
+const rawTheme = assertObject(themeConfig, 'theme YAML', siteThemeLabel);
 const siteUrl = readSiteUrl(rawConfig);
-const scrollBehaviorNames = ['instant', 'browser-smooth'];
+const scrollBehaviorNames = ['instant', 'smooth'];
 
 const defaultFontFamily = "Arial, 'Helvetica Neue', Helvetica, sans-serif";
 const layoutDensityNames = ['compact', 'normal', 'airy'];
@@ -337,7 +313,7 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 	const rawThemeConfig = assertObject(resolveThemeConfig(theme, sourceLabel), 'theme frontmatter', sourceLabel);
 	const rawLayoutConfig = assertObject(rawThemeConfig.layout ?? {}, 'layout', sourceLabel);
 	const rawLayoutSpacingConfig = assertObject(rawLayoutConfig.spacing ?? {}, 'layout.spacing', sourceLabel);
-	const rawGalleryConfig = assertObject(rawThemeConfig.gallery ?? {}, 'gallery', 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];
@@ -359,16 +335,16 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 				sectionGap: readResponsiveCssLength(rawLayoutSpacingConfig, 'sectionGap', 'layout.spacing', resolvedLayoutSpacingDefaults.sectionGap, sourceLabel),
 			}),
 		}),
-		gallery: Object.freeze({
-			maxAvailableHeightPercent: readResponsivePercent(rawGalleryConfig, 'maxAvailableHeightPercent', 'gallery', Object.freeze({
+		images: Object.freeze({
+			maxAvailableHeightPercent: readResponsivePercent(rawImagesConfig, 'maxAvailableHeightPercent', 'images', Object.freeze({
 				desktop: 74,
 				mobile: 68,
 			}), sourceLabel),
-			maxAvailableWidthPercent: readResponsivePercent(rawGalleryConfig, 'maxAvailableWidthPercent', 'gallery', Object.freeze({
+			maxAvailableWidthPercent: readResponsivePercent(rawImagesConfig, 'maxAvailableWidthPercent', 'images', Object.freeze({
 				desktop: 100,
 				mobile: 100,
 			}), sourceLabel),
-			width: readCssLength(rawGalleryConfig, 'width', 'gallery', '900px', sourceLabel),
+			width: readCssLength(rawImagesConfig, 'width', 'images', '900px', sourceLabel),
 		}),
 		typography: Object.freeze({
 			fontFamily: readFontFamily(rawTypographyConfig, 'fontFamily', 'typography', defaultFontFamily, sourceLabel),

package/scripts/lib/public-asset-conventions.mjs

@@ -0,0 +1,112 @@
+import path from 'node:path';
+
+export const logoAssetFilenames = Object.freeze([
+	'logo.svg',
+	'logo.png',
+	'logo.jpg',
+	'logo.jpeg',
+]);
+
+export const browserIconAssetDefinitions = Object.freeze([
+	Object.freeze({ filename: 'favicon.svg', rel: 'icon', type: 'image/svg+xml' }),
+	Object.freeze({ filename: 'favicon.ico', rel: 'icon', sizes: 'any' }),
+	Object.freeze({ filename: 'favicon.png', rel: 'icon', type: 'image/png' }),
+	Object.freeze({ filename: 'apple-touch-icon.png', rel: 'apple-touch-icon' }),
+]);
+
+export const browserIconAssetFilenames = Object.freeze(
+	browserIconAssetDefinitions.map(({ filename }) => filename),
+);
+
+const logoExtensions = new Set(['.svg', '.png', '.jpg', '.jpeg']);
+const faviconExtensions = new Set(['.svg', '.png', '.ico']);
+const exactLogoNames = new Set(logoAssetFilenames);
+const exactBrowserIconNames = new Set(browserIconAssetFilenames);
+
+export const isLogoAssetFilename = (filename) => exactLogoNames.has(filename);
+
+const editDistance = (left, right) => {
+	const rows = Array.from({ length: left.length + 1 }, (_, index) => [index]);
+	for (let column = 1; column <= right.length; column += 1) rows[0][column] = column;
+
+	for (let row = 1; row <= left.length; row += 1) {
+		for (let column = 1; column <= right.length; column += 1) {
+			rows[row][column] = Math.min(
+				rows[row - 1][column] + 1,
+				rows[row][column - 1] + 1,
+				rows[row - 1][column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1),
+			);
+		}
+	}
+
+	return rows[left.length][right.length];
+};
+
+const getSuspiciousAsset = (filename) => {
+	const lowerFilename = filename.toLowerCase();
+	const parsed = path.parse(lowerFilename);
+
+	if (exactLogoNames.has(lowerFilename) && filename !== lowerFilename) {
+		return {
+			code: 'public-asset-case',
+			message: `Norna does not recognize "${filename}" as the navigation logo on case-sensitive file systems. Rename it to "${lowerFilename}".`,
+		};
+	}
+
+	if (exactBrowserIconNames.has(lowerFilename) && filename !== lowerFilename) {
+		return {
+			code: 'public-asset-case',
+			message: `Norna does not recognize "${filename}" as a browser icon on case-sensitive file systems. Rename it to "${lowerFilename}".`,
+		};
+	}
+
+	if (parsed.name === 'logo' && !logoExtensions.has(parsed.ext)) {
+		return {
+			code: 'unsupported-logo-file',
+			message: `Norna does not recognize "${filename}" as the navigation logo. Use exactly one of ${logoAssetFilenames.join(', ')}.`,
+		};
+	}
+
+	if (parsed.name === 'favicon' && !faviconExtensions.has(parsed.ext)) {
+		return {
+			code: 'unsupported-favicon-file',
+			message: `Norna does not link "${filename}" as a browser icon. Use favicon.svg, favicon.ico, or favicon.png.`,
+		};
+	}
+
+	if (/^favicon[-_.]/.test(lowerFilename) && !exactBrowserIconNames.has(lowerFilename)) {
+		return {
+			code: 'unrecognized-favicon-file',
+			message: `Norna does not link "${filename}" automatically. Use favicon.svg, favicon.ico, favicon.png, or apple-touch-icon.png for convention-based browser icons.`,
+		};
+	}
+
+	if (logoExtensions.has(parsed.ext) && editDistance(parsed.name, 'logo') === 1) {
+		return {
+			code: 'possible-logo-typo',
+			message: `"${filename}" looks like a misspelled navigation logo filename. Norna recognizes ${logoAssetFilenames.join(', ')}.`,
+		};
+	}
+
+	if (faviconExtensions.has(parsed.ext) && editDistance(parsed.name, 'favicon') <= 2) {
+		return {
+			code: 'possible-favicon-typo',
+			message: `"${filename}" looks like a misspelled browser icon filename. Norna recognizes favicon.svg, favicon.ico, and favicon.png.`,
+		};
+	}
+
+	return null;
+};
+
+export const inspectPublicAssetFilenames = (filenames) => {
+	const files = [...filenames].sort((left, right) => left.localeCompare(right, 'en'));
+	const logos = files.filter(isLogoAssetFilename);
+	const browserIcons = files.filter((filename) => exactBrowserIconNames.has(filename));
+	const suspicious = files.flatMap((filename) => {
+		if (isLogoAssetFilename(filename) || exactBrowserIconNames.has(filename)) return [];
+		const issue = getSuspiciousAsset(filename);
+		return issue ? [{ filename, ...issue }] : [];
+	});
+
+	return { browserIcons, files, logos, suspicious };
+};

package/scripts/lib/schema-definitions.mjs

@@ -0,0 +1,213 @@
+import { z } from 'astro/zod';
+import { themePresetNames } from './theme-presets.mjs';
+
+const isDateOnly = (value) => {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+
+	const date = new Date(`${value}T00:00:00.000Z`);
+	return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === 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 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 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.')
+	.describe('Unitless line height between 1 and 3.');
+const cssLength = z.string().regex(
+	/^(?:0|(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|ch|lh))$/,
+	'Use a CSS length such as "0", "0.8em", "1rem", or "12px".',
+).describe('CSS length using px, rem, em, ch or lh.');
+const visualCssLengthUnit = String.raw`(?:px|rem|em|vw|vh|vmin|vmax|ch|%)`;
+const visualCssLengthValue = String.raw`(?:\d+(?:\.\d+)?|\.\d+)${visualCssLengthUnit}`;
+const visualCssLength = z.string().regex(
+	new RegExp(`^(?:0|${visualCssLengthValue}|clamp\\(\\s*${visualCssLengthValue}\\s*,\\s*${visualCssLengthValue}\\s*,\\s*${visualCssLengthValue}\\s*\\))$`),
+	'Use a CSS length such as "0", "900px", "56rem", "90%", or "clamp(1rem, 4vw, 3rem)".',
+).describe('Responsive CSS length or clamp() expression.');
+const dateOnly = z.string()
+	.regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD format.')
+	.refine(isDateOnly, 'Use a real calendar date.')
+	.describe('Calendar date using YYYY-MM-DD.');
+const visibilityWindow = z.object({
+	from: dateOnly.optional().describe('First date on which the content is visible.'),
+	until: dateOnly.optional().describe('First date on which the content is no longer visible.'),
+}).strict().refine(
+	(value) => value.from !== undefined || value.until !== undefined,
+	'Specify from, until, or both.',
+).refine(
+	(value) => value.from === undefined || value.until === undefined || value.from < value.until,
+	'visible.until must be later than visible.from.',
+).describe('Optional visibility interval.');
+const overrideResponsiveTextAlign = z.object({
+	desktop: textAlign.optional().describe('Text alignment on wider screens.'),
+	mobile: textAlign.optional().describe('Text alignment on narrow screens.'),
+}).strict().refine(
+	(value) => value.desktop !== undefined || value.mobile !== undefined,
+	'Specify desktop, mobile, or both.',
+);
+const commonTextPresentationOverride = {
+	align: overrideResponsiveTextAlign.optional().describe('Responsive text alignment override.'),
+	size: textSize.optional(),
+	lineHeight: lineHeight.optional(),
+};
+const headingPresentationOverride = z.object({
+	...commonTextPresentationOverride,
+	weight: headingWeight.optional().describe('Heading font weight. Omit this to keep the profile value.'),
+	spacingBefore: cssLength.optional().describe('Vertical space before the heading.'),
+	spacingAfter: cssLength.optional().describe('Vertical space after the heading.'),
+}).strict().describe('Focused overrides for one heading level.');
+const headingLevelsPresentationOverride = z.object({
+	h1: headingPresentationOverride.optional().describe('Overrides for Markdown level 1 headings.'),
+	h2: headingPresentationOverride.optional().describe('Overrides for Markdown level 2 section headings.'),
+	h3: headingPresentationOverride.optional().describe('Overrides for Markdown level 3 headings.'),
+	h4: headingPresentationOverride.optional().describe('Overrides for Markdown level 4 headings.'),
+}).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({
+	...commonTextPresentationOverride,
+	spacingBefore: cssLength.optional().describe('Vertical space between an image and its caption.'),
+}).strict().describe('Focused overrides for image captions.');
+const typographyOverrides = z.object({
+	headings: headingLevelsPresentationOverride.optional().describe('Overrides for heading levels.'),
+	body: bodyPresentationOverride.optional().describe('Overrides for body text.'),
+	caption: captionPresentationOverride.optional().describe('Overrides for image captions.'),
+}).strict().describe('Fine-grained typography overrides applied after profile and rhythm.');
+const themeTypography = z.object({
+	fontFamily: z.string()
+		.min(1)
+		.refine((value) => !/[\n\r;{}]/.test(value), 'Do not use semicolons, braces, or line breaks.')
+		.optional()
+		.describe('CSS font-family stack.'),
+	profile: typographyProfile.optional().describe('Typography profile. Omit this to keep the selected preset.'),
+	rhythm: spacingDensity.optional().describe('Typography spacing rhythm. Omit this to keep the selected preset.'),
+	overrides: typographyOverrides.optional().describe('Focused typography overrides applied after the profile.'),
+}).strict().refine(
+	(value) => value.fontFamily !== undefined || value.profile !== undefined || value.rhythm !== undefined || value.overrides !== undefined,
+	'Specify fontFamily, profile, rhythm, overrides, or a combination of them.',
+).describe('Typography profile, rhythm, font family, and focused overrides.');
+const responsiveCssLength = z.union([
+	visualCssLength,
+	z.object({
+		desktop: visualCssLength,
+		mobile: visualCssLength,
+	}).strict(),
+]);
+const responsivePercent = z.union([
+	z.number().positive().max(100),
+	z.object({
+		desktop: z.number().positive().max(100).describe('Percentage used on wider screens.'),
+		mobile: z.number().positive().max(100).describe('Percentage used on narrow screens.'),
+	}).strict(),
+]);
+const themeLayoutSpacing = z.object({
+	blockGap: responsiveCssLength.optional().describe('Default vertical gap between structured content blocks.'),
+	finalSectionBottom: responsiveCssLength.optional().describe('Bottom space after the final section.'),
+	firstSectionTop: responsiveCssLength.optional().describe('Top space before the first section.'),
+	headingToBlock: responsiveCssLength.optional().describe('Gap from a section heading to a following structured block.'),
+	imageGap: responsiveCssLength.optional().describe('Gap between images in an image stack.'),
+	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.'),
+	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 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 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.'),
+}).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 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.');
+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.'),
+}).strict().describe('Site-wide footer content.');
+
+export const configSchema = z.object({
+	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.'),
+	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.'),
+	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({
+	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
+	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.');
+
+export const sitewideSchema = z.object({
+	navigation: sitewideNavigation.optional().describe('Site-wide navigation identity.'),
+	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.');