@janga/norna 0.7.27 → 0.7.28

package/src/components/SiteNavigation.astro

@@ -1,18 +1,24 @@
 ---
+import NavigationState from './NavigationState.astro';
 import { Menu, Search, X } from '@lucide/astro';
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { withBasePath } from '../lib/basePath';
 import type { SectionNavigation } from '../lib/sectionContent';
 import {
 	getListedSiteNavigationTree,
+	getNavigationDestination,
+	type CategoryDestinationMap,
 	type SiteNavigationEntry,
-	type SiteNavigationNode,
 } from '../lib/siteNavigation';
 import type { SiteNode } from '../lib/sitePages';
 import DisplaySettings from './DisplaySettings.astro';
 import NavigationPageTree from './NavigationPageTree.astro';
 import NavigationTreeControls from './NavigationTreeControls.astro';
 import TopPageMenu from './TopPageMenu.astro';
+import AreaNavigationMenu from './AreaNavigationMenu.astro';
+import AreaNavigationSwitcher from './AreaNavigationSwitcher.astro';
+import SiteBreadcrumbs from './SiteBreadcrumbs.astro';
+import { hasLargeAreaMenu, withH2Outlines } from '../lib/areaNavigation';
 import SectionNavigationScript from './SectionNavigationScript.astro';
 import SearchNavigationScript from './SearchNavigationScript.astro';
 
@@ -29,6 +35,7 @@ interface Props {
 	};
 	currentPage?: SiteNode;
 	navigationEntries: SiteNavigationEntry[];
+	categoryDestinations?: CategoryDestinationMap;
 	navigationMode: 'sections' | 'top' | 'tree';
 	showTopNavigationSubmenus: boolean;
 	hasNavigationRailFrame: boolean;
@@ -46,18 +53,21 @@ interface Props {
 		};
 	};
 	searchPage?: boolean;
+	areaReadingFrame?: boolean;
 }
 
 const {
 	logo,
 	currentPage,
 	navigationEntries,
+	categoryDestinations,
 	navigationMode,
 	showTopNavigationSubmenus,
 	hasNavigationRailFrame,
 	frameColors,
 	readerPreferences,
 	searchPage = false,
+	areaReadingFrame = false,
 } = Astro.props;
 const siteTopBackgroundColor = frameColors.backgroundColor === 'transparent'
 	? 'var(--color-page)'
@@ -68,12 +78,7 @@ const navigationStyle = [
 	...(logo?.height ? [`--site-brand-logo-height: ${logo.height}`] : []),
 ].join('; ');
 const siteNavigationTree = getListedSiteNavigationTree(navigationEntries);
-const mobileNavigationTree = navigationMode === 'top'
-	? getListedSiteNavigationTree(navigationEntries.map((entry) => ({
-		...entry,
-		headings: entry.headings.filter((heading) => heading.depth === 2),
-	})))
-	: siteNavigationTree;
+const mobileNavigationTree = withH2Outlines(siteNavigationTree);
 const topLevelNavigation = siteNavigationTree;
 const showSiteNavigation = topLevelNavigation.some(({ node }) => !node.isHome);
 const homeNode = navigationEntries.find(({ node }) => node.isHome)?.node;
@@ -88,7 +93,6 @@ const isCurrentBranch = (node: SiteNode) => Boolean(currentPage && (
 	|| currentPage.pageDirectory.startsWith(`${node.pageDirectory}/pages/`)
 ));
 const pageHref = (page: SiteNode) => withBasePath(projectConfig.site.basePath, page.pathname);
-const getNavigationPage = (node: SiteNavigationNode) => node.node;
 const hasSectionMenu = (pageSections: SectionNavigation[]) => pageSections.length > 1;
 const showSinglePageTopLink = !showSiteNavigation;
 const currentPageSectionCount = currentPageNavigation?.sections.length ?? 0;
@@ -131,35 +135,41 @@ const needsNavigationScript = showMobileNavigation || hasCurrentPageSectionMenu
 >
 	{showNavigationRow && (
 		<div class:list={['site-nav-row', { 'site-nav-row-mobile-only': !showDesktopNavigationRow }]}>
-			{logo && (
+			{(logo || areaReadingFrame) && (
 				<div class="site-nav-leading">
-					<a class="site-brand" href={pageHref(homePage)}>
-						<img class="site-brand-logo" src={withBasePath(projectConfig.site.basePath, logo.src)} alt={logo.alt} />
+					<a class="site-brand" href={pageHref(homePage)} aria-label={projectConfig.locale.labels.returnHome} title={projectConfig.locale.labels.returnHome}>
+						{logo ? <img class="site-brand-logo" src={withBasePath(projectConfig.site.basePath, logo.src)} alt={logo.alt} /> : homePage.title}
 					</a>
 				</div>
 			)}
 
 			<div class="site-nav-actions">
-				{showSiteNavigation && (
+				{showSiteNavigation && !areaReadingFrame && (
 					<nav class="site-nav" aria-label={projectConfig.locale.labels.siteNavigation}>
 					<ul>
 					{topLevelNavigation.map((navigationNode) => {
-						const destination = getNavigationPage(navigationNode);
+						const destination = getNavigationDestination(navigationNode.node, categoryDestinations);
 						if (!destination) return null;
 						const nodeIsCurrentPage = isCurrentPage(navigationNode.node);
+						const useAreaMenu = navigationMode === 'tree';
 						return (
 							<li class:list={['site-nav-item', {
-								'site-nav-item-current-branch': !nodeIsCurrentPage && isCurrentBranch(navigationNode.node),
+								'site-nav-item-current-branch': (!nodeIsCurrentPage || useAreaMenu) && isCurrentBranch(navigationNode.node),
 							}]}>
-								<a href={pageHref(destination)} aria-current={nodeIsCurrentPage ? 'page' : undefined}>
+								{useAreaMenu && navigationNode.children.length > 0 && !hasLargeAreaMenu(navigationNode) ? <AreaNavigationMenu
+									node={navigationNode}
+									currentPage={currentPage}
+									categoryDestinations={categoryDestinations}
+								/> : <a href={pageHref(destination)} aria-current={nodeIsCurrentPage ? 'page' : undefined}>
 									{navigationNode.node.title}
-								</a>
-								<TopPageMenu
+								</a>}
+								{!useAreaMenu && <TopPageMenu
 									node={navigationNode}
 									currentPage={currentPage}
+									categoryDestinations={categoryDestinations}
 									showSections={navigationMode === 'top'}
 									showChildren={showTopNavigationSubmenus}
-								/>
+								/>}
 							</li>
 						);
 					})}
@@ -211,9 +221,10 @@ const needsNavigationScript = showMobileNavigation || hasCurrentPageSectionMenu
 								</div>
 								<div
 									class="mobile-site-nav"
-									data-navigation-root={pageHref(homePage)}
-									data-navigation-state-root={pageHref(homePage)}
+									data-navigation-root={`area:${pageHref(homePage)}`}
+									data-navigation-state-root={`area:${pageHref(homePage)}`}
 								>
+									<NavigationState scope="mobile" />
 									{showSiteNavigation && (
 										<nav class="mobile-nav-view" aria-label={projectConfig.locale.labels.siteNavigation}>
 											<h2 tabindex="-1">{projectConfig.locale.labels.siteNavigation}</h2>
@@ -224,6 +235,7 @@ const needsNavigationScript = showMobileNavigation || hasCurrentPageSectionMenu
 											<NavigationPageTree
 												nodes={mobileNavigationTree}
 												currentPage={currentPage}
+												categoryDestinations={categoryDestinations}
 												variant="mobile"
 												integratePageSections={navigationMode === 'tree' || navigationMode === 'top'}
 											/>
@@ -260,6 +272,19 @@ const needsNavigationScript = showMobileNavigation || hasCurrentPageSectionMenu
 						</details>
 					)}
 			</div>
+			{areaReadingFrame && (
+				<div class="site-reading-location">
+					<AreaNavigationSwitcher
+						nodes={siteNavigationTree}
+						currentPage={currentPage}
+						categoryDestinations={categoryDestinations}
+						label={searchPage ? projectConfig.locale.labels.search : undefined}
+					/>
+					{currentPage
+						? <SiteBreadcrumbs currentPage={currentPage} nodes={navigationEntries.map(({ node }) => node)} />
+						: <span class="site-reading-location-label">{projectConfig.locale.labels.search}</span>}
+				</div>
+			)}
 		</div>
 	)}
 

package/src/components/SitePage.astro

@@ -9,7 +9,6 @@ import ImageStackEnhancement from './ImageStackEnhancement.astro';
 import SiteBreadcrumbs from './SiteBreadcrumbs.astro';
 import SiteNavigation from './SiteNavigation.astro';
 import SiteBanners from './SiteBanners.astro';
-import PageContentsNavigation from './PageContentsNavigation.astro';
 import PageSequenceNavigation from './PageSequenceNavigation.astro';
 import SiteSection from './SiteSection.astro';
 import SiteTreeNavigation from './SiteTreeNavigation.astro';
@@ -22,47 +21,37 @@ import {
 	flattenSiteNavigationTree,
 	getDirectChildPages,
 	getListedSiteNavigationTree,
+	getNavigationDestination,
 	getSequentialPageNavigation,
 } from '../lib/siteNavigation';
 import { getToday, isVisibleToday } from '../lib/visibility';
 import { getLogoAsset } from '../lib/sitePublicAssets';
 import {
 	resolveNavigationModel,
-	resolvePageContentsPlacement,
 } from '../../scripts/lib/navigation-model.mjs';
 import { projectConfig, resolveThemeVisualConfig } from '../../scripts/lib/project-config.mjs';
 import { resolveEditSourceTarget } from '../../scripts/lib/edit-source-link.mjs';
 import { getTextWidthCssValue, resolveFrameColors, resolvePagePresentation } from '../../scripts/lib/presentation.mjs';
-import { mergePageThemeConfig } from '../../scripts/lib/theme-presets.mjs';
 
 type SiteEntry = CollectionEntry<'site'>;
 
 interface Props {
 	entry?: SiteEntry;
-	categoryPath?: string;
 }
 
-const { entry, categoryPath } = Astro.props;
+const { entry } = Astro.props;
 const siteDirectory = (process.env.NORNA_SITE_DIR ?? 'site').trim();
 const siteModel = await getSiteModel(await getCollection('site'));
+const categoryDestinations = siteModel.categoryDestinations.byPathname;
 const { nodes: siteNodes, pages: sitePages } = siteModel;
-const categoryDestination = categoryPath ? siteModel.categoryDestinations.byPathname.get(categoryPath) : null;
-const currentPage = categoryDestination?.category
-	?? sitePages.find((page) => page.entry.id === entry?.id);
-if (!currentPage) throw new Error(`Page entry "${entry?.id ?? categoryPath}" is missing from the site page model.`);
-const [siteTheme] = await getCollection('theme');
-if (!siteTheme) {
-	throw new Error('site/theme.yaml is required. Add a root theme before building the site.');
-}
+const currentPage = sitePages.find((page) => page.entry.id === entry?.id);
+if (!currentPage) throw new Error(`Page entry "${entry?.id}" is missing from the site page model.`);
 const [sitewide] = await getCollection('sitewide');
 const sitewideData = sitewide?.data ?? {};
 const homePage = sitePages.find((page) => page.isHome) ?? currentPage;
-const siteThemeData = siteTheme.data;
 const pageTheme = await getPageTheme(currentPage.pageDirectory);
-const themeData = mergePageThemeConfig(siteThemeData, pageTheme?.data);
-const themeLabel = pageTheme
-	? `${siteDirectory || 'site'}/${pageTheme.id}`
-	: `${siteDirectory || 'site'}/${siteTheme.id}`;
+const themeData = pageTheme.data;
+const themeLabel = pageTheme.id;
 const visualTheme = resolveThemeVisualConfig(themeData, themeLabel);
 const logoAsset = getLogoAsset();
 const logoSettings = sitewideData.logo;
@@ -99,20 +88,20 @@ const renderedNavigationEntries = flattenSiteNavigationTree(listedNavigationTree
 const pageSequence = getSequentialPageNavigation(listedNavigationTree, currentPage.pagePath);
 const childPages = getDirectChildPages(listedNavigationTree, currentPage.pagePath);
 const siteHtml = entry?.rendered?.html ?? '';
-const resolvedSections: ResolvedSection[] = categoryDestination ? [{
-	id: null,
-	title: currentPage.title,
-	titleHtml: currentPage.title.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;'),
-	headingLevel: 1,
-	contentBlocks: [{
-		type: 'page-list',
-		pages: categoryDestination.children.map((node) => ({
-			title: node.title,
-			pathname: node.pathname,
-			description: node.kind === 'page' ? node.entry.data.page?.description : undefined,
-		})),
-	}],
-}] : await getSectionsContent(siteHtml, currentPage, childPages);
+const resolvedSections: ResolvedSection[] = await getSectionsContent(siteHtml, currentPage, childPages);
+if (currentPage.kind === 'page' && currentPage.entry.data.page?.listChildren) {
+	const lastSection = resolvedSections.at(-1);
+	if (lastSection && childPages.length > 0) {
+		lastSection.contentBlocks.push({
+			type: 'page-list',
+			pages: childPages.map((child) => ({
+				title: child.title,
+				pathname: child.pathname,
+				description: child.entry.data.page?.description,
+			})),
+		});
+	}
+}
 const allContentBlocks = resolvedSections.flatMap((section) => flattenContentBlocks(section.contentBlocks));
 const hasTabs = allContentBlocks.some((block) => block.type === 'tabs');
 const hasNotes = allContentBlocks.some((block) => (
@@ -167,33 +156,21 @@ const pagePresentation = resolvePagePresentation(themeData, themeLabel, {
 	navigationMode: navigationModel.mode,
 });
 const pageTextWidth = getTextWidthCssValue(pagePresentation.typography.values.body.width);
-const frameColors = resolveFrameColors({ theme: siteThemeData, sourceLabel: `${siteDirectory || 'site'}/${siteTheme.id}` });
+const frameColors = resolveFrameColors({ theme: themeData, sourceLabel: themeLabel });
 const hasTreeNavigation = navigationModel.mode === 'tree';
-const showTreeNavigation = hasTreeNavigation && !currentPage.isHome;
+// Keep one reading frame across tree-mode pages, including pages with no H2.
+// Home remains the site's entry point with the global navigation row.
+const areaReadingFrame = hasTreeNavigation && !currentPage.isHome;
 const currentPageNavigation = siteNavigation.find(({ node }) => (
 	node.kind === 'page' && node.pathname === currentPage.pathname
 ));
 const pageContentsHeadings = currentPageNavigation?.headings.filter(({ depth }) => depth === 2 || depth === 3) ?? [];
-const pageContentsPlacement = resolvePageContentsPlacement({
-	navigationMode: navigationModel.mode,
-	nodes: renderedNavigationEntries.map(({ node }) => ({
-		depth: Math.max(1, node.depth),
-		isHome: node.isHome,
-		listed: node.navigation.listed,
-		pagePath: node.pagePath,
-	})),
-	currentPage: {
-		isHome: currentPage.isHome,
-		pagePath: currentPage.pagePath,
-	},
-	headingCount: pageContentsHeadings.length,
-});
-const hasContentsNavigation = pageContentsPlacement.placement !== 'none';
-const hasTrackedSectionNavigation = hasContentsNavigation
-	|| (hasTreeNavigation && currentPage.isHome && pageContentsHeadings.length >= 2);
+const showTreeNavigation = hasTreeNavigation && !currentPage.isHome;
+const hasContentsNavigation = showTreeNavigation && pageContentsHeadings.some(({ depth }) => depth === 2);
+const hasTrackedSectionNavigation = hasTreeNavigation && pageContentsHeadings.some(({ depth }) => depth === 2);
 const integratePageContentsInTree = hasTreeNavigation;
-const showContentsRail = pageContentsPlacement.placement === 'contents-rail';
-const hasNavigationRailFrame = !currentPage.isHome && (
+// Home's global row and the reading layout share the site's wide coordinates.
+const hasNavigationRailFrame = (
 	navigationModel.requestedMode === 'tree'
 	|| (
 		navigationModel.requestedMode === 'automatic'
@@ -215,30 +192,35 @@ const reserveBreadcrumbSpace = showTreeNavigation || showBreadcrumbs;
 	footer={sitewideData.footer}
 	contentsNavigation={hasTrackedSectionNavigation}
 	searchable
+	areaNavigation={hasTreeNavigation}
+	areaReadingFrame={areaReadingFrame}
 >
 	<SiteNavigation
 		logo={logo}
 		currentPage={currentPage}
 		navigationEntries={siteNavigation}
+		categoryDestinations={categoryDestinations}
 		navigationMode={navigationModel.mode}
 		showTopNavigationSubmenus={navigationModel.requestedMode !== 'automatic' && navigationModel.mode !== 'tree'}
 		hasNavigationRailFrame={hasNavigationRailFrame}
 		frameColors={frameColors}
 		readerPreferences={pagePresentation.readerPreferences}
+		areaReadingFrame={areaReadingFrame}
 	/>
 	{siteBanners.length > 0 && <SiteBanners banners={siteBanners} />}
 
 	<div class:list={['site-page-layout', {
 		'site-page-layout-tree': showTreeNavigation,
-		'site-page-layout-contents': showContentsRail,
 	}]}
-		data-page-contents-placement={hasContentsNavigation ? pageContentsPlacement.placement : undefined}
+		data-page-contents-placement={hasContentsNavigation ? 'page-tree' : undefined}
 	>
 		{showTreeNavigation && (
 			<SiteTreeNavigation
 				currentPage={currentPage}
 				navigationEntries={siteNavigation}
+				categoryDestinations={categoryDestinations}
 				integratePageSections={integratePageContentsInTree}
+				areaReadingFrame={areaReadingFrame}
 			/>
 		)}
 		<main
@@ -273,12 +255,6 @@ const reserveBreadcrumbSpace = showTreeNavigation || showBreadcrumbs;
 			)}
 			<PageSequenceNavigation previous={pageSequence.previous} next={pageSequence.next} />
 		</main>
-		{showContentsRail && (
-			<PageContentsNavigation
-				headings={pageContentsHeadings}
-				pageTitle={currentPage.title}
-			/>
-		)}
 	</div>
 	{hasTreeNavigation && <TreeNavigationScript />}
 	{hasCodeBlocks && <CodeBlockCopyScript />}

package/src/components/SiteTreeNavigation.astro

@@ -1,45 +1,65 @@
 ---
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { withBasePath } from '../lib/basePath';
-import { getListedSiteNavigationTree, type SiteNavigationEntry } from '../lib/siteNavigation';
+import { getListedSiteNavigationTree, getNavigationDestination, type CategoryDestinationMap, type SiteNavigationEntry } from '../lib/siteNavigation';
+import { resolveAreaNavigation, withH2Outlines } from '../lib/areaNavigation';
 import type { SiteNode } from '../lib/sitePages';
 import NavigationPageTree from './NavigationPageTree.astro';
 import NavigationTreeControls from './NavigationTreeControls.astro';
+import NavigationState from './NavigationState.astro';
+import PageContentsLinks from './PageContentsLinks.astro';
 
 interface Props {
 	currentPage: SiteNode;
 	navigationEntries: SiteNavigationEntry[];
+	categoryDestinations?: CategoryDestinationMap;
 	integratePageSections?: boolean;
+	areaReadingFrame?: boolean;
 }
 
-const { currentPage, navigationEntries, integratePageSections = false } = Astro.props;
-const roots = getListedSiteNavigationTree(navigationEntries);
-const activeRoot = roots.find((node) => (
-	currentPage.pageDirectory === node.node.pageDirectory
-	|| currentPage.pageDirectory.startsWith(`${node.node.pageDirectory}/pages/`)
-));
-const navigationRoot = activeRoot?.node.pagePath ? `/${activeRoot.node.pagePath}/` : '/';
+const { currentPage, navigationEntries, categoryDestinations, integratePageSections = false, areaReadingFrame = false } = Astro.props;
+const roots = withH2Outlines(getListedSiteNavigationTree(navigationEntries));
+const area = resolveAreaNavigation(roots, currentPage);
+const activeRoot = area.localRoot;
+const ownOutline = !activeRoot
+	? navigationEntries.find(({ node }) => node.pagePath === currentPage.pagePath)?.headings.filter(({ depth }) => depth === 2) ?? []
+	: [];
+const navigationPage = activeRoot?.node ?? currentPage;
+const navigationRoot = navigationPage.pagePath ? `/${navigationPage.pagePath}/` : '/';
 const navigationStateRoot = withBasePath(projectConfig.site.basePath, '/');
+const showAreaTitle = activeRoot?.node.kind === 'category';
+const showReadingAreaTitle = areaReadingFrame
+	&& navigationPage.pagePath !== area?.globalRoot?.node.pagePath;
+const localNodes = activeRoot ? (showAreaTitle ? activeRoot.children : [activeRoot]) : [];
+// Retain the reviewed state namespace so existing sessions keep their position.
 ---
 
-{activeRoot && (
+{(activeRoot || ownOutline.length > 0) && (
 	<aside
 		id="tree-local-navigation"
 		class="tree-local-navigation"
-		data-navigation-root={navigationRoot}
-		data-navigation-state-root={navigationStateRoot}
+		data-navigation-root={`area:${navigationRoot}`}
+		data-navigation-state-root={`area:${navigationStateRoot}`}
+		data-navigation-area={activeRoot?.node.pagePath}
+		data-navigation-outline={ownOutline.length > 0 ? currentPage.pagePath : undefined}
 	>
-		<NavigationTreeControls
+		<NavigationState scope="desktop" />
+		{showReadingAreaTitle && <p class="navigation-area-title">{navigationPage.title}</p>}
+		{!areaReadingFrame && (showAreaTitle || ownOutline.length > 0) && <a class="navigation-area-title" href={withBasePath(projectConfig.site.basePath,
+			getNavigationDestination(navigationPage, categoryDestinations).pathname)}>{navigationPage.title}</a>}
+		{activeRoot && <NavigationTreeControls
 			idPrefix="desktop-tree-navigation"
-			nodes={[activeRoot]}
-		/>
-		<nav aria-label={`${activeRoot.node.title}: ${projectConfig.locale.labels.siteNavigation}`}>
-			<NavigationPageTree
-				nodes={[activeRoot]}
+			nodes={localNodes}
+			forceVisible
+		/>}
+		<nav aria-label={`${navigationPage.title}: ${projectConfig.locale.labels.siteNavigation}`}>
+			{activeRoot ? <NavigationPageTree
+				nodes={localNodes}
 				currentPage={currentPage}
+				categoryDestinations={categoryDestinations}
 				variant="sidebar"
 				integratePageSections={integratePageSections}
-			/>
+			/> : <PageContentsLinks headings={ownOutline} variant="desktop" />}
 		</nav>
 	</aside>
 )}

package/src/components/TopPageMenu.astro

@@ -2,17 +2,18 @@
 import { ChevronDown } from '@lucide/astro';
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { withBasePath } from '../lib/basePath';
-import type { SiteNavigationNode } from '../lib/siteNavigation';
+import type { CategoryDestinationMap, SiteNavigationNode } from '../lib/siteNavigation';
 import type { SiteNode } from '../lib/sitePages';
 import NavigationPageTree from './NavigationPageTree.astro';
 
 interface Props {
 	node: SiteNavigationNode;
 	currentPage?: SiteNode;
+	categoryDestinations?: CategoryDestinationMap;
 	showSections: boolean;
 	showChildren: boolean;
 }
-const { node, currentPage, showSections, showChildren } = Astro.props;
+const { node, currentPage, categoryDestinations, showSections, showChildren } = Astro.props;
 const sections = showSections ? node.sections : [];
 const children = showChildren ? node.children : [];
 const pageHref = node.node.kind === 'page'
@@ -39,7 +40,7 @@ const label = `${projectConfig.locale.labels.navigationMenu}: ${node.node.title}
 			{children.length > 0 && (
 				<nav class="top-page-children" aria-label={`${projectConfig.locale.labels.navigationChildren}: ${node.node.title}`}>
 					{sections.length > 0 && <p>{projectConfig.locale.labels.navigationChildren}</p>}
-					<NavigationPageTree nodes={children} currentPage={currentPage} variant="submenu" />
+					<NavigationPageTree nodes={children} currentPage={currentPage} categoryDestinations={categoryDestinations} variant="submenu" />
 				</nav>
 			)}
 		</div>

package/src/components/TreeNavigationScript.astro

@@ -1,4 +1,6 @@
 <script>
+	import { createNavigationStateHelpers } from '../lib/navigationState.mjs';
+
 	type NavigationState = {
 		openPaths: string[];
 		sectionOpenByPath: Record<string, boolean>;
@@ -10,12 +12,12 @@
 		sectionOpen: boolean[];
 		scrollTop: number;
 	};
+	const { storageKeys, parseState, initialState, arrivalPolicy, readEntryState, saveEntryState, pageIsOpen, sectionsAreOpen } = createNavigationStateHelpers();
 
 	const setupNavigationState = (container: HTMLElement, scope: 'desktop' | 'mobile') => {
 		const root = container.dataset.navigationRoot ?? '/';
 		const sharedRoot = container.dataset.navigationStateRoot ?? root;
-		const stateKey = `norna:tree-navigation:${scope}:${root}`;
-		const sharedStateKey = `norna:tree-navigation:shared:${sharedRoot}`;
+		const { stateKey, sharedStateKey } = storageKeys(scope, root, sharedRoot);
 		const branches = Array.from(container.querySelectorAll<HTMLDetailsElement>(
 			'.navigation-page-disclosure[data-page-path]',
 		));
@@ -38,22 +40,7 @@
 		const scrollContainer = getScrollContainer();
 		let filterSnapshot: NavigationSnapshot | null = null;
 		let lastSharedState = '';
-		const parseState = (value: string | null): NavigationState => {
-			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): entry is [string, boolean] => typeof entry[1] === 'boolean'))
-						: {},
-					scrollTop: Number.isFinite(Number(parsedState.scrollTop)) ? Number(parsedState.scrollTop) : 0,
-				};
-			} catch {
-				return { openPaths: [], sectionOpenByPath: {}, scrollTop: 0 };
-			}
-		};
+		let preserveOutgoingEntry = false;
 		const getDisclosureState = (): SharedNavigationState => ({
 			openPaths: branches.filter((branch) => branch.open)
 				.map((branch) => branch.dataset.pagePath ?? ''),
@@ -64,23 +51,13 @@
 		});
 		const applyDisclosureState = (
 			state: SharedNavigationState,
-			openCurrentPageOnArrival = false,
+			policy: { onArrival?: boolean; preserveCurrentPage?: boolean; preserveCurrentOutline?: boolean } = {},
 		) => {
 			branches.forEach((branch) => {
-				const pagePath = branch.dataset.pagePath ?? '';
-				branch.open = (openCurrentPageOnArrival && branch.dataset.currentBranch === 'true')
-					|| state.openPaths.includes(pagePath);
+				branch.open = pageIsOpen(state, branch.dataset, policy);
 			});
 			sectionBranches.forEach((branch) => {
-				const pagePath = branch.dataset.pagePath ?? '';
-				const storedOpen = state.sectionOpenByPath[pagePath];
-				if (openCurrentPageOnArrival && branch.dataset.currentPage === 'true') {
-					branch.open = true;
-					return;
-				}
-				branch.open = typeof storedOpen === 'boolean'
-					? storedOpen
-					: branch.dataset.currentPage === 'true';
+				branch.open = sectionsAreOpen(state, branch.dataset, policy);
 			});
 		};
 		const mergeSharedState = (state: SharedNavigationState): SharedNavigationState => {
@@ -99,18 +76,16 @@
 		};
 
 		try {
-			const storedState = parseState(sessionStorage.getItem(stateKey));
-			const storedSharedState = sessionStorage.getItem(sharedStateKey);
-			applyDisclosureState(storedSharedState === null
-				? storedState
-				: parseState(storedSharedState), true);
+			const state = initialState(sessionStorage.getItem(stateKey), sessionStorage.getItem(sharedStateKey),
+				readEntryState(stateKey));
+			applyDisclosureState(state.disclosure, arrivalPolicy(state));
 			const initialSharedState = mergeSharedState(getDisclosureState());
 			lastSharedState = JSON.stringify(initialSharedState);
 			sessionStorage.setItem(sharedStateKey, lastSharedState);
 
-			if (storedState.scrollTop > 0) {
+			if (state.local.scrollTop > 0 || state.fromEntry) {
 				requestAnimationFrame(() => {
-					scrollContainer.scrollTop = storedState.scrollTop;
+					scrollContainer.scrollTop = Math.max(0, state.local.scrollTop);
 				});
 			}
 		} catch {
@@ -127,6 +102,7 @@
 					scrollTop: scrollContainer.scrollTop,
 				};
 				sessionStorage.setItem(stateKey, JSON.stringify(state));
+				if (!preserveOutgoingEntry) saveEntryState(stateKey, state);
 				const sharedState = mergeSharedState(disclosureState);
 				const serializedSharedState = JSON.stringify(sharedState);
 				sessionStorage.setItem(sharedStateKey, serializedSharedState);
@@ -278,23 +254,6 @@
 				- Math.max(0, (scrollContainer.clientHeight - linkBox.height) / 2);
 			setStatus(labels.located);
 		};
-		const openLinkedPage = (link: HTMLAnchorElement) => {
-			if (filterInput?.value) {
-				filterInput.value = '';
-				clearFilter();
-			}
-			const pageNode = link.closest<HTMLElement>('.navigation-page-node');
-			const pageDisclosure = pageNode?.querySelector<HTMLDetailsElement>(
-				':scope > .navigation-page-disclosure:not(.navigation-category-disclosure)',
-			);
-			const sectionDisclosure = pageNode?.querySelector<HTMLDetailsElement>(
-				':scope > .navigation-page-sections-disclosure[data-page-path]',
-			);
-
-			if (pageDisclosure) pageDisclosure.open = true;
-			if (sectionDisclosure) sectionDisclosure.open = true;
-			saveState();
-		};
 
 		requestAnimationFrame(() => {
 			branches.forEach((branch) => branch.addEventListener('toggle', saveState));
@@ -314,8 +273,42 @@
 		collapseButton?.addEventListener('click', () => setAllOpen(false));
 		locateButton?.addEventListener('click', locateCurrentPage);
 		scrollContainer.addEventListener('scroll', saveState, { passive: true });
-		container.querySelectorAll<HTMLAnchorElement>('.navigation-page-link, .navigation-page-open-link')
-			.forEach((link) => link.addEventListener('click', () => openLinkedPage(link)));
+		// Cross-document arrivals open their current branch in the early
+		// restore. Do not expand the departing tree and paint an extra frame.
+		document.addEventListener('click', (event) => {
+			if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+			const link = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>('a[href]') : null;
+			if (!link || link.hasAttribute('download') || (link.target && link.target !== '_self')) return;
+			const url = new URL(link.href, location.href);
+			if (url.origin !== location.origin || url.pathname !== location.pathname || url.search !== location.search || !currentPageNode) return;
+			// A same-document fragment creates a new history entry after this
+			// click. Keep the old entry's disclosure snapshot until then.
+			preserveOutgoingEntry = url.href !== location.href;
+			if (filterInput?.value) { filterInput.value = ''; clearFilter(); }
+			const scrollTop = scrollContainer.scrollTop;
+			revealNodeAndAncestors(currentPageNode);
+			currentPageNode.querySelectorAll<HTMLDetailsElement>(
+				':scope > .navigation-page-disclosure, :scope > .navigation-page-sections-disclosure',
+			).forEach((branch) => { branch.open = true; });
+			scrollContainer.scrollTop = scrollTop;
+			saveState();
+		});
+		const restoreEntry = () => {
+			preserveOutgoingEntry = false;
+			try {
+				const source = readEntryState(stateKey);
+				if (source === null) return;
+				const state = parseState(source);
+				applyDisclosureState(state);
+				scrollContainer.scrollTop = Math.max(0, state.scrollTop);
+				saveState();
+			} catch { /* Native links work when storage is unavailable. */ }
+		};
+		window.addEventListener('pageshow', (event) => { if (event.persisted) restoreEntry(); });
+		window.addEventListener('popstate', restoreEntry);
+		window.addEventListener('hashchange', () => { preserveOutgoingEntry = false; saveState(); });
+		requestAnimationFrame(saveState);
+
 		window.addEventListener('pagehide', saveState);
 	};