@janga/norna 0.7.24 → 0.7.26

package/src/components/TreeNavigationScript.astro

@@ -4,6 +4,7 @@
 		sectionOpenByPath: Record<string, boolean>;
 		scrollTop: number;
 	};
+	type SharedNavigationState = Pick<NavigationState, 'openPaths' | 'sectionOpenByPath'>;
 	type NavigationSnapshot = {
 		branchOpen: boolean[];
 		sectionOpen: boolean[];
@@ -12,7 +13,9 @@
 
 	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 branches = Array.from(container.querySelectorAll<HTMLDetailsElement>(
 			'.navigation-page-disclosure[data-page-path]',
 		));
@@ -34,31 +37,76 @@
 		};
 		const scrollContainer = getScrollContainer();
 		let filterSnapshot: NavigationSnapshot | null = null;
-
-		try {
-			const parsedState = JSON.parse(sessionStorage.getItem(stateKey) ?? '{}');
-			const storedState: NavigationState = {
-				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,
-			};
-
+		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 };
+			}
+		};
+		const getDisclosureState = (): SharedNavigationState => ({
+			openPaths: branches.filter((branch) => branch.open)
+				.map((branch) => branch.dataset.pagePath ?? ''),
+			sectionOpenByPath: Object.fromEntries(sectionBranches.map((branch) => [
+				branch.dataset.pagePath ?? '',
+				branch.open,
+			])),
+		});
+		const applyDisclosureState = (
+			state: SharedNavigationState,
+			openCurrentPageOnArrival = false,
+		) => {
 			branches.forEach((branch) => {
 				const pagePath = branch.dataset.pagePath ?? '';
-				branch.open = branch.dataset.currentBranch === 'true'
-					|| storedState.openPaths.includes(pagePath);
+				branch.open = (openCurrentPageOnArrival && branch.dataset.currentBranch === 'true')
+					|| state.openPaths.includes(pagePath);
 			});
 			sectionBranches.forEach((branch) => {
 				const pagePath = branch.dataset.pagePath ?? '';
-				const storedOpen = storedState.sectionOpenByPath[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';
 			});
+		};
+		const mergeSharedState = (state: SharedNavigationState): SharedNavigationState => {
+			const existingState = parseState(sessionStorage.getItem(sharedStateKey));
+			const knownBranchPaths = new Set(branches.map((branch) => branch.dataset.pagePath ?? ''));
+			return {
+				openPaths: [
+					...existingState.openPaths.filter((pagePath) => !knownBranchPaths.has(pagePath)),
+					...state.openPaths,
+				],
+				sectionOpenByPath: {
+					...existingState.sectionOpenByPath,
+					...state.sectionOpenByPath,
+				},
+			};
+		};
+
+		try {
+			const storedState = parseState(sessionStorage.getItem(stateKey));
+			const storedSharedState = sessionStorage.getItem(sharedStateKey);
+			applyDisclosureState(storedSharedState === null
+				? storedState
+				: parseState(storedSharedState), true);
+			const initialSharedState = mergeSharedState(getDisclosureState());
+			lastSharedState = JSON.stringify(initialSharedState);
+			sessionStorage.setItem(sharedStateKey, lastSharedState);
 
 			if (storedState.scrollTop > 0) {
 				requestAnimationFrame(() => {
@@ -73,21 +121,36 @@
 			if (filterSnapshot) return;
 
 			try {
-				const openBranches = branches.filter((branch) => branch.open);
-				const sectionOpenByPath = Object.fromEntries(sectionBranches.map((branch) => [
-					branch.dataset.pagePath ?? '',
-					branch.open,
-				]));
+				const disclosureState = getDisclosureState();
 				const state: NavigationState = {
-					openPaths: openBranches.map((branch) => branch.dataset.pagePath ?? ''),
-					sectionOpenByPath,
+					...disclosureState,
 					scrollTop: scrollContainer.scrollTop,
 				};
 				sessionStorage.setItem(stateKey, JSON.stringify(state));
+				const sharedState = mergeSharedState(disclosureState);
+				const serializedSharedState = JSON.stringify(sharedState);
+				sessionStorage.setItem(sharedStateKey, serializedSharedState);
+				if (serializedSharedState !== lastSharedState) {
+					lastSharedState = serializedSharedState;
+					window.dispatchEvent(new CustomEvent('norna:tree-navigation-state', {
+						detail: { root: sharedRoot, state: sharedState },
+					}));
+				}
 			} catch {
 				// Navigation state persistence is an optional enhancement.
 			}
 		};
+		window.addEventListener('norna:tree-navigation-state', (event) => {
+			const detail = (event as CustomEvent<{
+				root?: string;
+				state?: SharedNavigationState;
+			}>).detail;
+			if (detail?.root !== sharedRoot || !detail.state) return;
+			const serializedSharedState = JSON.stringify(detail.state);
+			if (serializedSharedState === lastSharedState) return;
+			lastSharedState = serializedSharedState;
+			applyDisclosureState(detail.state);
+		});
 		const controls = container.querySelector<HTMLElement>('[data-tree-controls]');
 		const filterInput = controls?.querySelector<HTMLInputElement>('[data-tree-filter]') ?? null;
 		const expandButton = controls?.querySelector<HTMLButtonElement>('[data-tree-expand-all]') ?? null;

package/src/layouts/BaseLayout.astro

@@ -1,5 +1,6 @@
 ---
 import projectConfig from '../../scripts/lib/project-config.mjs';
+import { marginNoteLayoutDeclarations } from '../../scripts/lib/markdown-notes-render-plugin.mjs';
 import { getPresentationCssVariables } from '../../scripts/lib/presentation.mjs';
 import { getIconLinks, getSocialImageAsset } from '../lib/sitePublicAssets';
 import { withBasePath } from '../lib/basePath';
@@ -145,27 +146,48 @@ const marginNoteReadingWidths = [
 	['standard', 'min(72ch, 680px)'],
 	['wide', `min(80ch, ${visualTheme.images.width})`],
 ] as const;
-const vacantContentsTrackWidth = `11rem + ${visualTheme.layout.localNavigationGap}`;
-const marginNoteDeclarations = [
-	'float: right;',
-	'clear: right;',
-	'width: var(--layout-note-width);',
-	'margin: 0 calc(0px - var(--layout-note-width) - var(--layout-note-gap)) 0.75rem var(--layout-note-gap);',
-].join('\n');
+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}"] .section-note {`,
+			`: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,
 			'}',
 		'}',
 		].join('\n'),
 		[
-			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap} - ${vacantContentsTrackWidth})) {`,
-			`:root[data-reading-width="${readingWidth}"] .site-page-layout-tree:not(.site-page-layout-contents) .section-note,`,
-			`:root[data-reading-width="${readingWidth}"][data-focus-reading="on"] .site-page-layout-tree .section-note {`,
+			`@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,
 			'}',
 		'}',
@@ -176,7 +198,7 @@ const marginNoteLayoutCss = [
 const { buildInfo, copyrightMessage } = footer ?? {};
 const showBuildInfo = buildInfo === true;
 const buildTime = showBuildInfo
-	? new Intl.DateTimeFormat(projectConfig.locale.lang, {
+	? new Intl.DateTimeFormat(projectConfig.locale.formattingLocale, {
 		dateStyle: 'short',
 		timeStyle: 'short',
 		timeZone: 'UTC',

package/src/lib/generatedImages.ts

@@ -45,6 +45,24 @@ export const getGeneratedImage = (src: string) => readGeneratedImages()[src];
 
 const displaySrc = (src: string) => withBasePath(projectConfig.site.basePath, src);
 
+export const getImageInspectionAttributes = (src: string) => {
+	const image = getGeneratedImage(src);
+	const largestVariant = image?.variants
+		? [...image.variants].sort((left, right) => left.width - right.width).at(-1)
+		: undefined;
+	const publishedSource = image?.kind === 'static'
+		? image.src
+		: largestVariant?.src;
+
+	return {
+		href: displaySrc(publishedSource ?? src),
+		scalable: image?.kind === 'static' || /\.svg(?:[?#]|$)/iu.test(publishedSource ?? src),
+		...(Number.isFinite(image?.width) && Number.isFinite(image?.height)
+			? { width: image?.width, height: image?.height }
+			: {}),
+	};
+};
+
 const getDisplayVariants = (variants: NonNullable<GeneratedImage['variants']>) => {
 	const sortedVariants = [...variants].sort((a, b) => a.width - b.width);
 	const displayVariants = sortedVariants.filter((variant) => variant.width <= maxDisplayImageWidth);

package/src/lib/navigationFollowing.ts

@@ -0,0 +1,142 @@
+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;
+};
+
+const visibleEntry = (link: HTMLElement, container: HTMLElement): HTMLElement | undefined => {
+	if (isDisplayed(link)) return link;
+
+	let node = link.closest<HTMLElement>('.navigation-page-node');
+	while (node && container.contains(node)) {
+		const entry = node.querySelector<HTMLElement>([
+			':scope > .navigation-page-link',
+			':scope > .navigation-page-open-link',
+			':scope > .navigation-category-disclosure > summary',
+		].join(', '));
+		if (entry && isDisplayed(entry)) return entry;
+		node = node.parentElement?.closest<HTMLElement>('.navigation-page-node') ?? null;
+	}
+	return undefined;
+};
+
+// Adjust only the navigation scrollport, never the document or its focus.
+const revealEntry = (container: HTMLElement, entry: HTMLElement) => {
+	const box = container.getBoundingClientRect();
+	const inset = Math.min(16, container.clientHeight / 8);
+	let top = Math.max(0, box.top + container.clientTop);
+	const bottom = Math.min(window.innerHeight, box.top + container.clientTop + container.clientHeight);
+	for (const control of container.querySelectorAll<HTMLElement>(
+		'.navigation-tree-controls, .mobile-nav-panel-actions',
+	)) {
+		if (isDisplayed(control) && getComputedStyle(control).position === 'sticky') {
+			top = Math.max(top, control.getBoundingClientRect().bottom);
+		}
+	}
+	const bounds = entry.getBoundingClientRect();
+	const available = bottom - top - inset * 2;
+	if (available <= 0) return;
+	const delta = bounds.top < top + inset || bounds.height > available
+		? bounds.top - top - inset
+		: Math.max(0, bounds.bottom - bottom + inset);
+	if (Math.abs(delta) > 1) {
+		container.scrollTo({ top: container.scrollTop + delta, behavior: 'instant' });
+	}
+};
+
+export const setupNavigationFollowing = () => {
+	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]
+		.filter((container): container is HTMLElement => container !== null)
+		.map((container) => ({
+			container,
+			paused: false,
+			pointerDown: false,
+			expectedScrollTop: container.scrollTop,
+			ancestor: undefined as HTMLElement | undefined,
+		}));
+	let frame: number | undefined;
+
+	const updateContainer = (state: typeof states[number], reveal: boolean) => {
+		const { container } = state;
+		state.ancestor?.removeAttribute('data-reading-position-ancestor');
+		state.ancestor = undefined;
+		if (!isDisplayed(container)) return;
+		if (container.matches('[data-tree-filter-active="true"]')
+			|| container.querySelector('[data-tree-filter-active="true"]')) return;
+
+		const link = container.querySelector<HTMLElement>('a[aria-current="location"]');
+		if (!link) return;
+		const entry = visibleEntry(link, container);
+		if (!entry) return;
+		if (entry !== link) {
+			entry.setAttribute('data-reading-position-ancestor', 'true');
+			state.ancestor = entry;
+		}
+		if (!reveal) return;
+		revealEntry(container, entry);
+		state.expectedScrollTop = container.scrollTop;
+	};
+
+	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
+				&& !document.querySelector('.mobile-nav-menu[open]'));
+		}
+	};
+	const schedule = () => {
+		if (frame === undefined) frame = requestAnimationFrame(update);
+	};
+
+	for (const state of states) {
+		const pause = () => { state.paused = true; };
+		state.container.addEventListener('wheel', pause, { passive: true });
+		state.container.addEventListener('touchstart', pause, { passive: true });
+		state.container.addEventListener('keydown', pause);
+		state.container.addEventListener('focusin', pause);
+		state.container.addEventListener('input', pause);
+		state.container.addEventListener('input', schedule);
+		state.container.addEventListener('pointerdown', () => {
+			pause();
+			state.pointerDown = true;
+		});
+		state.container.addEventListener('scroll', () => {
+			if (Math.abs(state.container.scrollTop - state.expectedScrollTop) > 1) pause();
+		}, { passive: true });
+		// A disclosure can hide the active link without changing the scrollport size.
+		state.container.addEventListener('toggle', schedule, true);
+	}
+	const releasePointer = () => {
+		states.forEach((state) => { state.pointerDown = false; });
+	};
+	document.addEventListener('pointerup', releasePointer);
+	document.addEventListener('pointercancel', releasePointer);
+	window.addEventListener('blur', releasePointer);
+	window.addEventListener('scroll', () => {
+		states.forEach((state) => { state.paused = false; });
+		// Section tracking schedules its own update for the new document position.
+	}, { passive: true });
+	window.addEventListener('resize', schedule);
+	if ('ResizeObserver' in window) {
+		const observer = new ResizeObserver(schedule);
+		states.forEach(({ container }) => observer.observe(container));
+	}
+
+	return {
+		update: schedule,
+		revealCompact: () => {
+			const state = states.find(({ container }) => container === compact);
+			if (state) updateContainer(state, true);
+		},
+	};
+};

package/src/lib/noteNavigation.ts

@@ -0,0 +1,50 @@
+export const installNoteNavigation = () => {
+	const revealReference = (target: HTMLElement) => {
+		const panel = target.closest<HTMLElement>('[data-tab-panel]');
+		if (panel?.hidden) {
+			const group = panel.closest('[data-content-tabs]');
+			const button = Array.from(group?.querySelectorAll<HTMLButtonElement>('[role="tab"]') ?? [])
+				.find((candidate) => candidate.getAttribute('aria-controls') === panel.id);
+			button?.click();
+		}
+		target.focus({ preventScroll: true });
+	};
+	const targetFor = (hash: string) => {
+		try { return document.getElementById(decodeURIComponent(hash.slice(1))); } catch { return null; }
+	};
+	document.querySelectorAll<HTMLAnchorElement>('.section-note-ref a').forEach((link) => {
+		const note = targetFor(link.hash);
+		if (!note?.classList.contains('section-note')) return;
+		let hovered = false;
+		const updateHighlight = () => {
+			note.classList.toggle('is-reference-highlighted', hovered || link.matches(':focus-visible'));
+		};
+		link.addEventListener('pointerenter', (event) => {
+			hovered = event.pointerType !== 'touch';
+			updateHighlight();
+		});
+		link.addEventListener('pointerleave', () => {
+			hovered = false;
+			updateHighlight();
+		});
+		link.addEventListener('pointercancel', () => {
+			hovered = false;
+			updateHighlight();
+		});
+		link.addEventListener('focus', updateHighlight);
+		link.addEventListener('blur', updateHighlight);
+	});
+	// Capture before native fragment navigation so a previously hidden reference
+	// is visible and focusable when the browser follows the real return link.
+	document.addEventListener('click', (event) => {
+		if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		const link = (event.target as Element | null)?.closest<HTMLAnchorElement>('a[data-footnote-backref]');
+		if (!link) return;
+		const target = targetFor(link.hash);
+		if (target?.hasAttribute('data-footnote-ref')) revealReference(target);
+	}, true);
+	window.addEventListener('hashchange', () => {
+		const target = targetFor(location.hash);
+		if (target?.hasAttribute('data-footnote-ref')) revealReference(target);
+	});
+};

package/src/lib/searchNavigation.ts

@@ -0,0 +1,107 @@
+type SearchOrigin = {
+	id: string;
+	href: string;
+	title: string;
+	x: number;
+	y: number;
+};
+
+const returnParameter = 'norna-return';
+const historyKey = 'nornaSearchOrigin';
+
+export const setupSearchNavigation = () => {
+	const searchLink = document.querySelector<HTMLAnchorElement>('.site-search-link[data-search-base]');
+	if (!searchLink) return;
+	const basePath = searchLink.dataset.searchBase!;
+	const searchUrl = new URL(searchLink.href);
+	const departureKey = `norna:search:${basePath}:departure`;
+	const restoreKey = `norna:search:${basePath}:restore`;
+	const localHref = () => location.pathname + location.search + location.hash;
+	const isNormalClick = (event: MouseEvent, link: HTMLAnchorElement) => !event.defaultPrevented
+		&& event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey
+		&& !link.hasAttribute('download') && (!link.target || link.target === '_self');
+	const readStorage = (key: string): unknown => {
+		try { return JSON.parse(sessionStorage.getItem(key) ?? 'null'); } catch { return null; }
+	};
+	const store = (key: string, value: SearchOrigin) => {
+		try { sessionStorage.setItem(key, JSON.stringify(value)); return true; } catch { return false; }
+	};
+	const remove = (key: string) => {
+		try { sessionStorage.removeItem(key); } catch {}
+	};
+	const validate = (value: unknown): SearchOrigin | null => {
+		if (!value || typeof value !== 'object') return null;
+		const origin = value as SearchOrigin;
+		if (typeof origin.id !== 'string' || !/^[a-z0-9-]{1,100}$/i.test(origin.id)
+			|| typeof origin.href !== 'string' || !origin.href.startsWith('/')
+			|| origin.href.startsWith('//') || /[\\\u0000-\u0020]/.test(origin.href)
+			|| typeof origin.title !== 'string' || !origin.title.trim() || origin.title.length > 1000
+			|| !Number.isFinite(origin.x) || origin.x < 0
+			|| !Number.isFinite(origin.y) || origin.y < 0) return null;
+		try {
+			const url = new URL(origin.href, location.origin);
+			if (url.origin !== location.origin || !url.pathname.startsWith(basePath)
+				|| url.pathname === searchUrl.pathname) return null;
+			return origin;
+		} catch { return null; }
+	};
+
+	document.addEventListener('click', (event) => {
+		const title = searchLink.dataset.searchSourceTitle;
+		const link = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>('a[href]') : null;
+		if (!title || !link || !isNormalClick(event, link)
+			|| link.origin !== searchUrl.origin || link.pathname !== searchUrl.pathname) return;
+		const origin: SearchOrigin = {
+			id: crypto.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`,
+			href: localHref(), title, x: Math.max(0, scrollX), y: Math.max(0, scrollY),
+		};
+		if (!store(departureKey, origin)) return;
+		try { history.replaceState({ ...history.state, [historyKey]: origin }, ''); } catch {}
+		const destination = new URL(link.href);
+		destination.searchParams.set(returnParameter, origin.id);
+		event.preventDefault();
+		location.assign(destination.href);
+	});
+
+	const returnLink = document.querySelector<HTMLAnchorElement>('[data-search-return]');
+	if (returnLink) {
+		const url = new URL(location.href);
+		const token = url.searchParams.get(returnParameter);
+		let origin = validate(history.state?.[historyKey]);
+		if (url.searchParams.has(returnParameter)) {
+			const departure = validate(readStorage(departureKey));
+			origin = departure?.id === token ? departure : null;
+			url.searchParams.delete(returnParameter);
+			// Keep return context on this history entry, not on subsequent direct visits.
+			try {
+				history.replaceState({ ...history.state, [historyKey]: origin }, '', url);
+			} catch { origin = null; }
+			if (departure?.id === token) remove(departureKey);
+		}
+		if (origin) {
+			const destination = origin;
+			returnLink.href = destination.href;
+			returnLink.querySelector('span')!.textContent = returnLink.dataset.searchReturnLabel!.replace('{page}', () => destination.title);
+			returnLink.addEventListener('click', (event) => {
+				if (isNormalClick(event, returnLink)) store(restoreKey, destination);
+			});
+		}
+		return;
+	}
+
+	const restore = (event: PageTransitionEvent) => {
+		const navigation = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined;
+		const fromHistory = event.persisted || navigation?.type === 'back_forward';
+		const origin = validate(readStorage(restoreKey))
+			?? (fromHistory ? validate(history.state?.[historyKey]) : null);
+		remove(restoreKey);
+		if (!origin || origin.href !== localHref()) return;
+		try { history.replaceState({ ...history.state, [historyKey]: null }, ''); } catch {}
+		// Wait for initial anchor alignment and font layout, then restore the actual reading position.
+		void document.fonts.ready.then(() => requestAnimationFrame(() => requestAnimationFrame(() => {
+			searchLink.focus({ preventScroll: true });
+			window.scrollTo({ left: origin.x, top: origin.y, behavior: 'instant' });
+		})));
+	};
+	window.addEventListener('pageshow', restore);
+};