@janga/norna 0.7.24 → 0.7.25

package/scripts/check-config.mjs

@@ -76,7 +76,11 @@ try {
 	console.log('Config check passed.');
 	console.log(`Site URL: ${projectConfig.site.url}`);
 	console.log(`Base path: ${projectConfig.site.basePath}`);
-	console.log(`Edit links: ${projectConfig.editLink?.baseUrl ?? '(disabled)'}`);
+	const editLinkDestinations = [
+		projectConfig.editLink?.localEditor ? `local ${projectConfig.editLink.localEditor}` : null,
+		projectConfig.editLink?.baseUrl ? `remote ${projectConfig.editLink.baseUrl}` : null,
+	].filter(Boolean);
+	console.log(`Edit links: ${editLinkDestinations.join(', ') || '(disabled)'}`);
 	console.log(`Theme preset: ${themeConfig.preset ?? '(none)'}`);
 	console.log(`Page width: ${projectConfig.layout.pageWidth}`);
 	console.log(`Gutter: desktop ${projectConfig.layout.gutter.desktop}, mobile ${projectConfig.layout.gutter.mobile}`);

package/scripts/dev-local.mjs

@@ -5,7 +5,12 @@ import { networkInterfaces } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { getAstroArgs, runAstroInherit } from './lib/astro-command.mjs';
-import { astroCacheDir, engineRoot, siteProjectRoot } from './lib/site-paths.mjs';
+import {
+	astroCacheDir,
+	engineRoot,
+	siteProjectRoot,
+	siteStateDir,
+} from './lib/site-paths.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -27,7 +32,10 @@ const probeUrls = [
 	`http://localhost:${port}${projectConfig.site.basePath}`,
 ];
 const skipOpen = process.env.NORNA_NO_OPEN === '1';
-const statePath = path.join(astroCacheDir, 'dev-local.json');
+const stateDirectory = path.join(siteStateDir, 'dev');
+const statePath = path.join(stateDirectory, 'state.json');
+const legacyStatePath = path.join(astroCacheDir, 'dev-local.json');
+const astroStatePath = path.join(astroCacheDir, 'dev.json');
 const logPath = path.join(astroCacheDir, 'dev.log');
 const args = process.argv.slice(2);
 const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
@@ -51,9 +59,9 @@ const generateImages = async () => execFileAsync(process.execPath, [path.join(en
 	maxBuffer: 1024 * 1024 * 10,
 });
 
-const readState = async () => {
+const readJsonFile = async (filePath) => {
 	try {
-		return JSON.parse(await readFile(statePath, 'utf8'));
+		return JSON.parse(await readFile(filePath, 'utf8'));
 	} catch (error) {
 		if (error.code === 'ENOENT') {
 			return null;
@@ -63,15 +71,34 @@ const readState = async () => {
 	}
 };
 
+const readState = async () => (
+	await readJsonFile(statePath)
+	?? await readJsonFile(legacyStatePath)
+);
+
 const getLanUrls = () => Object.values(networkInterfaces())
 	.flat()
 	.filter((network) => network?.family === 'IPv4' && !network.internal)
 	.map((network) => `http://${network.address}:${port}${projectConfig.site.basePath}`);
 
 const writeState = async (host) => {
-	await mkdir(path.dirname(statePath), { recursive: true });
+	const astroState = await readJsonFile(astroStatePath);
+	let pid = astroState?.port === port && isProcessAlive(astroState.pid)
+		? astroState.pid
+		: null;
+	if (!Number.isInteger(pid)) {
+		const listeningPids = await getPortPids({ required: false });
+		pid = listeningPids?.length === 1 ? listeningPids[0] : null;
+	}
+
+	if (!Number.isInteger(pid)) {
+		throw new Error(`The dev server started at ${localUrl}, but Norna could not record its process. Stop the process on port ${port} before starting it again.`);
+	}
+
+	await mkdir(stateDirectory, { recursive: true });
 	await writeFile(statePath, `${JSON.stringify({
 		port,
+		pid,
 		host,
 		mode: host === '0.0.0.0' ? 'lan' : 'local',
 		url: localUrl,
@@ -81,6 +108,8 @@ const writeState = async (host) => {
 
 const removeState = async () => {
 	await rm(statePath, { force: true });
+	await rm(legacyStatePath, { force: true });
+	await rm(stateDirectory, { recursive: true, force: true });
 };
 
 const readDevLog = async () => {
@@ -161,6 +190,16 @@ const sleep = (milliseconds) => new Promise((resolve) => {
 	setTimeout(resolve, milliseconds);
 });
 
+const isProcessAlive = (pid) => {
+	if (!Number.isInteger(pid)) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === 'EPERM';
+	}
+};
+
 const isServerReachable = async () => {
 	for (const probeUrl of probeUrls) {
 		try {
@@ -213,7 +252,7 @@ const parseWindowsPortPids = (stdout) => [...new Set(
 		.filter(Number.isInteger),
 )];
 
-const getPortPids = async () => {
+const getPortPids = async ({ required = true } = {}) => {
 	try {
 		if (process.platform === 'win32') {
 			const { stdout } = await execFileAsync('powershell.exe', [
@@ -234,6 +273,7 @@ const getPortPids = async () => {
 	} catch (error) {
 		if (error.code === 1) return [];
 		if (error.code === 'ENOENT') {
+			if (!required) return null;
 			const commandName = process.platform === 'win32' ? 'PowerShell' : 'lsof';
 			throw new Error(`Cannot use --kill because ${commandName} is not available. Stop the process on port ${port} manually, then rerun the command.`);
 		}
@@ -273,6 +313,31 @@ const terminatePortProcesses = async (host) => {
 	}
 };
 
+const terminateTrackedProcess = async (state, host) => {
+	if (state?.port !== port || !Number.isInteger(state.pid)) return false;
+	if (!isProcessAlive(state.pid)) return false;
+
+	const listeningPids = await getPortPids({ required: false });
+	if (listeningPids && !listeningPids.includes(state.pid)) return false;
+	if (!listeningPids && !(await isServerReachable())) return false;
+
+	try {
+		process.kill(state.pid, 'SIGTERM');
+	} catch (error) {
+		if (error.code !== 'ESRCH') throw error;
+	}
+
+	if (await waitForPortToBeFree(host)) return true;
+
+	try {
+		process.kill(state.pid, 'SIGKILL');
+	} catch (error) {
+		if (error.code !== 'ESRCH') throw error;
+	}
+
+	return waitForPortToBeFree(host);
+};
+
 const openBrowser = async () => {
 	if (skipOpen) {
 		console.log(`Browser open skipped. Open ${localUrl}`);
@@ -294,10 +359,27 @@ const openBrowser = async () => {
 
 const stopServer = async ({ quiet = false } = {}) => {
 	const state = await readState();
-	const { stdout = '', stderr = '' } = await runAstro(['dev', 'stop']);
-	const stopped = `${stdout}\n${stderr}`.includes('Stopped dev server');
-	if (stopped) await waitForPortToBeFree(state?.host ?? localHost);
-	await removeState();
+	let astroError;
+	let astroOutput = '';
+	try {
+		const { stdout = '', stderr = '' } = await runAstro(['dev', 'stop']);
+		astroOutput = `${stdout}\n${stderr}`;
+	} catch (error) {
+		astroError = error;
+	}
+
+	let stopped = astroOutput.includes('Stopped dev server');
+	if (stopped) {
+		await waitForPortToBeFree(state?.host ?? localHost);
+	} else {
+		stopped = await terminateTrackedProcess(state, state?.host ?? localHost);
+	}
+
+	if (stopped || !(await isServerReachable())) {
+		await removeState();
+	}
+
+	if (astroError && !stopped) throw astroError;
 
 	if (!quiet) {
 		console.log(stopped
@@ -370,7 +452,20 @@ const showStatus = async () => {
 	}
 
 	if (reachable) {
-		console.log(`A server is responding at ${localUrl}, but Astro does not track it for this site.`);
+		const listeningPids = await getPortPids({ required: false });
+		const stateOwnsPort = state?.port === port
+			&& Number.isInteger(state.pid)
+			&& (listeningPids ? listeningPids.includes(state.pid) : isProcessAlive(state.pid));
+		if (stateOwnsPort) {
+			console.log(`dev:${state.mode ?? 'local'} is running at ${localUrl}. Norna retained its process record after Astro cleared its cache.`);
+			if (state.host === '0.0.0.0') {
+				const lanUrls = getLanUrls();
+				if (lanUrls.length > 0) console.log(`On this local network: ${lanUrls.join(', ')}`);
+			}
+			return;
+		}
+
+		console.log(`A server is responding at ${localUrl}, but neither Astro nor Norna tracks it for this site.`);
 		return;
 	}
 

package/scripts/init-site.mjs

@@ -18,6 +18,7 @@ dist/
 # generated site state
 **/.norna/public/
 **/.norna/.astro/
+**/.norna/dev/
 
 # legacy Astro cache location
 .astro/
@@ -40,6 +41,7 @@ pnpm-debug.log*
 `;
 const siteGitignore = `.norna/public/
 .norna/.astro/
+.norna/dev/
 `;
 
 const usage = `

package/scripts/lib/code-fence-metadata.mjs

@@ -210,12 +210,17 @@ export const nornaCodeFenceTransformer = {
 			tagName: 'figure',
 			properties: { className: ['norna-code-example'] },
 			children: [
-				{
-					type: 'element',
-					tagName: 'figcaption',
-					properties: { className: ['norna-code-title'] },
-					children: [{ type: 'text', value: metadata.title }],
-				},
+					{
+						type: 'element',
+						tagName: 'figcaption',
+						properties: { className: ['norna-code-title'] },
+						children: [{
+							type: 'element',
+							tagName: 'span',
+							properties: { className: ['norna-code-title-text'] },
+							children: [{ type: 'text', value: metadata.title }],
+						}],
+					},
 				node,
 			],
 		};

package/scripts/lib/edit-source-link.mjs

@@ -1,3 +1,8 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const localEditorNames = Object.freeze(['vscode']);
+
 const assertHttpUrl = (value, label) => {
 	if (typeof value !== 'string' || value.trim() === '') {
 		throw new Error(`${label} must be a non-empty absolute URL.`);
@@ -47,3 +52,51 @@ export const getEditSourceUrl = ({ baseUrl, sourcePath }) => {
 	const encodedPath = segments.map((segment) => encodeURIComponent(segment)).join('/');
 	return new URL(encodedPath, normalizedBaseUrl).href;
 };
+
+export const isLoopbackHostname = (hostname) => {
+	const normalizedHostname = String(hostname ?? '')
+		.trim()
+		.toLowerCase()
+		.replace(/^\[|\]$/g, '')
+		.replace(/\.$/, '');
+
+	return normalizedHostname === 'localhost'
+		|| normalizedHostname.endsWith('.localhost')
+		|| normalizedHostname === '::1'
+		|| normalizedHostname.startsWith('::ffff:127.')
+		|| /^127(?:\.\d{1,3}){3}$/.test(normalizedHostname);
+};
+
+export const getLocalEditorSourceUrl = ({ editor, sourcePath }) => {
+	if (!localEditorNames.includes(editor)) {
+		throw new Error(`Unknown local editor "${editor}". Use one of: ${localEditorNames.join(', ')}.`);
+	}
+	if (typeof sourcePath !== 'string' || !path.isAbsolute(sourcePath)) {
+		throw new Error('Local editor source path must be absolute.');
+	}
+
+	const fileUrl = pathToFileURL(path.normalize(sourcePath));
+	return `vscode://file${fileUrl.pathname}`;
+};
+
+export const resolveEditSourceTarget = ({
+	baseUrl,
+	development = false,
+	hostname,
+	localEditor,
+	sourceLabel,
+	sourcePath,
+}) => {
+	if (development && localEditor && isLoopbackHostname(hostname)) {
+		return Object.freeze({
+			href: getLocalEditorSourceUrl({ editor: localEditor, sourcePath }),
+			kind: 'local',
+		});
+	}
+	if (!baseUrl) return null;
+
+	return Object.freeze({
+		href: getEditSourceUrl({ baseUrl, sourcePath: sourceLabel }),
+		kind: 'remote',
+	});
+};

package/scripts/lib/navigation-model.mjs

@@ -75,7 +75,7 @@ export const resolvePageContentsPlacement = ({
 		Math.max(maximum, getNodeDepth(node))
 	), 0);
 	const hasPageContents = headingCount >= 2;
-	const placement = navigationMode !== 'tree' || !hasPageContents
+	const placement = currentPage?.isHome || navigationMode !== 'tree' || !hasPageContents
 		? 'none'
 		: activeBranchDepth <= 2
 			? 'page-tree'

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

@@ -607,6 +607,97 @@ export const extractNornaMarkdownBlockDiagnostics = (markdown, options = {}) =>
 	return { blocks, errors };
 };
 
+const stripRenderedTags = (value) => value.replace(/<[^>]*>/g, '');
+const decodeRenderedEntities = (value) => value
+	.replace(/&amp;/g, '&')
+	.replace(/&lt;/g, '<')
+	.replace(/&gt;/g, '>')
+	.replace(/&quot;/g, '"')
+	.replace(/&#39;/g, "'");
+const normalizeRenderedBlockSource = (value) => value.replace(/\r\n?/g, '\n').trim();
+
+/**
+ * Splits rendered HTML at Norna markers. During an Astro content hot reload,
+ * custom code nodes can occasionally arrive as highlighted code instead of
+ * their marker; match that output against the already validated source block.
+ *
+ * @template {{ type: string, source?: string }} Block
+ * @param {string} html
+ * @param {Block[]} blocks
+ * @returns {Array<{ type: 'html', html: string } | Block>}
+ */
+export const splitNornaRenderedBlocks = (html, blocks) => {
+	const markerRegex = /<norna-block\s+data-index="(\d+)"\s*><\/norna-block>/g;
+	const markerMatches = [...html.matchAll(markerRegex)];
+	let replacements;
+
+	if (markerMatches.length > 0) {
+		const seen = new Set();
+		replacements = markerMatches.map((match) => {
+			const blockIndex = Number.parseInt(match[1] ?? '', 10);
+			if (!blocks[blockIndex]) {
+				throw new Error(`Rendered Norna block ${blockIndex + 1} has no matching parsed block.`);
+			}
+			if (seen.has(blockIndex)) {
+				throw new Error(`Rendered Norna block ${blockIndex + 1} appears more than once.`);
+			}
+			seen.add(blockIndex);
+			return { match, blockIndex };
+		});
+
+		if (seen.size !== blocks.length) {
+			throw new Error(`Rendered Markdown contains ${seen.size} Norna block markers, but ${blocks.length} blocks were parsed.`);
+		}
+	} else {
+		const codeRegex = /<pre\b[^>]*>\s*<code\b[^>]*>([\s\S]*?)<\/code>\s*<\/pre>/g;
+		const candidates = [...html.matchAll(codeRegex)].map((match) => ({
+			match,
+			source: normalizeRenderedBlockSource(decodeRenderedEntities(stripRenderedTags(match[1] ?? ''))),
+		}));
+		const solutions = [];
+		const findSolutions = (blockIndex, candidateIndex, selected) => {
+			if (solutions.length > 1) return;
+			if (blockIndex === blocks.length) {
+				solutions.push([...selected]);
+				return;
+			}
+
+			const source = normalizeRenderedBlockSource(blocks[blockIndex]?.source ?? '');
+			for (let index = candidateIndex; index < candidates.length; index += 1) {
+				if (candidates[index].source !== source) continue;
+				selected.push(index);
+				findSolutions(blockIndex + 1, index + 1, selected);
+				selected.pop();
+			}
+		};
+		findSolutions(0, 0, []);
+
+		if (solutions.length === 0) {
+			throw new Error(`Rendered Markdown contains 0 Norna block markers, but ${blocks.length} blocks were parsed.`);
+		}
+		if (solutions.length > 1) {
+			throw new Error('Rendered Markdown contains ambiguous plain-code matches for Norna blocks. Restart the local preview to rebuild the Markdown content cache.');
+		}
+
+		replacements = solutions[0].map((candidateIndex, blockIndex) => ({
+			match: candidates[candidateIndex].match,
+			blockIndex,
+		}));
+	}
+
+	const result = [];
+	let cursor = 0;
+	for (const { match, blockIndex } of replacements) {
+		const start = match.index ?? 0;
+		if (start > cursor) result.push({ type: 'html', html: html.slice(cursor, start) });
+		result.push(blocks[blockIndex]);
+		cursor = start + match[0].length;
+	}
+	if (cursor < html.length) result.push({ type: 'html', html: html.slice(cursor) });
+
+	return result.filter((block) => block.type !== 'html' || block.html.trim());
+};
+
 const maskFencedCodeBlocks = (markdown) => {
 	const lines = normalizeLines(markdown);
 	const maskedLines = [];

package/scripts/lib/project-config.mjs

@@ -13,7 +13,7 @@ import {
 	siteConfigPath,
 	siteThemeLabel,
 } from './site-paths.mjs';
-import { normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
+import { localEditorNames, normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
 import { readThemeConfig } from './theme-config.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
@@ -213,6 +213,7 @@ const localeLabels = Object.freeze({
 		calloutNote: 'Note',
 		calloutTip: 'Tip',
 		calloutWarning: 'Warning',
+		closeNavigation: 'Close navigation',
 		editSource: 'Edit this page',
 		displaySettings: 'Display',
 		focusReading: 'Focus reading',
@@ -227,6 +228,11 @@ const localeLabels = Object.freeze({
 		built: 'Built',
 		images: 'Images',
 		imageCarousel: 'image carousel',
+		imageInspection: 'Image inspection',
+		imageInspectionActualSize: 'Show actual size',
+		imageInspectionClose: 'Close image inspection',
+		imageInspectionFit: 'Fit image to window',
+		inspectImage: 'Inspect image: {description}',
 		navigationCollapsedAll: 'All navigation items collapsed.',
 		navigationCollapseAll: 'Collapse all',
 		navigationControls: 'Navigation tree controls',
@@ -242,6 +248,7 @@ const localeLabels = Object.freeze({
 		nextImage: 'Next image',
 		nextPage: 'Next page',
 		note: 'Note',
+		openInVsCode: 'Open in VS Code',
 		notFound: 'Page not found',
 		notFoundText: 'The requested page does not exist or may have moved.',
 		pageMoved: 'Page moved',
@@ -260,6 +267,10 @@ const localeLabels = Object.freeze({
 		siteBanners: 'Site notices',
 		siteNavigation: 'Pages',
 		skipToContent: 'Skip to content',
+		tableColumns: 'Table columns',
+		tableNextColumns: 'Show next columns',
+		tableOverflowDescription: 'More table columns are available horizontally.',
+		tablePreviousColumns: 'Show previous columns',
 	}),
 	sv: Object.freeze({
 		breadcrumb: 'Brödsmulor',
@@ -276,6 +287,7 @@ const localeLabels = Object.freeze({
 		calloutNote: 'Notera',
 		calloutTip: 'Tips',
 		calloutWarning: 'Varning',
+		closeNavigation: 'Stäng navigationen',
 		editSource: 'Redigera den här sidan',
 		displaySettings: 'Visning',
 		focusReading: 'Fokuserad läsning',
@@ -290,6 +302,11 @@ const localeLabels = Object.freeze({
 		built: 'Byggd',
 		images: 'Bilder',
 		imageCarousel: 'bildkarusell',
+		imageInspection: 'Bildgranskning',
+		imageInspectionActualSize: 'Visa faktisk storlek',
+		imageInspectionClose: 'Stäng bildgranskning',
+		imageInspectionFit: 'Anpassa bilden till fönstret',
+		inspectImage: 'Granska bild: {description}',
 		navigationCollapsedAll: 'Alla navigationsposter har fällts ihop.',
 		navigationCollapseAll: 'Fäll ihop alla',
 		navigationControls: 'Kontroller för navigationsträdet',
@@ -305,6 +322,7 @@ const localeLabels = Object.freeze({
 		nextImage: 'Nästa bild',
 		nextPage: 'Nästa sida',
 		note: 'Not',
+		openInVsCode: 'Öppna i VS Code',
 		notFound: 'Sidan hittades inte',
 		notFoundText: 'Den begärda sidan finns inte eller kan ha flyttats.',
 		pageMoved: 'Sidan har flyttats',
@@ -323,6 +341,10 @@ const localeLabels = Object.freeze({
 		siteBanners: 'Meddelanden',
 		siteNavigation: 'Sidor',
 		skipToContent: 'Hoppa till innehållet',
+		tableColumns: 'Tabellkolumner',
+		tableNextColumns: 'Visa nästa kolumner',
+		tableOverflowDescription: 'Fler tabellkolumner är tillgängliga i sidled.',
+		tablePreviousColumns: 'Visa föregående kolumner',
 	}),
 });
 
@@ -541,22 +563,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({

package/scripts/lib/schema-definitions.mjs

@@ -1,4 +1,5 @@
 import { z } from 'astro/zod';
+import { localEditorNames } from './edit-source-link.mjs';
 import { imagePresentationNames } from './image-presentation.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
 import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
@@ -51,8 +52,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.`)

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

@@ -160,15 +160,32 @@ const addConfigHelp = (jsonSchema) => {
 		documentationLink('Language reference', 'configuration.md', 'language'),
 	], ['en', 'sv', 'en-GB', 'sv-SE']);
 	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.',

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

@@ -32,6 +32,9 @@ export const schemaValueDefinitions = Object.freeze([
 		en: option('English', 'Use Norna\'s built-in English interface text.'),
 		sv: option('Swedish', 'Use Norna\'s built-in Swedish interface text.'),
 	}),
+	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.'),
 		center: option('Center', 'Center text within its text area.'),

package/scripts/lib/site-paths.mjs

@@ -5,6 +5,7 @@ import { homePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
+const stateDirectoryEnvName = 'NORNA_INTERNAL_STATE_DIR';
 const defaultSiteDirectory = 'site';
 export { homePageDirectory };
 
@@ -16,12 +17,19 @@ export const siteDirectoryEnv = siteDirectoryEnvName;
 
 const normalizeSiteDirectory = (value) => String(value ?? '').trim();
 const normalizeInvocationRoot = (value) => String(value ?? '').trim();
+const normalizeStateDirectory = (value) => String(value ?? '').trim();
 
 const configuredInvocationRoot = normalizeInvocationRoot(process.env[invocationRootEnvName]);
 export const invocationRoot = configuredInvocationRoot
 	? path.resolve(configuredInvocationRoot)
 	: process.cwd();
 
+const hasStateDirectoryEnv = Object.hasOwn(process.env, stateDirectoryEnvName);
+const configuredStateDirectory = normalizeStateDirectory(process.env[stateDirectoryEnvName]);
+if (hasStateDirectoryEnv && !configuredStateDirectory) {
+	throw new Error(`${stateDirectoryEnvName} must not be empty.`);
+}
+
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
 		existsSync(path.join(siteDir, 'config.yaml'))
@@ -126,9 +134,13 @@ export const siteHomePageDir = path.join(sitePagesDir, homePageDirectory);
 export const siteContentPath = path.join(siteHomePageDir, 'content.md');
 export const siteImagesDir = path.join(siteHomePageDir, 'images');
 export const sitePublicDir = path.join(siteDir, 'public');
-export const siteStateDir = path.join(siteDir, '.norna');
+export const siteStateDir = configuredStateDirectory
+	? path.resolve(configuredStateDirectory)
+	: path.join(siteDir, '.norna');
 export const astroPublicDir = path.join(siteStateDir, 'public');
-export const astroDistDir = path.join(siteProjectRoot, 'dist');
+export const astroDistDir = configuredStateDirectory
+	? path.join(siteStateDir, 'dist')
+	: path.join(siteProjectRoot, 'dist');
 export const astroRootDir = siteStateDir;
 export const astroCacheDir = path.join(astroRootDir, '.astro');
 export const generatedImagesDir = path.join(astroPublicDir, 'images', 'generated');