@janga/norna 0.7.24 → 0.7.26

package/scripts/lib/semantic-callouts.mjs

@@ -62,6 +62,7 @@ const formatDiagnostic = ({ code, fix, label, line, message, offset }) => ({
 	line,
 	message: `${label} line ${line}: ${message}`,
 	offset,
+	severity: 'error',
 });
 
 export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
@@ -101,7 +102,8 @@ export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
 				issue = {
 					code: 'unknown-semantic-callout-type',
 					message: `Unknown semantic callout type "${marker.rawType}".`,
-					fix: `Use one of: ${semanticCalloutTypes.join(', ')}.`,
+					fix: `Use one of: ${semanticCalloutTypes.join(', ')}. The block will remain a neutral blockquote until then.`,
+					severity: 'warning',
 				};
 			} else if (marker.title) {
 				issue = {
@@ -117,7 +119,7 @@ export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
 				};
 			}
 
-			if (issue) diagnostics.push(formatDiagnostic({ ...issue, label, line, offset }));
+			if (issue) diagnostics.push({ ...formatDiagnostic({ ...issue, label, line, offset }), severity: issue.severity ?? 'error' });
 		}
 
 		for (const child of node.children ?? []) visit(child, nextBlockquoteDepth);

package/scripts/lib/site-content.mjs

@@ -67,7 +67,6 @@ const knownNestedFrontmatterKeys = new Set([
 	'palette',
 	'preset',
 	'profile',
-	'readerControls',
 	'readingWidth',
 	'rhythm',
 	'sectionGap',
@@ -171,7 +170,10 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 			fix = fileKind === 'page theme'
 				? 'Remove "colorMode:" from this page theme. Set "appearance:" in the root theme.yaml when an override is needed.'
 				: 'Replace "colorMode:" with "appearance:".';
-		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'readerControls', 'corners', 'palette', 'typography'].includes(key)) {
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'readerControls') {
+			message = `Frontmatter line ${lineNumber}: Theme setting "readerControls" was removed. Appearance and reading width are always available; Focus reading follows tree navigation.`;
+			fix = 'Remove "readerControls:". Use "appearance.default" for the initial Appearance; reading width is always available and tree navigation provides Focus reading.';
+		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'corners', 'palette', 'typography'].includes(key)) {
 			message = `Frontmatter line ${lineNumber}: page themes may not define site-wide visual identity through "${key}".`;
 			fix = `Move "${key}:" to the root theme.yaml. Page themes may set only layout.textWidth, layout.contentSpacing, images, and sections.backgroundPattern.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && ['logo', 'site'].includes(key)) {

package/scripts/lib/site-link-graph.mjs

@@ -17,6 +17,7 @@ import {
 } from './site-paths.mjs';
 import { getSiteNodePathname } from './site-page-urls.mjs';
 import { getSiteStructure } from './site-structure.mjs';
+import { createCategoryDestinationModel } from './category-destinations.mjs';
 
 const internalUrlOrigin = 'https://norna.invalid';
 const externalSchemePattern = /^[a-z][a-z0-9+.-]*:/i;
@@ -161,6 +162,13 @@ export const createSiteLinkGraph = ({
 		return createPageRecord(pageDocument);
 	});
 	const pagesByPathname = new Map(pages.map((page) => [page.pathname, page]));
+	const pagesByDirectory = new Map(pages.map((page) => [page.contentFile.pageDirectory, page]));
+	const categoryModel = createCategoryDestinationModel(siteStructure.nodes.map((node) => ({
+		...node,
+		navigation: node.kind === 'page'
+			? pagesByDirectory.get(node.pageDirectory).navigation
+			: { listed: true },
+	})));
 	const categoriesByPathname = new Map(siteStructure.categories.map((category) => [
 		getSiteNodePathname(category),
 		{ ...category, pathname: getSiteNodePathname(category) },
@@ -185,7 +193,7 @@ export const createSiteLinkGraph = ({
 
 	const references = [];
 	const referencesByTarget = new Map();
-	const diagnostics = [...aliasModel.diagnostics];
+	const diagnostics = [...aliasModel.diagnostics, ...categoryModel.diagnostics];
 
 	for (const page of pages) {
 		for (const sourceReference of page.document.links) {
@@ -278,13 +286,14 @@ export const createSiteLinkGraph = ({
 			const targetCategory = target.pageLookupPathname
 				? categoriesByPathname.get(target.pageLookupPathname)
 				: null;
-			if (targetCategory) {
+			if (targetCategory && categoryModel.byPathname.has(targetCategory.pathname)) {
 				reference.resolution = { category: targetCategory, kind: 'category', pathname: targetCategory.pathname };
-				diagnostics.push(createIssue(
+				const destination = categoryModel.byPathname.get(targetCategory.pathname);
+				if (target.fragment && !(destination.kind === 'listing' && target.fragment === 'page-title')) diagnostics.push(createIssue(
 					reference,
-					'category-has-no-url',
-					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to navigation category ${targetCategory.pathname}, which does not have its own page.`,
-					'Link to one of the category pages, or replace category.yaml with content.md when the collection needs its own page.',
+					'missing-internal-anchor',
+					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to an unavailable category anchor.`,
+					'Link to the category without a fragment, or use the content page URL for a heading link.',
 				));
 				continue;
 			}
@@ -318,6 +327,7 @@ export const createSiteLinkGraph = ({
 	}
 
 	return {
+		categoryModel,
 		aliasModel,
 		aliases: aliasModel.aliases,
 		aliasesByPathname: aliasModel.aliasesByPathname,

package/scripts/lib/site-navigation-tree.mjs

@@ -37,17 +37,6 @@ export const getListedSiteNavigationTree = (entries) => {
 	return filterListed(getSiteNavigationTree(entries));
 };
 
-export const getFirstPageInNavigationNode = (node) => {
-	if (node.node.kind === 'page') return node.node;
-
-	for (const child of node.children) {
-		const page = getFirstPageInNavigationNode(child);
-		if (page) return page;
-	}
-
-	return null;
-};
-
 export const flattenSiteNavigationTree = (nodes) => nodes.flatMap((node) => [
 	node,
 	...flattenSiteNavigationTree(node.children),

package/scripts/lib/site-paths.mjs

@@ -5,6 +5,7 @@ import { homePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
+const stateDirectoryEnvName = 'NORNA_INTERNAL_STATE_DIR';
 const defaultSiteDirectory = 'site';
 export { homePageDirectory };
 
@@ -16,12 +17,19 @@ export const siteDirectoryEnv = siteDirectoryEnvName;
 
 const normalizeSiteDirectory = (value) => String(value ?? '').trim();
 const normalizeInvocationRoot = (value) => String(value ?? '').trim();
+const normalizeStateDirectory = (value) => String(value ?? '').trim();
 
 const configuredInvocationRoot = normalizeInvocationRoot(process.env[invocationRootEnvName]);
 export const invocationRoot = configuredInvocationRoot
 	? path.resolve(configuredInvocationRoot)
 	: process.cwd();
 
+const hasStateDirectoryEnv = Object.hasOwn(process.env, stateDirectoryEnvName);
+const configuredStateDirectory = normalizeStateDirectory(process.env[stateDirectoryEnvName]);
+if (hasStateDirectoryEnv && !configuredStateDirectory) {
+	throw new Error(`${stateDirectoryEnvName} must not be empty.`);
+}
+
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
 		existsSync(path.join(siteDir, 'config.yaml'))
@@ -126,9 +134,13 @@ export const siteHomePageDir = path.join(sitePagesDir, homePageDirectory);
 export const siteContentPath = path.join(siteHomePageDir, 'content.md');
 export const siteImagesDir = path.join(siteHomePageDir, 'images');
 export const sitePublicDir = path.join(siteDir, 'public');
-export const siteStateDir = path.join(siteDir, '.norna');
+export const siteStateDir = configuredStateDirectory
+	? path.resolve(configuredStateDirectory)
+	: path.join(siteDir, '.norna');
 export const astroPublicDir = path.join(siteStateDir, 'public');
-export const astroDistDir = path.join(siteProjectRoot, 'dist');
+export const astroDistDir = configuredStateDirectory
+	? path.join(siteStateDir, 'dist')
+	: path.join(siteProjectRoot, 'dist');
 export const astroRootDir = siteStateDir;
 export const astroCacheDir = path.join(astroRootDir, '.astro');
 export const generatedImagesDir = path.join(astroPublicDir, 'images', 'generated');

package/scripts/lib/sitemap.mjs

@@ -11,9 +11,11 @@ const escapeXml = (value) => String(value)
 
 const compareStrings = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 
-export const getSitemapUrls = ({ siteStructure, siteUrl }) => (
-	siteStructure.contentFiles
-		.map((page) => getSiteNodePathname(page))
+export const getSitemapUrls = ({ siteStructure, siteUrl, categoryDestinations = [] }) => (
+	[
+		...siteStructure.contentFiles.map((page) => getSiteNodePathname(page)),
+		...categoryDestinations.filter(({ kind }) => kind === 'listing').map(({ pathname }) => pathname),
+	]
 		.sort(compareStrings)
 		.map((pathname) => getAbsolutePageUrl(siteUrl, pathname))
 );

package/scripts/lib/structured-blocks.mjs

@@ -0,0 +1,108 @@
+import { isAlias, isMap, isScalar, isSeq, LineCounter, parseDocument } from 'yaml';
+
+const stringSchema = (name, definition) => ({
+	type: 'string',
+	description: definition.description,
+	...(definition.default !== undefined ? { default: definition.default } : {}),
+	...(definition.values ? { enum: Object.keys(definition.values) } : {}),
+	...(name === 'alt' ? {} : { minLength: 1 }),
+	pattern: name === 'image'
+		? '^[a-zA-Z0-9][a-zA-Z0-9.-]*\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[sS][vV][gG])$(?![\\s\\S])'
+		: name === 'caption' || name === 'text'
+			? '^(?=[\\s\\S]*\\S)[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F-\\x9F]*$(?![\\s\\S])'
+			: name === 'alt'
+				? '^(?:|(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+)$(?![\\s\\S])'
+				: '^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])',
+});
+
+export const createStructuredBlockSchema = (definition) => {
+	if (!definition?.item) return null;
+	const fields = { [definition.item.start.key]: definition.item.start, ...definition.item.fields };
+	const item = {
+		type: 'object',
+		additionalProperties: false,
+		required: [definition.item.start.key],
+		properties: Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, stringSchema(key, field)])),
+		...(definition.item.start.key === 'title' ? {
+			anyOf: ['text', 'image', 'link'].map((key) => ({ required: [key] })),
+		} : {}),
+	};
+	return {
+		$schema: 'https://json-schema.org/draft/2020-12/schema',
+		description: definition.description,
+		type: 'object',
+		additionalProperties: false,
+		required: ['items'],
+		properties: {
+			...Object.fromEntries(Object.entries(definition.options ?? {}).map(([key, field]) => [key, stringSchema(key, field)])),
+			items: { type: 'array', minItems: definition.minItems ?? 1, items: item },
+		},
+	};
+};
+
+// Validate the AST directly so errors and later link edits retain exact source ranges.
+export const parseStructuredBlock = (source, schema, options = {}) => {
+	const lines = new LineCounter();
+	const document = parseDocument(source, { schema: 'core', version: '1.2', uniqueKeys: true, lineCounter: lines });
+	const lineAt = (node) => (options.line ?? 1) + lines.linePos(node?.range?.[0] ?? 0).line - 1;
+	const fail = (message, node) => {
+		const line = lineAt(node);
+		throw Object.assign(new Error(`${options.label ? `${options.label} ` : ''}line ${line}: ${options.type}: ${message}`), { line });
+	};
+	if (document.errors.length) {
+		const error = document.errors[0];
+		fail(`Invalid YAML: ${error.message.split('\n')[0]}`, { range: error.pos });
+	}
+	if (document.directives.yaml.version !== '1.2') fail('Use YAML 1.2 Core; other YAML versions are not supported.', document.contents);
+	const validate = (node, rule, path, depth = 0) => {
+		if (depth > 16) fail('YAML nesting is too deep.', node);
+		if (node?.anchor || node?.tag || isAlias(node)) fail('YAML anchors, aliases, and explicit tags are not allowed.', node);
+		if (rule.type === 'object') {
+			if (!isMap(node)) fail(`${path} must be a YAML mapping${path === 'Block' ? ' with an items list' : ''}.`, node);
+			const result = {};
+			for (const pair of node.items) {
+				if (!isScalar(pair.key) || typeof pair.key.value !== 'string') fail(`${path} field names must be strings.`, pair.key);
+				if (pair.key.tag || pair.key.anchor) fail('YAML anchors and explicit tags are not allowed.', pair.key);
+				const key = pair.key.value;
+				if (!Object.hasOwn(rule.properties, key)) fail(`Unknown ${path} field "${key}".`, pair.key);
+				result[key] = validate(pair.value, rule.properties[key], `${path}.${key}`, depth + 1);
+			}
+			for (const key of rule.required ?? []) {
+				if (!Object.hasOwn(result, key)) fail(`${path} is missing "${key}".`, node);
+			}
+			if (rule.anyOf && !rule.anyOf.some((alternative) => alternative.required.every((key) => Object.hasOwn(result, key)))) {
+				fail(`${path} must specify at least one of text, image, or link.`, node);
+			}
+			return result;
+		}
+		if (rule.type === 'array') {
+			if (!isSeq(node)) fail(`${path} must be a YAML list.`, node);
+			if (node.items.length < rule.minItems) fail(`${path} must contain at least ${rule.minItems} item.`, node);
+			return node.items.map((item, index) => validate(item, rule.items, `${path}[${index + 1}]`, depth + 1));
+		}
+		if (!isScalar(node) || typeof node.value !== 'string') fail(`${path} must be a string; quote values that YAML would interpret as numbers, booleans, or null.`, node);
+		if (rule.enum && !rule.enum.includes(node.value)) fail(`Invalid ${path} "${node.value}". Use one of: ${rule.enum.join(', ')}.`, node);
+		if (!new RegExp(rule.pattern).test(node.value)) {
+			fail(path.endsWith('.image')
+				? 'Image reference must be a filename ending in jpg, jpeg, png, or svg.'
+				: `${path} must ${path.endsWith('.alt') ? 'be empty or contain single-line text' : 'contain non-empty text'}${/\.(caption|text)$/.test(path) ? '' : ' without line breaks or control characters'}.`, node);
+		}
+		return node.value;
+	};
+	const data = validate(document.contents, schema, 'Block');
+	const items = document.get('items', true).items;
+	data.items = data.items.map((item, index) => {
+		const node = items[index];
+		const link = node.get('link', true);
+		return {
+			...item,
+			line: lineAt(node),
+			...(link ? {
+				linkLine: lineAt(link),
+				// A block scalar owns its trailing newline; leave that separator in place when editing the value.
+				linkRange: { start: link.range[0], end: source.slice(0, link.range[1]).trimEnd().length },
+			} : {}),
+		};
+	});
+	return data;
+};

package/scripts/lib/table-render-plugin.mjs

@@ -0,0 +1,76 @@
+import { defineHastPlugin } from 'satteri';
+
+const transformTableSection = (section, { columnHeaders = false, rowHeaders = false } = {}) => ({
+	...section,
+	children: (section.children ?? []).map((child) => {
+		if (child.type !== 'element' || child.tagName !== 'tr') return child;
+		let columnIndex = 0;
+		return {
+			...child,
+			children: (child.children ?? []).map((cell) => {
+				if (cell.type !== 'element' || (cell.tagName !== 'th' && cell.tagName !== 'td')) return cell;
+				const currentColumn = columnIndex;
+				columnIndex += 1;
+				if (columnHeaders) {
+					return {
+						...cell,
+						properties: { ...(cell.properties ?? {}), scope: 'col' },
+					};
+				}
+				if (rowHeaders && currentColumn === 0) {
+					return {
+						...cell,
+						tagName: 'th',
+						properties: { ...(cell.properties ?? {}), scope: 'row' },
+					};
+				}
+				return cell;
+			}),
+		};
+	}),
+});
+
+const transformRowHeaderTable = (node) => ({
+	...node,
+	children: (node.children ?? []).map((child) => {
+		if (child.type !== 'element') return child;
+		if (child.tagName === 'thead') return transformTableSection(child, { columnHeaders: true });
+		if (child.tagName === 'tbody') return transformTableSection(child, { rowHeaders: true });
+		return child;
+	}),
+});
+
+export const nornaTableRenderPlugin = defineHastPlugin({
+	name: 'norna-table-render',
+	element: {
+		filter: ['table'],
+		visit(node, context) {
+			const hasRowHeaders = node.properties?.['data-row-headers'] === 'true';
+			const table = hasRowHeaders ? transformRowHeaderTable(node) : node;
+			context.replaceNode(node, {
+				type: 'element',
+				tagName: 'div',
+				properties: {
+					className: ['norna-table-frame', 'content-block-note-lane-boundary'],
+					'data-table-frame': '',
+					...(hasRowHeaders ? { 'data-table-row-headers': 'true' } : {}),
+				},
+				children: [{
+					type: 'element',
+					tagName: 'div',
+					properties: {
+						className: ['norna-table-scroll'],
+						'data-table-scroll': '',
+						tabIndex: 0,
+					},
+					children: [{
+						type: 'element',
+						tagName: table.tagName,
+						properties: { ...(table.properties ?? {}) },
+						children: [...(table.children ?? [])],
+					}],
+				}],
+			});
+		},
+	},
+});

package/scripts/lib/table-row-headers.mjs

@@ -0,0 +1,218 @@
+export const tableRowHeaderMarker = '{row-header}';
+
+const trailingMarkerPattern = /\s*\{row-header\}\s*$/u;
+
+const getNodeText = (node) => {
+	if (!node || typeof node !== 'object') return '';
+	if (node.type === 'text' || node.type === 'inlineCode') return node.value ?? '';
+	if (node.type === 'image') return node.alt ?? '';
+	if (!Array.isArray(node.children)) return '';
+	return node.children.map(getNodeText).join('');
+};
+
+const getUnescapedMarkerIndexes = (source) => {
+	const indexes = [];
+	let searchFrom = 0;
+	while (searchFrom < source.length) {
+		const index = source.indexOf(tableRowHeaderMarker, searchFrom);
+		if (index < 0) break;
+		let backslashes = 0;
+		for (let cursor = index - 1; cursor >= 0 && source[cursor] === '\\'; cursor -= 1) {
+			backslashes += 1;
+		}
+		if (backslashes % 2 === 0) indexes.push(index);
+		searchFrom = index + tableRowHeaderMarker.length;
+	}
+	return indexes;
+};
+
+const getTextNodeMarkerCount = (node, source) => {
+	if (node.type !== 'text' || !node.value?.includes(tableRowHeaderMarker)) return 0;
+	const start = node.position?.start.offset;
+	const end = node.position?.end.offset;
+	const raw = Number.isInteger(start) && Number.isInteger(end)
+		? source.slice(start, end)
+		: node.value;
+	return getUnescapedMarkerIndexes(raw).length;
+};
+
+const collectCellMarkers = (node, source, markers, location) => {
+	if (!node || typeof node !== 'object') return;
+	const count = getTextNodeMarkerCount(node, source);
+	for (let index = 0; index < count; index += 1) {
+		markers.push({ ...location, node });
+	}
+	for (const child of node.children ?? []) {
+		collectCellMarkers(child, source, markers, location);
+	}
+};
+
+const normalizeLabel = (value) => value.trim().replace(/\s+/gu, ' ').toLowerCase();
+
+const issue = (code, node, message, fix, otherNode = null) => ({
+	code,
+	fix,
+	message,
+	node,
+	otherNode,
+});
+
+export const inspectTableRowHeaders = (table, source = '') => {
+	if (table?.type !== 'table') return { declared: false, issues: [], valid: false };
+
+	const rows = table.children ?? [];
+	const markers = [];
+	for (const [rowIndex, row] of rows.entries()) {
+		for (const [columnIndex, cell] of (row.children ?? []).entries()) {
+			collectCellMarkers(cell, source, markers, { cell, columnIndex, rowIndex });
+		}
+	}
+
+	if (markers.length === 0) return { declared: false, issues: [], valid: false };
+
+	const issues = [];
+	const declaration = markers[0];
+	for (const repeated of markers.slice(1)) {
+		issues.push(issue(
+			'repeated-table-row-header-marker',
+			repeated.cell,
+			`A table may contain ${tableRowHeaderMarker} only once.`,
+			`Keep ${tableRowHeaderMarker} only in the first column heading.`,
+			declaration.cell,
+		));
+	}
+
+	const firstHeadingCell = rows[0]?.children?.[0];
+	if (declaration.rowIndex !== 0 || declaration.columnIndex !== 0) {
+		issues.push(issue(
+			'invalid-table-row-header-column',
+			declaration.cell,
+			`${tableRowHeaderMarker} must appear in the first column heading.`,
+			`Move ${tableRowHeaderMarker} to the end of the first heading cell.`,
+		));
+	} else if (!getNodeText(firstHeadingCell).trim().endsWith(tableRowHeaderMarker)) {
+		issues.push(issue(
+			'invalid-table-row-header-marker-position',
+			firstHeadingCell,
+			`${tableRowHeaderMarker} must be the final content in the first column heading.`,
+			`Move ${tableRowHeaderMarker} to the end of the first heading cell.`,
+		));
+	}
+
+	const headingLabel = getNodeText(firstHeadingCell).replace(trailingMarkerPattern, '').trim();
+	if (!headingLabel) {
+		issues.push(issue(
+			'empty-table-row-header-heading',
+			firstHeadingCell ?? table,
+			'The row-header column needs a visible column heading.',
+			`Write a heading before ${tableRowHeaderMarker}, for example "Feature ${tableRowHeaderMarker}".`,
+		));
+	}
+
+	if (rows.length < 2) {
+		issues.push(issue(
+			'empty-table-row-header-body',
+			table,
+			'A table with a row-header declaration needs at least one body row.',
+			'Add a body row or remove the row-header declaration.',
+		));
+	}
+
+	const labels = new Map();
+	for (const row of rows.slice(1)) {
+		const cell = row.children?.[0];
+		if (!cell) {
+			issues.push(issue(
+				'missing-table-row-header',
+				row,
+				'This table row has no cell in the row-header column.',
+				'Add a unique row label in the first column.',
+			));
+			continue;
+		}
+
+		const label = getNodeText(cell).trim().replace(/\s+/gu, ' ');
+		if (!label) {
+			issues.push(issue(
+				'empty-table-row-header',
+				cell,
+				'This table row has an empty row header.',
+				'Add a unique row label in the first column.',
+			));
+			continue;
+		}
+
+		const normalizedLabel = normalizeLabel(label);
+		const existing = labels.get(normalizedLabel);
+		if (existing) {
+			issues.push(issue(
+				'duplicate-table-row-header',
+				cell,
+				`Row header "${label}" is repeated.`,
+				'Give every row a unique label so its header association is unambiguous.',
+				existing,
+			));
+			continue;
+		}
+		labels.set(normalizedLabel, cell);
+	}
+
+	return {
+		declared: true,
+		firstHeadingCell,
+		issues,
+		markerNode: declaration.node,
+		valid: issues.length === 0,
+	};
+};
+
+const formatDiagnostic = (entry, options) => {
+	const lineOffset = options.lineOffset ?? 0;
+	const line = lineOffset + (entry.node?.position?.start.line ?? 1);
+	const otherLine = entry.otherNode
+		? lineOffset + (entry.otherNode.position?.start.line ?? 1)
+		: null;
+	const related = otherLine && otherLine !== line ? ` The first occurrence is on line ${otherLine}.` : '';
+	const label = options.label ?? 'Markdown';
+	return {
+		code: entry.code,
+		fix: entry.fix,
+		line,
+		message: `${label} line ${line}: ${entry.message}${related}`,
+		offset: entry.node?.position?.start.offset ?? 0,
+	};
+};
+
+export const getTableRowHeaderDiagnostics = (tree, options = {}) => {
+	const diagnostics = [];
+	const source = options.source ?? '';
+	const visit = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (node.type === 'table') {
+			const inspection = inspectTableRowHeaders(node, source);
+			diagnostics.push(...inspection.issues.map((entry) => formatDiagnostic(entry, options)));
+		}
+		for (const child of node.children ?? []) visit(child);
+	};
+	visit(tree);
+	return diagnostics;
+};
+
+export const applyTableRowHeaderDeclaration = (table, context) => {
+	const inspection = inspectTableRowHeaders(table, context.source);
+	if (!inspection.valid || !inspection.markerNode) return false;
+
+	context.setProperty(
+		inspection.markerNode,
+		'value',
+		inspection.markerNode.value.replace(trailingMarkerPattern, ''),
+	);
+	context.setProperty(table, 'data', {
+		...(table.data ?? {}),
+		hProperties: {
+			...(table.data?.hProperties ?? {}),
+			'data-row-headers': 'true',
+		},
+	});
+	return true;
+};

package/scripts/lib/theme-presets.mjs

@@ -50,25 +50,21 @@ export const themePresetDefinitions = Object.freeze({
 		title: 'Portfolio',
 		description: 'For portfolios and image-led sites, with restrained typography and generous space for images.',
 		recipe: themePresetRecipes.portfolio,
-		readerControls: Object.freeze({ appearance: true }),
 	}),
 	documentation: Object.freeze({
 		title: 'Documentation',
 		description: 'For guides and reference material, with reading-focused typography and compact spacing.',
 		recipe: themePresetRecipes.documentation,
-		readerControls: Object.freeze({ appearance: true, focusReading: true }),
 	}),
 	project: Object.freeze({
 		title: 'Project',
 		description: 'For project and product sites that balance explanation, code, cards, and images.',
 		recipe: themePresetRecipes.project,
-		readerControls: Object.freeze({ appearance: true, focusReading: true }),
 	}),
 	statement: Object.freeze({
 		title: 'Statement',
 		description: 'For short, expressive sites, with larger typography, airy spacing, and stronger section emphasis.',
 		recipe: themePresetRecipes.statement,
-		readerControls: Object.freeze({ appearance: true }),
 	}),
 });
 
@@ -82,7 +78,6 @@ export const themePresets = Object.freeze(Object.fromEntries(
 				themePresetDefinitions[name].recipe,
 				`${name} theme preset`,
 			),
-			readerControls: themePresetDefinitions[name].readerControls,
 		}),
 	]),
 ));
@@ -179,7 +174,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
-	const { appearance, readerControls, corners, layout, images, blocks, typography, palette, sections } = preset;
+	const { appearance, corners, layout, images, blocks, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -193,10 +188,8 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'appearance:',
 		`  default: ${appearance.default}`,
 		'',
-		'# Optional reader controls shown with the always-available reading-width choice.',
-		'readerControls:',
-		`  appearance: ${readerControls.appearance === true}`,
-		`  focusReading: ${readerControls.focusReading === true}`,
+		'# Appearance and reading width are always available in the Display panel.',
+		'# Focus reading is available automatically when navigation resolves to tree.',
 		'',
 		'# Alternatives: square, rounded.',
 		`corners: ${corners}`,

package/scripts/lib/yaml-config.mjs

@@ -36,12 +36,8 @@ const getLegacyThemeHint = (issue, data) => {
 		return 'Theme setting "colorMode" was replaced by "appearance".';
 	}
 
-	if (location === 'readerControls' && issue.keys?.includes('colorMode')) {
-		return 'Reader control "colorMode" was replaced by "appearance".';
-	}
-
-	if (location === 'readerControls' && issue.keys?.includes('readingWidth')) {
-		return 'Reader control "readingWidth" was removed because reading width is now always available. Remove this field.';
+	if (location === 'readerControls') {
+		return 'Theme setting "readerControls" was removed. Appearance and reading width are always available; Focus reading follows tree navigation. Remove this block.';
 	}
 
 	return undefined;