@refrakt-md/runes 0.8.4 → 0.9.0

package/dist/config.d.ts

@@ -14,7 +14,8 @@ export interface PageTreeNode {
 /**
  * Core cross-page pipeline hooks.
  * Run for every site, before any community package hooks.
- * Registers page and heading entities, aggregates the page tree and breadcrumb paths.
+ * Registers page and heading entities, aggregates the page tree and breadcrumb paths,
+ * and resolves blog post listings.
  */
 export declare const corePipelineHooks: PackagePipelineHooks;
 //# sourceMappingURL=config.d.ts.map

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,oBAAoB,EAAoE,MAAM,mBAAmB,CAAC;AA+EhI;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAsmBxB,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;AAsPD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,oBAoG/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,oBAAoB,EAAoE,MAAM,mBAAmB,CAAC;AAgFhI;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAqrBxB,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;AA4kBD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,oBA8H/B,CAAC"}

package/dist/config.js

@@ -5,6 +5,7 @@ import { createComponentRenderable } from './lib/index.js';
 import { schema } from './registry.js';
 import { BREADCRUMB_AUTO_SENTINEL } from './tags/breadcrumb.js';
 import { NAV_AUTO_SENTINEL } from './tags/nav.js';
+import { XREF_RUNE_MARKER } from './tags/xref.js';
 // ─── Budget postTransform helpers ───
 const BUDGET_CURRENCY_SYMBOLS = {
     USD: '$', EUR: '€', GBP: '£', JPY: '¥', CNY: '¥',
@@ -68,7 +69,7 @@ function readPropText(node, prop) {
 }
 /** autoLabel entries shared by all PageSection-based runes */
 const pageSectionAutoLabel = {
-    header: 'header', // <header> wrapper element
+    header: 'preamble', // <header> wrapper element → data-name="preamble"
     eyebrow: 'eyebrow', // property="eyebrow"
     headline: 'headline', // property="headline"
     blurb: 'blurb', // property="blurb"
@@ -82,11 +83,12 @@ export const coreConfig = {
     icons: {},
     runes: {
         // ─── Simple runes (block name only, engine adds BEM classes) ───
-        Accordion: { block: 'accordion', autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
-        AccordionItem: { block: 'accordion-item', parent: 'Accordion', autoLabel: { name: 'header' }, editHints: { header: 'inline', body: 'none' } },
-        Details: { block: 'details', autoLabel: { summary: 'summary' }, editHints: { summary: 'inline', body: 'none' } },
+        Accordion: { block: 'accordion', defaultDensity: 'full', sections: { preamble: 'preamble', headline: 'title', blurb: 'description' }, autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
+        AccordionItem: { block: 'accordion-item', parent: 'Accordion', rootAttributes: { 'data-state': 'closed' }, autoLabel: { name: 'header' }, editHints: { header: 'inline', body: 'none' } },
+        Details: { block: 'details', defaultDensity: 'compact', sections: { summary: 'title' }, autoLabel: { summary: 'summary' }, editHints: { summary: 'inline', body: 'none' } },
         Grid: {
             block: 'grid',
+            defaultDensity: 'full',
             modifiers: {
                 mode: { source: 'meta', default: 'columns' },
                 collapse: { source: 'meta', noBemClass: true },
@@ -108,6 +110,7 @@ export const coreConfig = {
         },
         CodeGroup: {
             block: 'codegroup',
+            defaultDensity: 'compact',
             modifiers: { title: { source: 'meta' }, overflow: { source: 'meta', default: 'scroll' } },
             structure: {
                 topbar: {
@@ -120,12 +123,14 @@ export const coreConfig = {
                     ],
                 },
             },
+            sections: { topbar: 'header', title: 'title' },
             editHints: { panel: 'code', title: 'none' },
         },
         PageSection: { block: 'page-section' },
         TableOfContents: { block: 'toc' },
         Embed: {
             block: 'embed',
+            defaultDensity: 'compact',
             editHints: { fallback: 'none' },
             postTransform(node) {
                 const block = node.attributes.class?.split(' ')[0] || 'rf-embed';
@@ -166,10 +171,27 @@ export const coreConfig = {
                 };
             },
         },
-        Breadcrumb: { block: 'breadcrumb', editHints: { items: 'none' } },
+        Breadcrumb: { block: 'breadcrumb', defaultDensity: 'minimal', sections: { items: 'body' }, editHints: { items: 'none' } },
         BreadcrumbItem: { block: 'breadcrumb-item', parent: 'Breadcrumb' },
+        Blog: {
+            block: 'blog',
+            defaultDensity: 'full',
+            sections: { preamble: 'preamble', headline: 'title', blurb: 'description', content: 'body' },
+            contentWrapper: { tag: 'div', ref: 'content' },
+            modifiers: {
+                layout: { source: 'meta', default: 'list' },
+                sort: { source: 'meta', default: 'date-desc', noBemClass: true },
+                filter: { source: 'meta', noBemClass: true },
+                limit: { source: 'meta', noBemClass: true },
+                folder: { source: 'meta', noBemClass: true },
+            },
+            autoLabel: pageSectionAutoLabel,
+            editHints: { headline: 'inline', blurb: 'inline' },
+        },
         Budget: {
             block: 'budget',
+            defaultDensity: 'full',
+            sections: { header: 'header', title: 'title', footer: 'footer' },
             editHints: { title: 'none', meta: 'none', 'meta-item': 'none' },
             modifiers: {
                 title: { source: 'meta' },
@@ -189,9 +211,9 @@ export const coreConfig = {
                         {
                             tag: 'div', ref: 'meta',
                             children: [
-                                { tag: 'span', ref: 'meta-item', metaText: 'currency', condition: 'currency' },
-                                { tag: 'span', ref: 'meta-item', metaText: 'travelers', textPrefix: 'Travelers: ', condition: 'travelers' },
-                                { tag: 'span', ref: 'meta-item', metaText: 'duration', textPrefix: 'Duration: ', condition: 'duration' },
+                                { tag: 'span', ref: 'meta-item', metaText: 'currency', condition: 'currency', metaType: 'category', metaRank: 'primary' },
+                                { tag: 'span', ref: 'meta-item', metaText: 'travelers', label: 'Travelers:', condition: 'travelers', metaType: 'quantity', metaRank: 'primary' },
+                                { tag: 'span', ref: 'meta-item', metaText: 'duration', label: 'Duration:', condition: 'duration', metaType: 'temporal', metaRank: 'secondary' },
                             ],
                         },
                     ],
@@ -269,8 +291,10 @@ export const coreConfig = {
         // ─── Runes with modifier meta tags ───
         Hint: {
             block: 'hint',
+            defaultDensity: 'compact',
             modifiers: { hintType: { source: 'meta', default: 'note' } },
             contextModifiers: { 'hero': 'in-hero', 'feature': 'in-feature' },
+            sections: { header: 'header' },
             editHints: { icon: 'none', title: 'none' },
             structure: {
                 header: {
@@ -284,14 +308,17 @@ export const coreConfig = {
         },
         Figure: {
             block: 'figure',
+            defaultDensity: 'compact',
             modifiers: {
                 size: { source: 'meta', default: 'default' },
                 align: { source: 'meta', default: 'center' },
             },
+            sections: { caption: 'description' },
             editHints: { caption: 'inline' },
         },
         Gallery: {
             block: 'gallery',
+            defaultDensity: 'full',
             modifiers: {
                 layout: { source: 'meta', default: 'grid' },
                 lightbox: { source: 'meta', default: 'true', noBemClass: true },
@@ -306,15 +333,18 @@ export const coreConfig = {
         },
         Sidenote: {
             block: 'sidenote',
+            defaultDensity: 'minimal',
             modifiers: { variant: { source: 'meta', default: 'sidenote' } },
+            sections: { body: 'body' },
             editHints: { body: 'inline' },
         },
         Compare: {
             block: 'compare',
+            defaultDensity: 'full',
             modifiers: { layout: { source: 'meta', default: 'side-by-side' } },
             editHints: { panels: 'none' },
         },
-        Conversation: { block: 'conversation', editHints: { messages: 'none' } },
+        Conversation: { block: 'conversation', defaultDensity: 'compact', editHints: { messages: 'none' } },
         ConversationMessage: {
             block: 'conversation-message',
             parent: 'Conversation',
@@ -323,12 +353,15 @@ export const coreConfig = {
         },
         Annotate: {
             block: 'annotate',
+            defaultDensity: 'full',
             modifiers: { variant: { source: 'meta', default: 'margin' } },
+            sections: { body: 'body' },
             editHints: { body: 'none', notes: 'none' },
         },
         AnnotateNote: { block: 'annotate-note', parent: 'Annotate', editHints: { body: 'inline' } },
         Nav: {
             block: 'nav',
+            defaultDensity: 'compact',
             postTransform(node) {
                 return { ...node, name: 'rf-nav' };
             },
@@ -364,11 +397,13 @@ export const coreConfig = {
         },
         Diff: {
             block: 'diff',
+            defaultDensity: 'compact',
             modifiers: { mode: { source: 'meta', default: 'unified' } },
             editHints: { line: 'none', 'gutter-num': 'none', 'gutter-prefix': 'none', 'line-content': 'none' },
         },
         Chart: {
             block: 'chart',
+            defaultDensity: 'compact',
             editHints: { data: 'none' },
             postTransform(node) {
                 const block = node.attributes.class?.split(' ')[0] || 'rf-chart';
@@ -482,33 +517,42 @@ export const coreConfig = {
         // ─── Text formatting & layout runes ───
         PullQuote: {
             block: 'pullquote',
+            defaultDensity: 'compact',
             modifiers: {
                 align: { source: 'meta', default: 'center' },
                 variant: { source: 'meta', default: 'default' },
             },
+            sections: { body: 'body' },
             editHints: { body: 'inline' },
         },
         TextBlock: {
             block: 'textblock',
+            defaultDensity: 'full',
             modifiers: {
                 dropcap: { source: 'meta' },
                 columns: { source: 'meta' },
                 lead: { source: 'meta' },
                 align: { source: 'meta', default: 'left' },
             },
+            sections: { body: 'body' },
             editHints: { body: 'none' },
         },
         MediaText: {
             block: 'mediatext',
+            defaultDensity: 'full',
             modifiers: {
                 align: { source: 'meta', default: 'left' },
                 ratio: { source: 'meta', default: '1:1' },
                 wrap: { source: 'meta' },
             },
+            sections: { body: 'body', media: 'media' },
+            mediaSlots: { media: 'cover' },
             editHints: { media: 'image', body: 'none' },
         },
         Showcase: {
             block: 'showcase',
+            defaultDensity: 'compact',
+            sections: { viewport: 'body' },
             modifiers: {
                 shadow: { source: 'meta', default: 'none' },
                 bleed: { source: 'meta', default: 'none' },
@@ -534,11 +578,13 @@ export const coreConfig = {
             },
         },
         // ─── Interactive runes (still get BEM classes, components add behavior) ───
-        TabGroup: { block: 'tabs', autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
-        Tab: { block: 'tab', parent: 'TabGroup', editHints: { name: 'inline' } },
-        TabPanel: { block: 'tab-panel', parent: 'TabGroup' },
+        TabGroup: { block: 'tabs', defaultDensity: 'full', sections: { preamble: 'preamble', headline: 'title', blurb: 'description' }, autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
+        Tab: { block: 'tab', parent: 'TabGroup', rootAttributes: { 'data-state': 'inactive' }, editHints: { name: 'inline' } },
+        TabPanel: { block: 'tab-panel', parent: 'TabGroup', rootAttributes: { 'data-state': 'inactive' } },
         DataTable: {
             block: 'datatable',
+            defaultDensity: 'compact',
+            sections: { table: 'body' },
             modifiers: {
                 searchable: { source: 'meta', default: 'false' },
                 sortable: { source: 'meta' },
@@ -549,6 +595,8 @@ export const coreConfig = {
         },
         Form: {
             block: 'form',
+            defaultDensity: 'full',
+            sections: { body: 'body' },
             modifiers: {
                 variant: { source: 'meta', default: 'stacked' },
                 action: { source: 'meta' },
@@ -568,15 +616,34 @@ export const coreConfig = {
         },
         Reveal: {
             block: 'reveal',
+            defaultDensity: 'full',
             modifiers: {
                 mode: { source: 'meta', default: 'click' },
             },
+            sections: { preamble: 'preamble', headline: 'title', blurb: 'description' },
             autoLabel: pageSectionAutoLabel,
             editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline', steps: 'none' },
         },
-        RevealStep: { block: 'reveal-step', parent: 'Reveal', editHints: { body: 'none' } },
+        RevealStep: { block: 'reveal-step', parent: 'Reveal', rootAttributes: { 'data-state': 'closed' }, editHints: { body: 'none' } },
+        Juxtapose: {
+            block: 'juxtapose',
+            defaultDensity: 'compact',
+            modifiers: {
+                variant: { source: 'meta', default: 'slider' },
+                orientation: { source: 'meta', default: 'vertical', noBemClass: true },
+                position: { source: 'meta', default: '50', noBemClass: true },
+                duration: { source: 'meta', default: '1000', noBemClass: true },
+            },
+            styles: {
+                position: '--jx-position',
+                duration: '--jx-duration',
+            },
+            editHints: { panels: 'none' },
+        },
+        JuxtaposePanel: { block: 'juxtapose-panel', parent: 'Juxtapose', rootAttributes: { 'data-state': 'inactive' }, editHints: { body: 'none' } },
         Diagram: {
             block: 'diagram',
+            defaultDensity: 'compact',
             editHints: { source: 'code' },
             postTransform(node) {
                 const block = node.attributes.class?.split(' ')[0] || 'rf-diagram';
@@ -605,8 +672,12 @@ export const coreConfig = {
                 };
             },
         },
+        Tint: { block: 'tint', parent: '*' },
+        Bg: { block: 'bg', parent: '*' },
+        Region: { block: 'region', parent: 'Layout' },
         Sandbox: {
             block: 'sandbox',
+            defaultDensity: 'compact',
             editHints: { source: 'code' },
             postTransform(node) {
                 // Read meta values
@@ -616,14 +687,23 @@ export const coreConfig = {
                 const label = readMeta(node, 'label') || '';
                 const height = readMeta(node, 'height') || 'auto';
                 const designTokens = readMeta(node, 'design-tokens') || '';
-                // Keep non-meta children (fallback pre, source panels)
-                const fallbackChildren = node.children.filter(child => {
-                    if (!isTag(child))
-                        return true;
-                    if (child.name === 'meta')
-                        return false;
-                    return true;
-                });
+                // Keep non-meta children (fallback pre) and extract source panels
+                const fallbackChildren = [];
+                const sourcePanelOrigins = [];
+                for (const child of node.children) {
+                    if (!isTag(child)) {
+                        fallbackChildren.push(child);
+                        continue;
+                    }
+                    if (child.name === 'meta') {
+                        // Collect origin data from source panels
+                        if (child.attributes?.['data-field'] === 'source-panel' && child.attributes?.['data-origin']) {
+                            sourcePanelOrigins.push(`${child.attributes['data-label'] || ''}\t${child.attributes['data-origin']}`);
+                        }
+                        continue;
+                    }
+                    fallbackChildren.push(child);
+                }
                 // Add hidden content div for web component
                 const children = [
                     ...fallbackChildren,
@@ -640,6 +720,7 @@ export const coreConfig = {
                         ...(label ? { 'data-label': label } : {}),
                         'data-height': height,
                         ...(designTokens ? { 'data-design-tokens': designTokens } : {}),
+                        ...(sourcePanelOrigins.length > 0 ? { 'data-source-origins': sourcePanelOrigins.join('\n') } : {}),
                     },
                     children,
                 };
@@ -821,10 +902,282 @@ function buildAutoNav(pageUrl, pagesByUrl, ctx) {
         children: [itemsList],
     });
 }
+function walkBlogTags(node, fn) {
+    if (Tag.isTag(node)) {
+        fn(node);
+        for (const child of node.children)
+            walkBlogTags(child, fn);
+    }
+    else if (Array.isArray(node)) {
+        node.forEach(n => walkBlogTags(n, fn));
+    }
+}
+function mapBlogTags(node, fn) {
+    if (Tag.isTag(node)) {
+        const mapped = fn(node);
+        if (mapped !== node)
+            return mapped;
+        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;
+}
+/** Normalise folder path for prefix matching: ensure leading slash and trailing slash */
+function normaliseFolderPath(folder) {
+    let f = folder.trim();
+    if (!f.startsWith('/'))
+        f = '/' + f;
+    if (!f.endsWith('/'))
+        f += '/';
+    return f;
+}
+/** Check if a page URL is a direct child of the given folder */
+function isInFolder(pageUrl, folder) {
+    if (!pageUrl.startsWith(folder))
+        return false;
+    const rest = pageUrl.slice(folder.length);
+    const segments = rest.replace(/\/$/, '').split('/').filter(Boolean);
+    return segments.length === 1;
+}
+/** Parse a simple filter expression like "tag:javascript" into field/value pairs */
+function parseBlogFilter(filter) {
+    if (!filter || !filter.trim())
+        return [];
+    return filter.split(',').map(part => {
+        const colonIdx = part.indexOf(':');
+        if (colonIdx === -1)
+            return { field: part.trim(), value: '' };
+        return {
+            field: part.slice(0, colonIdx).trim(),
+            value: part.slice(colonIdx + 1).trim(),
+        };
+    });
+}
+/** Check if a post's frontmatter matches all filter conditions */
+function matchesBlogFilter(post, filters) {
+    for (const { field, value } of filters) {
+        const fmValue = post.frontmatter[field];
+        if (value === '') {
+            if (fmValue === undefined || fmValue === null)
+                return false;
+        }
+        else if (Array.isArray(fmValue)) {
+            if (!fmValue.some(v => String(v).toLowerCase() === value.toLowerCase()))
+                return false;
+        }
+        else {
+            if (String(fmValue ?? '').toLowerCase() !== value.toLowerCase())
+                return false;
+        }
+    }
+    return true;
+}
+/** Sort blog posts by the specified order */
+function sortBlogPosts(posts, sort) {
+    const sorted = [...posts];
+    switch (sort) {
+        case 'date-asc':
+            sorted.sort((a, b) => (a.date || '').localeCompare(b.date || ''));
+            break;
+        case 'title-asc':
+            sorted.sort((a, b) => a.title.localeCompare(b.title));
+            break;
+        case 'title-desc':
+            sorted.sort((a, b) => b.title.localeCompare(a.title));
+            break;
+        case 'date-desc':
+        default:
+            sorted.sort((a, b) => (b.date || '').localeCompare(a.date || ''));
+            break;
+    }
+    return sorted;
+}
+/** 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 children = [titleTag];
+    if (post.date) {
+        children.push(new Tag('time', { datetime: post.date }, [post.date]));
+    }
+    if (post.description) {
+        children.push(new Tag('p', {}, [post.description]));
+    }
+    return new Tag('article', { 'data-name': 'post' }, children);
+}
+/** Resolve blog runes in a renderable tree by injecting matching posts */
+function resolveBlogPosts(renderable, allPosts, ctx, pageUrl) {
+    let modified = false;
+    const result = mapBlogTags(renderable, (tag) => {
+        if (tag.attributes['data-rune'] !== 'blog')
+            return tag;
+        const folderMeta = tag.children.find((c) => Tag.isTag(c) && c.attributes['data-field'] === 'folder');
+        const sortMeta = tag.children.find((c) => Tag.isTag(c) && c.attributes['data-field'] === 'sort');
+        const filterMeta = tag.children.find((c) => Tag.isTag(c) && c.attributes['data-field'] === 'filter');
+        const limitMeta = tag.children.find((c) => Tag.isTag(c) && c.attributes['data-field'] === 'limit');
+        const folder = Tag.isTag(folderMeta) ? folderMeta.attributes.content : '';
+        const sort = Tag.isTag(sortMeta) ? sortMeta.attributes.content : 'date-desc';
+        const filterStr = Tag.isTag(filterMeta) ? filterMeta.attributes.content : '';
+        const limitStr = Tag.isTag(limitMeta) ? limitMeta.attributes.content : '';
+        const limit = limitStr ? parseInt(limitStr, 10) : undefined;
+        if (!folder) {
+            ctx.warn('Blog rune missing folder attribute', pageUrl);
+            return tag;
+        }
+        const normalised = normaliseFolderPath(folder);
+        const filters = parseBlogFilter(filterStr);
+        let posts = allPosts.filter(post => {
+            if (post.draft)
+                return false;
+            if (!isInFolder(post.url, normalised))
+                return false;
+            if (filters.length > 0 && !matchesBlogFilter(post, filters))
+                return false;
+            return true;
+        });
+        posts = sortBlogPosts(posts, sort);
+        if (limit && limit > 0) {
+            posts = posts.slice(0, limit);
+        }
+        const postsContainer = tag.children.find((c) => Tag.isTag(c) && c.attributes['data-name'] === 'posts');
+        if (!Tag.isTag(postsContainer))
+            return tag;
+        const postTags = posts.map(createBlogPostTag);
+        modified = true;
+        const newPostsContainer = new Tag(postsContainer.name, postsContainer.attributes, postTags);
+        const newChildren = tag.children.map((c) => c === postsContainer ? newPostsContainer : c);
+        return new Tag(tag.name, tag.attributes, newChildren);
+    });
+    return modified ? result : renderable;
+}
+// ─── Xref resolution helpers ───
+/**
+ * Find an entity by exact ID across all types in the registry.
+ * If typeHint is provided, only search that type.
+ */
+function findEntityById(registry, id, typeHint) {
+    const types = typeHint ? [typeHint] : registry.getTypes();
+    for (const type of types) {
+        const entity = registry.getById(type, id);
+        if (entity)
+            return { entity, ambiguous: false };
+    }
+    return undefined;
+}
+/**
+ * Find entities by name/title match (case-insensitive) across all types.
+ * If typeHint is provided, only search that type.
+ */
+function findEntitiesByName(registry, name, typeHint) {
+    const nameLower = name.toLowerCase();
+    const types = typeHint ? [typeHint] : registry.getTypes();
+    const matches = [];
+    for (const type of types) {
+        for (const entity of registry.getAll(type)) {
+            const entityName = entity.data.name ?? '';
+            const entityTitle = entity.data.title ?? '';
+            if (entityName.toLowerCase() === nameLower || entityTitle.toLowerCase() === nameLower) {
+                matches.push(entity);
+            }
+        }
+    }
+    return matches;
+}
+/** Resolve an entity's URL for use as an href */
+function resolveEntityHref(entity) {
+    const baseUrl = entity.data.url || entity.sourceUrl;
+    const headingId = entity.data.headingId;
+    if (headingId)
+        return `${baseUrl}#${headingId}`;
+    return baseUrl;
+}
+/** Walk a Markdoc renderable tree, resolving any xref placeholders */
+function resolveXrefs(renderable, pageUrl, registry, ctx) {
+    if (!Tag.isTag(renderable)) {
+        if (Array.isArray(renderable)) {
+            const newChildren = renderable.map(c => resolveXrefs(c, pageUrl, registry, ctx));
+            if (newChildren.every((c, i) => c === renderable[i]))
+                return renderable;
+            return newChildren;
+        }
+        return renderable;
+    }
+    const tag = renderable;
+    // Check if this is an xref placeholder
+    if (tag.attributes?.['data-rune'] === XREF_RUNE_MARKER) {
+        const id = tag.attributes['data-xref-id'];
+        const label = tag.attributes['data-xref-label'];
+        const typeHint = tag.attributes['data-xref-type'];
+        // Try exact ID match first
+        const idMatch = findEntityById(registry, id, typeHint);
+        if (idMatch) {
+            const entity = idMatch.entity;
+            const href = resolveEntityHref(entity);
+            const text = label || entity.data.title || entity.data.name || entity.data.text || id;
+            if (entity.sourceUrl === pageUrl) {
+                ctx.info(`xref "${id}" on ${pageUrl} — references itself`, pageUrl);
+            }
+            return new Tag('a', {
+                class: `rf-xref rf-xref--${entity.type}`,
+                href,
+                'data-entity-type': entity.type,
+                'data-entity-id': entity.id,
+            }, [text]);
+        }
+        // Try name/title match
+        const nameMatches = findEntitiesByName(registry, id, typeHint);
+        if (nameMatches.length === 1) {
+            const entity = nameMatches[0];
+            const href = resolveEntityHref(entity);
+            const text = label || entity.data.title || entity.data.name || entity.data.text || id;
+            if (entity.sourceUrl === pageUrl) {
+                ctx.info(`xref "${id}" on ${pageUrl} — references itself`, pageUrl);
+            }
+            return new Tag('a', {
+                class: `rf-xref rf-xref--${entity.type}`,
+                href,
+                'data-entity-type': entity.type,
+                'data-entity-id': entity.id,
+            }, [text]);
+        }
+        if (nameMatches.length > 1) {
+            const matchList = nameMatches
+                .map(e => `${e.type} "${e.data.title || e.data.name || e.id}" on ${e.sourceUrl}`)
+                .join(', ');
+            ctx.warn(`xref "${id}" on ${pageUrl} — matches ${nameMatches.length} entities (${matchList}). Add type hint to disambiguate.`, pageUrl);
+            // Use first match
+            const entity = nameMatches[0];
+            const href = resolveEntityHref(entity);
+            const text = label || entity.data.title || entity.data.name || entity.data.text || id;
+            return new Tag('a', {
+                class: `rf-xref rf-xref--${entity.type}`,
+                href,
+                'data-entity-type': entity.type,
+                'data-entity-id': entity.id,
+            }, [text]);
+        }
+        // No match — unresolved
+        ctx.warn(`xref "${id}" on ${pageUrl} — entity not found`, pageUrl);
+        return new Tag('span', {
+            class: 'rf-xref rf-xref--unresolved',
+            'data-entity-id': id,
+        }, [label || id]);
+    }
+    // Recurse into children
+    const newChildren = (tag.children ?? []).map((c) => resolveXrefs(c, pageUrl, registry, ctx));
+    if (newChildren.every((c, i) => c === tag.children[i]))
+        return tag;
+    return { ...tag, children: newChildren };
+}
 /**
  * Core cross-page pipeline hooks.
  * Run for every site, before any community package hooks.
- * Registers page and heading entities, aggregates the page tree and breadcrumb paths.
+ * Registers page and heading entities, aggregates the page tree and breadcrumb paths,
+ * and resolves blog post listings.
  */
 export const corePipelineHooks = {
     register(pages, registry, ctx) {
@@ -879,7 +1232,16 @@ export const corePipelineHooks = {
         for (const h of registry.getAll('heading')) {
             headingIndex.set(h.id, h.data);
         }
-        return { pageTree, breadcrumbPaths, pagesByUrl, headingIndex };
+        // Blog: collect all pages as potential blog posts
+        const allPosts = pageEntities.map(e => ({
+            title: e.data.title || '',
+            url: e.data.url || e.id,
+            date: e.data.date || '',
+            description: e.data.description || '',
+            draft: e.data.draft || false,
+            frontmatter: e.data,
+        }));
+        return { pageTree, breadcrumbPaths, pagesByUrl, headingIndex, allPosts, registry };
     },
     postProcess(page, aggregated, ctx) {
         const coreData = aggregated['__core__'];
@@ -887,6 +1249,8 @@ 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);
+        renderable = resolveBlogPosts(renderable, coreData.allPosts, ctx, page.url);
+        renderable = resolveXrefs(renderable, page.url, coreData.registry, ctx);
         if (renderable === page.renderable)
             return page;
         return { ...page, renderable };