@janga/norna 0.7.28 → 0.7.29

package/scripts/lib/editor-site-preview.mjs

@@ -0,0 +1,149 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { verifyDevServer } from './dev-server-identity.mjs';
+import { getEditorPageAddresses } from './editor-page-addresses.mjs';
+
+export const sitePreviewApiVersion = 1;
+const engineRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const queues = new Map();
+const serialize = (key, action) => {
+	const task = (queues.get(key) ?? Promise.resolve()).catch(() => {}).then(action);
+	queues.set(key, task);
+	void task.finally(() => { if (queues.get(key) === task) queues.delete(key); }).catch(() => {});
+	return task;
+};
+const readState = async root => {
+	try { return JSON.parse(await readFile(path.join(root, '.norna/dev/state.json'), 'utf8')); }
+	catch (error) { if (error.code === 'ENOENT') return null; throw new Error('The preview server record is unreadable. Inspect Show Preview Log before restarting.', { cause: error }); }
+};
+const registryEntry = async siteRoot => {
+	let registry;
+	try { registry = await import(pathToFileURL(path.join(engineRoot, 'scripts/review-environment-registry.mjs')).href); }
+	catch (error) { if (error.code === 'ERR_MODULE_NOT_FOUND') return null; throw error; }
+	for (const [target, definition] of Object.entries(registry.reviewEnvironments)) {
+		const root = await realpath(path.join(engineRoot, definition.siteDirectory)).catch(() => null);
+		if (root === siteRoot) return { target, ...definition };
+	}
+	return null;
+};
+export const getEditorPreviewConfiguration = async ({ siteRoot, environment = process.env }) => {
+	const root = await realpath(siteRoot);
+	const registered = await registryEntry(root);
+	const value = registered ? String(registered.port) : environment.NORNA_DEV_PORT ?? '4321';
+	const port = /^\d+$/.test(value) ? Number(value) : NaN;
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('NORNA_DEV_PORT must be an integer from 1 through 65535. Correct the VS Code launch environment and restart VS Code.');
+	return { siteRoot: root, port, registered, source: registered ? `review registry (${registered.target})` : environment.NORNA_DEV_PORT === undefined ? 'default' : 'NORNA_DEV_PORT' };
+};
+export const getEditorPreviewStatus = async ({ siteRoot }) => {
+	const root = await realpath(siteRoot);
+	const state = await readState(root);
+	return { state, verified: await verifyDevServer(state, root) };
+};
+export const getEditorPreviewLog = async ({ siteRoot }) => {
+	const root = await realpath(siteRoot);
+	const files = ['dev/preparation.log', '.astro/dev.log', 'dev/state.json'];
+	const logs = await Promise.all(files.map(async name => {
+		try { return `${name}\n${(await readFile(path.join(root, '.norna', name), 'utf8')).slice(-64000)}`; }
+		catch (error) { if (error.code === 'ENOENT') return ''; throw error; }
+	}));
+	return logs.filter(Boolean).join('\n\n') || 'No preview log exists for this site yet.';
+};
+const runManager = (config, operation, { token, environment, onOutput = () => {} } = {}) => new Promise((resolve, reject) => {
+	const args = config.registered
+		? [path.join(engineRoot, 'scripts/review-environments.mjs'), operation === 'stop' ? 'stop' : 'start', config.registered.target]
+		: [path.join(engineRoot, 'bin/norna.mjs'), '--site-dir', config.siteRoot, operation === 'stop' ? 'dev:stop' : 'dev:local'];
+	const env = { ...process.env, ...environment, NORNA_DEV_PORT: String(config.port), NORNA_SITE_DIR: config.siteRoot,
+		NORNA_NO_OPEN: '1', NORNA_DEV_NO_RESTART: '1', ELECTRON_RUN_AS_NODE: '1' };
+	// The extension may itself have been launched while another site was selected.
+	delete env.NORNA_INTERNAL_STATE_DIR;
+	delete env.NORNA_INVOCATION_ROOT;
+	delete env.NORNA_DEV_EXPECT_TOKEN;
+	delete env.NORNA_DEV_START_TOKEN;
+	if (operation === 'stop') env.NORNA_DEV_EXPECT_TOKEN = token;
+	else env.NORNA_DEV_START_TOKEN = token;
+	const child = spawn(process.execPath, args, { cwd: engineRoot, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+	let output = '';
+	const capture = chunk => { output = (output + chunk).slice(-64000); onOutput(String(chunk)); };
+	child.stdout.on('data', capture); child.stderr.on('data', capture);
+	child.once('error', reject);
+	child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Preview ${operation} failed. ${output.replace(/\n\s+at [\s\S]*$/, '').trim().slice(-2500) || 'Show Preview Log for details.'}`)));
+});
+const portOccupied = (port, host) => new Promise((resolve, reject) => {
+	const socket = net.connect({ port, host });
+	socket.once('connect', () => { socket.destroy(); resolve(true); });
+	socket.once('error', error => { socket.destroy(); ['ECONNREFUSED', 'EADDRNOTAVAIL', 'ENETUNREACH', 'EHOSTUNREACH'].includes(error.code) ? resolve(false) : reject(error); });
+	socket.setTimeout(1000, () => { socket.destroy(); resolve(true); });
+});
+const cancelled = signal => { if (signal?.aborted) throw new Error('Preview cancelled.'); };
+const stopVerified = async (config, state, options) => {
+	if (!(await verifyDevServer(state, config.siteRoot))) throw new Error('Cannot verify this site’s preview server. No process was stopped. Use Show Preview Log to inspect its record.');
+	if (config.registered && config.registered.port !== state.port) throw new Error('The registered port differs from the tracked server. Restore its registry port before stopping through the registered review command.');
+	await runManager({ ...config, port: state.port }, 'stop', { ...options, token: state.token });
+};
+export const stopEditorSitePreview = async (options) => {
+	const root = await realpath(options.siteRoot);
+	return serialize(root, async () => {
+		const state = await readState(root);
+		if (!state) return { stopped: false };
+		await stopVerified({ siteRoot: root, registered: await registryEntry(root) }, state, options);
+		return { stopped: true };
+	});
+};
+export const startEditorSitePreview = async (options) => {
+	const config = await getEditorPreviewConfiguration(options);
+	return serialize(config.siteRoot, async () => {
+		cancelled(options.signal);
+		// Read saved sources now, after any explicit Save Site action.
+		const addresses = await getEditorPageAddresses({ siteRoot: config.siteRoot, sourcePath: options.sourcePath ?? path.join(config.siteRoot, 'root/content.md') });
+		if (!addresses.webAddress || addresses.incomplete.length) throw new Error(`Repair the site before previewing it. ${addresses.incomplete.join('\n')}`);
+		let state = await readState(config.siteRoot);
+		let created = false;
+		if (await verifyDevServer(state, config.siteRoot)) {
+			if (state.port !== config.port) throw new Error(`This site is already running on port ${state.port}, but ${config.source} selects ${config.port}. Use Stop Preview Server before starting on the new port.`);
+			if (state.mode !== 'local') throw new Error('This site is running in LAN mode. Stop that server explicitly before starting a local preview.');
+		} else {
+			if (state) throw new Error('The tracked preview server cannot be verified. It may be stopped or belong to an older engine. Inspect Show Preview Log and stop/restart it through the site’s dev commands; preview did not stop any process.');
+			if (await portOccupied(config.port, '127.0.0.1') || await portOccupied(config.port, '::1')) throw new Error(`Port ${config.port} is used by another or unverified server. Stop it yourself or configure NORNA_DEV_PORT in the VS Code launch environment. No port fallback was attempted.`);
+			cancelled(options.signal);
+			const token = randomUUID();
+			try {
+				await runManager(config, 'start', { ...options, token });
+				state = await readState(config.siteRoot);
+				if (state?.token !== token || !(await verifyDevServer(state, config.siteRoot))) throw new Error('The new preview server did not provide a matching site identity. Inspect Show Preview Log.');
+				created = true;
+			} catch (error) {
+				const failed = await readState(config.siteRoot);
+				if (failed?.token === token && await verifyDevServer(failed, config.siteRoot)) {
+					try { await stopVerified(config, failed, options); } catch (cleanup) { throw new Error(`${error.message}\nCleanup failed: ${cleanup.message}`); }
+				}
+				throw error;
+			}
+		}
+		const url = new URL(addresses.webAddress);
+		url.protocol = 'http:'; url.hostname = '127.0.0.1'; url.port = String(state.port);
+		try {
+			cancelled(options.signal);
+			const timeout = AbortSignal.timeout(30_000);
+			const signal = options.signal ? AbortSignal.any([timeout, options.signal]) : timeout;
+			const response = await fetch(url, { signal, redirect: 'manual' });
+			await response.arrayBuffer();
+			if (!response.ok) throw new Error(`The preview page returned HTTP ${response.status}: ${url.href}. Repair the page and use Show Preview Log for details.`);
+			cancelled(options.signal);
+			if (!(await verifyDevServer(state, config.siteRoot))) throw new Error('The preview server identity changed while loading the page. No browser was opened.');
+		} catch (failure) {
+			const message = options.signal?.aborted ? 'Preview cancelled.'
+				: failure.name === 'TimeoutError' ? `Timed out loading the preview page ${url.href}. Use Show Preview Log.`
+				: failure.message;
+			if (created) {
+				try { await stopVerified(config, state, options); }
+				catch (cleanup) { throw new Error(`${message}\nCleanup failed: ${cleanup.message} Use Stop Preview Server after inspecting the log.`); }
+			}
+			throw new Error(message, { cause: failure });
+		}
+		return { url: url.href, reused: !created, siteRoot: config.siteRoot, port: state.port };
+	});
+};

package/scripts/lib/editor-site-tree.mjs

@@ -17,12 +17,13 @@ import { readSiteEditingTree } from './editor-site-editing-tree.mjs';
 export const siteTreeApiVersion = 1;
 export const siteFileTreeApiVersion = 1;
 export const sitePageFormApiVersion = 1;
+export const sitePageOrderApiVersion = 1;
 export { siteTreeEditingApiVersion, getEditorSourceFileChoices, planEditorSourceFileCreation, createEditorSourceFile } from './editor-source-files.mjs';
 export { createSiteNode, planSiteNodeCreation, slugifyAsciiIdentifier };
 export { siteFileOperationsApiVersion, siteRemovalApiVersion, planEditorImageCopy, planEditorRemoval, getEditorImageUsage, createEditorImageAppend, createEditorImageBatchAppend } from './editor-site-files.mjs';
 export { getEditorIncomingLinks } from './editor-site-links.mjs';
-export { siteAddressApiVersion, getEditorPageAddresses, planEditorPageAddress, applyEditorPageAddress } from './editor-page-addresses.mjs';
-export { sitePagePlacementApiVersion, planEditorPagePlacement, applyEditorPagePlacement } from './editor-page-placement.mjs';
+export { siteAddressApiVersion, sitePageAddressOptionsApiVersion, getEditorPageAddresses, planEditorPageAddress, applyEditorPageAddress } from './editor-page-addresses.mjs';
+export { sitePagePlacementApiVersion, sitePagePlacementOptionsApiVersion, planEditorPagePlacement, applyEditorPagePlacement } from './editor-page-placement.mjs';
 
 const sourceParts = (source, kind) => {
 	const split = splitPageMarkdownSource(source);
@@ -87,7 +88,7 @@ export const readSiteTree = async ({ siteRoot, sources = new Map(), cache = new
 			problem: information.problem ?? node.problems?.[0] ?? null });
 	}
 	for (const filename of cache.keys()) if (!used.has(filename)) cache.delete(filename);
-	return { nodes, problems: structure.problems };
+	return { nodes, problems: [...structure.problems, ...structure.warnings.map(warning => ({ ...warning, severity: 'warning' }))] };
 };
 
 // One physical projection preserves resources and repairable entries even when
@@ -149,3 +150,9 @@ export const editSiteNodeInformation = async ({ siteRoot, sourcePath, source, fi
 	while (end > start && nextEnd > start && source[end - 1] === next[nextEnd - 1]) { end--; nextEnd--; }
 	return [{ start, end, text: next.slice(start, nextEnd) }];
 };
+
+export { siteResourceActionsApiVersion, getEditorResourceReferences, planEditorResourceRename, planEditorPublicCreation, planEditorFolderRemoval, getEditorResourceAddress } from './editor-resource-actions.mjs';
+
+export { siteAttachmentsApiVersion, planEditorAttachmentCopy, createEditorAttachmentInsertion } from './editor-attachments.mjs';
+
+export { sitePreviewApiVersion, getEditorPreviewConfiguration, getEditorPreviewStatus, getEditorPreviewLog, startEditorSitePreview, stopEditorSitePreview } from './editor-site-preview.mjs';

package/scripts/lib/editor-source-files.mjs

@@ -54,7 +54,7 @@ export const planEditorSourceFileCreation = async ({ siteRoot, directory, filena
 	if (definition.input) {
 		if (typeof value !== 'string' || !value.trim() || /[\r\n]/.test(value)) throw new Error('Enter a non-empty, single line of text.');
 		text = definition.input === 'title' ? `# ${escapeMarkdownHeading(value.trim())}\n`
-			: `${definition.input}: ${JSON.stringify(value.trim())}\n`;
+			: `${definition.schemaKind === 'config' ? 'sourceFormat: 2\n' : ''}${definition.input}: ${JSON.stringify(value.trim())}\n`;
 	}
 	if (definition.schema) parseYamlConfig(text, filename, { schema: definition.schema });
 	const identity = async (location) => { const entry = await stat(location); return entry ? [entry.dev, entry.ino] : null; };

package/scripts/lib/logo-assets.mjs

@@ -1,3 +1,4 @@
+import { publicFilePublication } from './publication-paths.mjs';
 import { readdirSync } from 'node:fs';
 import { sitePublicDir, sitePublicLabel } from './site-paths.mjs';
 import {
@@ -23,7 +24,7 @@ export const getPublicAssetInspection = () => inspectPublicAssetFilenames(getPub
 export const getLogoAssets = () => getPublicAssetInspection().logos
 	.map((entry) => ({
 		filename: entry,
-		href: `/${entry}`,
+		href: publicFilePublication(entry).pathname,
 	}));
 
 export const getLogoAsset = () => {

package/scripts/lib/markdown-images.mjs

@@ -0,0 +1,59 @@
+import { getNodeRange, getInlineLinkTargetRange, getDefinitionTargetRange, visitNodes } from './markdown-links.mjs';
+import { managedImageFilenamePattern } from './structured-blocks.mjs';
+
+const filenamePattern = new RegExp(managedImageFilenamePattern);
+
+// Public URLs and remote resources keep their existing rendering rules.
+export const classifyMarkdownImage = (target) => {
+	if (/^(?:[a-z][a-z0-9+.-]*:|\/|#)/i.test(target)) return { kind: 'external' };
+	let decoded;
+	try { decoded = decodeURIComponent(target); } catch { return { kind: 'invalid' }; }
+	const image = decoded.replace(/^(?:\.\/)?images\//, '');
+	return filenamePattern.test(image) ? { kind: 'managed', image } : { kind: 'invalid' };
+};
+
+export const getImageDefinitions = (tree) => {
+	const definitions = new Map();
+	visitNodes(tree, (node) => {
+		if (node.type === 'definition' && !definitions.has(node.identifier)) definitions.set(node.identifier, node);
+	});
+	return definitions;
+};
+
+export const extractMarkdownImageReferences = ({ source, tree, lineOffset = 0 }) => {
+	const definitions = getImageDefinitions(tree);
+	const references = [];
+	visitNodes(tree, (node) => {
+		if (!['image', 'imageReference'].includes(node.type)) return;
+		const destination = node.type === 'image' ? node : definitions.get(node.identifier);
+		if (!destination) return;
+		const target = destination.url ?? '';
+		const classification = classifyMarkdownImage(target);
+		if (classification.kind === 'external') return;
+		const targetRange = node.type === 'image'
+			? getInlineLinkTargetRange(source, node)
+			: getDefinitionTargetRange(source, destination);
+		references.push({
+			...classification,
+			target,
+			alt: node.alt ?? '',
+			title: destination.title,
+			line: lineOffset + (node.position?.start.line ?? 1),
+			blockType: 'markdown-image',
+			blockDisplayType: 'Markdown image',
+			range: getNodeRange(node),
+			targetRange,
+			targetSource: targetRange ? source.slice(targetRange.start, targetRange.end) : target,
+			definitionSource: node.type === 'imageReference' ? source.slice(destination.position.start.offset, destination.position.end.offset) : undefined,
+		});
+	});
+	return references;
+};
+
+export const markdownImageDiagnostic = (reference, label) => ({
+	code: 'invalid-markdown-image',
+	severity: 'error',
+	line: reference.line,
+	message: `${label} line ${reference.line}: Local Markdown image "${reference.target}" must identify a supported file in this page's images/ folder.`,
+	fix: 'Use images/name.jpg (or .jpeg, .png, .svg), with a filename containing letters, numbers, dots or hyphens. Norna also accepts ./images/name.jpg and the bare filename.',
+});

package/scripts/lib/markdown-links.mjs

@@ -1,4 +1,4 @@
-const getNodeRange = (node) => {
+export const getNodeRange = (node) => {
 	const start = node.position?.start.offset;
 	const end = node.position?.end.offset;
 	return Number.isInteger(start) && Number.isInteger(end)
@@ -6,7 +6,7 @@ const getNodeRange = (node) => {
 		: null;
 };
 
-const visitNodes = (node, visit) => {
+export const visitNodes = (node, visit) => {
 	if (!node || typeof node !== 'object') return;
 	visit(node);
 	if (!Array.isArray(node.children)) return;
@@ -55,9 +55,28 @@ const scanDestination = (source, start, end) => {
 	return { start: targetStart, end: cursor };
 };
 
-const getInlineLinkTargetRange = (source, node) => {
+export const getInlineLinkTargetRange = (source, node) => {
 	const nodeRange = getNodeRange(node);
 	if (!nodeRange) return null;
+	if (node.type === 'image') {
+		let depth = 1;
+		for (let cursor = nodeRange.start + 2; cursor < nodeRange.end; cursor += 1) {
+			if (source[cursor] === '\\') { cursor += 1; continue; }
+			if (source[cursor] === '`') {
+				const run = source.slice(cursor).match(/^`+/)[0];
+				const followingRuns = source.slice(cursor + run.length, nodeRange.end).matchAll(/`+/g);
+				const closing = [...followingRuns].find((match) => match[0].length === run.length);
+				if (closing) { cursor += run.length + closing.index + run.length - 1; continue; }
+				cursor += run.length - 1;
+				continue;
+			}
+			if (source[cursor] === '[') depth += 1;
+			if (source[cursor] === ']' && --depth === 0) {
+				return source[cursor + 1] === '(' ? scanDestination(source, cursor + 2, nodeRange.end) : null;
+			}
+		}
+		return null;
+	}
 	const childEnd = Array.isArray(node.children)
 		? Math.max(nodeRange.start, ...node.children.map((child) => child.position?.end.offset ?? nodeRange.start))
 		: nodeRange.start;
@@ -66,7 +85,7 @@ const getInlineLinkTargetRange = (source, node) => {
 	return scanDestination(source, delimiter + 2, nodeRange.end);
 };
 
-const getDefinitionTargetRange = (source, node) => {
+export const getDefinitionTargetRange = (source, node) => {
 	const nodeRange = getNodeRange(node);
 	if (!nodeRange) return null;
 	const delimiter = source.indexOf(']:', nodeRange.start);
@@ -82,16 +101,16 @@ export const extractMarkdownLinks = ({ source, tree, lineOffset = 0 }) => {
 	const definitions = new Map();
 	visitNodes(tree, (node) => {
 		if (node.type !== 'definition') return;
-		definitions.set(node.identifier, node);
+		if (!definitions.has(node.identifier)) definitions.set(node.identifier, node);
 	});
 
 	const links = [];
 	visitNodes(tree, (node) => {
-		if (node.type === 'link') {
+		if (node.type === 'link' || node.type === 'image' && /^(?:\/|https?:)/i.test(node.url ?? '')) {
 			const range = getNodeRange(node);
 			const targetRange = getInlineLinkTargetRange(source, node);
 			links.push({
-				kind: 'markdown-link',
+				kind: node.type === 'image' ? 'markdown-image-link' : 'markdown-link',
 				column: node.position?.start.column ?? 1,
 				line: lineOffset + (node.position?.start.line ?? 1),
 				range,
@@ -102,14 +121,15 @@ export const extractMarkdownLinks = ({ source, tree, lineOffset = 0 }) => {
 			return;
 		}
 
-		if (node.type !== 'linkReference') return;
+		if (!['linkReference', 'imageReference'].includes(node.type)) return;
 		const definition = definitions.get(node.identifier);
-		if (!definition) return;
+		if (!definition || node.type === 'imageReference' && !/^(?:\/|https?:)/i.test(definition.url ?? '')) return;
 		const targetRange = getDefinitionTargetRange(source, definition);
 		links.push({
 			kind: 'markdown-reference-link',
 			column: node.position?.start.column ?? 1,
 			definitionLine: lineOffset + (definition.position?.start.line ?? 1),
+			definitionSource: source.slice(definition.position.start.offset, definition.position.end.offset),
 			line: lineOffset + (node.position?.start.line ?? 1),
 			range: getNodeRange(node),
 			target: definition.url ?? '',

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

@@ -534,63 +534,6 @@ export const splitNornaRenderedBlocks = (html, blocks) => {
 	return result.filter((block) => block.type !== 'html' || block.html.trim());
 };
 
-const maskFencedCodeBlocks = (markdown) => {
-	const lines = normalizeLines(markdown);
-	const maskedLines = [];
-	let index = 0;
-
-	while (index < lines.length) {
-		const fence = getFenceInfo(lines[index]);
-		if (!fence || fence.length < 3) {
-			maskedLines.push(lines[index]);
-			index += 1;
-			continue;
-		}
-
-		let closingIndex = -1;
-		for (let candidateIndex = index + 1; candidateIndex < lines.length; candidateIndex += 1) {
-			if (getFenceCloseInfo(lines[candidateIndex], fence)) {
-				closingIndex = candidateIndex;
-				break;
-			}
-		}
-
-		if (closingIndex === -1) {
-			maskedLines.push(lines[index]);
-			index += 1;
-			continue;
-		}
-
-		for (let maskedIndex = index; maskedIndex <= closingIndex; maskedIndex += 1) {
-			maskedLines.push(lines[maskedIndex].replace(/[^\r\n]/g, ' '));
-		}
-		index = closingIndex + 1;
-	}
-
-	return maskedLines.join('\n');
-};
-
-const isExternalImageTarget = (target) => /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//');
-const isRootRelativePublicTarget = (target) => target.startsWith('/');
-
-export const extractMarkdownImageReferences = (markdown) => {
-	const masked = maskFencedCodeBlocks(markdown);
-	const references = [];
-	const imageRegex = /!\[[^\]\n]*\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
-
-	for (const match of masked.matchAll(imageRegex)) {
-		const target = match[1] ?? '';
-		if (!target || target.startsWith('#') || isExternalImageTarget(target) || isRootRelativePublicTarget(target)) continue;
-
-		references.push({
-			target,
-			line: getLineNumber(markdown, match.index ?? 0),
-		});
-	}
-
-	return references;
-};
-
 export const getNornaBlockImageReferences = (blocks) =>
 	blocks.flatMap((block) => {
 		if (block.type === 'card-list') {

package/scripts/lib/norna-markdown-render-plugin.mjs

@@ -3,6 +3,26 @@ import { nornaBlockTypes } from './norna-markdown-blocks.mjs';
 import projectConfig from './project-config.mjs';
 import { getSemanticCalloutMarker } from './semantic-callouts.mjs';
 import { applyTableRowHeaderDeclaration } from './table-row-headers.mjs';
+import { classifyMarkdownImage, getImageDefinitions } from './markdown-images.mjs';
+
+const escapeAttribute = (value) => String(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const markManagedImage = (node, context) => {
+	let root = node;
+	while (context.parent(root)) root = context.parent(root);
+	const destination = node.type === 'image' ? node : getImageDefinitions(root).get(node.identifier);
+	if (!destination) return;
+	const result = classifyMarkdownImage(destination.url ?? '');
+	if (result.kind === 'external') return;
+	if (result.kind === 'invalid') throw new Error(`Local Markdown image "${destination.url}" must reference a .jpg, .jpeg, .png or .svg file directly in this page's images/ folder.`);
+	const title = destination.title == null ? '' : ` title="${escapeAttribute(destination.title)}"`;
+	// Raw HTML keeps Astro's independent image importer from processing these
+	// sources. The page renderer resolves this marker through Norna's manifest.
+	context.replaceNode(node, { type: 'html', value: `<img data-norna-managed-image="${escapeAttribute(result.image)}" alt="${escapeAttribute(node.alt ?? '')}"${title}>` });
+};
+
+export const nornaMarkdownImagePlugin = defineMdastPlugin({
+	name: 'norna-markdown-images', image: markManagedImage, imageReference: markManagedImage,
+});
 
 const stateKey = 'nornaMarkdownRender';
 
@@ -33,6 +53,8 @@ const hasBlockquoteAncestor = (node, context) => {
 
 export const nornaMarkdownRenderPlugin = defineMdastPlugin({
 	name: 'norna-markdown-render',
+	image: markManagedImage,
+	imageReference: markManagedImage,
 	blockquote(node, context) {
 		const marker = getSemanticCalloutMarker(node);
 		if (
@@ -88,6 +110,13 @@ export const nornaMarkdownRenderPlugin = defineMdastPlugin({
 		});
 	},
 	heading(node, context) {
+		if (node.depth === 3) {
+			if (context.parent(node)?.type !== 'root') return;
+			context.setProperty(node, 'data', {
+				hProperties: { 'data-norna-page-heading': 'true' },
+			});
+			return;
+		}
 		if (node.depth !== 1 && node.depth !== 2) return;
 		const state = getState(context);
 		const regionIndex = state.regionIndex;

package/scripts/lib/page-aliases.mjs

@@ -2,6 +2,11 @@ import { getSiteNodePathname } from './site-page-urls.mjs';
 import { sitemapFilename } from './sitemap.mjs';
 
 export const getGeneratedSiteRoutes = ({ searchEnabled = false } = {}) => Object.freeze([
+	Object.freeze({
+		kind: 'generated-route',
+		label: 'Norna generated 404 page',
+		pathname: '/404.html',
+	}),
 	Object.freeze({
 		kind: 'generated-route',
 		label: `Norna generated ${sitemapFilename}`,

package/scripts/lib/page-attachments.mjs

@@ -0,0 +1,59 @@
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { getSiteNodePathname } from './site-page-urls.mjs';
+import { attachmentPublicationPath, publicationIssues } from './publication-paths.mjs';
+
+export const attachmentPathname = attachmentPublicationPath;
+export const encodeAttachmentPath = value => value.split('/').map(segment => encodeURIComponent(segment).replace(/[()']/g, char => '%' + char.charCodeAt(0).toString(16))).join('/');
+export const validateAttachmentName = name => {
+	if (typeof name !== 'string' || !name || name !== name.trim() || /[\\/\x00-\x1f\x7f<>:"|?*#%]/.test(name) || /^\.{1,2}$/.test(name) || /[. ]$/.test(name)) throw new Error('Use one filename without slashes, URL punctuation or trailing dots/spaces.');
+	return name;
+};
+
+export const readPageAttachments = async contentFile => {
+	const directory = path.join(path.dirname(contentFile.contentPath), 'downloads');
+	const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+	if (!info) return { files: [], diagnostics: [] };
+	const diagnostics = [], files = [];
+	const problem = message => diagnostics.push({ severity: 'error', code: 'invalid-attachment', contentFile, message, fix: 'Keep regular files directly in the page’s downloads/ folder; remove unsupported entries.' });
+	if (!info.isDirectory() || info.isSymbolicLink()) { problem(`${directory} must be a real directory.`); return { files, diagnostics }; }
+	const names = new Set();
+	for (const entry of await readdir(directory, { withFileTypes: true })) {
+		if (entry.name === '.DS_Store' || entry.name.startsWith('._')) continue;
+		const filePath = path.join(directory, entry.name);
+		try { validateAttachmentName(entry.name); } catch (error) { problem(`${filePath}: ${error.message}`); continue; }
+		if (!entry.isFile()) { problem(`${filePath}: attachment subfolders and symbolic links are not supported.`); continue; }
+		const key = entry.name.normalize('NFC').toLowerCase();
+		if (names.has(key)) problem(`${directory}: attachment filenames must be unique regardless of case or Unicode normalization.`);
+		names.add(key);
+		files.push({ filePath, filename: entry.name, contentPath: contentFile.contentPath, ownerPathname: getSiteNodePathname(contentFile), pathname: attachmentPathname(getSiteNodePathname(contentFile), entry.name) });
+	}
+	return { files, diagnostics };
+};
+export const getSiteAttachments = async siteStructure => {
+	const results = await Promise.all(siteStructure.contentFiles.map(readPageAttachments));
+	return { files: results.flatMap(result => result.files), diagnostics: results.flatMap(result => result.diagnostics) };
+};
+
+// Explicit downloads paths identify page-owned files. Bare names retain the
+// existing shorthand rules, including ambiguity with page/public links.
+export const parseLocalAttachmentTarget = target => {
+	const raw = target.split(/[?#]/, 1)[0];
+	if (!raw || /^[a-z][a-z\d+.-]*:/i.test(raw)) return null;
+	const prefix = raw.match(/^(?:\.\/)?downloads\//)?.[0] ?? '';
+	try {
+		const filename = decodeURIComponent(raw.slice(prefix.length));
+		validateAttachmentName(filename);
+		return { filename, prefix };
+	} catch { return null; }
+};
+export const localAttachmentName = target => parseLocalAttachmentTarget(target)?.filename ?? null;
+export const resolveAttachment = (target, sourcePathname, files, resolvedPathname) => {
+	const name = localAttachmentName(target);
+	return name ? files.find(file => file.ownerPathname === sourcePathname && file.filename === name)
+		: files.find(file => file.pathname === resolvedPathname);
+};
+export const attachmentHref = (file, target) => encodeAttachmentPath(file.pathname) + (target.match(/[?#].*$/)?.[0] ?? '');
+
+export const attachmentOutputIssues = ({ files, pages, publicFiles, generatedRoutes }) =>
+	publicationIssues({ attachments: files, pages, publicFiles, generatedRoutes });

package/scripts/lib/page-markdown.mjs

@@ -1,3 +1,4 @@
+import { extractMarkdownImageReferences, markdownImageDiagnostic } from './markdown-images.mjs';
 import { getCodeFenceMetadataDiagnostics } from './code-fence-metadata.mjs';
 import { parseContentTabs } from './content-tabs.mjs';
 import { getDetailsHeadingDiagnostics } from './details-headings.mjs';
@@ -11,7 +12,6 @@ import {
 } from './markdown-links.mjs';
 import {
 	extractInlineNoteDiagnostics,
-	extractMarkdownImageReferences,
 	extractNornaMarkdownBlockDiagnostics,
 	getNornaBlockImageReferences,
 	nornaBlockTypes,
@@ -191,6 +191,7 @@ const createRegion = ({
 	tableErrors,
 	tabResult,
 	pageNotes,
+	imageReferences,
 }) => {
 	const endOffset = nextHeading?.index ?? source.length;
 	const markdown = source.slice(heading.index, endOffset).trimEnd();
@@ -201,10 +202,7 @@ const createRegion = ({
 	});
 	const inRegion = (offset) => offset >= heading.index && offset < endOffset;
 	const fieldNoteErrors = getStructuredSidenoteDiagnostics(blockResult.blocks, { label, regionOffset: heading.index });
-	const markdownImages = extractMarkdownImageReferences(markdown).map((reference) => ({
-		...reference,
-		line: regionLineOffset + reference.line,
-	}));
+	const markdownImages = imageReferences.filter((reference) => inRegion(reference.range.start));
 	const regionHeadings = headings.filter((candidate) => (
 		candidate.index >= heading.index
 		&& candidate.index < endOffset
@@ -226,7 +224,7 @@ const createRegion = ({
 		kind: heading.depth === 1 ? 'page-intro' : 'section',
 		bodyLine: heading.line,
 		line: lineOffset + heading.line,
-		managedImages: getNornaBlockImageReferences(blockResult.blocks),
+		managedImages: [...getNornaBlockImageReferences(blockResult.blocks), ...markdownImages.filter((reference) => reference.kind === 'managed')],
 		markdown,
 		markdownImages,
 		notes: pageNotes.notes.filter((note) => inRegion(note.referenceOffset)),
@@ -246,6 +244,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 	const tabResult = parseContentTabs(source, { label, lineOffset });
 	const pageNotes = extractInlineNoteDiagnostics(source, { label, lineOffset, tabResult });
 	const { headings, tree } = await getMarkdownHeadings(tabResult.maskedSource);
+	const imageReferences = extractMarkdownImageReferences({ source, tree, lineOffset });
 	const detailsDiagnostics = getDetailsHeadingDiagnostics(tree, { source: tabResult.maskedSource, label, lineOffset });
 	const calloutErrors = getSemanticCalloutDiagnostics(tree, { label, lineOffset });
 	const codeFenceErrors = getCodeFenceMetadataDiagnostics(tree, {
@@ -271,6 +270,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 		pageNotes,
 		tableErrors,
 		tabResult,
+		imageReferences,
 	}));
 	const headingIssues = getHeadingIdentifierIssues(headings);
 	const headingDiagnostics = getHeadingDiagnostics(headings, lineOffset);
@@ -346,6 +346,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 	return {
 		blocks,
 		diagnostics: [
+			...imageReferences.filter((reference) => reference.kind === 'invalid').map((reference) => markdownImageDiagnostic(reference, label)),
 			...detailsDiagnostics,
 			...structureDiagnostics,
 			...headingDiagnostics,
@@ -363,7 +364,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 		lineOffset,
 		links,
 		managedImages: regions.flatMap((region) => region.managedImages),
-		markdownImages: regions.flatMap((region) => region.markdownImages),
+		markdownImages: imageReferences,
 		navigationHeadings,
 		notes: regions.flatMap((region) => region.notes),
 		noteDiagnostics,
@@ -395,8 +396,11 @@ export const parsePageMarkdownSource = async (source, options = {}) => {
 		};
 	};
 
+	const mapImage = (reference) => reference.blockType === 'markdown-image' ? { ...reference, range: toOriginalRange(reference.range), targetRange: toOriginalRange(reference.targetRange) } : reference;
 	return {
 		...model,
+		markdownImages: model.markdownImages.map(mapImage),
+		managedImages: model.managedImages.map(mapImage),
 		bodyOffset: normalization.originalOffsets[split.bodyOffset] ?? split.bodyOffset,
 		frontmatter: split.frontmatter,
 		frontmatterUnclosed: split.frontmatterUnclosed,