@janga/norna 0.7.28 → 0.7.29

package/scripts/lib/editor-page-placement.mjs

@@ -1,4 +1,3 @@
-import { randomUUID } from 'node:crypto';
 import { rename } from 'node:fs/promises';
 import path from 'node:path';
 import { checkedPath, snapshot } from './editor-site-files.mjs';
@@ -6,16 +5,15 @@ import { readEditorLinkState } from './editor-site-links.mjs';
 import { createPageMovePlan } from './page-move-plan.mjs';
 import { applyPageMovePlan } from './page-move-apply.mjs';
 import { getSiteSourcePaths } from './site-conventions.mjs';
-import { getSiteStructure } from './site-structure.mjs';
+import { comparePageOrder, planPageOrder, assertRenumberingAllowed } from './page-order.mjs';
+import { pageOrderFileChanges } from './page-order-source.mjs';
 
-export const sitePagePlacementApiVersion = 1;
+export const sitePagePlacementApiVersion = 2;
+export const sitePagePlacementOptionsApiVersion = 1;
 
 const urlFor = (node) => node.isHome ? '/' : `/${node.pagePath}/`;
 const childOf = (node, parent) => node.parentPagePath === (parent.pagePath || null);
 const inBranch = (node, ancestor) => node.pagePath === ancestor.pagePath || node.pagePath.startsWith(`${ancestor.pagePath}/`);
-const pad = (order) => String(order).padStart(3, '0');
-const renamedDirectory = (node, order) => path.join(path.dirname(node.nodeDir), `${pad(order)}-${node.pageId}`);
-
 const explainDestination = (owner, address) => {
 	if (owner.kind === 'page') return `Cannot move here. ${address} already belongs to “${owner.source.title}”. Choose another location.`;
 	if (owner.kind === 'page-alias') return `Cannot move here. ${address} is a previous address for “${owner.source.page.title}” at ${owner.source.targetPathname}. Choose another location.`;
@@ -24,45 +22,8 @@ const explainDestination = (owner, address) => {
 	return `Cannot move here. ${address} is already used by ${owner.label}. Choose another location.`;
 };
 
-const orderForInsertion = (siblings, index) => {
-	const before = siblings[index - 1]?.pageOrder ?? 0;
-	const after = siblings[index]?.pageOrder ?? 1000;
-	return after - before > 1 ? Math.floor((before + after) / 2) : null;
-};
-
-const applyDirectoryRenames = async (changes, renameDirectory) => {
-	const staged = changes.map((change) => ({ ...change,
-		temporary: path.join(path.dirname(change.from), `.${path.basename(change.from)}.norna-order-${randomUUID()}.tmp`),
-		current: change.from }));
-	const restore = async () => {
-		const failures = [];
-		for (const change of staged.filter((entry) => entry.current === entry.to).reverse()) {
-			try { await renameDirectory(change.to, change.temporary); change.current = change.temporary; }
-			catch (error) { failures.push(`${change.to}: ${error.message}`); }
-		}
-		for (const change of staged.filter((entry) => entry.current === entry.temporary).reverse()) {
-			try { await renameDirectory(change.temporary, change.from); change.current = change.from; }
-			catch (error) { failures.push(`${change.from}: ${error.message}`); }
-		}
-		return failures;
-	};
-	try {
-		for (const change of staged) {
-			await renameDirectory(change.from, change.temporary);
-			change.current = change.temporary;
-		}
-		for (const change of staged) {
-			await renameDirectory(change.temporary, change.to);
-			change.current = change.to;
-		}
-	} catch (error) {
-		const failures = await restore();
-		throw new Error(`${error.message}${failures.length ? `\nRestoration was incomplete. Inspect:\n${failures.join('\n')}` : '\nThe original page order was restored.'}`);
-	}
-	return restore;
-};
-
-export const planEditorPagePlacement = async ({ siteRoot, sourcePath, targetPath, placement, sources = new Map() }) => {
+export const planEditorPagePlacement = async ({ siteRoot, sourcePath, targetPath, placement, preserveAliases = true, sources = new Map() }) => {
+	if (typeof preserveAliases !== 'boolean') throw new Error('Choose whether to preserve old addresses as aliases.');
 	if (!['before', 'after', 'first', 'last'].includes(placement)) throw new Error('Choose before, after, first child or last child.');
 	siteRoot = path.resolve(siteRoot);
 	await checkedPath(siteRoot, sourcePath);
@@ -84,32 +45,18 @@ export const planEditorPagePlacement = async ({ siteRoot, sourcePath, targetPath
 	if (!parent || inBranch(parent, source)) throw new Error('A page cannot move inside its own branch. Choose another destination.');
 	const sameParent = source.parentPagePath === (parent.pagePath || null);
 	const existing = state.structure.nodes.filter((node) => node.kind === 'page' && !node.isHome && childOf(node, parent) && node.contentPath !== sourcePath)
-		.sort((left, right) => left.pageOrder - right.pageOrder);
+		.sort(comparePageOrder);
 	const targetIndex = existing.findIndex((node) => node.contentPath === targetPath);
 	if ((placement === 'before' || placement === 'after') && targetIndex < 0) throw new Error('The destination page changed. Refresh Site Tree and try again.');
 	const index = placement === 'first' ? 0 : placement === 'last' ? existing.length
 		: targetIndex + (placement === 'after' ? 1 : 0);
 	const current = state.structure.nodes.filter((node) => node.kind === 'page' && !node.isHome && node.parentPagePath === source.parentPagePath)
-		.sort((left, right) => left.pageOrder - right.pageOrder);
+		.sort(comparePageOrder);
 	if (sameParent && current[index]?.contentPath === sourcePath) throw new Error('This page is already in that position.');
-	if (existing.length >= 999) throw new Error('This parent already has the maximum of 999 pages. Choose another parent.');
-	const inserted = [...existing];
-	inserted.splice(index, 0, source);
-	let sourceOrder = orderForInsertion(existing, index);
-	const orderChanges = [];
-	if (sourceOrder === null) {
-		const step = Math.floor(999 / inserted.length);
-		for (let position = 0; position < inserted.length; position += 1) {
-			const node = inserted[position];
-			const order = (position + 1) * step;
-			if (node.contentPath === sourcePath) sourceOrder = order;
-			else if (node.pageOrder !== order) orderChanges.push({ from: node.nodeDir, to: renamedDirectory(node, order) });
-		}
-	}
-	const sourceDestination = sameParent ? renamedDirectory(source, sourceOrder) : null;
-	if (sameParent && sourceDestination !== source.nodeDir) orderChanges.push({ from: source.nodeDir, to: sourceDestination });
-	const dirtyRenamedFiles = [...sources.keys()].filter((filename) => orderChanges.some(({ from }) => filename.startsWith(from + path.sep)));
-	if (dirtyRenamedFiles.length) throw new Error(dirtyPaths(dirtyRenamedFiles));
+	const insertion = planPageOrder(existing, index);
+	const sourceOrder = insertion.order;
+	const orderChanges = await pageOrderFileChanges(insertion.orderChanges);
+	const sourceDestination = sameParent ? source.nodeDir : null;
 	const to = sameParent ? urlFor(source) : `${urlFor(parent)}${source.pageId}/`;
 	let movePreview = null;
 	if (!sameParent) {
@@ -117,17 +64,13 @@ export const planEditorPagePlacement = async ({ siteRoot, sourcePath, targetPath
 		if (owner && !(owner.kind === 'page-alias' && owner.source.page.contentFile.contentPath === sourcePath)) {
 			throw new Error(explainDestination(owner, to));
 		}
-		const occupied = new Set(existing.map((node) => node.pageOrder));
-		const provisionalOrder = occupied.has(sourceOrder)
-			? Array.from({ length: 999 }, (_, position) => position + 1).find((order) => !occupied.has(order))
-			: sourceOrder;
-		movePreview = await createPageMovePlan({ from: urlFor(source), to, order: provisionalOrder,
+		movePreview = await createPageMovePlan({ from: urlFor(source), to, order: sourceOrder, siblingOrderChanges: insertion.orderChanges, preserveAliases,
 			graph: state.graph, publicFiles: state.publicFiles, siteStructure: state.structure,
 			sitePagesDir: getSiteSourcePaths(siteRoot).pages,
 			sitePagesLabel: `${siteRoot}/root/pages`, generatedRoutes: state.generatedRoutes });
 	}
 	const watched = new Set([source.nodeDir, path.join(siteRoot, 'site-config/settings.yaml'),
-		...orderChanges.map(({ from }) => from),
+		...orderChanges.map(({ contentPath }) => contentPath),
 		...state.structure.nodes.map((node) => node.contentPath ?? node.categoryPath),
 		...state.publicFiles.map((file) => file.filePath)]);
 	const fingerprints = [];
@@ -135,38 +78,25 @@ export const planEditorPagePlacement = async ({ siteRoot, sourcePath, targetPath
 	return {
 		siteRoot, sourcePath, targetPath, placement, sourceDirectory: source.nodeDir,
 		sameParent, sourceOrder, sourceUrl: urlFor(source), destinationUrl: to,
-		sourceDestination, orderChanges, movePreview,
-		fingerprint: JSON.stringify(fingerprints),
+		sourceDestination, orderChanges, movePreview, preserveAliases,
+		fileChanges: sameParent ? [...orderChanges, ...await pageOrderFileChanges([{ node: source, oldOrder: source.pageOrder, newOrder: sourceOrder }])] : movePreview.fileChanges,
+		stateFingerprint: JSON.stringify(fingerprints),
+		fingerprint: JSON.stringify([fingerprints, preserveAliases]),
 	};
 };
 
-export const applyEditorPagePlacement = async (plan, { renameDirectory = rename } = {}) => {
-	const current = await planEditorPagePlacement(plan);
+export const applyEditorPagePlacement = async (plan, { renameDirectory = rename, writeSource, allowRenumber = false, sources = new Map() } = {}) => {
+	const current = await planEditorPagePlacement({ ...plan, sources });
 	if (current.fingerprint !== plan.fingerprint || current.sourceOrder !== plan.sourceOrder
 		|| JSON.stringify(current.orderChanges) !== JSON.stringify(plan.orderChanges)) {
 		throw new Error('The site changed since this move was previewed. Review the placement and addresses again.');
 	}
-	if (current.sameParent) {
-		await applyDirectoryRenames(current.orderChanges, renameDirectory);
-		try { await getSiteStructure({ siteRoot: plan.siteRoot }); }
-		catch (error) {
-			const reversed = current.orderChanges.map(({ from, to }) => ({ from: to, to: from }));
-			const restoreErrors = await applyDirectoryRenames(reversed, renameDirectory).then(() => [], (failure) => [failure.message]);
-			throw new Error(`${error.message}${restoreErrors.length ? `\nRestoration was incomplete: ${restoreErrors.join('\n')}` : '\nThe original page order was restored.'}`);
-		}
-		return { sourcePath: path.join(current.sourceDestination, 'content.md'), url: current.sourceUrl };
-	}
-	const restoreOrder = await applyDirectoryRenames(current.orderChanges, renameDirectory);
-	try {
-		const state = await readEditorLinkState({ siteRoot: plan.siteRoot });
-		const move = await createPageMovePlan({ from: current.sourceUrl, to: current.destinationUrl, order: current.sourceOrder,
-			graph: state.graph, publicFiles: state.publicFiles, siteStructure: state.structure,
-			sitePagesDir: getSiteSourcePaths(plan.siteRoot).pages,
-			sitePagesLabel: `${plan.siteRoot}/root/pages`, generatedRoutes: state.generatedRoutes });
-		await applyPageMovePlan(move, { siteRoot: plan.siteRoot, generatedRoutes: state.generatedRoutes, renameDirectory });
-		return { sourcePath: path.join(move.destinationDirectory, 'content.md'), url: current.destinationUrl };
-	} catch (error) {
-		const failures = await restoreOrder();
-		throw new Error(`${error.message}${failures.length ? `\nPage order restoration was incomplete. Inspect:\n${failures.join('\n')}` : ''}`);
-	}
+	assertRenumberingAllowed(current.orderChanges, allowRenumber);
+	const mutation = current.sameParent ? {
+		mode: 'reorder', orderChanges: current.orderChanges, fileChanges: current.fileChanges,
+		sourceFiles: current.fileChanges.map(change => ({ contentPath: change.originalPath, contentLabel: change.contentLabel, source: change.originalSource })),
+	} : current.movePreview;
+	await applyPageMovePlan(mutation, { siteRoot: plan.siteRoot, generatedRoutes: current.movePreview?.generatedRoutes, renameDirectory, writeSource, allowRenumber });
+	return { sourcePath: path.join(current.sameParent ? current.sourceDirectory : mutation.destinationDirectory, 'content.md'),
+		url: current.destinationUrl, renumberedPages: current.orderChanges.length };
 };

package/scripts/lib/editor-resource-actions.mjs

@@ -0,0 +1,216 @@
+import { publicFilePublication, publicationIssues } from './publication-paths.mjs';
+import { attachmentHref, attachmentPathname, attachmentOutputIssues, parseLocalAttachmentTarget, encodeAttachmentPath } from './page-attachments.mjs';
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseDocument, isScalar, isSeq } from 'yaml';
+import { checkedPath, snapshot, getEditorImageUsage, planEditorRemoval } from './editor-site-files.mjs';
+import { isInside, readEditorLinkState, summarizeReference } from './editor-site-links.mjs';
+import { getSourcePageLocation } from './source-files.mjs';
+import { parsePageMarkdownSource } from './page-markdown.mjs';
+import { inspectPublicAssetFilenames } from './public-asset-conventions.mjs';
+
+export const siteResourceActionsApiVersion = 1;
+const stat = (filename) => lstat(filename).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+const imageName = /^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$/i;
+const publicPath = (siteRoot, filename, settings, directory = false) => publicFilePublication(path.relative(path.join(siteRoot, 'public'), filename).split(path.sep).join('/'), settings, { directory }).pathname;
+const encodePath = encodeAttachmentPath;
+const checkedName = (name) => {
+	if (typeof name !== 'string' || !name || name !== name.trim() || /[\\/\x00-\x1f\x7f<>:"|?*#%]/.test(name) || /^\.{1,2}$/.test(name) || /[. ]$/.test(name)) {
+		throw new Error('Enter one filename or folder name, without slashes, URL punctuation or trailing dots/spaces.');
+	}
+	return name;
+};
+const available = async (filename) => {
+	const entries = await readdir(path.dirname(filename)).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+	if (entries.some(entry => entry.normalize('NFC').toLowerCase() === path.basename(filename).normalize('NFC').toLowerCase())) {
+		throw new Error('That name is already in use. Choose another name; existing files will not be overwritten.');
+	}
+};
+const resource = async ({ siteRoot, filePath }) => {
+	const filename = await checkedPath(siteRoot, filePath);
+	const info = await stat(filename);
+	if (!info || !(info.isFile() || info.isDirectory())) throw new Error('This file or folder no longer exists. Refresh Site Tree.');
+	const publicRoot = path.join(path.resolve(siteRoot), 'public');
+	if (isInside(publicRoot, filename)) return { filename, kind: 'public', directory: info.isDirectory(), fixed: filename === publicRoot };
+	const owner = path.dirname(path.dirname(filename));
+	if (info.isFile() && path.basename(path.dirname(filename)) === 'downloads' && getSourcePageLocation(siteRoot, owner)) return { filename, kind: 'attachment', directory: false, sourcePath: path.join(owner, 'content.md') };
+	if (info.isFile() && path.basename(path.dirname(filename)) === 'images' && getSourcePageLocation(siteRoot, owner) && imageName.test(path.basename(filename))) {
+		return { filename, kind: 'image', directory: false, sourcePath: path.join(owner, 'content.md') };
+	}
+	throw new Error('Choose a managed page image or a resource inside public/.');
+};
+
+const validatePublic = (siteRoot, state, filenames, directories = []) => {
+	for (const directory of directories) publicPath(siteRoot, directory, state.settings, true);
+	const issues = publicationIssues({ pages: state.graph.pages, attachments: state.graph.attachments.files, generatedRoutes: state.generatedRoutes,
+		publicFiles: filenames.map(filePath => ({ filePath, pathname: publicPath(siteRoot, filePath, state.settings) })) });
+	if (issues.length) throw new Error(issues.map(issue => issue.message).join('\n'));
+	const inspection = inspectPublicAssetFilenames(filenames.filter(filename => path.dirname(filename) === path.join(siteRoot, 'public')).map(filename => path.basename(filename)));
+	if (inspection.logos.length > 1) throw new Error(`Keep one navigation logo in public/: ${inspection.logos.join(', ')}. Use Replace on the existing logo.`);
+	if (inspection.socialImages.length > 1) throw new Error(`Keep one social image in public/: ${inspection.socialImages.join(', ')}.`);
+	return inspection.suspicious.map(entry => entry.message);
+};
+
+export const getEditorResourceReferences = async (options) => {
+	const selected = await resource(options);
+	if (selected.kind === 'image') return { ...await getEditorImageUsage({ ...options, sourcePath: selected.sourcePath, imagePath: selected.filename }), scope: 'Managed Markdown images and Norna image blocks on the owning page. HTML and external references are not checked.' };
+	const state = await readEditorLinkState(options);
+	return { references: state.graph.references.filter(ref => ['public-file', 'attachment'].includes(ref.resolution?.kind) && (selected.directory ? isInside(selected.filename, ref.resolution.file.filePath) : selected.filename === ref.resolution.file.filePath)).map(summarizeReference),
+		incomplete: state.incomplete, scope: 'Page-content links. HTML, configuration and external references are not checked.' };
+};
+
+// Change parsed image destinations and YAML scalars, preserving examples. Map the
+// scanner's normalized offsets back to the original CRLF/LF source.
+const renameImageReferences = async (source, oldName, newName) => {
+	const normalized = source.replace(/\r\n?/g, '\n');
+	const offsets = []; for (let i = 0; i < source.length; i++) { offsets.push(i); if (source[i] === '\r' && source[i + 1] === '\n') i++; } offsets.push(source.length);
+	const document = await parsePageMarkdownSource(normalized);
+	if (document.diagnostics.some(issue => issue.severity === 'error')) throw new Error('Repair the page content before renaming this image.');
+	const blocks = document.regions.flatMap(region => region.blocks.map(block => ({ ...block, sourceStartOffset: document.bodyOffset + region.startOffset + block.sourceStartOffset })));
+	const edits = [];
+	const destinations = new Set();
+	for (const reference of document.markdownImages.filter(reference => reference.image === oldName)) {
+		if (!reference.targetRange) throw new Error('This Markdown image reference has no editable source range.');
+		const { start, end } = reference.targetRange;
+		if (destinations.has(start)) continue;
+		destinations.add(start);
+		const prefix = reference.targetSource.slice(0, reference.targetSource.lastIndexOf('/') + 1);
+		edits.push({ start: offsets[start], end: offsets[end], text: prefix + newName });
+	}
+	for (const block of blocks) {
+		if (!['image-stack', 'image-carousel', 'card-list'].includes(block.blockType)) continue;
+		const doc = parseDocument(block.source);
+		const items = doc.get('items', true);
+		if (!isSeq(items)) continue;
+		for (const item of items.items) {
+			const image = item?.get?.('image', true);
+			if (!isScalar(image) || image.value !== oldName) continue;
+			if (!image.range) throw new Error('This image reference has no editable source range.');
+			edits.push({ start: offsets[block.sourceStartOffset + image.range[0]], end: offsets[block.sourceStartOffset + image.range[1]], text: JSON.stringify(newName) });
+		}
+	}
+	return edits;
+};
+const applyText = (source, edits) => [...edits].sort((a,b) => b.start-a.start).reduce((text,edit) => text.slice(0,edit.start)+edit.text+text.slice(edit.end),source);
+
+export const planEditorResourceRename = async ({ siteRoot, filePath, name, destinationDirectory, sources = new Map() }) => {
+	siteRoot = path.resolve(siteRoot);
+	const selected = await resource({ siteRoot, filePath });
+	if (selected.fixed) throw new Error('The public folder has a fixed name and location.');
+	const directory = destinationDirectory ?? path.dirname(selected.filename);
+	if (['image', 'attachment'].includes(selected.kind) && directory !== path.dirname(selected.filename)) throw new Error('Images stay in their owning page’s images folder.');
+	const destination = await checkedPath(siteRoot, path.join(directory, checkedName(name)));
+	if (destination === selected.filename) throw new Error('Enter a different name or location, or cancel.');
+	if (!(await stat(directory))?.isDirectory()) throw new Error('Choose an existing destination folder.');
+	if (selected.kind === 'public' && !isInside(path.join(siteRoot, 'public'), destination)) throw new Error('Public resources must stay inside public/.');
+	if (selected.directory && isInside(selected.filename, destination)) throw new Error('A folder cannot be moved inside itself.');
+	if (selected.kind === 'image' && (!imageName.test(name) || path.extname(name) !== path.extname(selected.filename))) throw new Error('Use an image filename with letters, numbers, dots or hyphens. Keep the existing extension; rename does not convert images.');
+	await available(destination);
+	const usage = await getEditorResourceReferences({ siteRoot, filePath, sources });
+	if (usage.incomplete.length || usage.references.some(ref => ref.unresolved)) throw new Error(`References could not be resolved safely. Repair them before renaming or moving.\n${usage.incomplete.join('\n')}`);
+	const files = await snapshot(selected.filename);
+	const changes = [];
+	let warnings = [];
+	if (selected.kind === 'image') {
+		for (const sourcePath of new Set(usage.references.map(ref => ref.sourcePath))) {
+			await checkedPath(siteRoot, sourcePath);
+			const original = sources.get(sourcePath) ?? await readFile(sourcePath, 'utf8');
+			const edits = await renameImageReferences(original, path.basename(selected.filename), name);
+			if (!edits.length) throw new Error(`Cannot locate the image reference in ${sourcePath}. No files changed.`);
+			changes.push({ sourcePath, original, updated: applyText(original, edits) });
+		}
+	} else if (selected.kind === 'attachment') {
+		const state = await readEditorLinkState({ siteRoot, sources });
+		const file = state.graph.attachments.files.find(file => file.filePath === selected.filename);
+		if (!file) throw new Error('The attachment is no longer available.');
+		const updated = { ...file, filePath: destination, filename: name, pathname: attachmentPathname(file.ownerPathname, name) };
+		const problems = attachmentOutputIssues({ files: state.graph.attachments.files.map(entry => entry === file ? updated : entry), pages: state.graph.pages, publicFiles: state.publicFiles, generatedRoutes: state.generatedRoutes });
+		if (problems.length) throw new Error(problems.map(issue => issue.message).join('\n'));
+		const bySource = new Map();
+		for (const ref of state.graph.references.filter(ref => ref.resolution?.kind === 'attachment' && ref.resolution.file.filePath === file.filePath)) {
+			if (!ref.targetRange) throw new Error('Cannot safely locate this attachment reference. No files changed.');
+			const filename = ref.sourceContentFile.contentPath;
+			if (!bySource.has(filename)) bySource.set(filename, { original: ref.sourcePage.document.fullSource, edits: new Map() });
+			const local = parseLocalAttachmentTarget(ref.sourceTarget);
+			const href = local ? local.prefix + encodeAttachmentPath(name) + (ref.targetSource.match(/[?#].*$/)?.[0] ?? '') : (ref.target.absolutePrefix ?? '') + attachmentHref(updated, ref.targetSource);
+			bySource.get(filename).edits.set(ref.targetRange.start, { ...ref.targetRange, text: ref.yamlScalar ? JSON.stringify(href) : href });
+		}
+		for (const [sourcePath, { original, edits }] of bySource) { await checkedPath(siteRoot, sourcePath); changes.push({ sourcePath, original, updated: applyText(original, [...edits.values()]) }); }
+	} else {
+		const state = await readEditorLinkState({ siteRoot, sources });
+		const mapped = state.publicFiles.map(file => isInside(selected.filename, file.filePath) ? path.join(destination, path.relative(selected.filename, file.filePath)) : file.filePath);
+		warnings = validatePublic(siteRoot, state, mapped, selected.directory ? [destination] : []);
+		const before = inspectPublicAssetFilenames(state.publicFiles.filter(file => path.dirname(file.filePath) === path.join(siteRoot, 'public')).map(file => path.basename(file.filePath)));
+		const after = inspectPublicAssetFilenames(mapped.filter(filename => path.dirname(filename) === path.join(siteRoot, 'public')).map(filename => path.basename(filename)));
+		for (const kind of ['logos', 'browserIcons', 'socialImages']) for (const filename of before[kind]) if (!after[kind].includes(filename)) warnings.push(`${filename} will no longer be selected automatically as a site logo, icon or social image.`);
+		const bySource = new Map();
+		for (const ref of state.graph.references) {
+			if (ref.resolution?.kind !== 'public-file' || !isInside(selected.filename, ref.resolution.file.filePath)) continue;
+			if (!ref.targetRange) throw new Error(`Cannot safely update the reference on line ${ref.line} in ${ref.sourceContentFile.contentPath}.`);
+			const target = publicPath(siteRoot, path.join(destination, path.relative(selected.filename, ref.resolution.file.filePath)), state.settings);
+			const suffix = ref.targetSource.match(/[?#].*$/)?.[0] ?? '';
+			const filename = ref.sourceContentFile.contentPath;
+			if (!bySource.has(filename)) bySource.set(filename, { original: ref.sourcePage.document.fullSource, edits: new Map() });
+			bySource.get(filename).edits.set(ref.targetRange.start, { ...ref.targetRange, text: (ref.target.absolutePrefix ?? '') + encodePath(target) + suffix });
+		}
+		for (const [sourcePath, { original, edits }] of bySource) { await checkedPath(siteRoot, sourcePath); changes.push({ sourcePath, original, updated: applyText(original, [...edits.values()]) }); }
+	}
+	return { siteRoot, filePath: selected.filename, name, destinationDirectory: directory, destination, changes, usage, warnings,
+		fingerprint: JSON.stringify([files, destination, changes, usage, warnings]) };
+};
+
+export const planEditorPublicCreation = async ({ siteRoot, directory, name, source, folder = false, replace = false, pending = [], sources = new Map() }) => {
+	siteRoot = path.resolve(siteRoot);
+	directory = await checkedPath(siteRoot, directory ?? path.join(siteRoot, 'public'));
+	const publicRoot = path.join(siteRoot, 'public');
+	if (!isInside(publicRoot, directory)) throw new Error('Choose a folder inside public/.');
+	if (directory !== publicRoot && !(await stat(directory))?.isDirectory()) throw new Error('The destination folder no longer exists.');
+	const destination = await checkedPath(siteRoot, path.join(directory, checkedName(name)));
+	if (replace) { if (!(await stat(destination))?.isFile() || folder || !source) throw new Error('Select an existing public file and a replacement file.'); }
+	else await available(destination);
+	if (source && (!(await stat(source))?.isFile() || (await stat(source)).isSymbolicLink())) throw new Error('Choose a regular file on this computer.');
+	if (source && path.resolve(source) === destination) throw new Error('This file already belongs to this folder.');
+	const state = await readEditorLinkState({ siteRoot, sources });
+	for (const filename of pending) { await checkedPath(siteRoot, filename); if (!isInside(publicRoot, filename)) throw new Error('Pending public files must stay inside public/.'); }
+	const filenames = [...new Set([...state.publicFiles.map(file => file.filePath), ...pending])].filter(filename => filename !== destination);
+	const warnings = validatePublic(siteRoot, state, [...filenames, ...(!folder ? [destination] : [])], folder ? [destination] : []);
+	return { siteRoot, directory, name, source, folder, replace, destination, warnings,
+		fingerprint: JSON.stringify([source ? await snapshot(source) : null, replace ? await snapshot(destination) : null, destination, warnings]) };
+};
+
+export const planEditorFolderRemoval = async ({ siteRoot, directory, sources = new Map() }) => {
+	siteRoot = path.resolve(siteRoot);
+	directory = await checkedPath(siteRoot, directory);
+	const publicRoot = path.join(siteRoot, 'public');
+	const publicFolder = isInside(publicRoot, directory);
+	const kind = path.basename(directory);
+	const ownerDirectory = path.dirname(directory);
+	if (!publicFolder && (!['images', 'downloads', 'pages'].includes(kind) || !getSourcePageLocation(siteRoot, ownerDirectory))) throw new Error('Only optional pages, images and public folders can be deleted.');
+	if (!(await stat(directory))?.isDirectory()) throw new Error('The selected folder no longer exists.');
+	const files = await snapshot(directory);
+	const plans = [];
+	if (publicFolder) {
+		for (const [relative, type] of files) if (type === 'file') plans.push(await planEditorRemoval({ siteRoot, sourcePath: siteRoot, filePath: path.join(directory, relative), sources }));
+	} else {
+		for (const entry of await readdir(directory, { withFileTypes: true })) {
+			const filename = path.join(directory, entry.name);
+			if (kind === 'downloads' && entry.isFile()) plans.push(await planEditorRemoval({ siteRoot, sourcePath: path.join(ownerDirectory, 'content.md'), filePath: filename, sources }));
+			else if (kind === 'images' && entry.isFile()) plans.push(await planEditorRemoval({ siteRoot, sourcePath: path.join(ownerDirectory, 'content.md'), imagePath: filename, sources }));
+			else if (kind === 'pages' && entry.isDirectory()) plans.push(await planEditorRemoval({ siteRoot, sourcePath: path.join(filename, 'content.md'), sources }));
+			else throw new Error(`Cannot delete this folder safely: ${entry.name} is not a supported ${kind === 'pages' ? 'page' : 'image'}. Review it in Explorer first.`);
+		}
+	}
+	const usage = { references: plans.flatMap(plan => plan.usage?.references ?? []).filter(ref => !isInside(directory, ref.sourcePath)), incomplete: [...new Set(plans.flatMap(plan => plan.usage?.incomplete ?? []))] };
+	return { target: directory, pages: plans.reduce((total,plan) => total + plan.pages, 0), files: files.filter(([,type]) => type === 'file').length, usage,
+		fingerprint: JSON.stringify([files, plans.map(plan => plan.fingerprint), usage]) };
+};
+
+export const getEditorResourceAddress = async (options) => {
+	const selected = await resource(options);
+	if (!['public', 'attachment'].includes(selected.kind) || selected.directory) throw new Error('Select a public file.');
+	const { settings, graph } = await readEditorLinkState(options);
+	if (!settings) throw new Error('Repair site-config/settings.yaml to copy the published address.');
+	const pathname = selected.kind === 'attachment' ? graph.attachments.files.find(file => file.filePath === selected.filename)?.pathname : publicPath(options.siteRoot, selected.filename, settings);
+	if (!pathname) throw new Error('The file no longer belongs to this site.');
+	return new URL(encodeAttachmentPath(pathname).slice(1), settings.url.replace(/\/$/, '') + '/').href;
+};

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

@@ -1,7 +1,8 @@
+import { comparePageOrder } from './page-order.mjs';
 import { getSiteSourcePaths } from './site-conventions.mjs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { editorPageLocation, editorSourceDefinition } from './editor-source-files.mjs';
+import { editorPageLocation, editorSourceDefinition, getEditorSourceFileChoices } from './editor-source-files.mjs';
 import { editorFileRemovalPolicy } from './editor-file-policy.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
 import { parsePageMarkdownSource } from './page-markdown.mjs';
@@ -82,14 +83,16 @@ export const readSiteEditingTree = async ({ siteRoot, sources = new Map(), snaps
 		} else {
 			container = { id: resourceId(directory), parentId, ownerId: owner.id, sourcePath: directory,
 				kind: 'directory', role, title: path.basename(directory), description: role === 'public'
-					? 'Files published unchanged with the site, such as robots.txt and icons.' : role === 'configuration' ? 'Settings and content shared by the complete site' : '' };
+					? 'Technical site files, logo, browser icons and social image. Put content images in a page’s images/ and documents in its downloads/.' : role === 'configuration' ? 'Settings and content shared by the complete site' : '' };
 			items.push(container);
 		}
-		const order = location ? ['images', 'tree-theme.yaml', 'page-theme.yaml', 'pages']
+		const order = location ? ['images', 'downloads', 'tree-theme.yaml', 'page-theme.yaml', 'pages']
 			: role === 'site' ? ['site-config', 'public', 'root']
 			: role === 'configuration' ? ['settings.yaml', 'shared-content.yaml'] : [];
 		const rank = (entry) => order.includes(entry.name) ? order.indexOf(entry.name) : order.length;
-		entries.sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name, 'en', { numeric: true }));
+		entries.sort((a, b) => role === 'pages'
+			? comparePageOrder(byDirectory.get(path.join(directory, a.name)) ?? { pageId: a.name }, byDirectory.get(path.join(directory, b.name)) ?? { pageId: b.name })
+			: rank(a) - rank(b) || a.name.localeCompare(b.name, 'en', { numeric: true }));
 		for (const entry of entries) {
 			const filename = path.join(directory, entry.name);
 			if (location && entry.name === 'content.md' && entry.isFile() && owner.kind === 'page') continue;
@@ -97,12 +100,20 @@ export const readSiteEditingTree = async ({ siteRoot, sources = new Map(), snaps
 				const childLocation = role === 'pages' || role === 'site' && entry.name === 'root' ? editorPageLocation(siteRoot, filename) : null;
 				const childRole = childLocation ? 'page' : location && entry.name === 'pages' ? 'pages'
 					: location && entry.name === 'images' && owner.kind === 'page' ? 'images'
+						: location && entry.name === 'downloads' && owner.kind === 'page' ? 'downloads'
 						: role === 'site' && entry.name === 'site-config' ? 'configuration'
 							: role === 'public' || role === 'site' && entry.name === 'public' ? 'public' : 'extra';
+				if (['images', 'downloads'].includes(childRole)) {
+					const resources = await entriesAt(filename);
+					if (!resources.some(resource => resource.isFile() && (childRole === 'downloads' || /\.(jpe?g|png|svg)$/i.test(resource.name)))) {
+						if (resources.length) issue(owner, `${filename} has no supported files; inspect its unsupported entries in Explorer.`, 'warning', filename);
+						continue;
+					}
+				}
 				await visit(filename, container.id, owner, childRole, childLocation);
 				const child = items.find((item) => item.sourcePath === filename);
-				if (child && childRole === 'extra' && (knownNames.has(entry.name) || ['images', 'pages', 'site-config', 'public'].includes(entry.name) || role === 'pages')) {
-					issue(child, `This directory is not at a permitted Norna location: ${filename}. Use pages/NNN-page-id for child entries, images/ beside page content, and site-config/ or public/ only at the site root.`, 'warning');
+				if (child && childRole === 'extra' && (knownNames.has(entry.name) || ['images', 'downloads', 'pages', 'site-config', 'public'].includes(entry.name) || role === 'pages')) {
+					issue(child, `This directory is not at a permitted Norna location: ${filename}. Use pages/page-id for child entries, images/ beside page content, and site-config/ or public/ only at the site root.`, 'warning');
 				}
 				continue;
 			}
@@ -113,10 +124,10 @@ export const readSiteEditingTree = async ({ siteRoot, sources = new Map(), snaps
 			items.push(file);
 			if (['rootTheme', 'theme', 'pageTheme'].includes(definition?.schemaKind)) file.themeHelp = await themeHelp(directory, filename);
 			if (definition) await validate(file);
-			else if (role !== 'public' && ['site-config', 'public', 'pages', 'images'].includes(entry.name)) issue(file, `Expected a directory named ${entry.name}, but this is a file. Rename or move this file through Explorer before creating the directory.`, 'warning');
+			else if (role !== 'public' && ['site-config', 'public', 'pages', 'images', 'downloads'].includes(entry.name)) issue(file, `Expected a directory named ${entry.name}, but this is a file. Rename or move this file through Explorer before creating the directory.`, 'warning');
 			else if (role !== 'public' && entry.name === 'category.yaml') issue(file, 'category.yaml is no longer supported. Create content.md with page.listChildren: true, then remove this file.', 'warning');
 			else if (role !== 'public' && knownNames.has(entry.name)) issue(file, `This source file is in the wrong location. Put content.md, tree-theme.yaml and page-theme.yaml in a valid page directory; put settings.yaml and shared-content.yaml in the site's site-config/.`, 'warning');
-			else if (role !== 'public' && !(role === 'images' && /\.(jpe?g|png|svg)$/i.test(entry.name))) file.note = 'Not used by Norna';
+			else if (!['public', 'downloads'].includes(role) && !(role === 'images' && /\.(jpe?g|png|svg)$/i.test(entry.name))) file.note = 'Not used by Norna';
 		}
 	};
 	const source = getSiteSourcePaths(siteRoot);
@@ -135,11 +146,35 @@ export const readSiteEditingTree = async ({ siteRoot, sources = new Map(), snaps
 		}
 	}
 
+	// Roles own actions; the adapter only maps these names to native commands.
+	// Future page-owned resources can extend this without image/file guessing.
+	const byId = new Map(items.map(item => [item.id, item]));
+	for (const item of items) {
+		const parent = byId.get(item.parentId);
+		item.actions = [];
+		if (item.kind === 'page') item.actions.push('addPage', 'addImages', 'addAttachments', 'renamePage', 'properties', 'copyPageLink', 'pageReferences', ...(!item.isHome ? ['movePage', 'deletePage'] : []));
+		if (['page', 'incomplete'].includes(item.kind) || item.role === 'configuration' && item.kind === 'directory') {
+			const directory = item.kind === 'directory' ? siteRoot : item.directory;
+			const choices = await getEditorSourceFileChoices({ siteRoot, directory }).catch(() => []);
+			item.missingFiles = choices.filter(choice => path.dirname(choice.filename) === (item.kind === 'directory' ? item.sourcePath : item.directory));
+			for (const choice of item.missingFiles) item.actions.push('add_' + path.basename(choice.filename).replaceAll('.', '_').replaceAll('-', '_'));
+		}
+		if (item.kind === 'directory' && ['pages', 'images'].includes(item.role)) item.actions.push(item.role === 'pages' ? 'addPage' : 'addImages', 'deleteFolder');
+		if (item.kind === 'directory' && item.role === 'downloads') item.actions.push('addAttachments', 'deleteFolder');
+		if (item.kind === 'directory' && item.role === 'public') item.actions.push('newPublicFile', 'addPublicFiles', 'newPublicFolder', 'deleteFolder', ...(item.sourcePath !== path.join(siteRoot, 'public') ? ['renameResource', 'moveResource'] : []));
+		if (item.kind === 'file') {
+			if (parent?.role === 'public') item.actions.push('renameResource', 'replacePublicFile', 'moveResource', 'copyResourceLink', 'resourceReferences', 'deleteFile');
+			else if (parent?.role === 'downloads') item.actions.push('insertAttachment', 'renameResource', 'replaceAttachment', 'resourceReferences', 'copyResourceLink', 'deleteFile');
+			else if (parent?.role === 'images' && /\.(jpe?g|png|svg)$/i.test(item.title)) item.actions.push('insertImage', 'renameResource', 'replaceImage', 'resourceReferences', 'deleteImage');
+			else if (item.removable) item.actions.push('deleteFile');
+		}
+	}
+
 	// Keep shared structural diagnostics, including duplicate sibling identifiers.
 	for (const problem of snapshot.problems) {
 		if (![owner, ...items].some((item) => item.issues?.some((entry) => entry.message === problem.message && entry.path === problem.path))) {
 			const target = items.find((item) => item.sourcePath === problem.path || item.directory === problem.path) ?? owner;
-			issue(target, problem.message, 'error', problem.path);
+			issue(target, problem.message, problem.severity ?? 'error', problem.path);
 		}
 	}
 	return { ...snapshot, items, problems: owner.issues };

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

@@ -82,6 +82,7 @@ export const getEditorImageUsage = async ({ siteRoot, sourcePath, imagePath, sou
 	const references = [];
 	const incomplete = structure.problems.map((problem) => problem.message);
 	for (const node of structure.nodes.filter((node) => node.contentPath)) {
+		if (path.dirname(node.contentPath) !== directory) continue;
 		try {
 			const source = sources.has(node.contentPath) ? sources.get(node.contentPath) : await readFile(node.contentPath, 'utf8');
 			const document = await parsePageMarkdownSource(source, { label: node.contentPath });
@@ -89,7 +90,7 @@ export const getEditorImageUsage = async ({ siteRoot, sourcePath, imagePath, sou
 			for (const reference of document.managedImages.filter((reference) => reference.image.toLowerCase() === path.basename(target).toLowerCase())) {
 				const localPath = path.join(path.dirname(node.contentPath), 'images', reference.image);
 				const local = await stat(localPath);
-				if (local ? local.dev !== targetStat.dev || local.ino !== targetStat.ino : reference.image !== path.basename(target)) continue;
+				if (!local || local.dev !== targetStat.dev || local.ino !== targetStat.ino) continue;
 				references.push({ sourcePath: node.contentPath, line: reference.line, unresolved: !local });
 			}
 		} catch (error) { incomplete.push(`${node.contentPath}: ${error.message}`); }
@@ -106,7 +107,7 @@ export const planEditorRemoval = async ({ siteRoot, sourcePath, imagePath, fileP
 	const policy = filePath ? editorFileRemovalPolicy({ siteRoot: path.resolve(siteRoot), sourcePath: target.sourcePath, filePath: filename }) : null;
 	if (filePath && (!policy || !(await stat(filename))?.isFile())) throw new Error('This file cannot be removed separately. Required page files belong to their page; required site settings must remain.');
 	const usage = imagePath ? await getEditorImageUsage({ siteRoot, sourcePath, imagePath, sources })
-		: !filePath || policy.kind === 'public' ? await getEditorIncomingLinks({ siteRoot, sourcePath, sources,
+		: !filePath || ['public', 'attachment'].includes(policy.kind) ? await getEditorIncomingLinks({ siteRoot, sourcePath, sources,
 			descendants: !filePath, excludeBranch: !filePath, filePath }) : null;
 	const files = await snapshot(filename);
 	const effect = policy?.kind === 'theme'

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

@@ -1,3 +1,4 @@
+import { getSiteAttachments } from './page-attachments.mjs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { getGeneratedSiteRoutes } from './page-aliases.mjs';
@@ -43,13 +44,13 @@ export const readEditorLinkState = async ({ siteRoot, sources = new Map() }) =>
 		return { contentFile, data, document };
 	}));
 	let publicFiles = [];
-	try { publicFiles = await getSitePublicFiles(path.join(siteRoot, 'public')); }
+	try { publicFiles = await getSitePublicFiles(path.join(siteRoot, 'public'), settings); }
 	catch (error) { incomplete.push(error.message); }
 	const generatedRoutes = getGeneratedSiteRoutes({ searchEnabled: settings?.search });
-	const graph = createSiteLinkGraph({ siteStructure: structure, pageDocuments, publicFiles, generatedRoutes });
+	const graph = createSiteLinkGraph({ siteUrl: settings?.url, siteStructure: structure, pageDocuments, publicFiles, generatedRoutes, attachments: await getSiteAttachments(structure) });
 	// Missing destinations do not make reference discovery incomplete. Ambiguous
 	// ownership of an address does, and must never be presented as a clean check.
-	incomplete.push(...graph.diagnostics.filter((entry) => !entry.reference && entry.severity === 'error').map(({ message }) => message));
+	incomplete.push(...graph.diagnostics.filter((entry) => (!entry.reference || entry.code === 'ambiguous-attachment') && entry.severity === 'error').map(({ message }) => message));
 	return { structure, graph, publicFiles, generatedRoutes, settings, incomplete: [...new Set(incomplete)].sort() };
 };
 
@@ -72,7 +73,8 @@ export const getEditorIncomingLinks = async ({ siteRoot, sourcePath, sources, de
 	const references = state.graph.references.filter((reference) => {
 		if (excludeBranch && isInside(directory, reference.sourceContentFile.contentPath)) return false;
 		if (alias) return reference.target.pageLookupPathname === alias;
-		if (filePath) return reference.resolution?.kind === 'public-file' && reference.resolution.file.filePath === filePath;
+		if (filePath) return ['public-file', 'attachment'].includes(reference.resolution?.kind) && reference.resolution.file.filePath === filePath;
+		if (reference.resolution?.kind === 'attachment' && targetPaths.has(reference.resolution.file.ownerPathname)) return true;
 		return targetPaths.has(reference.resolution?.pathname ?? reference.target.pageLookupPathname);
 	}).map(summarizeReference);
 	return { references, incomplete: state.incomplete };