@janga/norna 0.7.24 → 0.7.26

package/scripts/check-config.mjs

@@ -76,7 +76,11 @@ try {
 	console.log('Config check passed.');
 	console.log(`Site URL: ${projectConfig.site.url}`);
 	console.log(`Base path: ${projectConfig.site.basePath}`);
-	console.log(`Edit links: ${projectConfig.editLink?.baseUrl ?? '(disabled)'}`);
+	const editLinkDestinations = [
+		projectConfig.editLink?.localEditor ? `local ${projectConfig.editLink.localEditor}` : null,
+		projectConfig.editLink?.baseUrl ? `remote ${projectConfig.editLink.baseUrl}` : null,
+	].filter(Boolean);
+	console.log(`Edit links: ${editLinkDestinations.join(', ') || '(disabled)'}`);
 	console.log(`Theme preset: ${themeConfig.preset ?? '(none)'}`);
 	console.log(`Page width: ${projectConfig.layout.pageWidth}`);
 	console.log(`Gutter: desktop ${projectConfig.layout.gutter.desktop}, mobile ${projectConfig.layout.gutter.mobile}`);

package/scripts/dev-local.mjs

@@ -5,7 +5,12 @@ import { networkInterfaces } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { getAstroArgs, runAstroInherit } from './lib/astro-command.mjs';
-import { astroCacheDir, engineRoot, siteProjectRoot } from './lib/site-paths.mjs';
+import {
+	astroCacheDir,
+	engineRoot,
+	siteProjectRoot,
+	siteStateDir,
+} from './lib/site-paths.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -27,8 +32,12 @@ const probeUrls = [
 	`http://localhost:${port}${projectConfig.site.basePath}`,
 ];
 const skipOpen = process.env.NORNA_NO_OPEN === '1';
-const statePath = path.join(astroCacheDir, 'dev-local.json');
+const stateDirectory = path.join(siteStateDir, 'dev');
+const statePath = path.join(stateDirectory, 'state.json');
+const legacyStatePath = path.join(astroCacheDir, 'dev-local.json');
+const astroStatePath = path.join(astroCacheDir, 'dev.json');
 const logPath = path.join(astroCacheDir, 'dev.log');
+const preparationLogPath = path.join(stateDirectory, 'preparation.log');
 const args = process.argv.slice(2);
 const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
 const command = args.find((arg) => knownCommands.has(arg)) ?? args.find((arg) => !arg.startsWith('-')) ?? 'start';
@@ -51,9 +60,9 @@ const generateImages = async () => execFileAsync(process.execPath, [path.join(en
 	maxBuffer: 1024 * 1024 * 10,
 });
 
-const readState = async () => {
+const readJsonFile = async (filePath) => {
 	try {
-		return JSON.parse(await readFile(statePath, 'utf8'));
+		return JSON.parse(await readFile(filePath, 'utf8'));
 	} catch (error) {
 		if (error.code === 'ENOENT') {
 			return null;
@@ -63,15 +72,34 @@ const readState = async () => {
 	}
 };
 
+const readState = async () => (
+	await readJsonFile(statePath)
+	?? await readJsonFile(legacyStatePath)
+);
+
 const getLanUrls = () => Object.values(networkInterfaces())
 	.flat()
 	.filter((network) => network?.family === 'IPv4' && !network.internal)
 	.map((network) => `http://${network.address}:${port}${projectConfig.site.basePath}`);
 
 const writeState = async (host) => {
-	await mkdir(path.dirname(statePath), { recursive: true });
+	const astroState = await readJsonFile(astroStatePath);
+	let pid = astroState?.port === port && isProcessAlive(astroState.pid)
+		? astroState.pid
+		: null;
+	if (!Number.isInteger(pid)) {
+		const listeningPids = await getPortPids({ required: false });
+		pid = listeningPids?.length === 1 ? listeningPids[0] : null;
+	}
+
+	if (!Number.isInteger(pid)) {
+		throw new Error(`The dev server started at ${localUrl}, but Norna could not record its process. Stop the process on port ${port} before starting it again.`);
+	}
+
+	await mkdir(stateDirectory, { recursive: true });
 	await writeFile(statePath, `${JSON.stringify({
 		port,
+		pid,
 		host,
 		mode: host === '0.0.0.0' ? 'lan' : 'local',
 		url: localUrl,
@@ -81,6 +109,8 @@ const writeState = async (host) => {
 
 const removeState = async () => {
 	await rm(statePath, { force: true });
+	await rm(legacyStatePath, { force: true });
+	await rm(stateDirectory, { recursive: true, force: true });
 };
 
 const readDevLog = async () => {
@@ -161,6 +191,16 @@ const sleep = (milliseconds) => new Promise((resolve) => {
 	setTimeout(resolve, milliseconds);
 });
 
+const isProcessAlive = (pid) => {
+	if (!Number.isInteger(pid)) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === 'EPERM';
+	}
+};
+
 const isServerReachable = async () => {
 	for (const probeUrl of probeUrls) {
 		try {
@@ -213,7 +253,7 @@ const parseWindowsPortPids = (stdout) => [...new Set(
 		.filter(Number.isInteger),
 )];
 
-const getPortPids = async () => {
+const getPortPids = async ({ required = true } = {}) => {
 	try {
 		if (process.platform === 'win32') {
 			const { stdout } = await execFileAsync('powershell.exe', [
@@ -234,6 +274,7 @@ const getPortPids = async () => {
 	} catch (error) {
 		if (error.code === 1) return [];
 		if (error.code === 'ENOENT') {
+			if (!required) return null;
 			const commandName = process.platform === 'win32' ? 'PowerShell' : 'lsof';
 			throw new Error(`Cannot use --kill because ${commandName} is not available. Stop the process on port ${port} manually, then rerun the command.`);
 		}
@@ -273,6 +314,31 @@ const terminatePortProcesses = async (host) => {
 	}
 };
 
+const terminateTrackedProcess = async (state, host) => {
+	if (state?.port !== port || !Number.isInteger(state.pid)) return false;
+	if (!isProcessAlive(state.pid)) return false;
+
+	const listeningPids = await getPortPids({ required: false });
+	if (listeningPids && !listeningPids.includes(state.pid)) return false;
+	if (!listeningPids && !(await isServerReachable())) return false;
+
+	try {
+		process.kill(state.pid, 'SIGTERM');
+	} catch (error) {
+		if (error.code !== 'ESRCH') throw error;
+	}
+
+	if (await waitForPortToBeFree(host)) return true;
+
+	try {
+		process.kill(state.pid, 'SIGKILL');
+	} catch (error) {
+		if (error.code !== 'ESRCH') throw error;
+	}
+
+	return waitForPortToBeFree(host);
+};
+
 const openBrowser = async () => {
 	if (skipOpen) {
 		console.log(`Browser open skipped. Open ${localUrl}`);
@@ -294,10 +360,27 @@ const openBrowser = async () => {
 
 const stopServer = async ({ quiet = false } = {}) => {
 	const state = await readState();
-	const { stdout = '', stderr = '' } = await runAstro(['dev', 'stop']);
-	const stopped = `${stdout}\n${stderr}`.includes('Stopped dev server');
-	if (stopped) await waitForPortToBeFree(state?.host ?? localHost);
-	await removeState();
+	let astroError;
+	let astroOutput = '';
+	try {
+		const { stdout = '', stderr = '' } = await runAstro(['dev', 'stop']);
+		astroOutput = `${stdout}\n${stderr}`;
+	} catch (error) {
+		astroError = error;
+	}
+
+	let stopped = astroOutput.includes('Stopped dev server');
+	if (stopped) {
+		await waitForPortToBeFree(state?.host ?? localHost);
+	} else {
+		stopped = await terminateTrackedProcess(state, state?.host ?? localHost);
+	}
+
+	if (stopped || !(await isServerReachable())) {
+		await removeState();
+	}
+
+	if (astroError && !stopped) throw astroError;
 
 	if (!quiet) {
 		console.log(stopped
@@ -317,8 +400,29 @@ const startServer = async ({ host = localHost, open = true, killBlockingPort = f
 		await terminatePortProcesses(host);
 	}
 
-	await syncSitePublic();
-	await generateImages();
+	try {
+		await syncSitePublic();
+		await generateImages();
+	} catch (error) {
+		const output = [error.stdout, error.stderr].filter(Boolean).join('\n') || String(error);
+		const excerpt = getLogExcerpt(output)
+			.replace(/\n\s+at [\s\S]*$/u, '')
+			.replace(/\nNode\.js v[^\n]*$/u, '')
+			.trim();
+		let logHint;
+		try {
+			await mkdir(stateDirectory, { recursive: true });
+			await writeFile(preparationLogPath, output);
+			logHint = `Full log: ${preparationLogPath}`;
+		} catch (logError) {
+			logHint = `Could not save the preparation log: ${logError.message}`;
+		}
+		throw new Error([
+			`Could not prepare the site for the dev server at ${localUrl}.`,
+			excerpt,
+			logHint,
+		].join('\n\n'), { cause: error });
+	}
 	const previousLog = await readDevLog();
 	try {
 		await runAstroInherit(['dev', '--background', '--host', host, '--port', String(port)]);
@@ -370,7 +474,20 @@ const showStatus = async () => {
 	}
 
 	if (reachable) {
-		console.log(`A server is responding at ${localUrl}, but Astro does not track it for this site.`);
+		const listeningPids = await getPortPids({ required: false });
+		const stateOwnsPort = state?.port === port
+			&& Number.isInteger(state.pid)
+			&& (listeningPids ? listeningPids.includes(state.pid) : isProcessAlive(state.pid));
+		if (stateOwnsPort) {
+			console.log(`dev:${state.mode ?? 'local'} is running at ${localUrl}. Norna retained its process record after Astro cleared its cache.`);
+			if (state.host === '0.0.0.0') {
+				const lanUrls = getLanUrls();
+				if (lanUrls.length > 0) console.log(`On this local network: ${lanUrls.join(', ')}`);
+			}
+			return;
+		}
+
+		console.log(`A server is responding at ${localUrl}, but neither Astro nor Norna tracks it for this site.`);
 		return;
 	}
 

package/scripts/generate-schemas.mjs

@@ -11,6 +11,7 @@ import {
 	themeVisualSchema,
 } from './lib/schema-definitions.mjs';
 import { applySchemaEditorMetadata } from './lib/schema-editor-metadata.mjs';
+import { getNornaBlockSchema } from './lib/norna-markdown-blocks.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const schemaDirectory = path.join(root, 'schemas');
@@ -32,9 +33,20 @@ for (const [filename, title, schema] of definitions) {
 	schemaFiles.set(filename, `${JSON.stringify(jsonSchema, null, 2)}\n`);
 }
 
+const blockTypes = ['image-stack', 'image-carousel', 'card-list'];
+for (const type of blockTypes) {
+	const filename = `${type}.schema.json`;
+	schemaFiles.set(filename, `${JSON.stringify({
+		...getNornaBlockSchema(type),
+		$id: `https://janga.github.io/norna/schemas/${filename}`,
+		title: `Norna ${type}`,
+	}, null, 2)}\n`);
+}
+
 schemaFiles.set('manifest.json', `${JSON.stringify({
-	editorApiVersion: 1,
+	editorApiVersion: 2,
 	schemaVersion: 3,
+	blockSchemas: Object.fromEntries(blockTypes.map((type) => [type, `${type}.schema.json`])),
 	files: {
 		category: 'category.schema.json',
 		config: 'config.schema.json',
@@ -64,12 +76,12 @@ if (checkOnly) {
 		throw new Error(`Generated Norna schemas are stale: ${stale.join(', ')}. Run "npm run schemas:generate".`);
 	}
 
-	console.log(`Norna schemas are up to date (${definitions.length} schemas).`);
+	console.log(`Norna schemas are up to date (${definitions.length + blockTypes.length} schemas).`);
 } else {
 	await mkdir(schemaDirectory, { recursive: true });
 	for (const [filename, source] of schemaFiles) {
 		await writeFile(path.join(schemaDirectory, filename), source);
 	}
 
-	console.log(`Generated ${definitions.length} Norna schemas in ${path.relative(root, schemaDirectory)}.`);
+	console.log(`Generated ${definitions.length + blockTypes.length} Norna schemas in ${path.relative(root, schemaDirectory)}.`);
 }

package/scripts/init-site.mjs

@@ -18,6 +18,7 @@ dist/
 # generated site state
 **/.norna/public/
 **/.norna/.astro/
+**/.norna/dev/
 
 # legacy Astro cache location
 .astro/
@@ -40,6 +41,7 @@ pnpm-debug.log*
 `;
 const siteGitignore = `.norna/public/
 .norna/.astro/
+.norna/dev/
 `;
 
 const usage = `

package/scripts/lib/category-destinations.mjs

@@ -0,0 +1,48 @@
+import { getSiteNavigationTree } from './site-navigation-tree.mjs';
+import { getSiteNodePathname } from './site-page-urls.mjs';
+
+// Accept the same normalized nodes as navigation; excluded ancestors exclude
+// their whole subtree, including category destinations.
+export const createCategoryDestinationModel = (nodes) => {
+	const destinations = [];
+	const diagnostics = [];
+	const visit = (branch) => {
+		const { node } = branch;
+		if (node.navigation?.listed === false) return false;
+		const children = branch.children.filter(({ node: child }) => child.navigation?.listed !== false);
+		const reachable = children.map(visit).some(Boolean);
+		if (node.kind !== 'category') return true;
+		if (!reachable) {
+			const source = node.categorySourceLabel ?? node.nodeLabel ?? node.pageDirectory;
+			diagnostics.push({
+				code: 'category-without-listed-content',
+				severity: 'error',
+				message: `${source} has no listed reachable content page.`,
+				fix: 'Add a listed page under this category, or remove the category.',
+			});
+			return false;
+		}
+		const first = children[0].node;
+		destinations.push({
+			category: node,
+			pathname: getSiteNodePathname(node),
+			kind: first.kind === 'page' ? 'redirect' : 'listing',
+			target: first.kind === 'page' ? first : null,
+			children: children.map(({ node: child }) => child),
+		});
+		return true;
+	};
+	getSiteNavigationTree(nodes.map((node) => ({ node }))).forEach(visit);
+	return {
+		destinations,
+		byPathname: new Map(destinations.map((destination) => [destination.pathname, destination])),
+		diagnostics,
+	};
+};
+
+export const assertCategoryDestinationModel = (model) => {
+	if (model.diagnostics.length) {
+		throw new Error(model.diagnostics.map(({ message, fix }) => `${message}\n${fix}`).join('\n'));
+	}
+	return model;
+};

package/scripts/lib/code-fence-metadata.mjs

@@ -9,40 +9,17 @@ const invalidMetadata = (message, fix) => ({
 	},
 });
 
-const parseTitle = (source) => {
-	let title = '';
-	let index = titlePrefix.length;
-
-	while (index < source.length) {
-		const character = source[index];
-		if (character === '"') {
-			return {
-				rest: source.slice(index + 1),
-				title,
-			};
-		}
-
-		if (character === '\\') {
-			const escaped = source[index + 1];
-			if (escaped !== '"' && escaped !== '\\') {
-				return invalidMetadata(
-					`Code title contains unsupported escape "\\${escaped ?? ''}".`,
-					'Only escape a double quote (\\") or backslash (\\\\) inside the title.',
-				);
-			}
-			title += escaped;
-			index += 2;
-			continue;
-		}
-
-		title += character;
-		index += 1;
+export const parseQuotedContentString = (source) => {
+	const quoted = source.match(/^"(?:[^"\\]|\\[\s\S])*"/)?.[0];
+	if (!quoted) return { error: 'Use a JSON double-quoted string with a closing double quote.' };
+	let value;
+	try { value = JSON.parse(quoted); } catch {
+		return { error: 'Use valid JSON escapes inside the double-quoted string.' };
 	}
-
-	return invalidMetadata(
-		'Code title is missing its closing double quote.',
-		'Close the title, for example title="src/config.js".',
-	);
+	if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(value)) {
+		return { error: 'Quoted labels and titles cannot contain control characters, including line breaks and tabs.' };
+	}
+	return { value, rest: source.slice(quoted.length) };
 };
 
 const parseHighlightedLines = (selector, lineCount) => {
@@ -94,15 +71,15 @@ export const parseCodeFenceMetadata = (rawMetadata, options = {}) => {
 	let rest = source;
 	let title = null;
 	if (rest.startsWith(titlePrefix)) {
-		const titleResult = parseTitle(rest);
-		if (titleResult.error) return titleResult;
-		if (!titleResult.title.trim()) {
+		const titleResult = parseQuotedContentString(rest.slice('title='.length));
+		if (titleResult.error) return invalidMetadata(`Invalid code title. ${titleResult.error}`, 'Write a single-line title, for example title="src/config.js".');
+		if (!titleResult.value.trim()) {
 			return invalidMetadata(
 				'Code title cannot be empty.',
 				'Remove title="" or provide a short filename or label.',
 			);
 		}
-		title = titleResult.title;
+		title = titleResult.value;
 		rest = titleResult.rest;
 		if (rest && !rest.startsWith(' ')) {
 			return invalidMetadata(
@@ -210,12 +187,17 @@ export const nornaCodeFenceTransformer = {
 			tagName: 'figure',
 			properties: { className: ['norna-code-example'] },
 			children: [
-				{
-					type: 'element',
-					tagName: 'figcaption',
-					properties: { className: ['norna-code-title'] },
-					children: [{ type: 'text', value: metadata.title }],
-				},
+					{
+						type: 'element',
+						tagName: 'figcaption',
+						properties: { className: ['norna-code-title'] },
+						children: [{
+							type: 'element',
+							tagName: 'span',
+							properties: { className: ['norna-code-title-text'] },
+							children: [{ type: 'text', value: metadata.title }],
+						}],
+					},
 				node,
 			],
 		};

package/scripts/lib/content-tabs.mjs

@@ -0,0 +1,155 @@
+import { markdownToMdast } from 'satteri';
+import { parseQuotedContentString } from './code-fence-metadata.mjs';
+
+// Only delimiters belong to this scanner. Markdown parsing and source positions
+// stay with Satteri, including code examples that happen to contain delimiters.
+export const parseContentTabs = (source, { label = 'Markdown', lineOffset = 0 } = {}) => {
+	if (!/^\s*(?:(?:>\s*|[-+*]\s+))?:{3,}\s*tabs?\b/m.test(source)) return { groups: [], diagnostics: [], replacements: [], maskedSource: source };
+	const tree = markdownToMdast(source, { features: { gfm: true, frontmatter: true } });
+	const nodes = [];
+	const visit = (node, parent) => {
+		nodes.push({ node, parent });
+		for (const child of node.children ?? []) visit(child, node);
+	};
+	visit(tree, null);
+	const ignored = nodes.filter(({ node }) => ['code', 'inlineCode', 'html', 'yaml', 'toml'].includes(node.type));
+	const groups = [];
+	const diagnostics = [];
+	const replacements = [];
+	let group = null;
+	let panel = null;
+	const outerContainers = [];
+	let offset = 0;
+	let section = 'page introduction';
+	const error = (message, at = offset) => diagnostics.push({
+		code: 'invalid-content-tabs', severity: 'error', offset: at,
+		line: lineOffset + source.slice(0, at).split('\n').length,
+		message: `${label} line ${lineOffset + source.slice(0, at).split('\n').length}, section "${groups.find((item) => at >= item.start && at < (item.end ?? source.length))?.section ?? section}": ${message}`,
+	});
+	for (const [index, line] of source.split('\n').entries()) {
+		const start = offset;
+		offset += line.length + 1;
+		const contentStart = start + line.search(/\S|$/);
+		if (ignored.some(({ node }) => contentStart >= node.position.start.offset && contentStart < node.position.end.offset)) continue;
+		if (!group && /^#{1,3}\s/.test(line)) section = line.replace(/^#+\s*/, '').replace(/\s*\{#.*\}$/, '');
+		const match = line.match(/^(\s*)(:{3,})\s*(.*?)\s*$/);
+		if (!match) {
+			if (group && !panel && line.trim()) error('Put content inside a labelled tab, not directly inside tabs.', start);
+			if (/^\s*(?:>\s*|[-+*]\s+)(?::+)\s*tabs?\b/.test(line)) error('Place tabs directly in the section, outside lists and blockquotes.', start);
+			continue;
+		}
+		const [, indent, fence, declaration] = match;
+		const name = declaration.split(/\s/)[0];
+		if (!group && name !== 'tabs' && name !== 'tab') {
+			if (declaration) outerContainers.push(fence.length);
+			else if (outerContainers.length) outerContainers.pop();
+			else if (groups.length) error('This closing marker has no open tab group.', start);
+			continue;
+		}
+		const replace = (kind, data = {}) => replacements.push({ start, end: start + line.length, kind, ...data });
+		if (indent || (!group && nodes.some(({ node, parent }) => node.type === 'paragraph' && parent?.type !== 'root'
+			&& start >= node.position.start.offset && start < node.position.end.offset))) {
+			error('Place tabs directly in the section, outside other blocks.', start);
+		}
+		if (name === 'tabs') {
+			if (outerContainers.length) error('Place tabs directly in the section, outside other containers.', start);
+			if (group) { error('Tab groups cannot be nested.', start); continue; }
+			if (fence !== '::::' || declaration !== 'tabs') error('Open a tab group with ":::: tabs" on its own line.', start);
+			group = { index: groups.length, start, section, line: lineOffset + index + 1, panels: [] };
+			groups.push(group);
+			replace('group-start', { index: group.index });
+		} else if (name === 'tab') {
+			if (!group) { error('A tab must be inside a ":::: tabs" block.', start); continue; }
+			if (panel) error('Close the preceding tab with ":::" before starting another tab.', start);
+			const decoded = parseQuotedContentString(declaration.slice(3).trim());
+			let title = decoded.value ?? '';
+			if (fence !== ':::' || decoded.error || decoded.rest || !title.trim()) {
+				error(`Write a nonempty quoted label, for example ::: tab "Windows".${decoded.error ? ` ${decoded.error}` : ''}`, start);
+				title = '';
+			}
+			if (group.panels.some((item) => item.label.normalize('NFC') === title.trim().normalize('NFC'))) error(`Duplicate tab label "${title}". Use unique labels within this group.`, start);
+			panel = { label: title.trim(), start: offset, declarationStart: start, index: group.panels.length };
+			group.panels.push(panel);
+			replace('panel-start', { index: panel.index });
+		} else if (!declaration) {
+			if (fence === '::::') {
+				if (panel) error('Close the tab with ":::" before closing the group.', start);
+				if (group.panels.length < 2) error('A tab group needs at least two alternatives.', group.start);
+				group.end = offset;
+				replace('group-end');
+				group = panel = null;
+			} else if (fence !== ':::') {
+				error('Close tabs with ":::" and the group with "::::".', start);
+			} else if (panel) {
+				panel.end = start;
+				if (!source.slice(panel.start, start).replace(/<!--[\s\S]*?-->/g, '').trim()) error('A tab cannot be empty. Explain when the step does not apply.', panel.declarationStart);
+				replace('panel-end');
+				panel = null;
+			} else error('This closing marker has no open tab.', start);
+		} else error(`Unknown or misplaced tab marker "${declaration}". Write callouts as GitHub-style alerts, for example > [!TIP] followed by quoted body text.`, start);
+	}
+	if (group) error('The tab group is unclosed. Close each tab with ":::" and the group with "::::".', group.start);
+	let maskedSource = source;
+	for (const replacement of [...replacements].reverse()) maskedSource = maskedSource.slice(0, replacement.start)
+		+ ' '.repeat(replacement.end - replacement.start) + maskedSource.slice(replacement.end);
+	nodes.length = 0;
+	visit(markdownToMdast(maskedSource, { features: { gfm: true, frontmatter: true } }), null);
+	for (const item of groups) {
+		for (const tab of item.panels) {
+			const end = tab.end ?? item.end ?? source.length;
+			for (const { node } of nodes) {
+				if (!node.position || node.position.start.offset < tab.start || node.position.start.offset >= end) continue;
+				if (node.type === 'heading' || ['yaml', 'toml'].includes(node.type)
+					|| (node.type === 'html' && /<(?:h[1-6]|nav)\b/i.test(node.value))) error('Tabs cannot contain headings, frontmatter, or navigation definitions. Keep the shared headings outside the group.', node.position.start.offset);
+			}
+			if (/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/.test(source.slice(tab.start, end).trimStart())) error('Frontmatter belongs at the start of content.md, not inside a tab.', tab.declarationStart);
+		}
+	}
+	return { groups, diagnostics, replacements, maskedSource };
+};
+
+export const prepareContentTabs = (source, options = {}) => {
+	const parsed = parseContentTabs(source, options);
+	if (parsed.diagnostics.length) throw new Error(parsed.diagnostics[0].message);
+	let result = source;
+	for (const marker of [...parsed.replacements].reverse()) {
+		const html = `<div data-norna-tabs-marker="${marker.kind}"${marker.index === undefined ? '' : ` data-index="${marker.index}"`}></div>`;
+		result = result.slice(0, marker.start) + '\n' + html + '\n' + result.slice(marker.end);
+	}
+	return result;
+};
+
+export const groupRenderedTabs = (blocks, groups) => {
+	const result = [];
+	let group = null;
+	let panel = null;
+	const append = (block) => (panel ? panel.contentBlocks : result).push(block);
+	for (const block of blocks) {
+		if (block.type !== 'html') { append(block); continue; }
+		const pattern = /<div data-norna-tabs-marker="([a-z-]+)"(?: data-index="(\d+)")?><\/div>/g;
+		let cursor = 0;
+		for (const match of block.html.matchAll(pattern)) {
+			const before = block.html.slice(cursor, match.index);
+			if (before.trim()) append({ type: 'html', html: before });
+			const kind = match[1];
+			if (kind === 'group-start') {
+				const source = groups.find((item) => item.index === Number(match[2]));
+				if (!source) throw new Error('Rendered tab group has no matching source.');
+				group = { type: 'tabs', index: source.index, panels: [], source };
+			} else if (kind === 'panel-start') {
+				panel = { label: group.source.panels[Number(match[2])].label, contentBlocks: [] };
+				group.panels.push(panel);
+			} else if (kind === 'panel-end') panel = null;
+			else if (kind === 'group-end') {
+				const { source, ...resolved } = group;
+				result.push(resolved);
+				group = null;
+			}
+			cursor = match.index + match[0].length;
+		}
+		const after = block.html.slice(cursor);
+		if (after.trim()) append({ type: 'html', html: after });
+	}
+	if (group || panel) throw new Error('Rendered tab group is incomplete.');
+	return result;
+};

package/scripts/lib/details-headings.mjs

@@ -0,0 +1,58 @@
+import { parseFragment } from 'parse5';
+
+export const getDetailsHeadingDiagnostics = (tree, { source, label, lineOffset = 0 }) => {
+	if (!/<details[\s/>]/i.test(source)) return [];
+	const lines = source.split('\n');
+	const lineStarts = [];
+	let offset = 0;
+	for (const line of lines) {
+		lineStarts.push(offset);
+		offset += line.length + 1;
+	}
+	const html = source.replace(/[^\n]/g, ' ').split('');
+	const headings = [];
+	const visitMarkdown = (node) => {
+		if (node.type === 'heading') headings.push(node.position.start.offset);
+		if (node.type === 'html') {
+			// Keep only parsed HTML, preserving source offsets and stripping list/quote
+			// prefixes. Literal HTML in Markdown code or escapes never reaches parse5.
+			for (const [index, value] of node.value.split('\n').entries()) {
+				const lineIndex = node.position.start.line - 1 + index;
+				const column = index === 0 ? node.position.start.column - 1 : lines[lineIndex].indexOf(value);
+				const start = lineStarts[lineIndex] + column;
+				for (let i = 0; i < value.length; i += 1) html[start + i] = value[i];
+			}
+		}
+		for (const child of node.children ?? []) visitMarkdown(child);
+	};
+	visitMarkdown(tree);
+	const fragment = parseFragment(html.join(''), { sourceCodeLocationInfo: true });
+	const disclosures = [];
+	const visitHtml = (node) => {
+		const location = node.sourceCodeLocation;
+		if (location && node.tagName === 'details') {
+			disclosures.push({
+				start: location.startTag.endOffset,
+				end: location.endTag?.startOffset ?? location.endOffset,
+			});
+		}
+		if (location && /^h[1-6]$/.test(node.tagName)) headings.push(location.startOffset);
+		for (const child of node.childNodes ?? []) visitHtml(child);
+		if (node.content) visitHtml(node.content);
+	};
+	visitHtml(fragment);
+	const fix = 'Move the heading outside <details>, or use bold text inside it.';
+	return [...new Set(headings)].sort((a, b) => a - b)
+		.filter((start) => disclosures.some((details) => start >= details.start && start < details.end))
+		.map((start) => {
+			const line = lineOffset + source.slice(0, start).split('\n').length;
+			return {
+				code: 'heading-inside-details',
+				severity: 'error',
+				offset: start,
+				line,
+				message: `${label} line ${line}: Headings H1-H6 are not allowed inside <details>, including <summary>.`,
+				fix,
+			};
+		});
+};