@refrakt-md/runes 0.14.2 → 0.14.4

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA+B,MAAM,uBAAuB,CAAC;AAEtF,OAAO,KAAK,EAAE,mBAAmB,EAAmB,cAAc,EAAkB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAiF/H;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAitBxB,CAAC;AAEF,sGAAsG;AACtG,eAAO,MAAM,UAAU,aAAa,CAAC;AAIrC,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AAs3BD,UAAU,YAAY;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAiLD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;IACT,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChI,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CACnC,EACD,GAAG,EAAE,eAAe;AACpB;;yEAEyE;AACzE,cAAc,CAAC,EAAE,OAAO,EAAE,GACxB,OAAO,CAYT;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAqJ/B,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA+B,MAAM,uBAAuB,CAAC;AAEtF,OAAO,KAAK,EAAE,mBAAmB,EAAmB,cAAc,EAAkB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAiF/H;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAitBxB,CAAC;AAEF,sGAAsG;AACtG,eAAO,MAAM,UAAU,aAAa,CAAC;AAIrC,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AA0vCD,UAAU,YAAY;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAiLD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;IACT,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChI,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CACnC,EACD,GAAG,EAAE,eAAe;AACpB;;yEAEyE;AACzE,cAAc,CAAC,EAAE,OAAO,EAAE,GACxB,OAAO,CAqBT;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAgK/B,CAAC"}

package/dist/config.js

@@ -897,7 +897,7 @@ function resolveAutoNavs(renderable, pageUrl, pagesByUrl, ctx) {
     if (tag.attributes?.['data-rune'] === 'nav') {
         const hasSentinel = tag.children?.some((c) => Tag.isTag(c) && c.attributes?.['data-field'] === NAV_AUTO_SENTINEL);
         if (hasSentinel) {
-            return buildAutoNav(pageUrl, pagesByUrl, ctx);
+            return buildAutoNav(pageUrl, pagesByUrl, ctx, tag);
         }
     }
     // Recurse into children
@@ -906,8 +906,12 @@ function resolveAutoNavs(renderable, pageUrl, pagesByUrl, ctx) {
         return tag;
     return { ...tag, children: newChildren };
 }
-/** Build a resolved nav Tag from the direct children of the current page */
-function buildAutoNav(pageUrl, pagesByUrl, ctx) {
+/** Build a resolved nav Tag from the direct children of the current page.
+ *  Preserves contextual attributes from the original sentinel-bearing nav
+ *  (layout, data-auto, data-source-path) so downstream resolvers — including
+ *  the cards/auto enrichment pass — see the same configuration the author
+ *  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);
     if (children.length === 0) {
@@ -923,7 +927,7 @@ function buildAutoNav(pageUrl, pagesByUrl, ctx) {
         });
     });
     const itemsList = new Tag('ul', {}, listItems);
-    return createComponentRenderable({ rune: 'nav',
+    const newNav = createComponentRenderable({ rune: 'nav',
         tag: 'nav',
         properties: {
             group: [],
@@ -931,6 +935,123 @@ function buildAutoNav(pageUrl, pagesByUrl, ctx) {
         },
         children: [itemsList],
     });
+    // 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'];
+    for (const k of carry) {
+        const v = originalTag?.attributes?.[k];
+        if (v !== undefined) {
+            newNav.attributes[k] = v;
+        }
+    }
+    return newNav;
+}
+// ─── Nav slug resolution (SPEC-055) ───
+/** Strip trailing slash, normalize index suffixes, lowercase. Used for URL
+ *  comparison only — the canonical href written into the DOM keeps the
+ *  page's original casing from the registry. */
+function normaliseNavUrl(url) {
+    let u = url.trim();
+    if (u.length > 1 && u.endsWith('/'))
+        u = u.slice(0, -1);
+    if (u.endsWith('/index'))
+        u = u.slice(0, -'/index'.length) || '/';
+    return u.toLowerCase();
+}
+/** Derive a nav's base URL directory from its source file path.
+ *
+ *  - `_layout.md`                       → `/`
+ *  - `docs/_layout.md`                  → `/docs/`
+ *  - `docs/themes/_layout.md`           → `/docs/themes/`
+ *  - `docs/getting-started.md`          → `/docs/`
+ *  - `docs/themes/configuration.md`     → `/docs/themes/`
+ */
+function deriveNavBaseDir(sourcePath) {
+    const parts = sourcePath.split('/').filter(Boolean);
+    parts.pop(); // drop filename
+    if (parts.length === 0)
+        return '/';
+    return '/' + parts.join('/') + '/';
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const prev = new Array(b.length + 1);
+    const curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j];
+    }
+    return prev[b.length];
+}
+/** Find up to 3 suggestion URLs for an unresolvable bare slug.
+ *  Priority: (1) same final-segment pages outside base, (2) Levenshtein ≤ 2
+ *  typo matches within base. */
+function findNavSlugSuggestions(slug, baseDir, pagesByUrl) {
+    const baseNorm = baseDir.endsWith('/') ? baseDir : baseDir + '/';
+    const slugLower = slug.toLowerCase();
+    const sameSlug = [];
+    const typoMatches = [];
+    const expectedAtBase = (baseNorm + slug).replace(/\/+/g, '/').toLowerCase();
+    for (const page of pagesByUrl.values()) {
+        const url = page.url;
+        const urlLower = url.toLowerCase();
+        const tail = url.split('/').filter(Boolean).pop() ?? '';
+        const tailLower = tail.toLowerCase();
+        // Same-slug candidates: any page whose final segment equals the slug,
+        // except the (missing) expected URL at base — those would have resolved
+        // already, and a stale match would be misleading.
+        if (tailLower === slugLower && urlLower !== expectedAtBase) {
+            sameSlug.push(url);
+            continue;
+        }
+        // Typo candidates: pages under base with a near-match final segment.
+        if (urlLower.startsWith(baseNorm.toLowerCase())) {
+            const d = levenshtein(slugLower, tailLower);
+            if (d > 0 && d <= 2)
+                typoMatches.push({ url, distance: d });
+        }
+    }
+    sameSlug.sort();
+    typoMatches.sort((a, b) => a.distance - b.distance || a.url.localeCompare(b.url));
+    const suggestions = [...sameSlug, ...typoMatches.map(t => t.url)];
+    return suggestions.slice(0, 3);
+}
+/** SPEC-055 nav-location-relative slug resolution.
+ *
+ *  Rules:
+ *  - Slugs starting with `/`             → absolute path, passthrough
+ *  - Slugs containing `/`                → multi-segment relative to baseDir
+ *  - Bare slug                           → must resolve uniquely at baseDir
+ *
+ *  Returns the resolved canonical URL (from the registry, preserving case) or
+ *  an error with attemptedUrl and suggestions. */
+function resolveNavSlug(slug, baseDir, pagesByUrl) {
+    if (slug.startsWith('/')) {
+        return { ok: true, url: slug };
+    }
+    const base = baseDir.endsWith('/') ? baseDir : baseDir + '/';
+    const candidate = (base + slug).replace(/\/+/g, '/');
+    const candidateNorm = normaliseNavUrl(candidate);
+    // Look up by normalised URL — match against registry pages.
+    for (const page of pagesByUrl.values()) {
+        if (normaliseNavUrl(page.url) === candidateNorm) {
+            return { ok: true, url: page.url };
+        }
+    }
+    const suggestions = findNavSlugSuggestions(slug.includes('/') ? slug.split('/').pop() : slug, base, pagesByUrl);
+    return { ok: false, reason: 'not-found', attemptedUrl: candidate, suggestions };
 }
 // ─── Collapsible nav auto-open ───
 function sharedPrefixLength(a, b) {
@@ -939,8 +1060,10 @@ function sharedPrefixLength(a, b) {
         i++;
     return i;
 }
-/** Resolve a slug-only nav item to a page URL using the pagesByUrl registry.
- *  Mirrors the runtime resolution in @refrakt-md/behaviors RfNav. */
+/** @deprecated Legacy global-search slug resolver, retained for backwards
+ *  compatibility with auto-open / cards / pagination resolvers that haven't
+ *  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);
     if (candidates.length === 0)
@@ -1167,6 +1290,33 @@ function getNavItemUrl(item, pagesByUrl, currentUrl) {
     }
     return null;
 }
+/** Attach an icon (prepended) and a description (appended) inside a nav item's
+ *  existing `<a>` link, drawn from the page's frontmatter. Used for the
+ *  layout-agnostic `auto=true` enrichment (SPEC-054). Unlike the cards
+ *  full-replacement, this preserves any inline author content (badges,
+ *  custom link text) and just augments the link. Idempotent — re-runs do
+ *  nothing because the same data-name children would already be present. */
+function augmentNavItemFromFrontmatter(item, pageMeta) {
+    const newChildren = (item.children ?? []).map((c) => {
+        if (!Tag.isTag(c))
+            return c;
+        const t = c;
+        if (t.name !== 'a')
+            return c;
+        // Skip if this <a> has already been enriched (idempotency).
+        const hasIcon = (t.children ?? []).some((x) => Tag.isTag(x) && x.attributes?.['data-name'] === 'icon');
+        const hasDescription = (t.children ?? []).some((x) => Tag.isTag(x) && x.attributes?.['data-name'] === 'description');
+        const newLinkChildren = [...(t.children ?? [])];
+        if (pageMeta.icon && !hasIcon) {
+            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]));
+        }
+        return { ...t, children: newLinkChildren };
+    });
+    return { ...item, children: newChildren };
+}
 function resolveCardsNavs(renderable, pageUrl, pagesByUrl) {
     if (!Tag.isTag(renderable)) {
         if (Array.isArray(renderable)) {
@@ -1178,42 +1328,229 @@ function resolveCardsNavs(renderable, pageUrl, pagesByUrl) {
         return renderable;
     }
     const tag = renderable;
-    if (tag.attributes?.['data-rune'] === 'nav' &&
-        (tag.attributes?.['data-layout'] === 'cards' || tag.attributes?.['layout'] === 'cards')) {
-        const enrichItem = (node) => {
-            if (!Tag.isTag(node)) {
-                if (Array.isArray(node))
-                    return node.map(enrichItem);
-                return node;
-            }
-            const t = node;
-            if (t.attributes?.['data-rune'] === 'nav-item') {
-                const ref = getNavItemUrl(t, pagesByUrl, pageUrl);
-                if (!ref)
-                    return t;
-                if (ref.isExternal) {
-                    // External link — title only, no enrichment
-                    return enrichNavItemAsCard(t, null, ref.url);
+    if (tag.attributes?.['data-rune'] === 'nav') {
+        const layout = tag.attributes?.['data-layout'] ?? tag.attributes?.['layout'];
+        const isCards = layout === 'cards';
+        const isAuto = tag.attributes?.['data-auto'] === 'true';
+        // Cards layout: full replacement (icon + title + description inside the link).
+        // Any other layout with auto=true: augment existing links with frontmatter
+        // (icon prepended, description appended). Layouts without either: no enrichment.
+        if (isCards || isAuto) {
+            const enrichItem = (node) => {
+                if (!Tag.isTag(node)) {
+                    if (Array.isArray(node))
+                        return node.map(enrichItem);
+                    return node;
+                }
+                const t = node;
+                if (t.attributes?.['data-rune'] === 'nav-item') {
+                    const ref = getNavItemUrl(t, pagesByUrl, pageUrl);
+                    if (!ref)
+                        return t;
+                    if (isCards) {
+                        if (ref.isExternal)
+                            return enrichNavItemAsCard(t, null, ref.url);
+                        const page = pagesByUrl.get(ref.url);
+                        const meta = page
+                            ? { url: page.url, title: page.title, description: page.description, icon: page.icon }
+                            : null;
+                        return enrichNavItemAsCard(t, meta, ref.url);
+                    }
+                    // Auto-augment for non-cards layouts. External links don't have
+                    // frontmatter to enrich from — leave untouched.
+                    if (ref.isExternal)
+                        return t;
+                    const page = pagesByUrl.get(ref.url);
+                    if (!page)
+                        return t;
+                    const meta = {
+                        url: page.url,
+                        title: page.title,
+                        description: page.description,
+                        icon: page.icon,
+                    };
+                    return augmentNavItemFromFrontmatter(t, meta);
                 }
-                const page = pagesByUrl.get(ref.url);
-                const meta = page
-                    ? { url: page.url, title: page.title, description: page.description, icon: page.icon }
-                    : null;
-                return enrichNavItemAsCard(t, meta, ref.url);
+                const newChildren = (t.children ?? []).map(enrichItem);
+                if (newChildren.every((c, i) => c === t.children[i]))
+                    return t;
+                return { ...t, children: newChildren };
+            };
+            const newChildren = (tag.children ?? []).map(enrichItem);
+            return { ...tag, children: newChildren };
+        }
+    }
+    const newChildren = (tag.children ?? []).map((c) => resolveCardsNavs(c, pageUrl, pagesByUrl));
+    if (newChildren.every((c, i) => c === tag.children[i]))
+        return tag;
+    return { ...tag, children: newChildren };
+}
+// ─── Build-time nav slug resolution + active state (SPEC-055) ───
+function isExternalUrl(url) {
+    return /^[a-z]+:\/\//i.test(url) || url.startsWith('mailto:') || url.startsWith('//');
+}
+/** Format a nav resolution error for ctx.error. Includes the source file,
+ *  attempted URL, and closest-match suggestions. */
+function formatNavResolutionError(slug, sourcePath, attemptedUrl, suggestions) {
+    const where = sourcePath ? ` in ${sourcePath}` : '';
+    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.'];
+    return head + '\n' + lines.join('\n');
+}
+/** Walk a nav subtree, resolve every NavItem's `data-slug` to a real `<a href>`
+ *  using SPEC-055 rules. Items with explicit `<a>` link children pass through
+ *  unchanged. Unresolvable slugs emit a ctx.error and leave the item as
+ *  fallback text so the build can continue and surface every error. */
+function resolveNavItemsInSubtree(navTag, pagesByUrl, ctx, pageUrl) {
+    const sourcePath = navTag.attributes?.['data-source-path'];
+    const baseDir = deriveNavBaseDir(sourcePath ?? '');
+    const visit = (node) => {
+        if (!Tag.isTag(node)) {
+            if (Array.isArray(node)) {
+                const next = node.map(visit);
+                return next.every((c, i) => c === node[i]) ? node : next;
             }
-            const newChildren = (t.children ?? []).map(enrichItem);
-            if (newChildren.every((c, i) => c === t.children[i]))
+            return node;
+        }
+        const t = node;
+        if (t.attributes?.['data-rune'] === 'nav-item') {
+            // Skip items that already carry an explicit <a> link (passthrough).
+            const existingHref = findNavItemHref(t);
+            if (existingHref)
                 return t;
-            return { ...t, children: newChildren };
-        };
-        const newChildren = (tag.children ?? []).map(enrichItem);
-        return { ...tag, children: newChildren };
+            const slug = readNavItemSlug(t);
+            if (!slug)
+                return t;
+            const result = resolveNavSlug(slug, baseDir, pagesByUrl);
+            if (!result.ok) {
+                ctx.error(formatNavResolutionError(slug, sourcePath, result.attemptedUrl, result.suggestions), pageUrl);
+                return t;
+            }
+            const page = pagesByUrl.get(result.url);
+            const title = page?.title ?? slug;
+            // The engine's NavItem.postTransform adds the `rf-nav-item__link` class to
+            // any `<a>` child of a nav-item that has no slug span — so we deliberately
+            // omit the class here to avoid duplication.
+            const link = new Tag('a', { href: result.url }, [title]);
+            // Replace the slug span + fallback text with the resolved link.
+            const newChildren = (t.children ?? []).filter((c) => {
+                if (typeof c === 'string')
+                    return false; // drop slug fallback text
+                if (Tag.isTag(c)) {
+                    const ct = c;
+                    if (ct.name === 'span' && ct.attributes?.['data-field'] === 'slug')
+                        return false;
+                }
+                return true;
+            });
+            return { ...t, children: [link, ...newChildren] };
+        }
+        const newChildren = (t.children ?? []).map(visit);
+        if (newChildren.every((c, i) => c === t.children[i]))
+            return t;
+        return { ...t, children: newChildren };
+    };
+    return visit(navTag);
+}
+/** Walk a renderable tree and resolve nav slugs in every `<rf-nav>` /
+ *  `<nav data-rune="nav">` encountered. */
+function resolveNavSlugs(renderable, pagesByUrl, ctx, pageUrl) {
+    if (!Tag.isTag(renderable)) {
+        if (Array.isArray(renderable)) {
+            const next = renderable.map(c => resolveNavSlugs(c, pagesByUrl, ctx, pageUrl));
+            return next.every((c, i) => c === renderable[i]) ? renderable : next;
+        }
+        return renderable;
     }
-    const newChildren = (tag.children ?? []).map((c) => resolveCardsNavs(c, pageUrl, pagesByUrl));
+    const tag = renderable;
+    if (tag.attributes?.['data-rune'] === 'nav') {
+        return resolveNavItemsInSubtree(tag, pagesByUrl, ctx, pageUrl);
+    }
+    const newChildren = (tag.children ?? []).map((c) => resolveNavSlugs(c, pagesByUrl, ctx, pageUrl));
     if (newChildren.every((c, i) => c === tag.children[i]))
         return tag;
     return { ...tag, children: newChildren };
 }
+/** Apply active-state attributes (`aria-current="page"`, `data-active="ancestor"`)
+ *  to each nav's items, per SPEC-055. At most one item per nav gets aria-current
+ *  (exact URL match); at most one of the remaining items gets data-active
+ *  (longest strict-prefix match). */
+function applyNavActiveState(renderable, pageUrl) {
+    const pageNorm = normaliseNavUrl(pageUrl);
+    const markNav = (navTag) => {
+        // Collect all nav-item <a> links inside this nav.
+        const links = [];
+        const collect = (node) => {
+            if (!Tag.isTag(node)) {
+                if (Array.isArray(node))
+                    node.forEach(collect);
+                return;
+            }
+            const t = node;
+            if (t.name === 'a' && typeof t.attributes?.href === 'string') {
+                const href = String(t.attributes.href);
+                if (!isExternalUrl(href)) {
+                    links.push({ tag: t, href });
+                }
+            }
+            (t.children ?? []).forEach(collect);
+        };
+        (navTag.children ?? []).forEach(collect);
+        // Pass 1: exact match → aria-current="page". At most one.
+        let currentLink = null;
+        for (const { tag, href } of links) {
+            if (normaliseNavUrl(href) === pageNorm) {
+                currentLink = tag;
+                break;
+            }
+        }
+        // Pass 2: longest strict prefix among the remaining links → data-active="ancestor".
+        let ancestorLink = null;
+        let ancestorHrefLen = 0;
+        for (const { tag, href } of links) {
+            if (tag === currentLink)
+                continue;
+            const hrefNorm = normaliseNavUrl(href);
+            if (hrefNorm === '/' && pageNorm === '/')
+                continue;
+            // Strict prefix: hrefNorm is a proper prefix of pageNorm followed by '/'.
+            const isPrefix = hrefNorm !== pageNorm &&
+                (pageNorm.startsWith(hrefNorm + '/') || (hrefNorm === '/' && pageNorm.startsWith('/')));
+            if (isPrefix && hrefNorm.length > ancestorHrefLen) {
+                ancestorLink = tag;
+                ancestorHrefLen = hrefNorm.length;
+            }
+        }
+        // Mutate attributes in place — the link tags are nested within the navTag,
+        // so mutation propagates without rebuilding the whole tree.
+        if (currentLink)
+            currentLink.attributes['aria-current'] = 'page';
+        if (ancestorLink)
+            ancestorLink.attributes['data-active'] = 'ancestor';
+        return navTag;
+    };
+    const visit = (node) => {
+        if (!Tag.isTag(node)) {
+            if (Array.isArray(node)) {
+                node.forEach(visit);
+            }
+            return node;
+        }
+        const t = node;
+        if (t.attributes?.['data-rune'] === 'nav') {
+            markNav(t);
+            // Don't recurse into a nav we just processed — nested navs are unusual
+            // but if present, would be marked by their own pass.
+            return t;
+        }
+        (t.children ?? []).forEach(visit);
+        return t;
+    };
+    visit(renderable);
+    return renderable;
+}
 /** Walk a renderable tree collecting all nav-rune tags and their item URLs in order.
  *  Skips navs with non-sequential layouts (menubar / columns / cards) — those
  *  aren't reading sequences. */
@@ -1653,12 +1990,21 @@ export function resolveCoreSentinels(renderable, pageUrl, coreData, ctx,
 navSearchScope) {
     let result = resolveAutoBreadcrumbs(renderable, pageUrl, coreData.breadcrumbPaths, coreData.pagesByUrl, ctx);
     result = resolveAutoNavs(result, pageUrl, coreData.pagesByUrl, ctx);
+    // SPEC-055 — resolve bare-slug nav items to real <a href> links before any
+    // downstream resolver consumes the tree. Must run after auto-nav (which
+    // expands `{% nav auto %}` into item children) but before collapsible /
+    // cards (which both rely on resolved hrefs).
+    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;
     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
+    // item href set is final.
+    result = applyNavActiveState(result, pageUrl);
     result = resolveBlogPosts(result, coreData.allPosts, ctx, pageUrl);
     result = resolveXrefs(result, pageUrl, coreData.registry, ctx);
     return result;
@@ -1743,9 +2089,13 @@ export const corePipelineHooks = {
             return page;
         let renderable = resolveAutoBreadcrumbs(page.renderable, page.url, coreData.breadcrumbPaths, coreData.pagesByUrl, ctx);
         renderable = resolveAutoNavs(renderable, page.url, coreData.pagesByUrl, ctx);
+        // SPEC-055 build-time slug resolution (see note in resolveCoreSentinels).
+        renderable = resolveNavSlugs(renderable, coreData.pagesByUrl, ctx, page.url);
         renderable = resolveCollapsibleNavs(renderable, page.url, coreData.pagesByUrl);
         renderable = resolveCardsNavs(renderable, page.url, coreData.pagesByUrl);
         renderable = resolveAutoPagination(renderable, page.url, coreData.pagesByUrl, renderable);
+        // SPEC-055 build-time active state.
+        renderable = applyNavActiveState(renderable, page.url);
         renderable = resolveBlogPosts(renderable, coreData.allPosts, ctx, page.url);
         renderable = resolveXrefs(renderable, page.url, coreData.registry, ctx);
         if (renderable === page.renderable)