@janga/norna 0.7.27 → 0.7.29

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

package/src/content.config.ts

@@ -1,36 +1,35 @@
 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('/')
-				.filter((segment) => segment !== 'pages')
-				.join('/pages/');
+			const pageDirectory = pageEntryDirectory;
 			return encodePageEntryId(siteDirLabel, parsePageDirectoryPath(pageDirectory, `page directory pages/${pageEntryDirectory}`).pageDirectory);
 		},
 	}),
@@ -40,7 +39,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 +48,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/imagePresentation.ts

@@ -5,6 +5,9 @@ export type ManagedImage = {
 	src?: string;
 	alt?: string;
 	caption?: string;
+	title?: string;
+	href?: string;
+	linkTitle?: string;
 };
 
 type GeneratedImageWithDimensions = NonNullable<ReturnType<typeof getGeneratedImage>> & {

package/src/lib/markdownImages.ts

@@ -0,0 +1,101 @@
+import { parseFragment, serializeOuter, type DefaultTreeAdapterMap } from 'parse5';
+import { getPageImageSourceKey } from '../../scripts/lib/site-conventions.mjs';
+import { getGeneratedImage, getImageAttributes, getImageInspectionAttributes } from './generatedImages';
+import { getImageClass, getImageLoadingProps, getManagedImageSizes } from './imagePresentation';
+import projectConfig from '../../scripts/lib/project-config.mjs';
+
+type Node = DefaultTreeAdapterMap['node'];
+type Element = DefaultTreeAdapterMap['element'];
+const isElement = (node: Node): node is Element => 'tagName' in node;
+const attribute = (node: Element, name: string) => node.attrs.find((attr) => attr.name === name)?.value;
+const meaningfulChildren = (node: Element) => node.childNodes.filter((child) => child.nodeName !== '#text' || ('value' in child && child.value.trim()));
+const soleImage = (node: Element): { image: Element; href?: string; linkTitle?: string } | null => {
+	const children = meaningfulChildren(node);
+	if (children.length !== 1 || !isElement(children[0])) return null;
+	const child = children[0];
+	if (child.tagName === 'img' && attribute(child, 'data-norna-managed-image')) return { image: child };
+	if (child.tagName === 'a') {
+		const nested = soleImage(child);
+		if (nested) return { image: nested.image, href: attribute(child, 'href'), linkTitle: attribute(child, 'title') };
+	}
+	return null;
+};
+
+// Promote only top-level, single-image paragraphs to the shared Astro stack.
+// Nested images stay in their original list, quote, table, details or text.
+export const splitMarkdownImages = (html: string, pageDirectory: string) => {
+	if (!html.includes('data-norna-managed-image=')) return [{ type: 'html' as const, html }];
+	const fragment = parseFragment(html);
+	const result: Array<{ type: 'html'; html: string } | { type: 'image-stack'; images: Array<{ image: string; src: string; alt: string; title?: string; href?: string; linkTitle?: string }> }> = [];
+	let pending = '';
+	const flush = () => { if (pending.trim()) result.push({ type: 'html', html: pending }); pending = ''; };
+	const markSource = (node: Node) => {
+		if (!isElement(node)) return;
+		const marker = node.attrs.find((attr) => attr.name === 'data-norna-managed-image');
+		if (marker) marker.value = getPageImageSourceKey(pageDirectory, marker.value);
+		for (const child of node.childNodes) markSource(child);
+	};
+	for (const node of fragment.childNodes) {
+		const standalone = isElement(node) && node.tagName === 'p' ? soleImage(node) : null;
+		if (standalone) {
+			flush();
+			const name = attribute(standalone.image, 'data-norna-managed-image')!;
+			result.push({ type: 'image-stack', images: [{ image: name, src: getPageImageSourceKey(pageDirectory, name), alt: attribute(standalone.image, 'alt') ?? '', title: attribute(standalone.image, 'title'), href: standalone.href, linkTitle: standalone.linkTitle }] });
+		} else {
+			markSource(node);
+			pending += serializeOuter(node);
+		}
+	}
+	flush();
+	return result;
+};
+
+const escapeAttribute = (value: unknown) => String(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const attributes = (values: Record<string, unknown>) => Object.entries(values).filter(([, value]) => value !== undefined && value !== null).map(([key, value]) => ` ${key}="${escapeAttribute(value)}"`).join('');
+
+export const renderNestedMarkdownImages = (html: string, title: string, width: { desktop: number; mobile: number }) => {
+	if (!html.includes('data-norna-managed-image=')) return html;
+	const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+	const edits: Array<{ start: number; end: number; html: string }> = [];
+	const renderImage = (node: Element, standalone = false, href?: string, linkTitle?: string) => {
+		const src = attribute(node, 'data-norna-managed-image')!;
+		if (!getGeneratedImage(src)) throw new Error(`Managed Markdown image is missing from the generated manifest: ${src}. Run Norna's image preparation after correcting the source file.`);
+		const alt = attribute(node, 'alt') ?? '';
+		const imageClass = standalone ? ['managed-image', getImageClass({ image: src })].filter(Boolean).join(' ') : 'managed-markdown-inline';
+		const image = `<img${attributes({ ...getImageAttributes(src, getManagedImageSizes(width)), class: imageClass, alt, title: attribute(node, 'title'), ...getImageLoadingProps(false) })}>`;
+		if (!standalone) return image;
+		const inspection = getImageInspectionAttributes(src);
+		const link = attributes({
+			class: 'managed-image-inspection-link', href: href ?? inspection.href, title: linkTitle,
+			'aria-label': href === undefined ? projectConfig.locale.labels.inspectImage.replace('{description}', alt || title) : undefined,
+			'data-image-inspection-trigger': href === undefined ? '' : undefined,
+			'data-image-intrinsic-width': inspection.width, 'data-image-intrinsic-height': inspection.height,
+			'data-image-inspection-scalable': inspection.scalable ? 'true' : undefined,
+			style: inspection.width && inspection.height ? `--managed-image-intrinsic-width: ${inspection.width}px; --managed-image-aspect-ratio: ${inspection.width / inspection.height}` : undefined,
+		});
+		// The same Lucide Maximize2 affordance used by ImageStack.astro; this
+		// fragment stays inside the authored Markdown container.
+		const affordance = href === undefined ? '<span class="managed-image-inspection-affordance" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 3h6v6"/><path d="m21 3-7 7"/><path d="m3 21 7-7"/><path d="M9 21H3v-6"/></svg></span>' : '';
+		return `<div class="image-stack managed-markdown-standalone content-block-note-lane-boundary"><figure class="managed-image-item"><div class="managed-image-frame"><a${link}>${image}${affordance}</a></div></figure></div>`;
+	};
+	const visit = (node: Node) => {
+		if (!isElement(node)) return;
+		const location = node.sourceCodeLocation;
+		if (location && (node.tagName === 'p' || node.tagName === 'li')) {
+			const standalone = soleImage(node);
+			if (standalone) {
+				const start = node.tagName === 'li' ? location.startTag!.endOffset : location.startOffset;
+				const end = node.tagName === 'li' ? (location.endTag?.startOffset ?? location.endOffset) : location.endOffset;
+				edits.push({ start, end, html: renderImage(standalone.image, true, standalone.href, standalone.linkTitle) });
+				return;
+			}
+		}
+		if (location && node.tagName === 'img' && attribute(node, 'data-norna-managed-image')) {
+			edits.push({ start: location.startOffset, end: location.endOffset, html: renderImage(node) });
+			return;
+		}
+		for (const child of node.childNodes) visit(child);
+	};
+	for (const node of fragment.childNodes) visit(node);
+	return edits.sort((a, b) => b.start - a.start).reduce((result, edit) => result.slice(0, edit.start) + edit.html + result.slice(edit.end), html);
+};