@janga/norna 0.7.27 → 0.7.28

package/src/content.config.ts

@@ -1,31 +1,33 @@
 import { defineCollection } from 'astro:content';
 import { glob } from 'astro/loaders';
 import { z } from 'astro/zod';
-import { basename } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
-	siteDir,
+	siteHomePageDir,
 	siteDirLabel,
 	siteThemePath,
 	sitewideContentPath,
 } from '../scripts/lib/site-paths.mjs';
 import { encodePageEntryId, getSiteEntryPrefix, parsePageDirectoryPath } from '../scripts/lib/page-model.mjs';
+import { homePageDirectory } from '../scripts/lib/site-conventions.mjs';
 import {
 	siteSchema,
 	sitewideSchema,
-	themeVisualSchema,
+	rootThemeSchema,
 } from '../scripts/lib/schema-definitions.mjs';
 
 const siteEntryPrefix = getSiteEntryPrefix(siteDirLabel);
 const emptyYamlMapping = (value: unknown) => value ?? {};
-const siteThemeSchema = z.preprocess(emptyYamlMapping, themeVisualSchema);
+const siteThemeSchema = z.preprocess(emptyYamlMapping, rootThemeSchema);
 const sitewideContentSchema = z.preprocess(emptyYamlMapping, sitewideSchema);
 
 const site = defineCollection({
 	loader: glob({
-		pattern: 'pages/**/content.md',
-		base: pathToFileURL(siteDir),
+		pattern: ['content.md', 'pages/**/content.md'],
+		base: pathToFileURL(siteHomePageDir),
 		generateId: ({ entry }) => {
+			if (entry === 'content.md') return encodePageEntryId(siteDirLabel, homePageDirectory);
 			const pageEntryDirectory = entry.split('/').slice(1, -1).join('/');
 			const pageDirectory = pageEntryDirectory
 				.split('/')
@@ -40,7 +42,7 @@ const site = defineCollection({
 const theme = defineCollection({
 	loader: glob({
 		pattern: basename(siteThemePath),
-		base: pathToFileURL(siteDir),
+		base: pathToFileURL(dirname(siteThemePath)),
 		generateId: () => `${siteEntryPrefix}-theme`,
 	}),
 	schema: siteThemeSchema,
@@ -49,7 +51,7 @@ const theme = defineCollection({
 const sitewide = defineCollection({
 	loader: glob({
 		pattern: basename(sitewideContentPath),
-		base: pathToFileURL(siteDir),
+		base: pathToFileURL(dirname(sitewideContentPath)),
 		generateId: () => `${siteEntryPrefix}-sitewide`,
 	}),
 	schema: sitewideContentSchema,

package/src/layouts/BaseLayout.astro

@@ -5,6 +5,8 @@ import { getPresentationCssVariables } from '../../scripts/lib/presentation.mjs'
 import { getIconLinks, getSocialImageAsset } from '../lib/sitePublicAssets';
 import { withBasePath } from '../lib/basePath';
 import { getReaderPreferencesScript } from '../lib/readerPreferencesScript.mjs';
+import NavigationContinuity from '../components/NavigationContinuity.astro';
+import areaNavigationStyles from '../styles/area-navigation.css?inline';
 import '../styles/global.css';
 
 type FrameColors = {
@@ -80,6 +82,8 @@ interface Props {
 	contentsNavigation?: boolean;
 	indexable?: boolean;
 	searchable?: boolean;
+	areaNavigation?: boolean;
+	areaReadingFrame?: boolean;
 }
 
 const {
@@ -93,6 +97,8 @@ const {
 	contentsNavigation = false,
 	indexable = true,
 	searchable = false,
+	areaNavigation = false,
+	areaReadingFrame = false,
 } = Astro.props;
 
 const documentTitle = title;
@@ -150,49 +156,13 @@ const marginNoteOuterReserve = '0.5rem';
 const marginNoteDeclarations = marginNoteLayoutDeclarations;
 const marginNoteLayoutCss = [
 	'@media (min-width: 1101px) {',
-	...marginNoteReadingWidths.flatMap(([readingWidth, textWidth]) => [
-		[
-			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap})) {`,
-			`:root[data-reading-width="${readingWidth}"] .site-page-layout:not(.site-page-layout-tree) .section-note-paragraph {`,
-				marginNoteDeclarations,
-			'}',
-		'}',
-		].join('\n'),
-		[
-			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap} + ${marginNoteOuterReserve} - 11rem - ${visualTheme.layout.localNavigationGap})) {`,
-			`:root[data-reader-preferences-ready="true"][data-reading-width="${readingWidth}"][data-focus-reading="on"] .site-page-layout-tree .section-note-paragraph {`,
-				marginNoteDeclarations,
-			'}',
-		'}',
-		].join('\n'),
-	]),
-	'}',
-	'@media (min-width: 1101px) and (max-width: 1280px) {',
 	...marginNoteReadingWidths.map(([readingWidth, textWidth]) => [
 		`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap} + ${marginNoteOuterReserve})) {`,
-		`:root[data-reading-width="${readingWidth}"] .site-page-layout-tree:not(.site-page-layout-contents) .section-note-paragraph {`,
-			marginNoteDeclarations,
-		'}',
-	'}',
-	].join('\n')),
-	'}',
-	'@media (min-width: 1281px) {',
-	...marginNoteReadingWidths.flatMap(([readingWidth, textWidth]) => [
-		[
-			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap})) {`,
-			`:root[data-reading-width="${readingWidth}"] .site-page-layout-tree.site-page-layout-contents .section-note-paragraph {`,
-				marginNoteDeclarations,
-			'}',
+		`:root[data-reading-width="${readingWidth}"] .section-note-paragraph {`,
+		marginNoteDeclarations,
 		'}',
-		].join('\n'),
-		[
-			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap} + ${marginNoteOuterReserve} - 11rem - ${visualTheme.layout.localNavigationGap})) {`,
-			`:root[data-reading-width="${readingWidth}"] .site-page-layout-tree:not(.site-page-layout-contents) .section-note-paragraph {`,
-				marginNoteDeclarations,
-			'}',
 		'}',
-		].join('\n'),
-	]),
+	].join('\n')),
 	'}',
 ].join('\n');
 const { buildInfo, copyrightMessage } = footer ?? {};
@@ -227,6 +197,9 @@ const readerPreferencesScript = readerPreferencesEnabled
 	data-reading-width={presentation.readerPreferences.defaults.readingWidth}
 	data-focus-reading={presentation.readerPreferences.defaults.focusReading}
 	data-section-tracking={contentsNavigation ? 'enabled' : undefined}
+	data-navigation-continuity={projectConfig.site.basePath}
+	data-area-navigation={areaNavigation ? '' : undefined}
+	data-area-reading-frame={areaReadingFrame ? '' : undefined}
 	data-pagefind-ignore={searchable ? undefined : 'all'}
 	style={documentStyle}
 >
@@ -248,6 +221,8 @@ const readerPreferencesScript = readerPreferencesEnabled
 		{indexable && socialImageUrl && <meta name="twitter:image" content={socialImageUrl} />}
 		<meta name="theme-color" content={presentation.palette.page.backgroundColor} />
 		{readerPreferencesScript && <script is:inline set:html={readerPreferencesScript} />}
+		<NavigationContinuity />
+		{areaNavigation && <style is:inline set:html={areaNavigationStyles} />}
 		<style is:inline set:html={marginNoteLayoutCss} />
 		{indexable && <link rel="canonical" href={canonicalUrl} />}
 		<meta name="generator" content={Astro.generator} />
@@ -272,5 +247,6 @@ const readerPreferencesScript = readerPreferencesEnabled
 				</p>
 			</footer>
 		)}
+		<span id="norna-navigation-ready" hidden></span>
 	</body>
 </html>

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 };
+}