@refrakt-md/runes 0.33.0 → 0.35.0

package/dist/config.js

@@ -1,15 +1,15 @@
-import { isTag, readField, resolveGap, ratioToFr, resolveValign } from '@refrakt-md/transform';
+import { isTag, readField, resolveGap, ratioToFr, resolveValign, } from '@refrakt-md/transform';
 import Markdoc from '@markdoc/markdoc';
 const { Tag } = Markdoc;
-import { createComponentRenderable } from './lib/index.js';
-import { BREADCRUMB_AUTO_SENTINEL } from './tags/breadcrumb.js';
+import { applySchemaTable, createComponentRenderable } from './lib/index.js';
+import { BREADCRUMB_AUTO_SENTINEL, breadcrumbSchema } from './tags/breadcrumb.js';
 import { NAV_AUTO_SENTINEL, NAV_COLLAPSED_AUTO } from './tags/nav.js';
 import { PAGINATION_AUTO_SENTINEL } from './tags/pagination.js';
 import { resolveXrefs } from './xref-resolve.js';
 import { preprocessSnippets, wrapStandaloneSnippets } from './snippet-pipeline.js';
 import { preprocessData } from './data-pipeline.js';
 import { preprocessIncludes } from './include-pipeline.js';
-import { registerDrawers, resolveAutoDrawerTitleLevels, hoistPreviewDrawers } from './drawer-pipeline.js';
+import { registerDrawers, resolveAutoDrawerTitleLevels, hoistPreviewDrawers, } from './drawer-pipeline.js';
 import { resolveFileRefs } from './file-ref-resolve.js';
 import { resolveXrefPreviews } from './xref-preview-resolve.js';
 import { applyOutlineScopeWalkers, harvestHeadingsFromRenderable } from './outline-scope.js';
@@ -44,7 +44,12 @@ import { tabGroupSections } from './tags/tabs.js';
 /** Read text content from a property span child */
 function readPropText(node, prop) {
     for (const c of node.children) {
-        if (isTag(c) && c.attributes?.['data-field'] === prop.replace(/([a-z])([A-Z])/g, '$1-$2').replace(/([A-Z])([A-Z][a-z])/g, '$1-$2').toLowerCase()) {
+        if (isTag(c) &&
+            c.attributes?.['data-field'] ===
+                prop
+                    .replace(/([a-z])([A-Z])/g, '$1-$2')
+                    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+                    .toLowerCase()) {
             return c.children.filter((ch) => typeof ch === 'string').join('');
         }
     }
@@ -66,22 +71,35 @@ export const coreConfig = {
     icons: {},
     runes: {
         // ─── Simple runes (block name only, engine adds BEM classes) ───
-        Accordion: { block: 'accordion', defaultDensity: 'full', sections: accordionSections, autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
+        Accordion: {
+            block: 'accordion',
+            defaultDensity: 'full',
+            sections: accordionSections,
+            autoLabel: pageSectionAutoLabel,
+            editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' },
+        },
         // SPEC-125 Phase 1 — the answer panel is the item's `body` role, so
         // `reading` / `dropcap` land on it. The header decision is recorded in
         // `sectionRoleExceptions` so it travels with the rune.
         AccordionItem: {
-            block: 'accordion-item', parent: 'Accordion', requiresParent: 'Accordion',
+            block: 'accordion-item',
+            parent: 'Accordion',
+            requiresParent: 'Accordion',
             rootAttributes: { 'data-state': 'closed' },
             autoLabel: { name: 'header' },
             sections: accordionItemSections,
             provides: ['prose'],
             sectionRoleExceptions: {
-                header: 'The `header` slot is the <summary> disclosure control, not a page-section header. `header` would inherit the chrome-row rhythm (a 3rem margin under every summary); `title` would tighten every summary\'s line-height while leaving `prominence` inert anyway, since `.rf-accordion-item__header` pins the control\'s font size on purpose. The parent Accordion already holds `title`.',
+                header: "The `header` slot is the <summary> disclosure control, not a page-section header. `header` would inherit the chrome-row rhythm (a 3rem margin under every summary); `title` would tighten every summary's line-height while leaving `prominence` inert anyway, since `.rf-accordion-item__header` pins the control's font size on purpose. The parent Accordion already holds `title`.",
             },
             editHints: { header: 'inline', body: 'none' },
         },
-        Details: { block: 'details', defaultElevation: 'flush', autoLabel: { summary: 'summary' }, editHints: { summary: 'inline', body: 'none' } },
+        Details: {
+            block: 'details',
+            defaultElevation: 'flush',
+            autoLabel: { summary: 'summary' },
+            editHints: { summary: 'inline', body: 'none' },
+        },
         Grid: {
             block: 'grid',
             defaultDensity: 'full',
@@ -110,7 +128,10 @@ export const coreConfig = {
             interactive: true,
             defaultDensity: 'compact',
             defaultElevation: 'flat',
-            modifiers: { title: { source: 'meta', noBemClass: true }, overflow: { source: 'meta', default: 'scroll' } },
+            modifiers: {
+                title: { source: 'meta', noBemClass: true },
+                overflow: { source: 'meta', default: 'scroll' },
+            },
             // The window chrome (three dots) is pure decoration — drawn in CSS
             // on `.rf-codegroup__topbar`. The only metadata is the optional
             // filename `title`, a bare monospace field in the topbar bar.
@@ -263,7 +284,11 @@ export const coreConfig = {
                 separator: { prop: '--separator', template: '"{}"' },
             },
         },
-        BreadcrumbItem: { block: 'breadcrumb-item', parent: 'Breadcrumb', requiresParent: 'Breadcrumb' },
+        BreadcrumbItem: {
+            block: 'breadcrumb-item',
+            parent: 'Breadcrumb',
+            requiresParent: 'Breadcrumb',
+        },
         Blog: {
             block: 'blog',
             defaultDensity: 'full',
@@ -327,7 +352,7 @@ export const coreConfig = {
             defaultDensity: 'compact',
             defaultElevation: 'sunken',
             modifiers: { hintType: { source: 'meta', default: 'note' } },
-            contextModifiers: { 'hero': 'in-hero', 'feature': 'in-feature' },
+            contextModifiers: { hero: 'in-hero', feature: 'in-feature' },
             sections: hintSections,
             // SPEC-035 Zone 6 — the hintType value doubles as the visible title
             // (CSS capitalizes it). Declaring it as an enum lets `core.hint.<value>`
@@ -401,7 +426,12 @@ export const coreConfig = {
             modifiers: { layout: { source: 'meta', default: 'side-by-side' } },
             editHints: { panels: 'none' },
         },
-        Conversation: { block: 'conversation', defaultDensity: 'compact', defaultElevation: 'flush', editHints: { messages: 'none' } },
+        Conversation: {
+            block: 'conversation',
+            defaultDensity: 'compact',
+            defaultElevation: 'flush',
+            editHints: { messages: 'none' },
+        },
         ConversationMessage: {
             block: 'conversation-message',
             parent: 'Conversation',
@@ -444,7 +474,7 @@ export const coreConfig = {
                 // Extract slug from span[property="slug"] child → data-slug attribute
                 // Keep slug text as visible fallback for SSR; web component replaces with <a> links
                 let slug = '';
-                const children = node.children.filter(child => {
+                const children = node.children.filter((child) => {
                     if (isTag(child) && child.name === 'span' && child.attributes['data-field'] === 'slug') {
                         slug = child.children.filter((c) => typeof c === 'string').join('');
                         return false; // remove slug span from DOM
@@ -461,10 +491,16 @@ export const coreConfig = {
                     };
                 }
                 // Explicit link item: add nav-item__link class to <a> tags for styling
-                const styledChildren = children.map(child => {
+                const styledChildren = children.map((child) => {
                     if (isTag(child) && child.name === 'a') {
                         const existing = child.attributes.class || '';
-                        return { ...child, attributes: { ...child.attributes, class: ['rf-nav-item__link', existing].filter(Boolean).join(' ') } };
+                        return {
+                            ...child,
+                            attributes: {
+                                ...child.attributes,
+                                class: ['rf-nav-item__link', existing].filter(Boolean).join(' '),
+                            },
+                        };
                     }
                     return child;
                 });
@@ -474,7 +510,12 @@ export const coreConfig = {
         Diff: {
             block: 'diff',
             modifiers: { mode: { source: 'meta', default: 'unified' } },
-            editHints: { line: 'none', 'gutter-num': 'none', 'gutter-prefix': 'none', 'line-content': 'none' },
+            editHints: {
+                line: 'none',
+                'gutter-num': 'none',
+                'gutter-prefix': 'none',
+                'line-content': 'none',
+            },
         },
         Chart: {
             block: 'chart',
@@ -550,9 +591,27 @@ export const coreConfig = {
             editHints: { viewport: 'none' },
         },
         // ─── Interactive runes (still get BEM classes, components add behavior) ───
-        TabGroup: { block: 'tabs', interactive: true, defaultDensity: 'full', sections: tabGroupSections, autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
-        Tab: { block: 'tab', parent: 'TabGroup', requiresParent: 'TabGroup', rootAttributes: { 'data-state': 'inactive' }, editHints: { name: 'inline' } },
-        TabPanel: { block: 'tab-panel', parent: 'TabGroup', requiresParent: 'TabGroup', rootAttributes: { 'data-state': 'inactive' } },
+        TabGroup: {
+            block: 'tabs',
+            interactive: true,
+            defaultDensity: 'full',
+            sections: tabGroupSections,
+            autoLabel: pageSectionAutoLabel,
+            editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' },
+        },
+        Tab: {
+            block: 'tab',
+            parent: 'TabGroup',
+            requiresParent: 'TabGroup',
+            rootAttributes: { 'data-state': 'inactive' },
+            editHints: { name: 'inline' },
+        },
+        TabPanel: {
+            block: 'tab-panel',
+            parent: 'TabGroup',
+            requiresParent: 'TabGroup',
+            rootAttributes: { 'data-state': 'inactive' },
+        },
         DataTable: {
             block: 'datatable',
             interactive: true,
@@ -601,7 +660,12 @@ export const coreConfig = {
             autoLabel: pageSectionAutoLabel,
             editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline', steps: 'none' },
         },
-        RevealStep: { block: 'reveal-step', parent: 'Reveal', rootAttributes: { 'data-state': 'closed' }, editHints: { body: 'none' } },
+        RevealStep: {
+            block: 'reveal-step',
+            parent: 'Reveal',
+            rootAttributes: { 'data-state': 'closed' },
+            editHints: { body: 'none' },
+        },
         Section: {
             block: 'section',
             modifiers: {
@@ -627,7 +691,13 @@ export const coreConfig = {
             },
             editHints: { panels: 'none' },
         },
-        JuxtaposePanel: { block: 'juxtapose-panel', parent: 'Juxtapose', requiresParent: 'Juxtapose', rootAttributes: { 'data-state': 'inactive' }, editHints: { body: 'none' } },
+        JuxtaposePanel: {
+            block: 'juxtapose-panel',
+            parent: 'Juxtapose',
+            requiresParent: 'Juxtapose',
+            rootAttributes: { 'data-state': 'inactive' },
+            editHints: { body: 'none' },
+        },
         Diagram: {
             block: 'diagram',
             defaultDensity: 'compact',
@@ -712,7 +782,7 @@ function deriveParentUrl(url) {
 function resolveAutoBreadcrumbs(renderable, pageUrl, breadcrumbPaths, pagesByUrl, ctx) {
     if (!Tag.isTag(renderable)) {
         if (Array.isArray(renderable)) {
-            const newChildren = renderable.map(c => resolveAutoBreadcrumbs(c, pageUrl, breadcrumbPaths, pagesByUrl, ctx));
+            const newChildren = renderable.map((c) => resolveAutoBreadcrumbs(c, pageUrl, breadcrumbPaths, pagesByUrl, ctx));
             // Return original if nothing changed
             if (newChildren.every((c, i) => c === renderable[i]))
                 return renderable;
@@ -744,7 +814,19 @@ function buildAutoBreadcrumb(originalTag, pageUrl, breadcrumbPaths, pagesByUrl,
     // Find separator from existing meta child
     const separatorMeta = originalTag.children?.find((c) => Tag.isTag(c) && c.name === 'meta' && !c.attributes?.['data-field']);
     const separator = separatorMeta?.attributes?.content ?? '/';
-    // Build breadcrumb items: ancestor pages + current page (no link)
+    // Build breadcrumb items: ancestor pages + current page (no link).
+    //
+    // WORK-563 — the schema is not decoration on this path. `collectJsonLd`
+    // nests a typed node into its parent only when that node carries *both*
+    // `typeof` and `property`. Without them this hook emitted a
+    // `BreadcrumbList` with no `itemListElement` and a `ListItem` floating up
+    // beside it as a detached, empty top-level entity — while rendering a
+    // perfectly correct trail.
+    //
+    // The explicit `{% breadcrumb %}` form (tags/breadcrumb.ts) has always got
+    // this right. This path is the same output contract and must match it: the
+    // bar is that an auto trail publishes what the same trail written by hand
+    // would.
     const listItems = [];
     for (const ancestorUrl of ancestorUrls) {
         const ancestorPage = pagesByUrl.get(ancestorUrl);
@@ -752,7 +834,8 @@ function buildAutoBreadcrumb(originalTag, pageUrl, breadcrumbPaths, pagesByUrl,
             continue;
         const nameSpan = new Tag('span', { hidden: true }, [ancestorPage.title]);
         const urlLink = new Tag('a', { href: ancestorUrl }, [ancestorPage.title]);
-        listItems.push(createComponentRenderable({ rune: 'breadcrumb-item', schemaOrgType: 'ListItem',
+        listItems.push(createComponentRenderable({
+            rune: 'breadcrumb-item',
             tag: 'li',
             properties: { name: nameSpan, url: urlLink },
             children: [nameSpan, urlLink],
@@ -762,25 +845,38 @@ function buildAutoBreadcrumb(originalTag, pageUrl, breadcrumbPaths, pagesByUrl,
     const currentPage = pagesByUrl.get(pageUrl);
     const currentTitle = currentPage?.title ?? pageUrl;
     const currentSpan = new Tag('span', {}, [currentTitle]);
-    listItems.push(createComponentRenderable({ rune: 'breadcrumb-item', schemaOrgType: 'ListItem',
+    listItems.push(createComponentRenderable({
+        rune: 'breadcrumb-item',
         tag: 'li',
         properties: { name: currentSpan },
         children: [currentSpan],
     }));
     const newSeparatorMeta = new Tag('meta', { content: separator });
     const itemsList = new Tag('ol', {}, listItems);
-    return createComponentRenderable({ rune: 'breadcrumb', schemaOrgType: 'BreadcrumbList',
+    const node = createComponentRenderable({
+        rune: 'breadcrumb',
         tag: 'nav',
         properties: { separator: newSeparatorMeta },
         refs: { items: itemsList },
         children: [newSeparatorMeta, itemsList],
     });
+    // SPEC-130 D8 / WORK-571 — the hook calls the applier itself.
+    //
+    // `buildAutoBreadcrumb` runs from a `postProcess` hook, not from a Markdoc
+    // schema, so the `createContentModelSchema` wrapper that normally applies a
+    // rune's table cannot reach it. One extra call site keeps "the imperative
+    // form is fully migrated, not half of each" exceptionless rather than
+    // carving out the one emitter that happens to live in a pipeline phase —
+    // and, more to the point, it means both breadcrumb paths publish from the
+    // *same* table rather than from a declaration and a hand-written copy of it
+    // that can drift.
+    return applySchemaTable(node, breadcrumbSchema, {});
 }
 /** Walk a Markdoc renderable tree, resolving any auto-nav placeholders */
 function resolveAutoNavs(renderable, pageUrl, pagesByUrl, ctx) {
     if (!Tag.isTag(renderable)) {
         if (Array.isArray(renderable)) {
-            const newChildren = renderable.map(c => resolveAutoNavs(c, pageUrl, pagesByUrl, ctx));
+            const newChildren = renderable.map((c) => resolveAutoNavs(c, pageUrl, pagesByUrl, ctx));
             if (newChildren.every((c, i) => c === renderable[i]))
                 return renderable;
             return newChildren;
@@ -808,21 +904,23 @@ function resolveAutoNavs(renderable, pageUrl, pagesByUrl, ctx) {
  *  declared. */
 function buildAutoNav(pageUrl, pagesByUrl, ctx, originalTag) {
     // Find direct children: pages whose parentUrl is this page's URL (excluding self)
-    const children = Array.from(pagesByUrl.values()).filter(p => p.parentUrl === pageUrl && p.url !== pageUrl);
+    const children = Array.from(pagesByUrl.values()).filter((p) => p.parentUrl === pageUrl && p.url !== pageUrl);
     if (children.length === 0) {
         ctx.warn(`Nav auto: page '${pageUrl}' has no registered child pages`, pageUrl);
     }
-    const listItems = children.map(child => {
+    const listItems = children.map((child) => {
         const titleSpan = new Tag('span', { 'data-field': 'slug' }, [child.title]);
         const link = new Tag('a', { href: child.url }, [titleSpan]);
-        return createComponentRenderable({ rune: 'nav-item',
+        return createComponentRenderable({
+            rune: 'nav-item',
             tag: 'li',
             properties: { slug: titleSpan },
             children: [link],
         });
     });
     const itemsList = new Tag('ul', {}, listItems);
-    const newNav = createComponentRenderable({ rune: 'nav',
+    const newNav = createComponentRenderable({
+        rune: 'nav',
         tag: 'nav',
         properties: {
             group: [],
@@ -832,7 +930,14 @@ function buildAutoNav(pageUrl, pagesByUrl, ctx, originalTag) {
     });
     // Preserve contextual attributes from the original nav so layout / auto /
     // source-path survive sentinel replacement.
-    const carry = ['layout', 'data-layout', 'data-auto', 'data-source-path', 'data-collapsible', 'data-default-open'];
+    const carry = [
+        'layout',
+        'data-layout',
+        'data-auto',
+        'data-source-path',
+        'data-collapsible',
+        'data-default-open',
+    ];
     for (const k of carry) {
         const v = originalTag?.attributes?.[k];
         if (v !== undefined) {
@@ -920,7 +1025,7 @@ function findNavSlugSuggestions(slug, baseDir, pagesByUrl) {
     }
     sameSlug.sort();
     typoMatches.sort((a, b) => a.distance - b.distance || a.url.localeCompare(b.url));
-    const suggestions = [...sameSlug, ...typoMatches.map(t => t.url)];
+    const suggestions = [...sameSlug, ...typoMatches.map((t) => t.url)];
     return suggestions.slice(0, 3);
 }
 /** SPEC-055 nav-location-relative slug resolution.
@@ -960,15 +1065,14 @@ function sharedPrefixLength(a, b) {
  *  been migrated to use pre-resolved hrefs yet. SPEC-055's
  *  `resolveNavSlug` is the canonical resolver for new code. */
 function resolveSlugToUrl(slug, pagesByUrl, currentUrl) {
-    const candidates = Array.from(pagesByUrl.values()).filter(p => p.url.endsWith('/' + slug) || p.url === '/' + slug);
+    const candidates = Array.from(pagesByUrl.values()).filter((p) => p.url.endsWith('/' + slug) || p.url === '/' + slug);
     if (candidates.length === 0)
         return null;
     if (candidates.length === 1)
         return candidates[0].url;
     return candidates
         .slice()
-        .sort((a, b) => sharedPrefixLength(b.url, currentUrl) - sharedPrefixLength(a.url, currentUrl))[0]
-        .url;
+        .sort((a, b) => sharedPrefixLength(b.url, currentUrl) - sharedPrefixLength(a.url, currentUrl))[0].url;
 }
 /** Read a NavItem's slug from either `data-slug` (post-engine) or a nested
  *  `<span data-field="slug">` (pre-engine, e.g. layout regions). */
@@ -1084,7 +1188,7 @@ function urlMatchesGroup(currentUrl, itemUrls) {
 function resolveCollapsibleNavs(renderable, pageUrl, pagesByUrl) {
     if (!Tag.isTag(renderable)) {
         if (Array.isArray(renderable)) {
-            const newChildren = renderable.map(c => resolveCollapsibleNavs(c, pageUrl, pagesByUrl));
+            const newChildren = renderable.map((c) => resolveCollapsibleNavs(c, pageUrl, pagesByUrl));
             if (newChildren.every((c, i) => c === renderable[i]))
                 return renderable;
             return newChildren;
@@ -1092,11 +1196,13 @@ function resolveCollapsibleNavs(renderable, pageUrl, pagesByUrl) {
         return renderable;
     }
     const tag = renderable;
-    if (tag.attributes?.['data-rune'] === 'nav' &&
-        tag.attributes?.['data-collapsible'] === 'true') {
+    if (tag.attributes?.['data-rune'] === 'nav' && tag.attributes?.['data-collapsible'] === 'true') {
         const defaultOpenRaw = String(tag.attributes?.['data-default-open'] ?? '');
         const defaultOpen = defaultOpenRaw
-            ? defaultOpenRaw.split(',').map(s => s.trim()).filter(Boolean)
+            ? defaultOpenRaw
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)
             : [];
         const groups = [];
         const findGroups = (node) => {
@@ -1116,7 +1222,7 @@ function resolveCollapsibleNavs(renderable, pageUrl, pagesByUrl) {
             const inDefault = title && defaultOpen.includes(title);
             const itemUrls = collectGroupItemUrls(group, pagesByUrl, pageUrl);
             const matches = urlMatchesGroup(pageUrl, itemUrls);
-            group.attributes['data-collapsed'] = (inDefault || matches) ? 'false' : 'true';
+            group.attributes['data-collapsed'] = inDefault || matches ? 'false' : 'true';
         }
         const newChildren = (tag.children ?? []).map((c) => resolveCollapsibleNavs(c, pageUrl, pagesByUrl));
         if (newChildren.every((c, i) => c === tag.children[i]))
@@ -1139,7 +1245,9 @@ function enrichNavItemAsCard(item, pageMeta, itemUrl) {
     }
     linkChildren.push(new Tag('span', { 'data-name': 'title', class: 'rf-nav-item__title' }, [titleText]));
     if (description) {
-        linkChildren.push(new Tag('span', { 'data-name': 'description', class: 'rf-nav-item__description' }, [description]));
+        linkChildren.push(new Tag('span', { 'data-name': 'description', class: 'rf-nav-item__description' }, [
+            description,
+        ]));
     }
     const link = href
         ? new Tag('a', { href, class: 'rf-nav-item__link' }, linkChildren)
@@ -1206,7 +1314,9 @@ function augmentNavItemFromFrontmatter(item, pageMeta) {
             newLinkChildren.unshift(new Tag('rf-icon', { name: pageMeta.icon, 'data-name': 'icon', class: 'rf-nav-item__icon' }, []));
         }
         if (pageMeta.description && !hasDescription) {
-            newLinkChildren.push(new Tag('span', { 'data-name': 'description', class: 'rf-nav-item__description' }, [pageMeta.description]));
+            newLinkChildren.push(new Tag('span', { 'data-name': 'description', class: 'rf-nav-item__description' }, [
+                pageMeta.description,
+            ]));
         }
         return { ...t, children: newLinkChildren };
     });
@@ -1215,7 +1325,7 @@ function augmentNavItemFromFrontmatter(item, pageMeta) {
 function resolveCardsNavs(renderable, pageUrl, pagesByUrl) {
     if (!Tag.isTag(renderable)) {
         if (Array.isArray(renderable)) {
-            const newChildren = renderable.map(c => resolveCardsNavs(c, pageUrl, pagesByUrl));
+            const newChildren = renderable.map((c) => resolveCardsNavs(c, pageUrl, pagesByUrl));
             if (newChildren.every((c, i) => c === renderable[i]))
                 return renderable;
             return newChildren;
@@ -1291,7 +1401,13 @@ function formatNavResolutionError(slug, sourcePath, attemptedUrl, suggestions) {
     const head = `Nav item \`${slug}\`${where} cannot be resolved (no page at \`${attemptedUrl}\`).`;
     if (suggestions.length === 0)
         return head;
-    const lines = ['', 'Did you mean one of:', ...suggestions.map(s => `  - ${s}`), '', 'Use a multi-segment slug (e.g. `section/page`) or an explicit `[Label](/path)` link.'];
+    const lines = [
+        '',
+        'Did you mean one of:',
+        ...suggestions.map((s) => `  - ${s}`),
+        '',
+        'Use a multi-segment slug (e.g. `section/page`) or an explicit `[Label](/path)` link.',
+    ];
     return head + '\n' + lines.join('\n');
 }
 /** Walk a nav subtree, resolve every NavItem's `data-slug` to a real `<a href>`
@@ -1354,7 +1470,7 @@ function resolveNavItemsInSubtree(navTag, pagesByUrl, ctx, pageUrl) {
 function resolveNavSlugs(renderable, pagesByUrl, ctx, pageUrl) {
     if (!Tag.isTag(renderable)) {
         if (Array.isArray(renderable)) {
-            const next = renderable.map(c => resolveNavSlugs(c, pagesByUrl, ctx, pageUrl));
+            const next = renderable.map((c) => resolveNavSlugs(c, pagesByUrl, ctx, pageUrl));
             return next.every((c, i) => c === renderable[i]) ? renderable : next;
         }
         return renderable;
@@ -1570,10 +1686,10 @@ function getSiblingPages(currentUrl, pagesByUrl, scope) {
             cursor = parent;
         }
         const prefix = sectionRoot.endsWith('/') ? sectionRoot : sectionRoot + '/';
-        candidates = pages.filter(p => p.url === sectionRoot || p.url.startsWith(prefix));
+        candidates = pages.filter((p) => p.url === sectionRoot || p.url.startsWith(prefix));
     }
     else {
-        candidates = pages.filter(p => p.parentUrl === current.parentUrl);
+        candidates = pages.filter((p) => p.parentUrl === current.parentUrl);
     }
     // Sort by frontmatter order (asc, missing → end), tie-break by URL.
     candidates.sort((a, b) => {
@@ -1583,7 +1699,7 @@ function getSiblingPages(currentUrl, pagesByUrl, scope) {
             return ao - bo;
         return a.url.localeCompare(b.url);
     });
-    return candidates.map(p => ({ url: p.url, title: p.title }));
+    return candidates.map((p) => ({ url: p.url, title: p.title }));
 }
 function pickPrevNextFromSequence(sequence, currentUrl, pagesByUrl) {
     const idx = sequence.indexOf(currentUrl);
@@ -1620,7 +1736,7 @@ function buildPaginationLink(target, direction, label) {
 function resolveAutoPagination(renderable, pageUrl, pagesByUrl, rootRenderable) {
     if (!Tag.isTag(renderable)) {
         if (Array.isArray(renderable)) {
-            const newChildren = renderable.map(c => resolveAutoPagination(c, pageUrl, pagesByUrl, rootRenderable));
+            const newChildren = renderable.map((c) => resolveAutoPagination(c, pageUrl, pagesByUrl, rootRenderable));
             if (newChildren.every((c, i) => c === renderable[i]))
                 return renderable;
             return newChildren;
@@ -1638,10 +1754,14 @@ function resolveAutoPagination(renderable, pageUrl, pagesByUrl, rootRenderable)
             const scope = (scopeValue === 'section' ? 'section' : 'siblings');
             const prevLabelMeta = (tag.children ?? []).find((c) => Tag.isTag(c) && c.attributes?.['data-field'] === 'prev-label');
             const nextLabelMeta = (tag.children ?? []).find((c) => Tag.isTag(c) && c.attributes?.['data-field'] === 'next-label');
-            const prevLabel = prevLabelMeta ? String(prevLabelMeta.attributes.content ?? '') : undefined;
-            const nextLabel = nextLabelMeta ? String(nextLabelMeta.attributes.content ?? '') : undefined;
+            const prevLabel = prevLabelMeta
+                ? String(prevLabelMeta.attributes.content ?? '')
+                : undefined;
+            const nextLabel = nextLabelMeta
+                ? String(nextLabelMeta.attributes.content ?? '')
+                : undefined;
             // Skip when current page is a section index (has children)
-            const hasChildren = Array.from(pagesByUrl.values()).some(p => p.parentUrl === pageUrl && p.url !== pageUrl);
+            const hasChildren = Array.from(pagesByUrl.values()).some((p) => p.parentUrl === pageUrl && p.url !== pageUrl);
             if (hasChildren) {
                 return { ...tag, children: [] };
             }
@@ -1662,7 +1782,7 @@ function resolveAutoPagination(renderable, pageUrl, pagesByUrl, rootRenderable)
             else {
                 // 2. Sibling pages by frontmatter order → directory order
                 const siblings = getSiblingPages(pageUrl, pagesByUrl, scope);
-                const idx = siblings.findIndex(s => s.url === pageUrl);
+                const idx = siblings.findIndex((s) => s.url === pageUrl);
                 if (idx !== -1) {
                     prev = idx > 0 ? siblings[idx - 1] : null;
                     next = idx < siblings.length - 1 ? siblings[idx + 1] : null;
@@ -1689,7 +1809,9 @@ function resolveAutoPagination(renderable, pageUrl, pagesByUrl, rootRenderable)
         const newChildren = (tag.children ?? []).map((c) => {
             if (!Tag.isTag(c))
                 return c;
-            if (c.name === 'a' && typeof c.attributes?.href === 'string' && c.attributes.href.startsWith('__slug:')) {
+            if (c.name === 'a' &&
+                typeof c.attributes?.href === 'string' &&
+                c.attributes.href.startsWith('__slug:')) {
                 const slug = c.attributes.href.slice('__slug:'.length);
                 const resolvedUrl = resolveSlugToUrl(slug, pagesByUrl, pageUrl);
                 if (resolvedUrl) {
@@ -1698,14 +1820,20 @@ function resolveAutoPagination(renderable, pageUrl, pagesByUrl, rootRenderable)
                     // Replace label text if user didn't override (label child has same text as slug)
                     const newChildren = (c.children ?? []).map((child) => {
                         if (Tag.isTag(child) && child.attributes?.['data-name'] === 'label') {
-                            const currentLabel = (child.children ?? []).filter((x) => typeof x === 'string').join('');
+                            const currentLabel = (child.children ?? [])
+                                .filter((x) => typeof x === 'string')
+                                .join('');
                             if (currentLabel === slug) {
                                 return { ...child, children: [newLabel] };
                             }
                         }
                         return child;
                     });
-                    return { ...c, attributes: { ...c.attributes, href: resolvedUrl }, children: newChildren };
+                    return {
+                        ...c,
+                        attributes: { ...c.attributes, href: resolvedUrl },
+                        children: newChildren,
+                    };
                 }
             }
             return c;
@@ -1724,7 +1852,7 @@ function walkBlogTags(node, fn) {
             walkBlogTags(child, fn);
     }
     else if (Array.isArray(node)) {
-        node.forEach(n => walkBlogTags(n, fn));
+        node.forEach((n) => walkBlogTags(n, fn));
     }
 }
 function mapBlogTags(node, fn) {
@@ -1732,12 +1860,12 @@ function mapBlogTags(node, fn) {
         const mapped = fn(node);
         if (mapped !== node)
             return mapped;
-        const newChildren = node.children.map(c => mapBlogTags(c, fn));
+        const newChildren = node.children.map((c) => mapBlogTags(c, fn));
         const changed = newChildren.some((c, i) => c !== node.children[i]);
         return changed ? new Tag(node.name, node.attributes, newChildren) : node;
     }
     if (Array.isArray(node))
-        return node.map(n => mapBlogTags(n, fn));
+        return node.map((n) => mapBlogTags(n, fn));
     return node;
 }
 /** Normalise folder path for prefix matching: ensure leading slash and trailing slash */
@@ -1761,7 +1889,7 @@ function isInFolder(pageUrl, folder) {
 function parseBlogFilter(filter) {
     if (!filter || !filter.trim())
         return [];
-    return filter.split(',').map(part => {
+    return filter.split(',').map((part) => {
         const colonIdx = part.indexOf(':');
         if (colonIdx === -1)
             return { field: part.trim(), value: '' };
@@ -1780,7 +1908,7 @@ function matchesBlogFilter(post, filters) {
                 return false;
         }
         else if (Array.isArray(fmValue)) {
-            if (!fmValue.some(v => String(v).toLowerCase() === value.toLowerCase()))
+            if (!fmValue.some((v) => String(v).toLowerCase() === value.toLowerCase()))
                 return false;
         }
         else {
@@ -1812,9 +1940,7 @@ function sortBlogPosts(posts, sort) {
 }
 /** Build an <article> Tag for a single blog post entry */
 function createBlogPostTag(post) {
-    const titleTag = new Tag('h3', {}, [
-        new Tag('a', { href: post.url }, [post.title]),
-    ]);
+    const titleTag = new Tag('h3', {}, [new Tag('a', { href: post.url }, [post.title])]);
     const children = [titleTag];
     if (post.date) {
         children.push(new Tag('time', { datetime: post.date }, [post.date]));
@@ -1843,7 +1969,7 @@ function resolveBlogPosts(renderable, allPosts, ctx, pageUrl) {
         }
         const normalised = normaliseFolderPath(folder);
         const filters = parseBlogFilter(filterStr);
-        let posts = allPosts.filter(post => {
+        let posts = allPosts.filter((post) => {
             if (post.draft)
                 return false;
             if (!isInFolder(post.url, normalised))
@@ -1890,9 +2016,7 @@ navSearchScope) {
     result = resolveNavSlugs(result, coreData.pagesByUrl, ctx, pageUrl);
     result = resolveCollapsibleNavs(result, pageUrl, coreData.pagesByUrl);
     result = resolveCardsNavs(result, pageUrl, coreData.pagesByUrl);
-    const searchRoot = navSearchScope && navSearchScope.length > 0
-        ? [result, ...navSearchScope]
-        : result;
+    const searchRoot = navSearchScope && navSearchScope.length > 0 ? [result, ...navSearchScope] : result;
     result = resolveAutoPagination(result, pageUrl, coreData.pagesByUrl, searchRoot);
     // SPEC-055 — mark aria-current / data-active="ancestor" on resolved nav
     // links per page. Runs after slug + auto-pagination resolution so the
@@ -1918,9 +2042,15 @@ navSearchScope) {
  * any custom field.
  */
 const RESERVED_PAGE_FRONTMATTER = new Set([
-    'layout', 'tint', 'tint-mode', 'tint-lock', 'slug', 'redirect',
+    'layout',
+    'tint',
+    'tint-mode',
+    'tint-lock',
+    'slug',
+    'redirect',
     // entity-declaration keys (SPEC-092 Layer 2) — meta, not queryable content
-    'type', 'id',
+    'type',
+    'id',
 ]);
 export function createCorePipelineHooks(opts = {}) {
     const xrefPatterns = opts.xrefPatterns ?? [];
@@ -1941,7 +2071,7 @@ export function createCorePipelineHooks(opts = {}) {
             const includeChanged = preprocessIncludes(ast, page, ctx);
             const snippetChanged = preprocessSnippets(ast, page, ctx);
             const dataChanged = preprocessData(ast, page, ctx);
-            return (includeChanged || snippetChanged || dataChanged) ? ast : undefined;
+            return includeChanged || snippetChanged || dataChanged ? ast : undefined;
         },
         register(pages, registry, ctx) {
             for (const page of pages) {
@@ -1995,7 +2125,7 @@ export function createCorePipelineHooks(opts = {}) {
         },
         aggregate(registry, ctx) {
             const pageEntities = registry.getAll('page');
-            const pages = pageEntities.map(e => ({
+            const pages = pageEntities.map((e) => ({
                 url: e.data.url,
                 title: e.data.title,
                 parentUrl: e.data.parentUrl,
@@ -2006,14 +2136,14 @@ export function createCorePipelineHooks(opts = {}) {
             const pageTree = buildPageTree(pages);
             const breadcrumbPaths = buildBreadcrumbPaths(pages);
             // Quick lookup: url → { url, title } for postProcess use
-            const pagesByUrl = new Map(pages.map(p => [p.url, p]));
+            const pagesByUrl = new Map(pages.map((p) => [p.url, p]));
             // Build heading index: "url#id" → heading data
             const headingIndex = new Map();
             for (const h of registry.getAll('heading')) {
                 headingIndex.set(h.id, h.data);
             }
             // Blog: collect all pages as potential blog posts
-            const allPosts = pageEntities.map(e => ({
+            const allPosts = pageEntities.map((e) => ({
                 title: e.data.title || '',
                 url: e.data.url || e.id,
                 date: e.data.date || '',
@@ -2021,7 +2151,18 @@ export function createCorePipelineHooks(opts = {}) {
                 draft: e.data.draft || false,
                 frontmatter: e.data,
             }));
-            return { pageTree, breadcrumbPaths, pagesByUrl, headingIndex, allPosts, registry, xrefPatterns, embedConfig, repoUrl, repoBranch };
+            return {
+                pageTree,
+                breadcrumbPaths,
+                pagesByUrl,
+                headingIndex,
+                allPosts,
+                registry,
+                xrefPatterns,
+                embedConfig,
+                repoUrl,
+                repoBranch,
+            };
         },
         postProcess(page, aggregated, ctx) {
             const coreData = aggregated['__core__'];