@janga/norna 0.7.13 → 0.7.15

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

@@ -0,0 +1,86 @@
+import {
+	getThemePresetMetadata,
+	themePresetNames,
+} from './theme-presets.mjs';
+
+const option = (title, description) => Object.freeze({ title, description });
+const definition = (values, options) => Object.freeze({
+	values: Object.freeze(values),
+	options: Object.freeze(options),
+});
+
+export const schemaValueDefinitions = Object.freeze([
+	definition(themePresetNames, Object.fromEntries(themePresetNames.map((name) => {
+		const metadata = getThemePresetMetadata(name);
+		return [name, option(metadata.title, metadata.description)];
+	}))),
+	definition(['instant', 'smooth'], {
+		instant: option('Instant', 'Jump directly to anchors without animated scrolling. This is the default.'),
+		smooth: option('Browser smooth', 'Use the browser\'s native smooth scrolling for anchor navigation.'),
+	}),
+	definition(['en', 'sv'], {
+		en: option('English', 'Use Norna\'s built-in English interface text.'),
+		sv: option('Swedish', 'Use Norna\'s built-in Swedish interface text.'),
+	}),
+	definition(['left', 'center', 'right'], {
+		left: option('Left', 'Align text with the left edge of its text area.'),
+		center: option('Center', 'Center text within its text area.'),
+		right: option('Right', 'Align text with the right edge of its text area.'),
+	}),
+	definition(['small', 'medium', 'large', 'xlarge'], {
+		small: option('Small', 'Use the small type size from the active typography system.'),
+		medium: option('Medium', 'Use the standard type size from the active typography system.'),
+		large: option('Large', 'Use a larger type size for stronger emphasis.'),
+		xlarge: option('Extra large', 'Use the largest available type size for exceptional emphasis.'),
+	}),
+	definition(['narrow', 'normal', 'wide'], {
+		narrow: option('Narrow', 'Use a shorter line length suited to reading-focused text.'),
+		normal: option('Normal', 'Use the balanced default line length.'),
+		wide: option('Wide', 'Allow body text to use more horizontal space.'),
+	}),
+	definition([400, 500, 600, 700], {
+		400: option('Regular', 'Use regular font weight.'),
+		500: option('Medium', 'Use medium font weight.'),
+		600: option('Semibold', 'Use semibold font weight.'),
+		700: option('Bold', 'Use bold font weight.'),
+	}),
+	definition(['restrained', 'dense', 'reading', 'statement'], {
+		restrained: option('Restrained', 'Quiet typography with regular-weight headings and balanced line lengths.'),
+		dense: option('Dense', 'Compact typography with wider text and tighter line height.'),
+		reading: option('Reading', 'Reading-focused typography with narrower text and relaxed line height.'),
+		statement: option('Statement', 'Stronger headings and tighter body rhythm for short, expressive pages.'),
+	}),
+	definition(['dark', 'light', 'paper'], {
+		dark: option('Dark', 'Black page and section surfaces with light text.'),
+		light: option('Light', 'White and cool light surfaces with dark text.'),
+		paper: option('Paper', 'Warm off-white surfaces with dark text.'),
+	}),
+	definition(['base', 'soft', 'emphasis'], {
+		base: option('Base', 'Use the palette\'s normal page surface.'),
+		soft: option('Soft', 'Use the palette\'s subtle contrasting surface.'),
+		emphasis: option('Emphasis', 'Use the palette\'s strongest section surface.'),
+	}),
+	definition(['compact', 'normal', 'airy'], {
+		compact: option('Compact', 'Reduce vertical spacing while preserving readable separation.'),
+		normal: option('Normal', 'Use balanced vertical spacing.'),
+		airy: option('Airy', 'Increase vertical spacing for a more expansive presentation.'),
+	}),
+	definition(['warning'], {
+		warning: option('Warning', 'Present the banner as an important warning notice.'),
+	}),
+	definition(['short', 'medium', 'long', 'full'], {
+		short: option('Short', 'Use a compact localized date or time representation.'),
+		medium: option('Medium', 'Use a moderately detailed localized representation.'),
+		long: option('Long', 'Use a detailed localized representation.'),
+		full: option('Full', 'Use the most detailed localized representation.'),
+	}),
+]);
+
+const valuesEqual = (left, right) => (
+	left.length === right.length
+	&& left.every((value, index) => value === right[index])
+);
+
+export const getSchemaValueDefinition = (values) => (
+	schemaValueDefinitions.find((candidate) => valuesEqual(candidate.values, values))
+);

package/scripts/lib/site-content.mjs

@@ -8,7 +8,6 @@ import {
 	siteImagesLabel,
 	siteRoutesDir,
 	siteRoutesLabel,
-	siteThemeLabel,
 } from './site-paths.mjs';
 import { parseRouteDirectory } from './route-model.mjs';
 
@@ -22,15 +21,14 @@ const deprecatedInlineStyleReferenceRegex = /\[[^\]\n]+\]\{\.([a-z][a-z0-9-]*)\}
 const frontmatterDelimiterRegex = /^---\s*$/;
 const knownConfigTopLevelFrontmatterKeys = new Set(['url', 'language', 'scrollBehavior']);
 const knownContentTopLevelFrontmatterKeys = new Set(['title', 'description', 'navigation', 'sections']);
-const knownThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'gallery', 'typography', 'presentation']);
-const knownRouteThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'gallery', 'typography', 'presentation']);
+const knownThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'images', 'typography', 'palette', 'sectionSurfaces']);
+const knownRouteThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'images', 'typography', 'palette', 'sectionSurfaces']);
 const knownSitewideTopLevelFrontmatterKeys = new Set(['navigation', 'banners', 'footer']);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
 	'alt',
 	'body',
 	'blockGap',
-	'brand',
 	'caption',
 	'carousel',
 	'density',
@@ -38,7 +36,6 @@ const knownNestedFrontmatterKeys = new Set([
 	'fontFamily',
 	'from',
 	'finalSectionBottom',
-	'gallery',
 	'gutter',
 	'headingToBlock',
 	'h1',
@@ -51,6 +48,7 @@ const knownNestedFrontmatterKeys = new Set([
 	'include',
 	'image',
 	'imageGap',
+	'images',
 	'label',
 	'logo',
 	'lineHeight',
@@ -63,16 +61,14 @@ const knownNestedFrontmatterKeys = new Set([
 	'pageWidth',
 	'palette',
 	'preset',
-	'presentation',
+	'profile',
 	'rhythm',
-	'sequence',
 	'sections',
 	'sectionGap',
 	'sectionSurfaces',
 	'size',
 	'spacingAfter',
 	'spacingBefore',
-	'surface',
 	'theme',
 	'typography',
 	'until',
@@ -108,14 +104,14 @@ export const getContentFiles = async () => {
 
 		const routeDirectory = entry.name;
 		const routeDir = path.join(siteRoutesDir, routeDirectory);
-		const routeContentPath = path.join(routeDir, 'route-content.md');
+		const routeContentPath = path.join(routeDir, 'content.md');
 
 		if (!(await fileExists(routeContentPath))) continue;
 
 		const { routeId, routeOrder } = parseRouteDirectory(routeDirectory, `${siteRoutesLabel}/${routeDirectory}`);
 
 		contentFiles.push({
-			contentLabel: `${siteRoutesLabel}/${routeDirectory}/route-content.md`,
+			contentLabel: `${siteRoutesLabel}/${routeDirectory}/content.md`,
 			contentPath: routeContentPath,
 			imagesDir: path.join(routeDir, 'images'),
 			imagesLabel: `${siteRoutesLabel}/${routeDirectory}/images`,
@@ -253,9 +249,16 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		const key = keyMatch[1];
 		if (knownTopLevelFrontmatterKeys.has(key)) continue;
 
-		const fix = knownNestedFrontmatterKeys.has(key)
-			? `Indent "${key}:" under the object it belongs to, or move image content into Norna Markdown blocks.`
-			: `Move "${key}:" under the correct parent key, or remove it if it is not part of the ${fileKind} schema.`;
+		let fix;
+		if (fileKind === 'content' && key === 'images') {
+			fix = 'Put local image references in norna-image-stack or norna-image-carousel blocks in the Markdown body.';
+		} else if (fileKind === 'content' && knownThemeTopLevelFrontmatterKeys.has(key)) {
+			fix = `Move "${key}:" to theme.yaml. Visual settings do not belong in content frontmatter.`;
+		} else if (knownNestedFrontmatterKeys.has(key)) {
+			fix = `Indent "${key}:" under the object it belongs to.`;
+		} else {
+			fix = `Move "${key}:" under the correct parent key, or remove it if it is not part of the ${fileKind} schema.`;
+		}
 
 		addIssue({
 			severity: 'error',
@@ -271,31 +274,34 @@ export const validateContentFrontmatterStructure = (frontmatter, addIssue) =>
 		fileKind: 'content',
 	});
 
-export const validateConfigFrontmatterStructure = (frontmatter, addIssue) =>
+export const validateConfigYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownConfigTopLevelFrontmatterKeys,
 		fileKind: 'config',
 	});
 
-export const validateThemeFrontmatterStructure = (frontmatter, addIssue) =>
+export const validateThemeYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownThemeTopLevelFrontmatterKeys,
 		fileKind: 'theme',
 	});
 
-export const validateRouteThemeFrontmatterStructure = (frontmatter, addIssue) =>
+export const validateRouteThemeYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownRouteThemeTopLevelFrontmatterKeys,
 		fileKind: 'route theme',
 	});
 
-export const validateSitewideFrontmatterStructure = (frontmatter, addIssue) =>
+export const validateSitewideYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownSitewideTopLevelFrontmatterKeys,
 		fileKind: 'sitewide content',
 	});
 
-export const readThemeFile = async (sitePath) => readSiteFile(sitePath, siteThemeLabel);
+export const readThemeFile = async (sitePath) => {
+	const source = await readFile(sitePath, 'utf8');
+	return { frontmatter: source, frontmatterBody: source, body: '' };
+};
 
 export const getFrontmatterSections = (frontmatter) => {
 	const sections = [];

package/scripts/lib/site-paths.mjs

@@ -22,10 +22,7 @@ export const invocationRoot = configuredInvocationRoot
 
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
-		(
-			existsSync(path.join(siteDir, 'config.md'))
-			|| existsSync(path.join(siteDir, 'config.mjs'))
-		)
+		existsSync(path.join(siteDir, 'config.yaml'))
 		&& existsSync(path.join(siteDir, 'content.md'))
 	);
 };
@@ -117,11 +114,10 @@ const getPathLabel = (filePath) => {
 };
 
 export const siteDir = resolvedSitePaths.siteDir;
-export const siteConfigPath = path.join(siteDir, 'config.md');
-export const legacySiteConfigPath = path.join(siteDir, 'config.mjs');
-export const siteThemePath = path.join(siteDir, 'theme.md');
+export const siteConfigPath = path.join(siteDir, 'config.yaml');
+export const siteThemePath = path.join(siteDir, 'theme.yaml');
 export const siteContentPath = path.join(siteDir, 'content.md');
-export const sitewideContentPath = path.join(siteDir, 'sitewide-content.md');
+export const sitewideContentPath = path.join(siteDir, 'sitewide-content.yaml');
 export const siteImagesDir = path.join(siteDir, 'images');
 export const siteRoutesDir = path.join(siteDir, 'routes');
 export const sitePublicDir = path.join(siteDir, 'public');

package/scripts/lib/sitewide-content.mjs

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import { sitewideSchema } from './schema-definitions.mjs';
+import {
+	sitewideContentLabel,
+	sitewideContentPath,
+} from './site-paths.mjs';
+import {
+	validateSitewideYamlStructure,
+} from './site-content.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+
+export const readSitewideContent = async () => {
+	const source = await readFile(sitewideContentPath, 'utf8').catch((error) => {
+		if (error?.code === 'ENOENT') return null;
+		throw error;
+	});
+
+	if (!source) return {};
+
+	return parseYamlConfig(source, sitewideContentLabel, {
+		schema: sitewideSchema,
+		validateStructure: validateSitewideYamlStructure,
+	});
+};

package/scripts/lib/theme-config.mjs

@@ -1,11 +1,8 @@
 import { readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
-import { parseYamlMapping } from './frontmatter-yaml.mjs';
 import {
-	splitSiteFile,
-	validateFrontmatterIndentation,
-	validateRouteThemeFrontmatterStructure,
-	validateThemeFrontmatterStructure,
+	validateRouteThemeYamlStructure,
+	validateThemeYamlStructure,
 } from './site-content.mjs';
 import {
 	siteRoutesDir,
@@ -14,7 +11,9 @@ import {
 	siteThemePath,
 	sitewideContentLabel,
 } from './site-paths.mjs';
+import { resolveThemePresentation } from './presentation.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
 
 export const readThemeConfig = async () => {
 	const themeFile = await readFile(siteThemePath, 'utf8').catch((error) => {
@@ -24,24 +23,14 @@ export const readThemeConfig = async () => {
 
 		throw error;
 	});
-	const { frontmatter, frontmatterBody } = splitSiteFile(themeFile, siteThemeLabel);
-	const issues = [];
-
-	validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
-	validateThemeFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
-
-	if (issues.length > 0) {
-		throw new Error([
-			`${siteThemeLabel} has invalid frontmatter.`,
-			...issues.map((issue) => `- ${issue.message}`),
-		].join('\n'));
-	}
-
-	const config = parseYamlMapping(frontmatterBody);
+	const config = parseYamlConfig(themeFile, siteThemeLabel, {
+		validateStructure: validateThemeYamlStructure,
+	});
 	if (Object.hasOwn(config, 'navigation')) {
-		throw new Error(`${siteThemeLabel} may not define navigation. Brand and logo belong in ${sitewideContentLabel}.`);
+		throw new Error(`${siteThemeLabel} may not define navigation. The site label and logo settings belong in ${sitewideContentLabel}.`);
 	}
 	resolveThemeConfig(config, siteThemeLabel);
+	resolveThemePresentation(config, siteThemeLabel);
 
 	return config;
 };
@@ -61,7 +50,7 @@ const getRouteThemeFiles = async (directory, relativeDirectory = '') => {
 			continue;
 		}
 
-		if (entry.name === 'theme.md') {
+		if (entry.name === 'theme.yaml') {
 			files.push({
 				path: absolutePath,
 				label: `${siteRoutesLabel}/${relativePath.split(path.sep).join('/')}`,
@@ -78,23 +67,14 @@ export const validateRouteThemeFiles = async () => {
 
 	for (const file of files) {
 		const source = await readFile(file.path, 'utf8');
-		const { frontmatter, frontmatterBody } = splitSiteFile(source, file.label);
-		const issues = [];
-		validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
-		validateRouteThemeFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
-
-		if (issues.length > 0) {
-			throw new Error([
-				`${file.label} has invalid frontmatter.`,
-				...issues.map((issue) => `- ${issue.message}`),
-			].join('\n'));
-		}
-
-		const config = parseYamlMapping(frontmatterBody);
+		const config = parseYamlConfig(source, file.label, {
+			validateStructure: validateRouteThemeYamlStructure,
+		});
 		if (Object.hasOwn(config, 'navigation')) {
-			throw new Error(`${file.label} may not define navigation. Brand and logo belong in ${sitewideContentLabel}.`);
+			throw new Error(`${file.label} may not define navigation. The site label and logo settings belong in ${sitewideContentLabel}.`);
 		}
 		resolveThemeConfig(config, file.label);
+		resolveThemePresentation(config, file.label);
 
 		configs.push({ ...file, config });
 	}

package/scripts/lib/theme-presets.mjs

@@ -1,13 +1,6 @@
 import { mergeDeep } from './typography.mjs';
 
-export const themePresetNames = [
-	'portfolio',
-	'documentation',
-	'project',
-	'statement',
-];
-
-export const themePresets = Object.freeze({
+const themePresetConfigurations = Object.freeze({
 	portfolio: Object.freeze({
 		layout: {
 			density: 'normal',
@@ -17,23 +10,18 @@ export const themePresets = Object.freeze({
 				mobile: '1rem',
 			},
 		},
-		gallery: {
+		images: {
 			width: '1000px',
 			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
 			maxAvailableHeightPercent: { desktop: 78, mobile: 68 },
 		},
 		typography: {
 			fontFamily: "'Helvetica Neue', Arial, sans-serif",
-			preset: 'quiet-gallery',
+			profile: 'restrained',
 			rhythm: 'normal',
 		},
-		presentation: {
-			palette: 'dark',
-			sectionSurfaces: {
-				mode: 'none',
-				sequence: ['base', 'soft', 'emphasis'],
-			},
-		},
+		palette: 'dark',
+		sectionSurfaces: ['base'],
 	}),
 	documentation: Object.freeze({
 		layout: {
@@ -44,23 +32,18 @@ export const themePresets = Object.freeze({
 				mobile: '1rem',
 			},
 		},
-		gallery: {
+		images: {
 			width: '920px',
 			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
 			maxAvailableHeightPercent: { desktop: 74, mobile: 68 },
 		},
 		typography: {
 			fontFamily: "Georgia, 'Times New Roman', serif",
-			preset: 'text-forward',
+			profile: 'reading',
 			rhythm: 'compact',
 		},
-		presentation: {
-			palette: 'paper',
-			sectionSurfaces: {
-				mode: 'cycle',
-				sequence: ['base', 'soft'],
-			},
-		},
+		palette: 'paper',
+		sectionSurfaces: ['base', 'soft'],
 	}),
 	project: Object.freeze({
 		layout: {
@@ -71,23 +54,18 @@ export const themePresets = Object.freeze({
 				mobile: '1rem',
 			},
 		},
-		gallery: {
+		images: {
 			width: '840px',
 			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
 			maxAvailableHeightPercent: { desktop: 70, mobile: 62 },
 		},
 		typography: {
 			fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
-			preset: 'text-forward',
+			profile: 'reading',
 			rhythm: 'compact',
 		},
-		presentation: {
-			palette: 'light',
-			sectionSurfaces: {
-				mode: 'cycle',
-				sequence: ['base', 'soft'],
-			},
-		},
+		palette: 'light',
+		sectionSurfaces: ['base', 'soft'],
 	}),
 	statement: Object.freeze({
 		layout: {
@@ -98,27 +76,62 @@ export const themePresets = Object.freeze({
 				mobile: '1rem',
 			},
 		},
-		gallery: {
+		images: {
 			width: '1080px',
 			maxAvailableWidthPercent: { desktop: 100, mobile: 100 },
 			maxAvailableHeightPercent: { desktop: 80, mobile: 70 },
 		},
 		typography: {
 			fontFamily: "'Trebuchet MS', 'Helvetica Neue', Arial, sans-serif",
-			preset: 'statement',
+			profile: 'statement',
 			rhythm: 'airy',
 		},
-		presentation: {
-			palette: 'paper',
-			sectionSurfaces: {
-				mode: 'cycle',
-				sequence: ['base', 'emphasis'],
-			},
-		},
+		palette: 'paper',
+		sectionSurfaces: ['base', 'emphasis'],
+	}),
+});
+
+export const themePresetDefinitions = Object.freeze({
+	portfolio: Object.freeze({
+		title: 'Portfolio',
+		description: 'For portfolios and image-led sites, with restrained typography and generous space for images.',
+		theme: themePresetConfigurations.portfolio,
+	}),
+	documentation: Object.freeze({
+		title: 'Documentation',
+		description: 'For guides and reference material, with reading-focused typography and compact spacing.',
+		theme: themePresetConfigurations.documentation,
+	}),
+	project: Object.freeze({
+		title: 'Project',
+		description: 'For project and product sites that balance explanation, code, cards, and images.',
+		theme: themePresetConfigurations.project,
+	}),
+	statement: Object.freeze({
+		title: 'Statement',
+		description: 'For short, expressive sites, with larger typography, airy spacing, and stronger section emphasis.',
+		theme: themePresetConfigurations.statement,
 	}),
 });
 
-export const getThemePreset = (presetName, sourceLabel = 'theme.md') => {
+export const themePresetNames = Object.freeze(Object.keys(themePresetDefinitions));
+
+export const themePresets = Object.freeze(Object.fromEntries(
+	themePresetNames.map((name) => [name, themePresetDefinitions[name].theme]),
+));
+
+export const getThemePresetMetadata = (presetName) => {
+	const definition = themePresetDefinitions[presetName];
+	if (!definition) return undefined;
+
+	return {
+		name: presetName,
+		title: definition.title,
+		description: definition.description,
+	};
+};
+
+export const getThemePreset = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = themePresets[presetName];
 
 	if (!preset) {
@@ -128,7 +141,7 @@ export const getThemePreset = (presetName, sourceLabel = 'theme.md') => {
 	return structuredClone(preset);
 };
 
-export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.md') => {
+export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.yaml') => {
 	const presetName = theme?.preset;
 	if (presetName === undefined) return structuredClone(theme ?? {});
 
@@ -151,15 +164,16 @@ const responsiveValueLines = (label, value, indent = 2) => {
 	];
 };
 
-export const renderThemePresetReference = (presetName, sourceLabel = 'theme.md') => {
+export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
-	const { layout, gallery, typography, presentation } = preset;
+	const metadata = getThemePresetMetadata(presetName);
+	const { layout, images, typography, palette, sectionSurfaces } = preset;
 
 	return [
-		'---',
 		`# Original values for Norna's "${presetName}" theme preset.`,
-		'# This is a reference file. Norna only loads theme.md.',
-		'# Keep the preset in theme.md and copy only the values you want to override.',
+		`# ${metadata.description}`,
+		'# This is a reference file. Norna only loads theme.yaml.',
+		'# Keep the preset in theme.yaml and copy only the values you want to override.',
 		`# Available theme presets: ${themePresetNames.join(', ')}.`,
 		`preset: ${presetName}`,
 		'',
@@ -174,18 +188,18 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.md')
 		'  # Optional spacing overrides use blockGap, finalSectionBottom,',
 		'  # firstSectionTop, headingToBlock, imageGap, and sectionGap.',
 		'',
-		'gallery:',
+		'images:',
 		'  # width accepts a positive CSS length.',
-		`  width: ${gallery.width}`,
+		`  width: ${images.width}`,
 		'  # Percent values must be greater than 0 and at most 100.',
-		...responsiveValueLines('maxAvailableWidthPercent', gallery.maxAvailableWidthPercent),
-		...responsiveValueLines('maxAvailableHeightPercent', gallery.maxAvailableHeightPercent),
+		...responsiveValueLines('maxAvailableWidthPercent', images.maxAvailableWidthPercent),
+		...responsiveValueLines('maxAvailableHeightPercent', images.maxAvailableHeightPercent),
 		'',
 		'typography:',
 		'  # Any valid CSS font-family stack without semicolons.',
 		`  fontFamily: ${quote(typography.fontFamily)}`,
-		'  # Alternatives: quiet-gallery, compact-gallery, text-forward, statement.',
-		`  preset: ${typography.preset}`,
+		'  # Alternatives: restrained, dense, reading, statement.',
+		`  profile: ${typography.profile}`,
 		'  # Alternatives: compact, normal, airy.',
 		`  rhythm: ${typography.rhythm}`,
 		'  # Fine-grained overrides can target headings.h1-h4, body, and caption.',
@@ -195,15 +209,11 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.md')
 		'  #     h2:',
 		'  #       size: large  # small, medium, large, or xlarge',
 		'',
-		'presentation:',
-		'  # Alternatives: dark, light, paper.',
-		`  palette: ${presentation.palette}`,
-		'  sectionSurfaces:',
-		'    # Alternatives: none, cycle.',
-		`    mode: ${presentation.sectionSurfaces.mode}`,
-		'    # Use one to three unique values from: base, soft, emphasis.',
-		`    sequence: [${presentation.sectionSurfaces.sequence.join(', ')}]`,
-		'---',
+		'# Alternatives: dark, light, paper.',
+		`palette: ${palette}`,
+		'# One value keeps every section on the same surface; multiple values cycle.',
+		'# Use one to three unique values from: base, soft, emphasis.',
+		`sectionSurfaces: [${sectionSurfaces.join(', ')}]`,
 		'',
 	].join('\n');
 };