@janga/norna 0.7.24 → 0.7.26

package/scripts/lib/presentation.mjs

@@ -87,16 +87,16 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f3f6f8', textColor: '#202932' },
+				page: { backgroundColor: '#e8f1f8', textColor: '#202932' },
 				surfaces: {
-					base: { backgroundColor: '#f3f6f8', textColor: '#202932' },
+					base: { backgroundColor: '#e8f1f8', textColor: '#202932' },
 					soft: { backgroundColor: '#e4eaf0', textColor: '#202932' },
 					emphasis: { backgroundColor: '#d3dee8', textColor: '#202932' },
 				},
-				frame: { backgroundColor: '#f3f6f8', textColor: '#202932' },
+				frame: { backgroundColor: '#e8f1f8', textColor: '#202932' },
 				css: {
 					surface: '#e9eef2',
-					muted: '#5d6a76',
+					muted: '#56636f',
 					soft: '#d5dfe7',
 					accent: '#2a5877',
 					border: 'rgb(32 41 50 / 16%)',
@@ -127,13 +127,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#eef4f1', textColor: '#203631' },
+				page: { backgroundColor: '#e3f1eb', textColor: '#203631' },
 				surfaces: {
-					base: { backgroundColor: '#eef4f1', textColor: '#203631' },
+					base: { backgroundColor: '#e3f1eb', textColor: '#203631' },
 					soft: { backgroundColor: '#dce9e4', textColor: '#203631' },
 					emphasis: { backgroundColor: '#c8ddd5', textColor: '#203631' },
 				},
-				frame: { backgroundColor: '#eef4f1', textColor: '#203631' },
+				frame: { backgroundColor: '#e3f1eb', textColor: '#203631' },
 				css: {
 					surface: '#e3ece8',
 					muted: '#536560',
@@ -167,16 +167,16 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f7f3fa', textColor: '#2e2736' },
+				page: { backgroundColor: '#f0e8f8', textColor: '#2e2736' },
 				surfaces: {
-					base: { backgroundColor: '#f7f3fa', textColor: '#2e2736' },
+					base: { backgroundColor: '#f0e8f8', textColor: '#2e2736' },
 					soft: { backgroundColor: '#ebe4f1', textColor: '#2e2736' },
 					emphasis: { backgroundColor: '#ddd3e8', textColor: '#2e2736' },
 				},
-				frame: { backgroundColor: '#f7f3fa', textColor: '#2e2736' },
+				frame: { backgroundColor: '#f0e8f8', textColor: '#2e2736' },
 				css: {
 					surface: '#eee8f3',
-					muted: '#6c6273',
+					muted: '#655b6c',
 					soft: '#ded5e7',
 					accent: '#604678',
 					border: 'rgb(46 39 54 / 16%)',
@@ -207,13 +207,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f8f5ee', textColor: '#272522' },
+				page: { backgroundColor: '#fdf6e3', textColor: '#272522' },
 				surfaces: {
-					base: { backgroundColor: '#f8f5ee', textColor: '#272522' },
+					base: { backgroundColor: '#fdf6e3', textColor: '#272522' },
 					soft: { backgroundColor: '#ebe5d9', textColor: '#272522' },
 					emphasis: { backgroundColor: '#ded4c5', textColor: '#272522' },
 				},
-				frame: { backgroundColor: '#f8f5ee', textColor: '#272522' },
+				frame: { backgroundColor: '#fdf6e3', textColor: '#272522' },
 				css: {
 					surface: '#f0ebe1',
 					muted: '#6b655b',
@@ -247,13 +247,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f7efd9', textColor: '#34291c' },
+				page: { backgroundColor: '#fbf1c7', textColor: '#34291c' },
 				surfaces: {
-					base: { backgroundColor: '#f7efd9', textColor: '#34291c' },
+					base: { backgroundColor: '#fbf1c7', textColor: '#34291c' },
 					soft: { backgroundColor: '#eadbb8', textColor: '#34291c' },
 					emphasis: { backgroundColor: '#d8c18c', textColor: '#34291c' },
 				},
-				frame: { backgroundColor: '#f7efd9', textColor: '#34291c' },
+				frame: { backgroundColor: '#fbf1c7', textColor: '#34291c' },
 				css: {
 					surface: '#efe2c4',
 					muted: '#6c5e4c',
@@ -287,13 +287,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f7efed', textColor: '#3c2929' },
+				page: { backgroundColor: '#f8e9e7', textColor: '#3c2929' },
 				surfaces: {
-					base: { backgroundColor: '#f7efed', textColor: '#3c2929' },
+					base: { backgroundColor: '#f8e9e7', textColor: '#3c2929' },
 					soft: { backgroundColor: '#ecdeda', textColor: '#3c2929' },
 					emphasis: { backgroundColor: '#ddc7c1', textColor: '#3c2929' },
 				},
-				frame: { backgroundColor: '#f7efed', textColor: '#3c2929' },
+				frame: { backgroundColor: '#f8e9e7', textColor: '#3c2929' },
 				css: {
 					surface: '#f0e3e0',
 					muted: '#6d5558',
@@ -327,13 +327,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f1f3e8', textColor: '#263225' },
+				page: { backgroundColor: '#eaf0da', textColor: '#263225' },
 				surfaces: {
-					base: { backgroundColor: '#f1f3e8', textColor: '#263225' },
+					base: { backgroundColor: '#eaf0da', textColor: '#263225' },
 					soft: { backgroundColor: '#e1e6d2', textColor: '#263225' },
 					emphasis: { backgroundColor: '#cbd5b7', textColor: '#263225' },
 				},
-				frame: { backgroundColor: '#f1f3e8', textColor: '#263225' },
+				frame: { backgroundColor: '#eaf0da', textColor: '#263225' },
 				css: {
 					surface: '#e7eadb',
 					muted: '#52604c',
@@ -367,16 +367,16 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f2f4fb', textColor: '#25243a' },
+				page: { backgroundColor: '#e8ebfa', textColor: '#25243a' },
 				surfaces: {
-					base: { backgroundColor: '#f2f4fb', textColor: '#25243a' },
+					base: { backgroundColor: '#e8ebfa', textColor: '#25243a' },
 					soft: { backgroundColor: '#e2e6f3', textColor: '#25243a' },
 					emphasis: { backgroundColor: '#d0d7eb', textColor: '#25243a' },
 				},
-				frame: { backgroundColor: '#f2f4fb', textColor: '#25243a' },
+				frame: { backgroundColor: '#e8ebfa', textColor: '#25243a' },
 				css: {
 					surface: '#e8eaf5',
-					muted: '#62647a',
+					muted: '#5b5d73',
 					soft: '#d5daec',
 					accent: '#3b568f',
 					border: 'rgb(37 36 58 / 16%)',
@@ -467,7 +467,6 @@ export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 	const paletteName = normalizedTheme.palette ?? 'near-monochrome';
 	const palette = getPresentationPalette(paletteName);
 	const appearance = normalizedTheme.appearance ?? {};
-	const readerControls = normalizedTheme.readerControls ?? {};
 	const defaultAppearance = appearance.default ?? 'system';
 	if (!appearanceNames.includes(defaultAppearance)) {
 		throw new Error(`appearance.default must be one of ${appearanceNames.join(', ')} in ${sourceLabel}.`);
@@ -488,9 +487,9 @@ export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 		},
 		readerPreferences: {
 			controls: {
-				appearance: readerControls.appearance === true,
+				appearance: true,
 				readingWidth: true,
-				focusReading: readerControls.focusReading === true,
+				focusReading: false,
 			},
 			defaults: {
 				appearance: defaultAppearance,

package/scripts/lib/project-config.mjs

@@ -13,7 +13,8 @@ import {
 	siteConfigPath,
 	siteThemeLabel,
 } from './site-paths.mjs';
-import { normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
+import { localEditorNames, normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
+import { resolveLocale } from './locale-registry.mjs';
 import { readThemeConfig } from './theme-config.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
@@ -197,156 +198,6 @@ const readSiteUrl = (config) => {
 	return url;
 };
 
-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',
-		calloutCaution: 'Caution',
-		calloutDanger: 'Danger',
-		calloutImportant: 'Important',
-		calloutNote: 'Note',
-		calloutTip: 'Tip',
-		calloutWarning: 'Warning',
-		editSource: 'Edit this page',
-		displaySettings: 'Display',
-		focusReading: 'Focus reading',
-		footnoteBackReference: 'Back to reference {reference}',
-		footnotes: 'Footnotes',
-		readingWidth: 'Reading width',
-		readingWidthNarrow: 'Narrow',
-		readingWidthStandard: 'Standard',
-		readingWidthWide: 'Wide',
-		resetDisplaySettings: 'Reset',
-		dismissBanner: 'Dismiss notice',
-		built: 'Built',
-		images: 'Images',
-		imageCarousel: 'image carousel',
-		navigationCollapsedAll: 'All navigation items collapsed.',
-		navigationCollapseAll: 'Collapse all',
-		navigationControls: 'Navigation tree controls',
-		navigationChildren: 'Child pages',
-		navigationExpandedAll: 'All navigation items expanded.',
-		navigationExpandAll: 'Expand all',
-		navigationFilter: 'Filter pages and groups',
-		navigationFilterEmpty: 'No matching pages or groups. The current page remains available.',
-		navigationFilterMatches: 'Matching navigation items: {count}',
-		navigationLocatedCurrent: 'Current page located.',
-		navigationLocateCurrent: 'Locate current page',
-		navigationMenu: 'Menu',
-		nextImage: 'Next image',
-		nextPage: 'Next page',
-		note: 'Note',
-		notFound: 'Page not found',
-		notFoundText: 'The requested page does not exist or may have moved.',
-		pageMoved: 'Page moved',
-		pageMovedText: 'This address now identifies',
-		pageNavigation: 'Page contents',
-		pageSequence: 'Page sequence',
-		pageSections: 'Sections',
-		previousImage: 'Previous image',
-		previousPage: 'Previous page',
-		returnHome: 'Go to the homepage',
-		search: 'Search',
-		searchDescription: 'Search the published content on this site.',
-		searchLoading: 'Loading search…',
-		searchNoScript: 'Search requires JavaScript. Use the page navigation when JavaScript is unavailable.',
-		searchUnavailable: 'Search is unavailable. During local work, run norna build:local to create or refresh the search index.',
-		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',
-		calloutCaution: 'Var försiktig',
-		calloutDanger: 'Fara',
-		calloutImportant: 'Viktigt',
-		calloutNote: 'Notera',
-		calloutTip: 'Tips',
-		calloutWarning: 'Varning',
-		editSource: 'Redigera den här sidan',
-		displaySettings: 'Visning',
-		focusReading: 'Fokuserad läsning',
-		footnoteBackReference: 'Tillbaka till referens {reference}',
-		footnotes: 'Fotnoter',
-		readingWidth: 'Textbredd',
-		readingWidthNarrow: 'Smal',
-		readingWidthStandard: 'Standard',
-		readingWidthWide: 'Bred',
-		resetDisplaySettings: 'Återställ',
-		dismissBanner: 'Stäng meddelande',
-		built: 'Byggd',
-		images: 'Bilder',
-		imageCarousel: 'bildkarusell',
-		navigationCollapsedAll: 'Alla navigationsposter har fällts ihop.',
-		navigationCollapseAll: 'Fäll ihop alla',
-		navigationControls: 'Kontroller för navigationsträdet',
-		navigationChildren: 'Undersidor',
-		navigationExpandedAll: 'Alla navigationsposter har fällts ut.',
-		navigationExpandAll: 'Fäll ut alla',
-		navigationFilter: 'Filtrera sidor och grupper',
-		navigationFilterEmpty: 'Inga sidor eller grupper matchar. Den aktuella sidan är fortfarande tillgänglig.',
-		navigationFilterMatches: 'Matchande navigationsposter: {count}',
-		navigationLocatedCurrent: 'Den aktuella sidan har hittats.',
-		navigationLocateCurrent: 'Hitta aktuell sida',
-		navigationMenu: 'Meny',
-		nextImage: 'Nästa bild',
-		nextPage: 'Nästa sida',
-		note: 'Not',
-		notFound: 'Sidan hittades inte',
-		notFoundText: 'Den begärda sidan finns inte eller kan ha flyttats.',
-		pageMoved: 'Sidan har flyttats',
-		pageMovedText: 'Den här adressen identifierar nu',
-		pageNavigation: 'Sidinnehåll',
-		pageSequence: 'Sidföljd',
-		pageSections: 'Avsnitt',
-		previousImage: 'Föregående bild',
-		previousPage: 'Föregående sida',
-		returnHome: 'Gå till startsidan',
-		search: 'Sök',
-		searchDescription: 'Sök i det publicerade innehållet på webbplatsen.',
-		searchLoading: 'Laddar sökning…',
-		searchNoScript: 'Sökning kräver JavaScript. Använd sidnavigeringen när JavaScript inte är tillgängligt.',
-		searchUnavailable: 'Sökningen är inte tillgänglig. Kör norna build:local under lokalt arbete för att skapa eller uppdatera sökindexet.',
-		siteBanners: 'Meddelanden',
-		siteNavigation: 'Sidor',
-		skipToContent: 'Hoppa till innehållet',
-	}),
-});
-
-const readLocale = (config) => {
-	const lang = config.language ?? 'en';
-
-	if (typeof lang !== 'string' || !/^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]+)*$/.test(lang.trim())) {
-		throw new Error(`language must be a valid language tag such as "en" or "sv" in ${siteConfigLabel}.`);
-	}
-
-	const normalizedLang = lang.trim();
-	const languageKey = normalizedLang.toLowerCase().split('-')[0];
-	const labels = localeLabels[languageKey];
-
-	if (!labels) {
-		throw new Error(`language "${normalizedLang}" has no built-in Norna UI text. Supported languages: ${Object.keys(localeLabels).join(', ')}.`);
-	}
-
-	return Object.freeze({
-		lang: normalizedLang,
-		labels,
-	});
-};
-
 const rawConfig = assertObject(siteConfig, 'config YAML');
 const rawTheme = assertObject(themeConfig, 'theme YAML', siteThemeLabel);
 const siteUrl = readSiteUrl(rawConfig);
@@ -541,22 +392,30 @@ export const resolveEditLinkConfig = (config, sourceLabel = siteConfigLabel) =>
 	if (config.editLink === undefined) return null;
 
 	const rawEditLink = assertObject(config.editLink, 'editLink', sourceLabel);
-	if (!Object.hasOwn(rawEditLink, 'baseUrl')) {
-		throw new Error(`editLink.baseUrl is required when editLink is configured in ${sourceLabel}.`);
-	}
-	const unknownKeys = Object.keys(rawEditLink).filter((key) => key !== 'baseUrl');
+	const unknownKeys = Object.keys(rawEditLink).filter((key) => !['baseUrl', 'localEditor'].includes(key));
 	if (unknownKeys.length > 0) {
 		throw new Error(`editLink.${unknownKeys[0]} is not a valid setting in ${sourceLabel}.`);
 	}
+	if (!Object.hasOwn(rawEditLink, 'baseUrl') && !Object.hasOwn(rawEditLink, 'localEditor')) {
+		throw new Error(`editLink must specify baseUrl, localEditor, or both in ${sourceLabel}.`);
+	}
 
-	try {
-		return Object.freeze({
-			baseUrl: normalizeEditLinkBaseUrl(rawEditLink.baseUrl, 'editLink.baseUrl'),
-		});
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`${message.replace(/\.$/, '')} in ${sourceLabel}.`);
+	let baseUrl = null;
+	if (Object.hasOwn(rawEditLink, 'baseUrl')) {
+		try {
+			baseUrl = normalizeEditLinkBaseUrl(rawEditLink.baseUrl, 'editLink.baseUrl');
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`${message.replace(/\.$/, '')} in ${sourceLabel}.`);
+		}
 	}
+
+	return Object.freeze({
+		baseUrl,
+		localEditor: Object.hasOwn(rawEditLink, 'localEditor')
+			? readEnum(rawEditLink, 'localEditor', 'editLink', localEditorNames, undefined, sourceLabel)
+			: null,
+	});
 };
 
 export const projectConfig = Object.freeze({
@@ -579,7 +438,7 @@ export const projectConfig = Object.freeze({
 			'instant',
 		),
 	}),
-	locale: readLocale(rawConfig),
+	locale: resolveLocale(rawConfig.language, siteConfigLabel),
 });
 
 export default projectConfig;

package/scripts/lib/schema-definitions.mjs

@@ -1,5 +1,7 @@
 import { z } from 'astro/zod';
+import { localEditorNames } from './edit-source-link.mjs';
 import { imagePresentationNames } from './image-presentation.mjs';
+import { supportedLocaleTagPattern } from './locale-registry.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
 import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { themePresetNames } from './theme-presets.mjs';
@@ -24,13 +26,6 @@ const themeAppearance = z.object({
 	(value) => value.default !== undefined,
 	'Specify default.',
 ).describe('Site-wide initial appearance. The default is system.');
-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', 'accented']).describe('How coordinated backgrounds are assigned to H2 sections. Non-uniform patterns are unavailable with tree navigation.');
@@ -51,8 +46,15 @@ const editLink = z.object({
 			return false;
 		}
 	}, 'Use an absolute http or https URL without credentials, a query string, or a fragment.')
-		.describe('Absolute edit URL prefix containing the repository, branch, and any repository subdirectory.'),
-}).strict().describe('Optional base URL for links from rendered pages to their Markdown source files.');
+		.describe('Absolute edit URL prefix containing the repository, branch, and any repository subdirectory.')
+		.optional(),
+	localEditor: z.enum(localEditorNames)
+		.optional()
+		.describe('Editor used by source links in a development preview opened through a loopback address.'),
+}).strict().refine(
+	(value) => value.baseUrl !== undefined || value.localEditor !== undefined,
+	'Specify baseUrl, localEditor, or both.',
+).describe('Optional local and remote links from rendered pages to their Markdown source files.');
 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.`)
@@ -188,7 +190,7 @@ const themeBlocks = z.object({
 	'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.'),
+	mode: navigationMode.optional().describe('How Norna presents the discovered page and heading hierarchy. Omit this to select automatic.'),
 }).strict().describe('Site-wide navigation behavior.');
 const themeSections = z.object({
 	backgroundPattern: backgroundPattern.optional().describe('Section background pattern. Alternating and accented create full-width bands with sections or top navigation; tree navigation requires uniform.'),
@@ -236,7 +238,7 @@ const sitewideFooter = z.object({
 
 const configShape = {
 	url: z.string().url().describe('Absolute public URL for the built site.'),
-	language: z.string().regex(/^(?:en|sv)(?:-[a-zA-Z0-9]+)*$/).optional().describe('Site language tag using Norna\'s English or Swedish interface text; the default is en.'),
+	language: z.string().regex(supportedLocaleTagPattern).optional().describe('Site language tag selecting one complete built-in Norna interface language; the default is en.'),
 	editLink: editLink.optional(),
 	navigation: configNavigation.optional(),
 	search: z.boolean().optional().default(false).describe('Generate a static site search page and Pagefind index. The default is false.'),
@@ -251,7 +253,6 @@ const siteShape = {
 const themeVisualShape = {
 	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
 	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(),

package/scripts/lib/schema-editor-metadata.mjs

@@ -1,4 +1,8 @@
 import { documentationLink } from './documentation-links.mjs';
+import {
+	localeDefinitions,
+	supportedQualifiedLocaleTagPatternSource,
+} from './locale-registry.mjs';
 import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { getSchemaValueDefinition } from './schema-value-definitions.mjs';
 
@@ -105,20 +109,21 @@ const addValueDescriptions = (schema) => {
 const addLanguageSuggestions = (jsonSchema) => {
 	const language = jsonSchema.properties?.language;
 	if (!language) throw new Error('Generated config schema has no language property.');
-	const definition = getSchemaValueDefinition(['en', 'sv']);
 	language.default = 'en';
-	language.examples = ['en', 'sv', 'en-GB', 'sv-SE'];
+	language.examples = ['en', 'sv', 'es', 'el', 'uk', 'sr-Cyrl', 'en-GB', 'pt-BR'];
 	language.oneOf = [
-		...definition.values.map((value) => ({
-			const: value,
-			title: definition.options[value].title,
-			description: definition.options[value].description,
+		...localeDefinitions.map(({ tag, name, nativeName, script, requiresScript }) => ({
+			const: tag,
+			title: nativeName === name ? name : `${nativeName} — ${name}`,
+			description: requiresScript
+				? `Use Norna's built-in ${name} interface text in the ${script} script.`
+				: `Use Norna's built-in ${name} interface text.`,
 		})),
 		{
 			type: 'string',
-			pattern: '^(?:en|sv)-[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$',
-			title: 'Regional language tag',
-			description: 'Use an English or Swedish regional language tag such as en-GB or sv-SE.',
+			pattern: supportedQualifiedLocaleTagPatternSource,
+			title: 'Regional or script-qualified tag',
+			description: 'Add a region to a supported language, such as en-GB, pt-BR, or sr-Cyrl-RS. Norna preserves the complete tag in generated HTML.',
 		},
 	];
 };
@@ -156,34 +161,51 @@ const addConfigHelp = (jsonSchema) => {
 	], ['https://example.com/', 'https://owner.github.io/repository-name/']);
 	addHelp(jsonSchema, 'language', [
 		yamlExample('language: en-GB'),
-		'Sets the page language and selects Norna\'s built-in English or Swedish interface text. The default is `en`.',
+		'Sets the language of the complete site and selects the matching built-in Norna interface text. Regional tags are preserved. The default is `en`; editorial Markdown is not translated.',
 		documentationLink('Language reference', 'configuration.md', 'language'),
-	], ['en', 'sv', 'en-GB', 'sv-SE']);
+	], ['en', 'sv', 'es', 'el', 'uk', 'sr-Cyrl', 'en-GB', 'pt-BR']);
 	addHelp(jsonSchema, 'editLink', [
-		yamlExample('editLink:\n  baseUrl: https://github.com/owner/repository/edit/main/'),
-		'Adds a localized **Edit this page** link from each rendered page to its `content.md` source file. The base URL identifies the repository, branch, and any repository subdirectory; Norna appends the page source path.',
+		yamlExample('editLink:\n  localEditor: vscode\n  baseUrl: https://github.com/owner/repository/edit/main/'),
+		'Links each rendered page to its `content.md` source. A loopback development preview uses the explicitly selected local editor; published output and LAN previews use the optional remote base URL. Specify either destination or both.',
 		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
 	]);
+	const editLink = schemaProperty(jsonSchema, 'editLink');
+	editLink.anyOf = [{ required: ['localEditor'] }, { required: ['baseUrl'] }];
+	addSnippets(jsonSchema, 'editLink', [schemaSnippet({
+		label: 'Local and remote source links',
+		body: {
+			localEditor: 'vscode',
+			baseUrl: 'https://github.com/${1:owner}/${2:repository}/edit/${3:main}/',
+		},
+		description: 'Open page source in VS Code during same-computer development and on the remote source host elsewhere.',
+		file: 'configuration.md',
+		anchor: 'edit-link',
+	})]);
 	addHelp(jsonSchema, 'editLink.baseUrl', [
 		yamlExample('editLink:\n  baseUrl: https://github.com/owner/repository/edit/main/'),
-		'Absolute edit URL prefix. Include any repository subdirectory and branch in this URL. Norna adds the project-relative path to each page\'s `content.md` file.',
+		'Optional absolute remote edit URL prefix. Include any repository subdirectory and branch. Norna adds the project-relative path to each page\'s `content.md` file. This destination is used by published output and LAN previews.',
 		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
 	], ['https://github.com/owner/repository/edit/main/']);
+	addHelp(jsonSchema, 'editLink.localEditor', [
+		yamlExample('editLink:\n  localEditor: vscode'),
+		'Optional editor for a development preview opened through localhost or another loopback address. `vscode` opens the absolute page source path through VS Code\'s registered URL handler. The setting is never emitted as a local path in published output.',
+		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
+	], ['vscode']);
 	addHelp(jsonSchema, 'navigation', [
 		yamlExample('navigation:\n  mode: automatic'),
-		'Sets the site-wide navigation policy. `automatic` uses sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a hierarchical site.',
-		documentationLink('Navigation reference', 'pages.md', 'navigation'),
+		'Chooses how Norna presents the discovered page and heading hierarchy. Keep `automatic` unless the site deliberately needs to retain one presentation as its structure changes.',
+		documentationLink('Navigation setting reference', 'configuration.md', 'navigation'),
 	]);
 	addHelp(jsonSchema, 'search', [
 		yamlExample('search: true'),
-		'Generates a localized `/search/` page and a static Pagefind index during each build. Search is off by default, and only the search page loads the search JavaScript.',
+		'Generates a localized `/search/` page and a static Pagefind index during each build. Search is off by default. Only the search page loads the search engine and index; a small navigation script remembers where readers opened it.',
 		documentationLink('Search reference', 'configuration.md', 'search'),
 	], [true, false]);
 	addFieldHelp(
 		jsonSchema,
 		'navigation.mode',
 		'navigation:\n  mode: automatic',
-		'pages.md',
+		'configuration.md',
 		'navigation',
 		['automatic', 'sections', 'top', 'tree'],
 	);
@@ -261,7 +283,7 @@ const addThemeHelp = (jsonSchema) => {
 	], presentationPaletteNames);
 	addHelp(jsonSchema, 'appearance', [
 		yamlExample('appearance:\n  default: system'),
-		'Selects the initial Appearance. Omit this setting to follow the visitor\'s system preference. Enable the reader-facing choice under readerControls.',
+		'Selects the initial Appearance. The Appearance choice is always available in the site-wide Display panel. Omit this setting to follow the visitor\'s system preference.',
 		documentationLink('Appearance', 'theme.md', 'appearance'),
 	]);
 	addFieldHelp(jsonSchema, 'appearance.default', 'appearance:\n  default: system', 'theme.md', 'appearance', ['system', 'light', 'dark']);
@@ -272,32 +294,6 @@ const addThemeHelp = (jsonSchema) => {
 		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 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.',
@@ -611,7 +607,7 @@ const addContentHelp = (jsonSchema) => {
 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.',
+		'`category.yaml` groups child pages without editorial content. Its URL opens the first listed direct page, or a generated child list when the first child is a category.',
 		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
 	].join('\n\n');
 	addHelp(jsonSchema, 'label', [

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

@@ -23,14 +23,13 @@ export const schemaValueDefinitions = Object.freeze([
 		smooth: option('Browser smooth', 'Use the browser\'s native smooth scrolling for anchor navigation.'),
 	}),
 	definition(['automatic', 'sections', 'top', 'tree'], {
-		automatic: option('Automatic', 'Choose sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a site with listed child pages or categories.'),
-		sections: option('Sections', 'Navigate the sections of the current page.'),
-		top: option('Top', 'Use pages in the top navigation and sections below them.'),
-		tree: option('Tree', 'Use a left page rail and a separate right H2/H3 contents rail where the page has enough headings.'),
-	}),
-	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.'),
+		automatic: option('Automatic', 'Choose one site-wide navigation presentation from the listed page hierarchy. This is the default.'),
+		sections: option('Sections', 'Keep a one-page site title and its H2 sections in sticky page navigation.'),
+		top: option('Top', 'Keep top-level pages in the global row and give the current page section navigation when needed.'),
+		tree: option('Tree', 'Keep top-level areas global and add a persistent left page tree. Deep branches can add a right H2/H3 contents rail.'),
+	}),
+	definition(['vscode'], {
+		vscode: option('Visual Studio Code', 'Open the current page source in the locally installed Visual Studio Code application.'),
 	}),
 	definition(['left', 'center', 'right'], {
 		left: option('Left', 'Align text with the left edge of its text area.'),