@janga/norna 0.7.26 → 0.7.28

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

@@ -0,0 +1,94 @@
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+
+const collectComments = (token, start, end, comments = []) => {
+	if (!token || typeof token !== 'object') return comments;
+	if (token.type === 'comment' && token.offset >= start && token.offset < end) comments.push(token.source);
+	for (const value of Object.values(token)) {
+		if (Array.isArray(value)) for (const item of value) collectComments(item, start, end, comments);
+		else if (value && typeof value === 'object') collectComments(value, start, end, comments);
+	}
+	return comments;
+};
+
+export const changeYamlField = (yaml, keys, value, eol) => {
+	const document = parseDocument(yaml, { keepSourceTokens: true });
+	if (document.errors.length) throw new Error('Repair the YAML before editing it automatically.');
+	if (document.contents && !isMap(document.contents)) throw new Error('This YAML document requires a mapping.');
+	const scalar = (data) => JSON.stringify(data);
+	const entryText = (key, data, indent) => {
+		const prefix = ' '.repeat(indent);
+		if (Array.isArray(data)) return `${prefix}${key}:${eol}${data.map((entry) => `${prefix}  - ${scalar(entry)}${eol}`).join('')}`;
+		return data && typeof data === 'object' && !Array.isArray(data)
+			? `${prefix}${key}:${eol}${Object.entries(data).map(([child, value]) => entryText(child, value, indent + 2)).join('')}`
+			: `${prefix}${key}: ${scalar(data)}${eol}`;
+	};
+	const edit = (start, end, text) => yaml.slice(0, start) + text + yaml.slice(end);
+	const insert = (map, key, data) => {
+		if (!map) return yaml + (yaml && !yaml.endsWith('\n') ? eol : '') + entryText(key, data, 0);
+		if (map.flow) {
+			const position = map.range[1] - 1;
+			const separator = map.items.length && !yaml.slice(0, position).trimEnd().endsWith(',') ? ', ' : '';
+			return edit(position, position, `${separator}${key}: ${scalar(data)}`);
+		}
+		const indent = map.items[0]?.key.srcToken.indent ?? 0;
+		const position = map.range[2];
+		return edit(position, position, `${position && yaml[position - 1] !== '\n' ? eol : ''}${entryText(key, data, indent)}`);
+	};
+	const visit = (map, remaining, ancestors = []) => {
+		const [key, ...rest] = remaining;
+		const pair = map?.items.find((item) => item.key.value === key);
+		if (!pair) {
+			if (value === undefined) return yaml;
+			return insert(map, key, rest.reduceRight((child, part) => ({ [part]: child }), value));
+		}
+		if (rest.length) {
+			if (!isMap(pair.value)) throw new Error(`Edit ${key} as a YAML mapping in the source before editing it automatically.`);
+			return visit(pair.value, rest, [...ancestors, { map, pair }]);
+		}
+		if (value !== undefined) {
+			if ((!isScalar(pair.value) && !(Array.isArray(value) && isSeq(pair.value))) || pair.value.anchor || pair.value.tag
+				|| (isSeq(pair.value) && pair.value.items.some((item) => !isScalar(item) || item.anchor || item.tag))) {
+				throw new Error(`Edit ${keys.join('.')} in the source; this field uses YAML anchors, tags or values that cannot be changed automatically.`);
+			}
+			if (Array.isArray(value) && !map.flow) {
+				// Keep aliases in block form so a later page:move can preserve
+				// old addresses without asking the author to reformat our output.
+				const start = yaml.lastIndexOf('\n', pair.key.range[0] - 1) + 1;
+				const end = pair.value.range[2];
+				const indent = pair.key.srcToken.indent ?? 0;
+				const comments = collectComments(pair.srcToken, start, end);
+				return edit(start, end, comments.map((comment) => `${' '.repeat(indent)}${comment}${eol}`).join('')
+					+ entryText(pair.key.value, value, indent));
+			}
+			const start = pair.value.range[0];
+			const end = pair.value.range[1];
+			const comments = collectComments(pair.value.srcToken, start, end);
+			const trailing = yaml.slice(start, end).endsWith('\n') ? eol : '';
+			return edit(start, end, scalar(value) + comments.map((comment) => ` ${comment}`).join('') + trailing);
+		}
+		return remove(map, pair, ancestors);
+	};
+	const remove = (map, pair, ancestors) => {
+		if (!map.flow && map.items.length === 1 && ancestors.length) {
+			const parent = ancestors.pop();
+			return remove(parent.map, parent.pair, ancestors);
+		}
+		let start = pair.key.range[0];
+		let end = pair.value?.range[2] ?? pair.key.range[2];
+		if (map.flow) {
+			end = pair.value?.range[1] ?? pair.key.range[1];
+			const index = map.items.indexOf(pair);
+			const previousComma = pair.srcToken?.start.find((token) => token.type === 'comma');
+			const nextComma = map.items[index + 1]?.srcToken?.start.find((token) => token.type === 'comma');
+			if (previousComma) start = previousComma.offset;
+			else if (nextComma) end = nextComma.offset + 1;
+		} else {
+			start = yaml.lastIndexOf('\n', start - 1) + 1;
+		}
+		const comments = collectComments(pair.srcToken, start, end);
+		const indent = pair.key.srcToken.indent ?? 0;
+		const replacement = comments.map((comment) => `${' '.repeat(indent)}${comment}${eol}`).join('');
+		return edit(start, end, replacement);
+	};
+	return visit(document.contents, keys);
+};

package/scripts/move-site-page.mjs

@@ -1,13 +1,4 @@
-import { randomUUID } from 'node:crypto';
-import {
-	access,
-	mkdir,
-	readFile,
-	rename,
-	rm,
-	rmdir,
-	writeFile,
-} from 'node:fs/promises';
+import { applyPageMovePlan } from './lib/page-move-apply.mjs';
 import path from 'node:path';
 import {
 	createPageMovePlan,
@@ -21,6 +12,7 @@ import {
 	sitePagesDir,
 	sitePagesLabel,
 	siteProjectRoot,
+	siteDir,
 } from './lib/site-paths.mjs';
 import { getSiteStructure } from './lib/site-structure.mjs';
 
@@ -101,119 +93,6 @@ const toDisplayPath = (filePath) => {
 		: filePath).split(path.sep).join('/');
 };
 
-const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
-
-const writeFileAtomically = async (filePath, source, mode) => {
-	const temporaryPath = path.join(
-		path.dirname(filePath),
-		`.${path.basename(filePath)}.norna-${process.pid}-${randomUUID()}.tmp`,
-	);
-	try {
-		await writeFile(temporaryPath, source, { mode: mode & 0o777 });
-		await rename(temporaryPath, filePath);
-	} finally {
-		await rm(temporaryPath, { force: true });
-	}
-};
-
-const assertSourcesUnchanged = async (plan) => {
-	for (const file of plan.sourceFiles) {
-		const currentSource = await readFile(file.contentPath, 'utf8');
-		if (currentSource !== file.source) {
-			throw new Error([
-				`Page move stopped because ${file.contentLabel} changed after the plan was created.`,
-				'Run the command again to build a fresh plan. No file was changed.',
-			].join('\n'));
-		}
-	}
-};
-
-const assertFinalSite = async () => {
-	const structure = await getSiteStructure();
-	const graph = await getSiteLinkGraph({ siteStructure: structure });
-	if (graph.diagnostics.length === 0) return;
-	throw new Error([
-		'Post-move link validation failed.',
-		...graph.diagnostics.flatMap((diagnostic) => [
-			`- ${diagnostic.message}`,
-			...(diagnostic.fix ? [`  Fix: ${diagnostic.fix}`] : []),
-		]),
-	].join('\n'));
-};
-
-const applyPlan = async (plan) => {
-	await assertSourcesUnchanged(plan);
-	let collectionCreated = false;
-	let directoryMoved = false;
-	let fileWritten = false;
-
-	try {
-		if (plan.mode === 'move') {
-			if (!plan.destinationCollectionExists) {
-				await mkdir(plan.destinationCollectionDirectory);
-				collectionCreated = true;
-			}
-			try {
-				await rename(plan.sourceDirectory, plan.destinationDirectory);
-				directoryMoved = true;
-			} catch (error) {
-				if (error?.code === 'EXDEV') {
-					throw new Error('Page directories must stay on one filesystem so Norna can move the complete subtree atomically.');
-				}
-				throw error;
-			}
-		}
-
-		for (const change of plan.fileChanges) {
-			await writeFileAtomically(change.finalPath, change.updatedSource, change.mode);
-			fileWritten = true;
-		}
-		await assertFinalSite();
-	} catch (error) {
-		const changesStarted = directoryMoved || fileWritten;
-		const rollbackErrors = [];
-		if (directoryMoved) {
-			try {
-				await rename(plan.destinationDirectory, plan.sourceDirectory);
-				directoryMoved = false;
-			} catch (rollbackError) {
-				rollbackErrors.push(`Could not restore the page directory: ${rollbackError.message}`);
-			}
-		}
-
-		for (const change of plan.fileChanges) {
-			try {
-				const restorePath = directoryMoved && change.finalPath !== change.originalPath
-					? change.finalPath
-					: change.originalPath;
-				await writeFileAtomically(restorePath, change.originalSource, change.mode);
-			} catch (rollbackError) {
-				rollbackErrors.push(`Could not restore ${change.contentLabel}: ${rollbackError.message}`);
-			}
-		}
-
-		if (collectionCreated && !directoryMoved) {
-			try {
-				await rmdir(plan.destinationCollectionDirectory);
-			} catch (rollbackError) {
-				if (rollbackError?.code !== 'ENOENT' && rollbackError?.code !== 'ENOTEMPTY') {
-					rollbackErrors.push(`Could not remove the newly created pages directory: ${rollbackError.message}`);
-				}
-			}
-		}
-
-		throw new Error([
-			error instanceof Error ? error.message : String(error),
-			rollbackErrors.length === 0
-				? (changesStarted
-					? 'The original page directory and content files were restored.'
-					: 'No source file was changed.')
-				: 'Rollback was incomplete. Inspect these paths before running page:move again:',
-			...rollbackErrors.map((message) => `- ${message}`),
-		].join('\n'));
-	}
-};
-
 const main = async () => {
 	const options = parseArgs(process.argv.slice(2));
 	if (options.help) {
@@ -244,7 +123,7 @@ const main = async () => {
 		return;
 	}
 
-	await applyPlan(plan);
+	await applyPageMovePlan(plan, { siteRoot: siteDir });
 	console.log(`\nPage move completed: ${plan.from} -> ${plan.to}`);
 };
 

package/scripts/show-typography.mjs

@@ -1,6 +1,4 @@
 import {
-	defaultTypography,
-	resolveTypographyConfig,
 	toYamlLines,
 	typographyProfiles,
 	typographyRhythms,
@@ -13,10 +11,13 @@ import {
 } from './lib/site-content.mjs';
 import { parsePageMarkdown } from './lib/page-markdown.mjs';
 import {
+	siteDir,
 	siteThemeLabel,
 } from './lib/site-paths.mjs';
 import { readThemeConfig } from './lib/theme-config.mjs';
 import { resolveThemeConfig } from './lib/theme-presets.mjs';
+import { selectPageTheme } from './lib/theme-packages.mjs';
+import { resolveThemePresentation } from './lib/presentation.mjs';
 
 const mode = process.argv[2] ?? 'show';
 
@@ -137,14 +138,14 @@ const defaultSources = (profileName, rhythmName) => {
 	return sources;
 };
 
-const applyOverrideSources = (sources, typographyConfig, sourceLabel) => {
+const applyOverrideSources = (sources, typographyConfig, sourceFor) => {
 	const overrides = typographyConfig?.overrides;
 	if (!overrides) return sources;
 
 	for (const path of typographyValuePaths) {
 		if (hasPath(overrides, path)) {
 			setPath(sources, path, {
-				source: `${sourceLabel} override`,
+				source: `${sourceFor(['typography', 'overrides', ...path])} override`,
 				inherited: false,
 			});
 		}
@@ -153,25 +154,38 @@ const applyOverrideSources = (sources, typographyConfig, sourceLabel) => {
 	return sources;
 };
 
-const resolveAnnotatedTypographyConfig = (typographyConfig, sourceLabel) => {
-	const resolved = resolveTypographyConfig(typographyConfig ?? defaultTypography);
+const resolveAnnotatedTypographyConfig = (theme, sourceLabel, sourceFiles) => {
+	const normalized = resolveThemeConfig(theme, sourceLabel);
+	const typographyConfig = normalized.typography;
+	const resolved = resolveThemePresentation(theme, sourceLabel).typography;
+	// Attribute a value to its last authored setting, stopping at the preset
+	// that replaced its base. The resolver still determines all effective values.
+	const sourceFor = (propertyPath) => {
+		for (const file of sourceFiles.toReversed()) {
+			if (hasPath(file.config, propertyPath)) return file.label;
+			if (file.config.preset !== undefined) return `preset:${file.config.preset} (${file.label})`;
+		}
+		return 'engine default';
+	};
 	const sources = applyOverrideSources(
 		defaultSources(resolved.profile, resolved.rhythm),
 		typographyConfig,
-		sourceLabel,
+		sourceFor,
 	);
+	if (normalized.layout?.textWidth !== undefined) {
+		setPath(sources, ['body', 'width'], { source: sourceFor(['layout', 'textWidth']), inherited: false });
+	}
 
 	return {
 		profile: {
 			value: resolved.profile,
-			source: typographyConfig?.profile ? sourceLabel : 'engine default',
-			...(typographyConfig?.profile ? {} : { inherited: true }),
+			source: sourceFor(['typography', 'profile']),
 		},
 		rhythm: {
 			value: resolved.rhythm,
-			source: typographyConfig?.rhythm ? sourceLabel : 'engine default',
-			...(typographyConfig?.rhythm ? {} : { inherited: true }),
+			source: sourceFor(['typography', 'rhythm']),
 		},
+		fontFamily: { value: typographyConfig.fontFamily, source: sourceFor(['typography', 'fontFamily']) },
 		resolved,
 		sources,
 	};
@@ -180,16 +194,16 @@ const resolveAnnotatedTypographyConfig = (typographyConfig, sourceLabel) => {
 const formatAnnotatedTypography = (annotated) => ({
 	profile: annotated.profile,
 	rhythm: annotated.rhythm,
+	fontFamily: annotated.fontFamily,
 	resolved: annotateResolvedValues(annotated.resolved, annotated.sources),
 });
 
 const readThemeTypography = async () => {
-	const themeConfig = resolveThemeConfig(await readThemeConfig(), siteThemeLabel);
-	const themeTypographyConfig = themeConfig.typography;
-	return resolveAnnotatedTypographyConfig(themeTypographyConfig ?? defaultTypography, siteThemeLabel);
+	const config = await readThemeConfig();
+	return resolveAnnotatedTypographyConfig(config, siteThemeLabel, [{ config, label: siteThemeLabel }]);
 };
 
-const readPageTypography = async (contentFile, siteThemeTypography) => {
+const readPageTypography = async (contentFile) => {
 	const { frontmatter, body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
 	const indentationIssues = [];
 	validateFrontmatterIndentation(frontmatter, (issue) => indentationIssues.push(issue));
@@ -201,7 +215,8 @@ const readPageTypography = async (contentFile, siteThemeTypography) => {
 		].join('\n'));
 	}
 
-	const pageTypography = siteThemeTypography;
+	const { selected, sourceFiles } = await selectPageTheme({ siteRoot: siteDir, pageDirectory: contentFile.pageDirectory });
+	const pageTypography = resolveAnnotatedTypographyConfig(selected.config, selected.label, sourceFiles);
 	const sections = (await parsePageMarkdown(body, { label: contentFile.contentLabel })).sections
 		.map((section) => {
 		return {
@@ -225,7 +240,7 @@ if (mode === 'profiles') {
 	}).join('\n'));
 } else if (mode === 'show') {
 	const themeTypography = await readThemeTypography();
-	const pages = await Promise.all((await getContentFiles()).map((contentFile) => readPageTypography(contentFile, themeTypography)));
+	const pages = await Promise.all((await getContentFiles()).map(readPageTypography));
 	const output = {
 		theme: {
 			source: siteThemeLabel,

package/scripts/sync-content-sections.mjs

@@ -233,7 +233,6 @@ try {
 const siteStructure = await getSiteStructure();
 const contentFiles = siteStructure.contentFiles;
 for (const warning of siteStructure.warnings) {
-	if (warning.code === 'empty-category') continue;
 	addIssue({
 		severity: 'warning',
 		message: warning.message,
@@ -424,17 +423,20 @@ const listedNavigationTree = getListedSiteNavigationTree(siteStructure.nodes.map
 	return {
 		node: {
 			...node,
-			navigation: {
-				listed: node.kind === 'category'
-					? true
-					: context?.frontmatterData.navigation?.listed ?? true,
-			},
+			navigation: { listed: context?.frontmatterData.navigation?.listed ?? true },
 		},
 	};
 }));
 
 for (const context of contentFileContexts) {
 	const childPages = getDirectChildPages(listedNavigationTree, context.contentFile.pagePath);
+	if (context.frontmatterData.page?.listChildren && childPages.length === 0) {
+		addContentIssue(context.contentFile, {
+			severity: 'warning',
+			message: 'page.listChildren has no listed direct child pages to display.',
+			fix: 'Add a listed direct child page, or remove page.listChildren while this page has no children.',
+		});
+	}
 	const warnedChildren = new Set();
 
 	for (const section of context.sections) {
@@ -444,7 +446,7 @@ for (const context of contentFileContexts) {
 			if (childPages.length === 0) {
 				addSectionIssue(context.contentFile, section, {
 					severity: 'error',
-					message: `page-list on line ${block.line} has no listed direct child pages to display. Navigation categories are not pages.`,
+					message: `page-list on line ${block.line} has no listed direct child pages to display.`,
 					fix: 'Add a listed direct child page or remove the block.',
 				});
 				continue;

package/scripts/sync-site-public.mjs

@@ -33,7 +33,7 @@ const sourceEntries = await readDirectory(sitePublicDir);
 const generatedPublicFiles = [
 	{
 		filename: sitemapFilename,
-		explanation: `Norna generates ${sitemapFilename} from the public page tree and the URL in site/config.yaml.`,
+		explanation: `Norna generates ${sitemapFilename} from the public page tree and the URL in site/site-config/settings.yaml.`,
 	},
 	{
 		filename: '404.html',

package/scripts/upgrade-site.mjs

@@ -0,0 +1,17 @@
+import { siteDir } from './lib/site-paths.mjs';
+import { planSiteUpgrade } from './lib/site-upgrade.mjs';
+
+const usage = 'Usage: norna site:upgrade [--apply]\nCheck the root/ source layout. Former layouts require manual conversion; --apply is retained but does not convert old sources.';
+const args = process.argv.slice(2);
+try {
+	if (args.includes('--help') || args.includes('-h')) {
+		console.log(usage);
+	} else {
+		if (args.length > 1 || args.some((arg) => arg !== '--apply')) throw new Error(usage);
+		await planSiteUpgrade(siteDir);
+		console.log('The site already uses the current configuration and homepage layout. No files changed.');
+	}
+} catch (error) {
+	console.error(error.message);
+	process.exitCode = 1;
+}

package/src/components/AreaNavigationMenu.astro

@@ -0,0 +1,24 @@
+---
+import projectConfig from '../../scripts/lib/project-config.mjs';
+import type { CategoryDestinationMap, SiteNavigationNode } from '../lib/siteNavigation';
+import type { SiteNode } from '../lib/sitePages';
+import AreaNavigationPanel from './AreaNavigationPanel.astro';
+
+interface Props {
+	node: SiteNavigationNode;
+	currentPage?: SiteNode;
+	categoryDestinations?: CategoryDestinationMap;
+}
+const { node, currentPage, categoryDestinations } = Astro.props;
+const label = `${projectConfig.locale.labels.navigationMenu}: ${node.node.title}`;
+const panelId = `area-menu-${encodeURIComponent(node.node.pagePath)}`;
+---
+
+{node.children.length > 0 && (
+	<details class="top-page-menu area-navigation-menu" data-area-menu={node.node.pagePath}>
+		<summary aria-label={label} aria-controls={panelId}>
+			<span class="top-page-menu-title">{node.node.title}</span>
+		</summary>
+		<AreaNavigationPanel id={panelId} node={node} currentPage={currentPage} categoryDestinations={categoryDestinations} />
+	</details>
+)}

package/src/components/AreaNavigationPanel.astro

@@ -0,0 +1,55 @@
+---
+import { Check } from '@lucide/astro';
+import projectConfig from '../../scripts/lib/project-config.mjs';
+import { withBasePath } from '../lib/basePath';
+import { getNavigationDestination, type CategoryDestinationMap, type SiteNavigationNode } from '../lib/siteNavigation';
+import { getAreaMenuGroups, resolveAreaNavigation } from '../lib/areaNavigation';
+import type { SiteNode } from '../lib/sitePages';
+
+interface Props {
+	id: string;
+	node?: SiteNavigationNode;
+	currentPage?: SiteNode;
+	categoryDestinations?: CategoryDestinationMap;
+	otherRoots?: SiteNavigationNode[];
+}
+const { id, node, currentPage, categoryDestinations, otherRoots = [] } = Astro.props;
+const { localRoot } = resolveAreaNavigation(node ? [node] : [], currentPage);
+const { branches, pages } = node ? getAreaMenuGroups(node) : { branches: [], pages: [] };
+const columnsFor = (count: number, maximum: number) => count === 0 ? 0 : Math.ceil(count / Math.ceil(count / maximum));
+const branchColumns = columnsFor(branches.length, pages.length > 0 ? 2 : 3);
+const pageColumns = branches.length === 0 ? columnsFor(pages.length, 3) : pages.length > 0 ? 1 : 0;
+const groups = [
+	{ kind: 'branches', choices: branches, columns: branchColumns },
+	{ kind: 'pages', choices: pages, columns: pageColumns },
+].filter(({ choices }) => choices.length > 0);
+---
+
+<nav id={id} class="top-page-panel area-navigation-panel"
+	style={`--area-menu-columns: ${branchColumns + pageColumns || 2}`}
+	aria-label={node ? `${node.node.title}: ${projectConfig.locale.labels.navigationChildren}` : projectConfig.locale.labels.siteNavigation}>
+	{groups.map((group) => <ul class="area-navigation-choices" data-area-choice-group={group.kind}
+		style={`--area-group-columns: ${group.columns}; --area-group-rows: ${Math.ceil(group.choices.length / group.columns)}`}>
+		{group.choices.map((child) => {
+			const destination = getNavigationDestination(child.node, categoryDestinations);
+			const selected = localRoot === child || currentPage?.pagePath === child.node.pagePath;
+			const description = child.node.kind === 'page'
+				? child.node.entry.data.page?.description
+				: child.node.description;
+			return <li>
+				<a href={withBasePath(projectConfig.site.basePath, destination.pathname)}
+					aria-current={selected ? 'true' : undefined} data-area-choice={child.node.pagePath}>
+					<span class="area-navigation-title">{child.node.title}{selected && <Check aria-hidden="true" />}</span>
+					{group.kind === 'branches' && description && <span class="area-navigation-description">{description}</span>}
+				</a>
+			</li>;
+		})}
+	</ul>)}
+	{otherRoots.length > 0 && <ul class="area-navigation-other-roots" aria-label={projectConfig.locale.labels.siteNavigation}>
+		{otherRoots.map(({ node: root }) => <li>
+			<a href={withBasePath(projectConfig.site.basePath, getNavigationDestination(root, categoryDestinations).pathname)}>
+				{root.isHome ? projectConfig.locale.labels.returnHome : root.title}
+			</a>
+		</li>)}
+	</ul>}
+</nav>

package/src/components/AreaNavigationSwitcher.astro

@@ -0,0 +1,30 @@
+---
+import { Menu } from '@lucide/astro';
+import projectConfig from '../../scripts/lib/project-config.mjs';
+import { hasLargeAreaMenu, resolveAreaNavigation } from '../lib/areaNavigation';
+import type { CategoryDestinationMap, SiteNavigationNode } from '../lib/siteNavigation';
+import type { SiteNode } from '../lib/sitePages';
+import AreaNavigationPanel from './AreaNavigationPanel.astro';
+
+interface Props {
+	nodes: SiteNavigationNode[];
+	currentPage?: SiteNode;
+	categoryDestinations?: CategoryDestinationMap;
+	label?: string;
+}
+
+const { nodes, currentPage, categoryDestinations, label } = Astro.props;
+const { globalRoot } = resolveAreaNavigation(nodes, currentPage);
+const currentLabel = label ?? globalRoot?.node.title ?? projectConfig.locale.labels.navigationMenu;
+const menuRoot = globalRoot && globalRoot.children.length > 0 && !hasLargeAreaMenu(globalRoot) ? globalRoot : undefined;
+const otherRoots = nodes.filter((root) => root !== menuRoot);
+const menuLabel = `${projectConfig.locale.labels.navigationMenu}: ${currentLabel}`;
+---
+
+<details class="top-page-menu area-navigation-switcher" data-area-switcher>
+	<summary aria-label={menuLabel} title={menuLabel} aria-controls="area-switcher-panel">
+		<Menu aria-hidden="true" />
+	</summary>
+	<AreaNavigationPanel id="area-switcher-panel" node={menuRoot} currentPage={currentPage}
+		categoryDestinations={categoryDestinations} otherRoots={otherRoots} />
+</details>

package/src/components/ImageStackEnhancement.astro

@@ -104,13 +104,6 @@ const labels = projectConfig.locale.labels;
 		const imageBounds = image.getBoundingClientRect();
 		if (imageBounds.height < usableViewportHeight * persistentCaptionHeightRatio) return;
 
-		const visibleContentsRail = Array.from(
-			layout.querySelectorAll<HTMLElement>('.page-contents-navigation-rail'),
-		).some(isVisible);
-		const reservesContentsLane = layout.dataset.pageContentsPlacement === 'contents-rail'
-			&& document.documentElement.dataset.focusReading !== 'on';
-		if (visibleContentsRail || reservesContentsLane) return;
-
 		const frameBounds = frame.getBoundingClientRect();
 		const figureBounds = figure.getBoundingClientRect();
 		const captionBounds = caption.getBoundingClientRect();

package/src/components/NavigationContinuity.astro

@@ -0,0 +1,26 @@
+---
+import styles from '../styles/navigation-continuity.css?inline';
+---
+
+<style is:inline set:html={styles} />
+<script is:inline>
+	// A cold history arrival can restore its position at pagereveal, then lose
+	// it to native fragment scrolling when deferred modules finish parsing.
+	// Keep the browser's restored position until that initial load completes.
+	window.addEventListener('pagereveal', () => {
+		if (!location.hash || document.readyState === 'complete'
+			|| performance.getEntriesByType('navigation')[0]?.type !== 'back_forward'
+			|| history.scrollRestoration !== 'auto') return;
+
+		history.scrollRestoration = 'manual';
+		const release = () => {
+			history.scrollRestoration = 'auto';
+			window.removeEventListener('load', release);
+			window.removeEventListener('pagehide', release);
+		};
+		window.addEventListener('load', release);
+		window.addEventListener('pagehide', release);
+	}, { once: true });
+</script>
+<!-- A streamed response must finish the page before its transition snapshot. -->
+<link rel="expect" blocking="render" href="#norna-navigation-ready" />

package/src/components/NavigationPageTree.astro

@@ -1,19 +1,23 @@
 ---
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { withBasePath } from '../lib/basePath';
-import type { SiteNavigationNode } from '../lib/siteNavigation';
+import { getNavigationDestination, type CategoryDestinationMap, type SiteNavigationNode } from '../lib/siteNavigation';
 import type { SiteNode, SitePage } from '../lib/sitePages';
 import PageContentsLinks from './PageContentsLinks.astro';
 
 interface Props {
 	nodes: SiteNavigationNode[];
 	currentPage?: SiteNode;
+	categoryDestinations?: CategoryDestinationMap;
 	variant: 'mobile' | 'sidebar' | 'submenu';
 	integratePageSections?: boolean;
 }
 
-const { nodes, currentPage, variant, integratePageSections = false } = Astro.props;
+const { nodes, currentPage, categoryDestinations, variant, integratePageSections = false } = Astro.props;
 const pageHref = (page: SitePage) => withBasePath(projectConfig.site.basePath, page.pathname);
+const categoryHref = (node: SiteNavigationNode) => withBasePath(
+	projectConfig.site.basePath, getNavigationDestination(node.node, categoryDestinations).pathname,
+);
 const hasBranch = (node: SiteNavigationNode) => node.children.length > 0;
 const isCurrentPage = (page: SitePage) => currentPage?.pathname === page.pathname;
 const isCurrentBranch = (node: SiteNode) => Boolean(currentPage && (
@@ -71,13 +75,17 @@ const usesPageDisclosure = (node: SiteNavigationNode) => variant !== 'submenu' &
 						class="navigation-page-summary"
 						aria-controls={getBranchId(node.node)}
 					>
-						<span class="navigation-page-summary-title">{node.node.title}</span>
+							<a class:list={['navigation-page-summary-title', 'navigation-category-link', {
+								'mobile-nav-destination': variant === 'mobile',
+							}]}
+								href={categoryHref(node)}>{node.node.title}</a>
 						<span class="navigation-page-chevron" aria-hidden="true"></span>
 					</summary>
 					<div id={getBranchId(node.node)} class="navigation-page-branch-content">
 						<Astro.self
 							nodes={node.children}
 							currentPage={currentPage}
+							categoryDestinations={categoryDestinations}
 							variant={variant}
 							integratePageSections={integratePageSections}
 						/>
@@ -123,6 +131,7 @@ const usesPageDisclosure = (node: SiteNavigationNode) => variant !== 'submenu' &
 						<Astro.self
 							nodes={node.children}
 							currentPage={currentPage}
+							categoryDestinations={categoryDestinations}
 							variant={variant}
 							integratePageSections={integratePageSections}
 						/>
@@ -174,7 +183,7 @@ const usesPageDisclosure = (node: SiteNavigationNode) => variant !== 'submenu' &
 						{node.node.title}
 					</a>
 					{node.children.length > 0 && (
-						<Astro.self nodes={node.children} currentPage={currentPage} variant={variant} />
+						<Astro.self nodes={node.children} currentPage={currentPage} categoryDestinations={categoryDestinations} variant={variant} />
 					)}
 				</>
 			)}

package/src/components/NavigationState.astro

@@ -0,0 +1,11 @@
+---
+import { getNavigationStateScript } from '../lib/navigationStateScript.mjs';
+
+interface Props {
+	scope: 'desktop' | 'mobile';
+}
+
+const { scope } = Astro.props;
+---
+
+<script is:inline data-navigation-state-scope={scope} set:html={getNavigationStateScript()} />