@janga/norna 0.7.26 → 0.7.28

package/src/lib/areaNavigation.ts

@@ -0,0 +1,42 @@
+import type { SiteNavigationNode } from './siteNavigation';
+import type { SiteNode } from './sitePages';
+
+const containsPage = (root: SiteNavigationNode, page: SiteNode) => (
+	root.node.pagePath === page.pagePath
+	|| (root.node.pagePath !== '' && page.pagePath.startsWith(`${root.node.pagePath}/`))
+);
+
+// Beyond twelve choices, use a destination with a local tree instead of a panel.
+export const hasLargeAreaMenu = (root: SiteNavigationNode) => (
+	root.children.length + (root.node.kind === 'page' ? 1 : 0) > 12
+);
+
+export const getAreaMenuGroups = (root: SiteNavigationNode) => {
+	const choices = root.node.kind === 'page' ? [root, ...root.children] : root.children;
+	return {
+		branches: choices.filter(({ children }) => children.length > 0),
+		pages: choices.filter(({ children }) => children.length === 0),
+	};
+};
+
+// Only the listed tree enters this resolver. Flat collections keep their pages
+// together; collections with subgroups select child branches. Large collections
+// and a parent's own overview retain the full tree. Scope never depends on the
+// arrival route, stored state or the number of headings on a page.
+export const resolveAreaNavigation = (roots: SiteNavigationNode[], page?: SiteNode) => {
+	const globalRoot = page ? roots.find((root) => containsPage(root, page)) : undefined;
+	if (globalRoot && globalRoot.children.length > 0 && (
+		globalRoot.children.every((child) => child.children.length === 0)
+		|| hasLargeAreaMenu(globalRoot) || page?.pagePath === globalRoot.node.pagePath
+	)) return { globalRoot, localRoot: globalRoot };
+	const area = page && globalRoot?.children.find((child) => (
+		child.children.length > 0 && containsPage(child, page)
+	));
+	return { globalRoot, localRoot: area };
+};
+
+export const withH2Outlines = (roots: SiteNavigationNode[]): SiteNavigationNode[] => roots.map((root) => ({
+	...root,
+	headings: root.headings.filter(({ depth }) => depth === 2),
+	children: withH2Outlines(root.children),
+}));

package/src/lib/navigationContinuity.ts

@@ -0,0 +1,212 @@
+import { isNavigationElementDisplayed } from './navigationVisibility';
+
+type Prefetch = (url: string) => void;
+
+const setupTreeScrollport = () => {
+	const tree = document.querySelector<HTMLElement>('.tree-local-navigation');
+	const layout = tree?.parentElement;
+	if (!tree || !layout) return;
+	const update = () => {
+		if (!tree.getClientRects().length) return;
+		// Notices above the layout can place the tree below its sticky offset.
+		// Reserve that space even after document scrolling, so the tree does not
+		// resize and move its rows while the reader scrolls the article.
+		const flowTop = layout.getBoundingClientRect().top + window.scrollY;
+		const stickyTop = parseFloat(getComputedStyle(tree).top) || 0;
+		tree.style.setProperty('--navigation-scrollport-top', `${Math.ceil(Math.max(flowTop, stickyTop))}px`);
+	};
+	const observer = new ResizeObserver(update);
+	for (const element of document.querySelectorAll('.site-top, .site-banners')) observer.observe(element);
+	window.addEventListener('resize', update);
+	window.addEventListener('pageshow', update);
+	void document.fonts.ready.then(update);
+	update();
+};
+
+const setupDisclosures = (reducedMotion: MediaQueryList) => {
+	const finishers = new Set<() => void>();
+	for (const details of document.querySelectorAll<HTMLDetailsElement>(
+		'.navigation-page-disclosure, .navigation-page-sections-disclosure',
+	)) {
+		const summary = details.querySelector<HTMLElement>(':scope > summary');
+		const contentId = summary?.getAttribute('aria-controls');
+		const content = contentId ? document.getElementById(contentId) : null;
+		if (!summary || !content) continue;
+		let animation: Animation | null = null;
+		let destination = details.open;
+		const originallyInert = content.inert;
+		const finish = () => {
+			details.open = destination;
+			animation?.cancel();
+			animation = null;
+			content.inert = originallyInert;
+			content.removeAttribute('data-navigation-motion-active');
+			details.removeAttribute('data-navigation-motion-open');
+			summary.removeAttribute('aria-expanded');
+			finishers.delete(finish);
+		};
+		summary.addEventListener('click', (event) => {
+			if (event.defaultPrevented || reducedMotion.matches || typeof content.animate !== 'function') return;
+			if (event.target instanceof Element && event.target.closest('a')) return;
+			event.preventDefault();
+			const height = isNavigationElementDisplayed(content) ? content.getBoundingClientRect().height : 0;
+			const opacity = height ? getComputedStyle(content).opacity : '0';
+			destination = animation ? !destination : !details.open;
+			animation?.cancel();
+			if (!destination && content.contains(document.activeElement)) summary.focus({ preventScroll: true });
+			details.open = true;
+			const fullHeight = content.getBoundingClientRect().height;
+			content.inert = !destination || originallyInert;
+			content.setAttribute('data-navigation-motion-active', '');
+			details.dataset.navigationMotionOpen = String(destination);
+			summary.setAttribute('aria-expanded', String(destination));
+			animation = content.animate([
+				{ height: `${height}px`, opacity },
+				{ height: `${destination ? fullHeight : 0}px`, opacity: destination ? '1' : '0' },
+			], {
+				duration: 180,
+				easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)',
+				fill: 'both',
+			});
+			animation.onfinish = finish;
+			finishers.add(finish);
+		});
+	}
+	const finishAll = () => {
+		for (const finish of finishers) finish();
+	};
+	reducedMotion.addEventListener('change', () => {
+		if (reducedMotion.matches) finishAll();
+	});
+	window.addEventListener('pagehide', finishAll, { capture: true });
+	// Let filtering and the existing tree controls act on settled disclosure state.
+	for (const event of ['click', 'input']) {
+		document.addEventListener(event, (event) => {
+			if (!(event.target instanceof Element)) return;
+			if (event.target.closest('[data-tree-controls]') || (
+				event.type === 'click' && event.target.closest('a[href]')
+			)) finishAll();
+		}, { capture: true });
+	}
+};
+
+const setupOutlineMarkers = () => {
+	const outlines = [...document.querySelectorAll<HTMLOListElement>('.page-contents-links')];
+	let frame: number | undefined;
+	const update = () => {
+		frame = undefined;
+		for (const outline of outlines) {
+			const current = outline.querySelector<HTMLElement>('a[aria-current="location"]');
+			if (!current || !isNavigationElementDisplayed(current)) {
+				outline.style.setProperty('--navigation-marker-opacity', '0');
+				continue;
+			}
+			const initial = !outline.hasAttribute('data-navigation-marker');
+			outline.setAttribute('data-navigation-marker', '');
+			if (initial) outline.setAttribute('data-navigation-marker-initial', '');
+			const bounds = current.getBoundingClientRect();
+			const style = getComputedStyle(current);
+			const paddingTop = parseFloat(style.paddingTop);
+			const paddingBottom = parseFloat(style.paddingBottom);
+			outline.style.setProperty('--navigation-marker-top', `${bounds.top + paddingTop - outline.getBoundingClientRect().top}px`);
+			outline.style.setProperty('--navigation-marker-height', `${bounds.height - paddingTop - paddingBottom}px`);
+			outline.style.setProperty('--navigation-marker-opacity', '1');
+			if (initial) requestAnimationFrame(() => outline.removeAttribute('data-navigation-marker-initial'));
+		}
+	};
+	const schedule = () => { frame ??= requestAnimationFrame(update); };
+	new MutationObserver(schedule).observe(document.body, {
+		subtree: true,
+		attributes: true,
+		attributeFilter: ['aria-current', 'open', 'hidden'],
+	});
+	const observer = new ResizeObserver(schedule);
+	for (const outline of outlines) observer.observe(outline);
+	window.addEventListener('resize', schedule);
+	window.addEventListener('pageshow', schedule);
+	schedule();
+};
+
+const setupScrollArrival = () => {
+	const root = document.documentElement;
+	const originalHash = location.hash;
+	const scrollBehavior = root.style.scrollBehavior;
+	let interrupted = false;
+	const interrupt = () => { interrupted = true; };
+	for (const event of ['wheel', 'touchstart', 'pointerdown', 'keydown']) {
+		window.addEventListener(event, interrupt, { once: true, passive: true });
+	}
+	const ready = async (restoreHistory: boolean) => {
+		await document.fonts.ready;
+		requestAnimationFrame(() => requestAnimationFrame(() => {
+			if (!restoreHistory && !interrupted && originalHash && location.hash === originalHash) {
+				try {
+					const target = document.getElementById(decodeURIComponent(originalHash.slice(1)));
+					const header = document.querySelector<HTMLElement>('.site-top');
+					if (target) {
+						const offset = Math.ceil(header?.getBoundingClientRect().height ?? 0);
+						window.scrollTo({ top: target.getBoundingClientRect().top + scrollY - offset, behavior: 'instant' });
+					}
+				} catch {
+					// Leave malformed URL fragments to the browser's native handling.
+				}
+			}
+			root.style.scrollBehavior = scrollBehavior;
+			root.setAttribute('data-navigation-motion-ready', '');
+		}));
+	};
+	window.addEventListener('pageswap', () => root.removeAttribute('data-navigation-motion-ready'));
+	window.addEventListener('pageshow', (event) => {
+		if (event.persisted) void ready(true);
+	});
+	const initialReady = () => {
+		const navigation = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined;
+		void ready(navigation?.type === 'back_forward');
+	};
+	if (document.readyState === 'complete') initialReady();
+	else window.addEventListener('load', initialReady, { once: true });
+};
+
+const setupIntentPrefetch = (prefetch: Prefetch) => {
+	const basePath = document.documentElement.dataset.navigationContinuity ?? '/';
+	let timer: number | undefined;
+	let pending: HTMLAnchorElement | null = null;
+	const eligible = (target: EventTarget | null) => {
+		const link = target instanceof Element ? target.closest<HTMLAnchorElement>('a[href]') : null;
+		if (!link || link.hasAttribute('download') || (link.target && link.target !== '_self')) return null;
+		const url = new URL(link.href, location.href);
+		if (url.origin !== location.origin || !url.pathname.startsWith(basePath) || url.search) return null;
+		if (!url.pathname.endsWith('/') || url.pathname === location.pathname) return null;
+		return link;
+	};
+	const cancel = () => {
+		window.clearTimeout(timer);
+		pending = null;
+	};
+	const prepare = (event: Event) => {
+		const link = eligible(event.target);
+		if (link === pending) return;
+		cancel();
+		if (!link) return;
+		pending = link;
+		timer = window.setTimeout(() => {
+			prefetch(link.href);
+		}, 100);
+	};
+	document.addEventListener('pointerover', prepare, { passive: true });
+	document.addEventListener('focusin', prepare);
+	document.addEventListener('pointerout', (event) => {
+		if (pending && !(event.relatedTarget instanceof Node && pending.contains(event.relatedTarget))) cancel();
+	}, { passive: true });
+	document.addEventListener('focusout', cancel);
+	window.addEventListener('pagehide', cancel);
+};
+
+export const setupNavigationContinuity = (prefetch: Prefetch) => {
+	const reducedMotion = matchMedia('(prefers-reduced-motion: reduce)');
+	setupTreeScrollport();
+	setupDisclosures(reducedMotion);
+	setupOutlineMarkers();
+	setupScrollArrival();
+	setupIntentPrefetch(prefetch);
+};

package/src/lib/navigationFollowing.ts

@@ -1,15 +1,7 @@
-const isDisplayed = (element: HTMLElement) => {
-	if (!element.getClientRects().length || getComputedStyle(element).visibility === 'hidden') return false;
-	// Closed native details can retain layout rectangles for their hidden links.
-	for (let parent = element.parentElement; parent; parent = parent.parentElement) {
-		if (parent instanceof HTMLDetailsElement && !parent.open
-			&& !parent.querySelector(':scope > summary')?.contains(element)) return false;
-	}
-	return true;
-};
+import { isNavigationElementDisplayed } from './navigationVisibility';
 
 const visibleEntry = (link: HTMLElement, container: HTMLElement): HTMLElement | undefined => {
-	if (isDisplayed(link)) return link;
+	if (isNavigationElementDisplayed(link)) return link;
 
 	let node = link.closest<HTMLElement>('.navigation-page-node');
 	while (node && container.contains(node)) {
@@ -18,7 +10,7 @@ const visibleEntry = (link: HTMLElement, container: HTMLElement): HTMLElement |
 			':scope > .navigation-page-open-link',
 			':scope > .navigation-category-disclosure > summary',
 		].join(', '));
-		if (entry && isDisplayed(entry)) return entry;
+		if (entry && isNavigationElementDisplayed(entry)) return entry;
 		node = node.parentElement?.closest<HTMLElement>('.navigation-page-node') ?? null;
 	}
 	return undefined;
@@ -33,7 +25,7 @@ const revealEntry = (container: HTMLElement, entry: HTMLElement) => {
 	for (const control of container.querySelectorAll<HTMLElement>(
 		'.navigation-tree-controls, .mobile-nav-panel-actions',
 	)) {
-		if (isDisplayed(control) && getComputedStyle(control).position === 'sticky') {
+		if (isNavigationElementDisplayed(control) && getComputedStyle(control).position === 'sticky') {
 			top = Math.max(top, control.getBoundingClientRect().bottom);
 		}
 	}
@@ -49,14 +41,15 @@ const revealEntry = (container: HTMLElement, entry: HTMLElement) => {
 };
 
 export const setupNavigationFollowing = () => {
+	const areaNavigation = document.documentElement.hasAttribute('data-area-navigation');
 	const left = document.querySelector<HTMLElement>('.tree-local-navigation');
-	const right = document.querySelector<HTMLElement>('.page-contents-navigation-rail');
 	const compact = document.querySelector<HTMLElement>('[data-compact-navigation-panel]');
-	const states = [left, right, compact]
+	const states = [left, compact]
 		.filter((container): container is HTMLElement => container !== null)
 		.map((container) => ({
 			container,
 			paused: false,
+			arrivalPaused: areaNavigation,
 			pointerDown: false,
 			expectedScrollTop: container.scrollTop,
 			ancestor: undefined as HTMLElement | undefined,
@@ -67,7 +60,7 @@ export const setupNavigationFollowing = () => {
 		const { container } = state;
 		state.ancestor?.removeAttribute('data-reading-position-ancestor');
 		state.ancestor = undefined;
-		if (!isDisplayed(container)) return;
+		if (!isNavigationElementDisplayed(container)) return;
 		if (container.matches('[data-tree-filter-active="true"]')
 			|| container.querySelector('[data-tree-filter-active="true"]')) return;
 
@@ -86,11 +79,10 @@ export const setupNavigationFollowing = () => {
 
 	const update = () => {
 		frame = undefined;
-		const selected = right && isDisplayed(right) ? right : left;
 		for (const state of states) {
 			const ownsFocus = state.container.contains(document.activeElement);
-			updateContainer(state, state.container === selected
-				&& !state.paused && !state.pointerDown && !ownsFocus
+			updateContainer(state, state.container === left
+				&& !state.paused && !state.arrivalPaused && !state.pointerDown && !ownsFocus
 				&& !document.querySelector('.mobile-nav-menu[open]'));
 		}
 	};
@@ -122,6 +114,24 @@ export const setupNavigationFollowing = () => {
 	document.addEventListener('pointerup', releasePointer);
 	document.addEventListener('pointercancel', releasePointer);
 	window.addEventListener('blur', releasePointer);
+	if (areaNavigation) {
+		// A restored menu may deliberately be scrolled away from the current
+		// heading. Resume following when the reader acts outside navigation,
+		// not when native history/hash restoration emits a window scroll.
+		const resumeAfterArrival = (event: Event) => {
+			if (event.target instanceof Node && states.some(({ container }) => container.contains(event.target as Node))) return;
+			states.forEach((state) => { state.arrivalPaused = false; state.paused = false; });
+			// A wheel gesture at the document's end may not emit scroll. Resume
+			// the outline after that real input too, without moving the document.
+			schedule();
+		};
+		for (const type of ['wheel', 'touchstart', 'pointerdown', 'keydown']) {
+			window.addEventListener(type, resumeAfterArrival, { passive: true });
+		}
+		const pauseArrival = () => states.forEach((state) => { state.arrivalPaused = true; });
+		window.addEventListener('popstate', pauseArrival);
+		window.addEventListener('pageshow', (event) => { if (event.persisted) pauseArrival(); });
+	}
 	window.addEventListener('scroll', () => {
 		states.forEach((state) => { state.paused = false; });
 		// Section tracking schedules its own update for the new document position.

package/src/lib/navigationState.mjs

@@ -0,0 +1,88 @@
+/**
+ * @typedef {{ openPaths: string[], sectionOpenByPath: Record<string, boolean> }} DisclosureState
+ * @typedef {DisclosureState & { scrollTop: number }} NavigationState
+ * @typedef {{ pagePath?: string, currentBranch?: string, currentPage?: string }} BranchData
+ * @typedef {{ onArrival?: boolean, preserveCurrentPage?: boolean, preserveCurrentOutline?: boolean }} DisclosurePolicy
+ */
+
+// Keep this factory self-contained: the early inline script embeds its source,
+// while the deferred runtime calls it as a normal module. No imported or outer
+// values may be referenced inside it.
+export function createNavigationStateHelpers() {
+	/** @param {'desktop' | 'mobile'} scope @param {string} root @param {string} sharedRoot */
+	const storageKeys = (scope, root = '/', sharedRoot = root) => ({
+		stateKey: `norna:tree-navigation:${scope}:${root}`,
+		sharedStateKey: `norna:tree-navigation:shared:${sharedRoot}`,
+	});
+	/** @param {string | null} value @returns {NavigationState} */
+	const parseState = (value) => {
+		try {
+			const parsedState = JSON.parse(value ?? '{}');
+			return {
+				openPaths: Array.isArray(parsedState.openPaths) ? parsedState.openPaths : [],
+				sectionOpenByPath: parsedState.sectionOpenByPath
+					&& typeof parsedState.sectionOpenByPath === 'object'
+					? Object.fromEntries(Object.entries(parsedState.sectionOpenByPath)
+						.filter((entry) => typeof entry[1] === 'boolean'))
+					: {},
+				scrollTop: Number.isFinite(Number(parsedState.scrollTop)) ? Number(parsedState.scrollTop) : 0,
+			};
+		} catch {
+			return { openPaths: [], sectionOpenByPath: {}, scrollTop: 0 };
+		}
+	};
+	/** @param {string | null} localSource @param {string | null} sharedSource @param {string | null} entrySource */
+	const initialState = (localSource, sharedSource, entrySource = null) => {
+		if (entrySource !== null) {
+			const entry = parseState(entrySource);
+			return { local: entry, disclosure: entry, hasSavedState: true, fromEntry: true };
+		}
+		const local = parseState(localSource);
+		return {
+			local,
+			// An existing invalid shared record is empty, not a local fallback.
+			disclosure: sharedSource === null ? local : parseState(sharedSource),
+			hasSavedState: localSource !== null || sharedSource !== null,
+			fromEntry: false,
+		};
+	};
+	const arrivalPolicy = (state) => ({ onArrival: !state.fromEntry });
+	// Keep snapshots per history entry. Only the identity goes
+	// into history.state: scrolling must not repeatedly call replaceState.
+	let activeEntry = null;
+	const currentEntry = () => {
+		const entry = history.state?.nornaAreaNavigationEntry;
+		return entry?.url === location.href && typeof entry.id === 'string'
+			? entry : null;
+	};
+	const readEntryState = (stateKey) => {
+		activeEntry = currentEntry();
+		return activeEntry === null ? null : sessionStorage.getItem(`${stateKey}:entry:${activeEntry.id}`);
+	};
+	const saveEntryState = (stateKey, state) => {
+		// WebKit can expose the destination's history.state during the departing
+		// document's pagehide. Save into this document's remembered entry instead
+		// of replacing the destination's identity. Traversal reads and hash changes
+		// select a new entry while the document is active.
+		if (activeEntry?.url !== location.href) activeEntry = currentEntry();
+		if (activeEntry === null) {
+			activeEntry = { url: location.href, id: `${Date.now()}-${Math.random().toString(36).slice(2)}` };
+			history.replaceState({ ...history.state, nornaAreaNavigationEntry: activeEntry }, '');
+		}
+		sessionStorage.setItem(`${stateKey}:entry:${activeEntry.id}`, JSON.stringify(state));
+	};
+	/** @param {DisclosureState} state @param {BranchData} branch @param {DisclosurePolicy} policy */
+	const pageIsOpen = (state, branch, policy = {}) => (
+		(Boolean(policy.onArrival) && branch.currentBranch === 'true'
+			&& (!policy.preserveCurrentPage || branch.currentPage !== 'true'))
+		|| state.openPaths.includes(branch.pagePath ?? '')
+	);
+	/** @param {DisclosureState} state @param {BranchData} branch @param {DisclosurePolicy} policy */
+	const sectionsAreOpen = (state, branch, policy = {}) => {
+		const storedOpen = state.sectionOpenByPath[branch.pagePath ?? ''];
+		if (policy.onArrival && branch.currentPage === 'true'
+			&& !(policy.preserveCurrentOutline && typeof storedOpen === 'boolean')) return true;
+		return typeof storedOpen === 'boolean' ? storedOpen : branch.currentPage === 'true';
+	};
+	return { storageKeys, parseState, initialState, arrivalPolicy, readEntryState, saveEntryState, pageIsOpen, sectionsAreOpen };
+}

package/src/lib/navigationStateScript.mjs

@@ -0,0 +1,76 @@
+import { createNavigationStateHelpers } from './navigationState.mjs';
+
+// Serialized into a parser-time script. Like the helpers, this entry point must
+// only reference its arguments and browser globals, never module-scope values.
+function restoreEarlyNavigationState(createHelpers) {
+	// Restore branches as the parser adds them, before they can be painted.
+	// pagereveal may precede this tree and is unavailable in some browsers.
+	const script = document.currentScript;
+	const container = script?.parentElement;
+	if (!container?.hasAttribute('data-navigation-root')) return;
+	const scope = script.dataset.navigationStateScope;
+	const { storageKeys, initialState, arrivalPolicy, readEntryState, pageIsOpen, sectionsAreOpen } = createHelpers();
+	const initialized = new WeakSet();
+	const restore = (refresh = false) => {
+		try {
+			// Establish the scroll limit before restoring a position near its end.
+			if (scope === 'desktop' && container.parentElement) {
+				const flowTop = container.parentElement.getBoundingClientRect().top + window.scrollY;
+				const stickyTop = parseFloat(getComputedStyle(container).top) || 0;
+				container.style.setProperty('--navigation-scrollport-top', `${Math.ceil(Math.max(flowTop, stickyTop))}px`);
+			}
+			const { stateKey, sharedStateKey } = storageKeys(scope,
+				container.dataset.navigationRoot, container.dataset.navigationStateRoot);
+			const state = initialState(sessionStorage.getItem(stateKey), sessionStorage.getItem(sharedStateKey),
+				readEntryState(stateKey));
+			const policy = arrivalPolicy(state);
+			for (const branch of container.querySelectorAll('.navigation-page-disclosure[data-page-path]')) {
+				if (!refresh && initialized.has(branch)) continue;
+				branch.open = pageIsOpen(state.disclosure, branch.dataset, policy);
+				initialized.add(branch);
+			}
+			for (const branch of container.querySelectorAll('.navigation-page-sections-disclosure[data-page-path]')) {
+				if (!refresh && initialized.has(branch)) continue;
+				branch.open = sectionsAreOpen(state.disclosure, branch.dataset, policy);
+				initialized.add(branch);
+			}
+			let scrollContainer = container;
+			for (let candidate = container; candidate; candidate = candidate.parentElement) {
+				if (/auto|scroll/.test(getComputedStyle(candidate).overflowY)) {
+					scrollContainer = candidate;
+					break;
+				}
+			}
+			if (state.local.scrollTop > 0 || state.fromEntry) scrollContainer.scrollTop = Math.max(0, state.local.scrollTop);
+			if (scope === 'desktop' && !state.fromEntry && state.local.scrollTop <= 0) {
+				// A direct arrival in a short viewport can put the selected page
+				// below the fold. Reveal its title now, before heading following is
+				// paused. An already visible title or restored position stays put.
+				const node = container.querySelector('[data-navigation-current-page="true"]');
+				const link = node?.querySelector(':scope > .navigation-page-link, :scope > .navigation-page-open-link');
+				if (link && link.getBoundingClientRect().width > 0) {
+					const box = scrollContainer.getBoundingClientRect();
+					const controls = container.querySelector('[data-tree-controls]')?.getBoundingClientRect();
+					const top = Math.max(box.top, controls?.bottom ?? box.top) + 12;
+					const bottom = box.bottom - 16;
+					const row = link.getBoundingClientRect();
+					if (row.top < top) scrollContainer.scrollTop += row.top - top;
+					else if (row.bottom > bottom) scrollContainer.scrollTop += row.bottom - bottom;
+				}
+			}
+		} catch {
+			// Ordinary links and native details remain usable without storage.
+		}
+	};
+	restore();
+	const observer = new MutationObserver(() => restore());
+	observer.observe(container, { childList: true, subtree: true });
+	document.addEventListener('DOMContentLoaded', () => {
+		restore();
+		observer.disconnect();
+	}, { once: true });
+	// Reapply before a transition snapshot, including a cached history entry.
+	window.addEventListener('pagereveal', () => restore(true));
+}
+
+export const getNavigationStateScript = () => `(${restoreEarlyNavigationState.toString()})(${createNavigationStateHelpers.toString()});`;

package/src/lib/navigationVisibility.ts

@@ -0,0 +1,9 @@
+export const isNavigationElementDisplayed = (element: HTMLElement) => {
+	if (!element.getClientRects().length || getComputedStyle(element).visibility === 'hidden') return false;
+	// Closed native details can retain layout rectangles for their hidden links.
+	for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+		if (parent instanceof HTMLDetailsElement && !parent.open
+			&& !parent.querySelector(':scope > summary')?.contains(element)) return false;
+	}
+	return true;
+};

package/src/lib/pageThemes.ts

@@ -1,44 +1,7 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import {
-	validatePageThemeYamlStructure,
-} from '../../scripts/lib/site-content.mjs';
-import { pageThemeSchema } from '../../scripts/lib/schema-definitions.mjs';
-import { sitePagesDir, sitePagesLabel } from '../../scripts/lib/site-paths.mjs';
-import { mergePageThemeConfig } from '../../scripts/lib/theme-presets.mjs';
-import { parseYamlConfig } from '../../scripts/lib/yaml-config.mjs';
-import { getPageDirectoryAncestors } from '../../scripts/lib/page-model.mjs';
+import { selectPageTheme } from '../../scripts/lib/theme-packages.mjs';
+import { siteDir } from '../../scripts/lib/site-paths.mjs';
 
-type PageTheme = {
-	id: string;
-	data: Record<string, unknown>;
-};
-
-export const getPageTheme = async (pageDirectory: string | null): Promise<PageTheme | null> => {
-	if (!pageDirectory) return null;
-
-	const pageAncestors = getPageDirectoryAncestors(pageDirectory);
-	let inheritedData: Record<string, unknown> = {};
-	const inheritedIds: string[] = [];
-	for (const pageAncestor of pageAncestors) {
-		const themeSegments = pageAncestor.split('/');
-		const themePath = path.join(sitePagesDir, ...themeSegments, 'theme.yaml');
-		const source = await readFile(themePath, 'utf8').catch((error) => {
-			if (error?.code === 'ENOENT') return null;
-			throw error;
-		});
-		if (!source) continue;
-		const themeLabel = `${sitePagesLabel}/${themeSegments.join('/')}/theme.yaml`;
-
-		const data = parseYamlConfig(source, themeLabel, {
-			schema: pageThemeSchema,
-			validateStructure: validatePageThemeYamlStructure,
-		});
-		inheritedData = mergePageThemeConfig(inheritedData, data);
-		inheritedIds.push(`pages/${themeSegments.join('/')}/theme`);
-	}
-
-	return inheritedIds.length > 0
-		? { id: inheritedIds.join(' + '), data: inheritedData }
-		: null;
+export const getPageTheme = async (pageDirectory: string) => {
+	const { selected } = await selectPageTheme({ siteRoot: siteDir, pageDirectory });
+	return { id: selected.label, data: selected.config };
 };

package/src/lib/sectionContent.ts

@@ -1,3 +1,4 @@
+import { getPageImageSourceKey } from '../../scripts/lib/site-conventions.mjs';
 import { markdownToHtml } from 'satteri';
 import { groupRenderedTabs } from '../../scripts/lib/content-tabs.mjs';
 import projectConfig from '../../scripts/lib/project-config.mjs';
@@ -111,7 +112,7 @@ const applyH3HeadingIds = (
 	return result;
 };
 
-const getImageSourceKey = (page: SitePage, image: string) => `pages/${page.pageDirectory}/images/${image}`;
+const getImageSourceKey = (page: SitePage, image: string) => getPageImageSourceKey(page.pageDirectory, image);
 
 const renderHeadingTitleHtml = async (headingSource: string) => {
 	const headingMarkdown = headingSource
@@ -178,7 +179,7 @@ const resolveContentBlocks = async (
 		}
 		if (block.type === 'page-list') {
 			if (childPages.length === 0) {
-				throw new Error(`${page.contentLabel} line ${block.line}: page-list has no listed direct child pages to display. Navigation categories are not pages. Add a listed direct child page or remove the block.`);
+				throw new Error(`${page.contentLabel} line ${block.line}: page-list has no listed direct child pages to display. Add a listed direct child page or remove the block.`);
 			}
 			resolvedBlocks.push({
 				type: 'page-list',

package/src/lib/siteNavigation.ts

@@ -7,6 +7,12 @@ import {
 	getSequentialPageNavigation as getSequentialPageNavigationShared,
 } from '../../scripts/lib/site-navigation-tree.mjs';
 
+export type CategoryDestinationMap = ReadonlyMap<string, { target: SitePage | null }>;
+
+export const getNavigationDestination = (node: SiteNode, categoryDestinations?: CategoryDestinationMap): SiteNode => (
+	categoryDestinations?.get(node.pathname)?.target ?? node
+);
+
 export type SiteNavigationEntry = {
 	node: SiteNode;
 	headings: HeadingNavigation[];