@janga/norna 0.7.18 → 0.7.23

package/scripts/lib/project-config.mjs

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import {
 	validateConfigYamlStructure,
 } from './site-content.mjs';
+import { defaultImagePresentation, imagePresentationNames } from './image-presentation.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
 import {
 	siteConfigLabel,
@@ -184,26 +185,64 @@ const readSiteUrl = (config) => {
 const localeLabels = Object.freeze({
 	en: Object.freeze({
 		breadcrumb: 'Breadcrumb',
+		appearance: 'Appearance',
+		appearanceDark: 'Dark',
+		appearanceLight: 'Light',
+		appearanceSystem: 'System',
+		codeCopied: 'Copied',
+		codeCopyFailed: 'Could not copy code',
+		copyCode: 'Copy code',
+		displaySettings: 'Display',
+		focusReading: 'Focus reading',
+		readingWidth: 'Reading width',
+		readingWidthNarrow: 'Narrow',
+		readingWidthStandard: 'Standard',
+		readingWidthWide: 'Wide',
+		resetDisplaySettings: 'Reset',
 		dismissBanner: 'Dismiss notice',
 		built: 'Built',
 		images: 'Images',
+		imageCarousel: 'image carousel',
 		navigationChildren: 'Child pages',
 		navigationMenu: 'Menu',
+		nextImage: 'Next image',
 		note: 'Note',
+		pageMoved: 'Page moved',
+		pageMovedText: 'This address now identifies',
 		pageNavigation: 'Page contents',
+		previousImage: 'Previous image',
 		siteBanners: 'Site notices',
 		siteNavigation: 'Pages',
 		skipToContent: 'Skip to content',
 	}),
 	sv: Object.freeze({
 		breadcrumb: 'Brödsmulor',
+		appearance: 'Utseende',
+		appearanceDark: 'Mörkt',
+		appearanceLight: 'Ljust',
+		appearanceSystem: 'System',
+		codeCopied: 'Kopierat',
+		codeCopyFailed: 'Kunde inte kopiera koden',
+		copyCode: 'Kopiera kod',
+		displaySettings: 'Visning',
+		focusReading: 'Fokuserad läsning',
+		readingWidth: 'Textbredd',
+		readingWidthNarrow: 'Smal',
+		readingWidthStandard: 'Standard',
+		readingWidthWide: 'Bred',
+		resetDisplaySettings: 'Återställ',
 		dismissBanner: 'Stäng meddelande',
 		built: 'Byggd',
 		images: 'Bilder',
+		imageCarousel: 'bildkarusell',
 		navigationChildren: 'Undersidor',
 		navigationMenu: 'Meny',
+		nextImage: 'Nästa bild',
 		note: 'Not',
+		pageMoved: 'Sidan har flyttats',
+		pageMovedText: 'Den här adressen identifierar nu',
 		pageNavigation: 'Sidinnehåll',
+		previousImage: 'Föregående bild',
 		siteBanners: 'Meddelanden',
 		siteNavigation: 'Sidor',
 		skipToContent: 'Hoppa till innehållet',
@@ -326,7 +365,22 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 	const rawTypographyConfig = assertObject(rawThemeConfig.typography ?? {}, 'typography', sourceLabel);
 	const resolvedContentSpacing = readEnum(rawLayoutConfig, 'contentSpacing', 'layout', contentSpacingNames, 'normal', sourceLabel);
 	const resolvedLayoutSpacingDefaults = contentSpacingProfiles[resolvedContentSpacing];
-	const shape = readEnum(rawThemeConfig, 'shape', 'theme', ['square', 'soft'], 'soft', sourceLabel);
+	const corners = readEnum(rawThemeConfig, 'corners', 'theme', ['square', 'rounded'], 'rounded', sourceLabel);
+	const imagePresentation = readEnum(
+		rawImagesConfig,
+		'presentation',
+		'images',
+		imagePresentationNames,
+		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({
@@ -337,6 +391,8 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 				'layout.localNavigationGap',
 				sourceLabel,
 			),
+			noteWidth: readCssLengthValue(rawLayoutConfig.noteWidth ?? '12rem', 'layout.noteWidth', sourceLabel),
+			noteGap: readCssLengthValue(rawLayoutConfig.noteGap ?? '1.25rem', 'layout.noteGap', sourceLabel),
 			gutter: readResponsiveCssLength(rawLayoutConfig, 'gutter', 'layout', Object.freeze({
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -352,10 +408,15 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 			}),
 		}),
 		images: Object.freeze({
-			maxAvailableHeightPercent: readResponsivePercent(rawImagesConfig, 'maxAvailableHeightPercent', 'images', Object.freeze({
-				desktop: 74,
-				mobile: 68,
-			}), sourceLabel),
+			presentation: imagePresentation,
+			...(imagePresentation === 'centered-fit'
+				? {
+					maxAvailableHeightPercent: readResponsivePercent(rawImagesConfig, 'maxAvailableHeightPercent', 'images', Object.freeze({
+						desktop: 74,
+						mobile: 68,
+					}), sourceLabel),
+				}
+				: {}),
 			maxAvailableWidthPercent: readResponsivePercent(rawImagesConfig, 'maxAvailableWidthPercent', 'images', Object.freeze({
 				desktop: 100,
 				mobile: 100,
@@ -365,17 +426,24 @@ 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',
+		corners: Object.freeze({
+			name: corners,
+			radiusSmall: corners === 'square' ? '0' : '2px',
+			radiusMedium: corners === 'square' ? '0' : '6px',
+			radiusLarge: corners === 'square' ? '0' : '8px',
 		}),
 	});
 };
 
 export const resolveNavigationConfig = (config, sourceLabel = siteConfigLabel) => {
 	const rawNavigation = assertObject(config.navigation ?? {}, 'navigation', sourceLabel);
+	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.',
+			'Remove navigation.sectionTracking.',
+		].join('\n'));
+	}
 
 	return Object.freeze({
 		mode: readEnum(

package/scripts/lib/schema-definitions.mjs

@@ -1,5 +1,7 @@
 import { z } from 'astro/zod';
+import { imagePresentationNames } from './image-presentation.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
+import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { themePresetNames } from './theme-presets.mjs';
 
 const isDateOnly = (value) => {
@@ -15,16 +17,34 @@ const textWidth = z.enum(['narrow', 'normal', 'wide']).describe('Maximum width o
 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 presentationPalette = z.enum(presentationPaletteNames).describe('Coordinated site color palette. Every palette provides light and dark variants. Omit this to use the selected preset.');
+const themeAppearance = z.object({
+	default: z.enum(['system', 'light', 'dark']).optional().describe('Initial appearance. System follows the visitor\'s operating-system preference.'),
+}).strict().refine(
+	(value) => value.default !== undefined,
+	'Specify default.',
+).describe('Site-wide initial appearance.');
+const readerControls = z.object({
+	appearance: z.boolean().optional().describe('Show an Appearance control that lets readers choose System, Light, or Dark.'),
+	focusReading: z.boolean().optional().describe('Show a Focus reading control that lets readers hide navigation, breadcrumbs, and the footer. Sites with tree navigation always show this control.'),
+}).strict().refine(
+	(value) => value.appearance !== undefined || value.focusReading !== undefined,
+	'Specify appearance, focusReading, or both.',
+).describe('Optional controls for the site-wide Display panel.');
 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.')
-	.describe('Unitless line height between 1 and 3.');
+const backgroundPattern = z.enum(['uniform', 'alternating', 'accented']).describe('How coordinated backgrounds are assigned to H2 sections. Non-uniform patterns are unavailable with tree navigation.');
+const cornerTreatment = z.enum(['square', 'rounded']).describe('Site-wide corner treatment for navigation, cards and framed content.');
+const cardListWidth = z.enum(['text', 'narrow', 'normal', 'wide']).describe('Default maximum width for card lists. A width written in a norna-card-list block overrides this value.');
+const imagePresentation = z.enum(imagePresentationNames).describe('How managed image stacks and carousels are placed on the page. Prose-aligned starts them at the body-text edge; centered-fit centers them and constrains them by available width and viewport height.');
+const navigationMode = z.enum(navigationModeNames).describe('Site-wide navigation policy. Automatic selects an effective mode for each page from its active top-level branch.');
+const createLineHeight = (minimum, role) => z.number()
+	.min(minimum, `Use a unitless ${role} line height of at least ${minimum}.`)
+	.max(3, `Use a unitless ${role} line height of at most 3.`)
+	.describe(`Unitless ${role} line height between ${minimum} and 3.`);
+const headingLineHeight = createLineHeight(1, 'heading');
+const bodyLineHeight = createLineHeight(1.4, 'body-text');
+const captionLineHeight = createLineHeight(1.25, 'caption');
 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".',
@@ -59,10 +79,10 @@ const overrideResponsiveTextAlign = z.object({
 const commonTextPresentationOverride = {
 	align: overrideResponsiveTextAlign.optional().describe('Responsive text alignment override.'),
 	size: textSize.optional(),
-	lineHeight: lineHeight.optional(),
 };
 const headingPresentationOverride = z.object({
 	...commonTextPresentationOverride,
+	lineHeight: headingLineHeight.optional(),
 	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.'),
@@ -75,10 +95,12 @@ const headingLevelsPresentationOverride = z.object({
 }).strict().describe('Heading overrides by Markdown level.');
 const bodyPresentationOverride = z.object({
 	...commonTextPresentationOverride,
+	lineHeight: bodyLineHeight.optional(),
 	paragraphSpacing: cssLength.optional().describe('Vertical space between body paragraphs.'),
 }).strict().describe('Focused overrides for body text.');
 const captionPresentationOverride = z.object({
 	...commonTextPresentationOverride,
+	lineHeight: captionLineHeight.optional(),
 	spacingBefore: cssLength.optional().describe('Vertical space between an image and its caption.'),
 }).strict().describe('Focused overrides for image captions.');
 const typographyOverrides = z.object({
@@ -136,18 +158,28 @@ const pageThemeLayout = z.object({
 	'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.'),
 	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.');
+	maxAvailableHeightPercent: responsivePercent.optional().describe('Maximum percentage of viewport height used by centered-fit images. This setting is unavailable with prose-aligned presentation.'),
+}).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.');
+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.');
 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.'),
+	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.'),
+	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.',
@@ -155,11 +187,20 @@ const pageThemeSections = z.object({
 const pageNavigation = z.object({
 	listed: z.boolean().optional().default(true).describe('List this page in site navigation. The page remains public when false.'),
 }).strict();
+const pageAlias = z.string().regex(
+	/^\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)+$/,
+	'Use an old site-relative Norna page URL such as "/guides/install/". Start and end with / and use lowercase letters, numbers, and single hyphens.',
+).describe('Previous site-relative URL that permanently identifies this page.');
 const pageMetadata = z.object({
 	description: z.string().min(1).optional().describe('Optional page-specific meta description.'),
+	aliases: z.array(pageAlias)
+		.min(1)
+		.refine((values) => new Set(values).size === values.length, 'Page aliases must be unique within the page.')
+		.optional()
+		.describe('Previous site-relative URLs that permanently identify this page. The current page is always the target.'),
 }).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.'),
+	height: visualCssLength.optional().describe('Displayed logo height on wider screens. Omit it to use 2.6rem; narrow screens cap the height at 2.15rem. Width follows the intrinsic aspect ratio.'),
 }).strict().describe('Optional display settings for a convention-based navigation logo.');
 
 const banner = z.object({
@@ -192,9 +233,12 @@ const siteShape = {
 
 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.'),
+	appearance: themeAppearance.optional(),
+	readerControls: readerControls.optional(),
+	corners: cornerTreatment.optional().describe('Site-wide corner treatment. Omit this to use the selected preset.'),
 	layout: themeLayout.optional(),
 	images: themeImages.optional(),
+	blocks: themeBlocks.optional(),
 	typography: themeTypography.optional(),
 	palette: presentationPalette.optional(),
 	sections: themeSections.optional(),
@@ -212,8 +256,13 @@ const sitewideShape = {
 	footer: sitewideFooter.optional().describe('Site-wide footer content.'),
 };
 
+const categoryShape = {
+	label: z.string().trim().min(1).describe('Navigation label for this non-routable page category.'),
+};
+
 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)),
@@ -222,6 +271,8 @@ export const schemaTopLevelKeys = Object.freeze({
 
 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 non-routable navigation category containing child pages.');
 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()
@@ -231,6 +282,6 @@ export const pageThemeSchema = z.object(pageThemeShape).strict()
 		(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.');
+	.describe('Limited page presentation overrides inherited by descendant pages. Site colors, corners, typography, content-block defaults and navigation remain global.');
 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

@@ -1,4 +1,5 @@
 import { documentationLink } from './documentation-links.mjs';
+import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { getSchemaValueDefinition } from './schema-value-definitions.mjs';
 
 const yamlExample = (source) => `\`\`\`yaml\n${source}\n\`\`\``;
@@ -32,6 +33,13 @@ const schemaProperty = (schema, propertyPath) => schemaProperties(schema, proper
 const addHelp = (schema, propertyPath, paragraphs, examples = []) => {
 	for (const property of schemaProperties(schema, propertyPath)) {
 		property.markdownDescription = paragraphs.join('\n\n');
+		const reference = paragraphs.findLast((paragraph) => /^\[[^\]]+\]\(https:\/\//.test(paragraph));
+		if (reference && Array.isArray(property.oneOf)) {
+			for (const candidate of property.oneOf) {
+				if (!Object.hasOwn(candidate, 'const') || !candidate.description) continue;
+				candidate.markdownDescription = [candidate.description, reference].join('\n\n');
+			}
+		}
 		if (examples.length > 0) property.examples = examples;
 	}
 };
@@ -121,7 +129,7 @@ const addSitewideLogoHelp = (jsonSchema) => {
 
 	logo.markdownDescription = [
 		yamlExample('logo:\n  height: 2rem'),
-		'`logo` optionally overrides the displayed height of the convention-based logo file. The logo links home, and its alternative text comes from the homepage Markdown H1. This setting does not enable or select the file.',
+		'`logo` optionally overrides the displayed height of the convention-based logo file. Without an override, Norna uses 2.6rem on wider screens and caps the logo at 2.15rem on narrow screens. The logo links home, and its alternative text comes from the homepage Markdown H1. This setting does not enable or select the file.',
 		documentationLink('Navigation logo filenames and placement', 'public-files.md', 'navigation-logo'),
 	].join('\n\n');
 	logo.properties.height.examples = ['2rem'];
@@ -153,7 +161,7 @@ const addConfigHelp = (jsonSchema) => {
 	], ['en', 'sv', 'en-GB', 'sv-SE']);
 	addHelp(jsonSchema, 'navigation', [
 		yamlExample('navigation:\n  mode: automatic'),
-		'Sets one navigation model for the complete site. `automatic` selects from the page hierarchy.',
+		'Sets the site-wide navigation policy. `automatic` selects an effective mode for each page from its active top-level branch.',
 		documentationLink('Navigation reference', 'pages.md', 'navigation'),
 	]);
 	addFieldHelp(
@@ -179,40 +187,108 @@ const addThemeHelp = (jsonSchema) => {
 	].join('\n\n');
 	addHelp(jsonSchema, 'preset', [
 		yamlExample('preset: documentation'),
-		'Selects coordinated shapes, layout, image sizing, typography, palette and section backgrounds. This is the normal starting point for a theme.',
+		'Selects coordinated corners, layout, image sizing, content-block defaults, typography, palette and section backgrounds. This is the normal starting point for a theme.',
 		documentationLink('Compare theme presets', 'theme.md', 'theme-presets'),
 	]);
-	addHelp(jsonSchema, 'shape', [
-		yamlExample('shape: soft'),
+	addHelp(jsonSchema, 'corners', [
+		yamlExample('corners: rounded'),
 		'Chooses one consistent corner treatment for navigation, cards and framed content throughout the site.',
-		documentationLink('Theme reference', 'theme.md'),
-	], ['square', 'soft']);
+		documentationLink('Corner reference', 'theme.md', 'corners'),
+	], ['square', 'rounded']);
 	addHelp(jsonSchema, 'layout', [
 		yamlExample('layout:\n  contentSpacing: compact\n  textWidth: narrow'),
 		'Overrides text width, content spacing, page width and gutters after the selected preset.',
 		documentationLink('Layout reference', 'theme.md', 'layout'),
 	]);
 	addHelp(jsonSchema, 'images', [
-		yamlExample('images:\n  width: 900px\n  maxAvailableHeightPercent: 74'),
-		'Overrides the available width and height used by Norna-managed images.',
+		yamlExample('images:\n  presentation: prose-aligned\n  width: 900px'),
+		'Overrides how Norna-managed image stacks and carousels align inside the page content area and how much space they may use. Persistent navigation remains outside this area.',
 		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
 	]);
+	addHelp(jsonSchema, 'blocks', [
+		yamlExample('blocks:\n  cardList:\n    width: text'),
+		'Overrides preset defaults for structured Norna content blocks throughout the site. Options written directly in a Markdown block take priority.',
+		documentationLink('Content block defaults', 'theme.md', 'content-block-defaults'),
+	]);
+	addHelp(jsonSchema, 'blocks.cardList', [
+		yamlExample('blocks:\n  cardList:\n    width: text'),
+		'Sets site-wide defaults for card lists. A `width` option in an individual `norna-card-list` block overrides this setting.',
+		documentationLink('Content block defaults', 'theme.md', 'content-block-defaults'),
+	]);
+	addFieldHelp(
+		jsonSchema,
+		'blocks.cardList.width',
+		'blocks:\n  cardList:\n    width: text',
+		'theme.md',
+		'content-block-defaults',
+		['text', 'narrow', 'normal', 'wide'],
+	);
+	addSnippets(jsonSchema, 'blocks', [schemaSnippet({
+		label: 'Override content-block defaults',
+		body: {
+			cardList: {
+				width: '${1:text}',
+			},
+		},
+		description: 'Override a preset default for structured content blocks across the site.',
+		file: 'theme.md',
+		anchor: 'content-block-defaults',
+	})]);
 	addHelp(jsonSchema, 'typography', [
 		yamlExample('typography:\n  profile: reading\n  rhythm: normal'),
 		'Overrides the preset\'s font stack, typography profile, rhythm or individual text settings.',
 		documentationLink('Typography configuration reference', 'typography.md', 'configuration-shape'),
 	]);
 	addHelp(jsonSchema, 'palette', [
-		yamlExample('palette: paper'),
-		'Chooses a coordinated color system for the page frame, navigation, footer and section surfaces.',
-		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
-	], ['dark', 'light', 'paper']);
+		yamlExample('palette: warm-paper'),
+		'Chooses the site color character. Every palette provides coordinated light and dark variants.',
+		documentationLink('Palette and appearance', 'theme.md', 'palette-and-appearance'),
+	], presentationPaletteNames);
+	addHelp(jsonSchema, 'appearance', [
+		yamlExample('appearance:\n  default: system'),
+		'Selects the initial appearance. Enable the reader-facing choice under readerControls.',
+		documentationLink('Appearance', 'theme.md', 'appearance'),
+	]);
+	addFieldHelp(jsonSchema, 'appearance.default', 'appearance:\n  default: system', 'theme.md', 'appearance', ['system', 'light', 'dark']);
+	addSnippets(jsonSchema, 'appearance', [schemaSnippet({
+		label: 'Set the initial appearance',
+		body: 'appearance:\n  default: ${1:system}',
+		description: 'Follow the system color preference or choose a fixed initial appearance.',
+		file: 'theme.md',
+		anchor: 'appearance',
+	})]);
+	addHelp(jsonSchema, 'readerControls', [
+		yamlExample('readerControls:\n  appearance: true\n  focusReading: true'),
+		'Choose which optional controls readers can use in the site-wide Display panel.',
+		'`appearance: true` lets readers choose System, Light, or Dark. `focusReading: true` lets them hide navigation, breadcrumbs, and the footer while reading.',
+		'Reading width is always included. Sites with tree navigation always include Focus reading, even when it is not enabled here.',
+		documentationLink('Reader Display controls', 'theme.md', 'reader-display-controls'),
+	]);
+	for (const [propertyPath, example] of [
+		['readerControls.appearance', 'readerControls:\n  appearance: true'],
+		['readerControls.focusReading', 'readerControls:\n  focusReading: true'],
+	]) {
+		addFieldHelp(
+			jsonSchema,
+			propertyPath,
+			example,
+			'theme.md',
+			'reader-display-controls',
+		);
+	}
+	addSnippets(jsonSchema, 'readerControls', [schemaSnippet({
+		label: 'Configure the Display panel',
+		body: 'readerControls:\n  appearance: ${1:true}\n  focusReading: ${2:true}',
+		description: 'Show optional Appearance and Focus reading controls. Reading width is already included, and tree navigation always includes Focus reading.',
+		file: 'theme.md',
+		anchor: 'reader-display-controls',
+	})]);
 	addHelp(jsonSchema, 'sections', [
 		yamlExample('sections:\n  backgroundPattern: alternating'),
-		'Chooses whether section backgrounds stay uniform, alternate between two surfaces or cycle through three.',
-		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
+		'Chooses whether H2 section backgrounds stay uniform, alternate between two backgrounds or move from base to soft to emphasis and back through soft. Non-uniform patterns are available with sections and top navigation; tree navigation requires uniform.',
+		documentationLink('Section backgrounds', 'theme.md', 'section-backgrounds'),
 	]);
-	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'palette-and-section-surfaces', ['uniform', 'alternating', 'cycling']);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'section-backgrounds', ['uniform', 'alternating', 'accented']);
 
 	const layoutFields = [
 		['layout.contentSpacing', 'layout:\n  contentSpacing: compact'],
@@ -277,6 +353,7 @@ const addThemeHelp = (jsonSchema) => {
 	})]);
 
 	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'],
@@ -378,22 +455,23 @@ const addThemeHelp = (jsonSchema) => {
 const addPageThemeHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
 		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
-		'A page theme may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Site colors, shapes and typography stay consistent.',
+		'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 this page and its descendants.',
+		'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  width: 900px'),
-		'Adjusts managed-image sizing for this page and its descendants.',
+		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'],
@@ -407,10 +485,10 @@ const addPageThemeHelp = (jsonSchema) => {
 	}
 	addHelp(jsonSchema, 'sections', [
 		yamlExample('sections:\n  backgroundPattern: alternating'),
-		'Adjusts the section background sequence for this page and its descendants.',
+		'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', 'cycling']);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'page-themes', ['uniform', 'alternating', 'accented']);
 };
 
 const addSitewideHelp = (jsonSchema) => {
@@ -488,8 +566,8 @@ const addContentHelp = (jsonSchema) => {
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	].join('\n\n');
 	addHelp(jsonSchema, 'page', [
-		yamlExample('page:\n  description: About this project.'),
-		'Contains optional metadata for the current homepage or additional page. The Markdown H1 supplies its title.',
+		yamlExample('page:\n  description: About this project.\n  aliases:\n    - /old-about/'),
+		'Contains optional metadata for the current homepage or additional page. The Markdown H1 supplies its title. An alias records an old URL for this same page.',
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	]);
 	addHelp(jsonSchema, 'page.description', [
@@ -497,6 +575,16 @@ const addContentHelp = (jsonSchema) => {
 		'An optional page-specific description rendered as `<meta name="description">`. It is not visible in page content.',
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	], ['About this project.']);
+	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.',
+		documentationLink('Preserve old page URLs', 'pages.md', 'preserve-old-page-urls'),
+	], [['/old-about/']]);
+	addHelp(jsonSchema, 'page.aliases.[]', [
+		yamlExample('page:\n  aliases:\n    - /old-about/'),
+		'Use a previous Norna page URL. Start and end with `/`; use lowercase ASCII letters, numbers, and single hyphens; do not include the configured base path, a query string, or a fragment.',
+		documentationLink('Alias path rules', 'pages.md', 'preserve-old-page-urls'),
+	], ['/old-about/']);
 	addHelp(jsonSchema, 'navigation', [
 		yamlExample('navigation:\n  listed: false'),
 		'Optionally excludes an additional page from site navigation without removing its public URL.',
@@ -505,8 +593,22 @@ 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` creates a navigation-only group for child pages. It has no page content and produces no URL of its own.',
+		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);