@refrakt-md/runes 0.14.4 → 0.15.0

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { ThemeConfig } from '@refrakt-md/transform';
 import type { PluginPipelineHooks, EntityRegistry, PipelineContext } from '@refrakt-md/types';
+import type { CompiledXrefPattern } from './xref-patterns.js';
 /** Core theme configuration — universal rune-to-BEM-block mappings shared by all themes.
  *  Icons are empty; themes provide their own icon SVGs via mergeThemeConfig. */
 export declare const coreConfig: ThemeConfig;
@@ -40,16 +41,51 @@ export declare function resolveCoreSentinels(renderable: unknown, pageUrl: strin
     }>;
     allPosts: BlogPostData[];
     registry: Readonly<EntityRegistry>;
+    /** Compiled xref patterns from `refrakt.config.json#/xrefs`. Empty
+     *  array when no patterns are configured (the resolver's
+     *  "patterns step" then matches nothing and falls through to
+     *  unresolved). */
+    xrefPatterns?: CompiledXrefPattern[];
 }, ctx: PipelineContext, 
 /** Extra trees (e.g. layout regions + page content) to scan when looking
  *  for nav sequences during auto-pagination. Required when calling against
  *  a layout region where the sidebar nav lives in a different region. */
 navSearchScope?: unknown[]): unknown;
+/** Options accepted by {@link createCorePipelineHooks}. */
+export interface CorePipelineHooksOptions {
+    /** Compiled xref patterns from `refrakt.config.json#/xrefs`. Threaded
+     *  through `aggregate` into the postProcess `coreData` shape so the xref
+     *  resolver can use them as a URL-resolution fallback. */
+    xrefPatterns?: CompiledXrefPattern[];
+    /** Merged Markdoc transform config (tags + nodes from core + every
+     *  loaded plugin) plus the project root. Threaded through `aggregate`
+     *  so the expand postProcess (SPEC-066) can re-transform embedded
+     *  AST subtrees using the same rune schemas the host page used,
+     *  and read source files with the same sandbox boundary as snippet. */
+    embedConfig?: {
+        tags: Record<string, unknown>;
+        nodes: Record<string, unknown>;
+        projectRoot?: string;
+    };
+}
 /**
- * Core cross-page pipeline hooks.
- * Run for every site, before any plugin hooks.
- * Registers page and heading entities, aggregates the page tree and breadcrumb paths,
- * and resolves blog post listings.
+ * Build core cross-page pipeline hooks parameterized by build-time options.
+ *
+ * Most callers (existing adapters, tests) use the {@link corePipelineHooks}
+ * default below — equivalent to `createCorePipelineHooks()` with no patterns
+ * configured. The content-loader bootstrap passes compiled
+ * {@link CompiledXrefPattern}s when `refrakt.config.json#/xrefs` is set.
+ */
+export declare function createCorePipelineHooks(opts?: CorePipelineHooksOptions): PluginPipelineHooks;
+/**
+ * Core cross-page pipeline hooks (no xref patterns configured).
+ *
+ * Equivalent to `createCorePipelineHooks()`. The content loader bootstrap
+ * uses {@link createCorePipelineHooks} directly when
+ * `refrakt.config.json#/xrefs` is configured so the resolver can use the
+ * compiled patterns as a URL-resolution fallback. Run for every site,
+ * before any plugin hooks. Registers page and heading entities, aggregates
+ * the page tree and breadcrumb paths, and resolves blog post listings.
  */
 export declare const corePipelineHooks: PluginPipelineHooks;
 export {};

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;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"}
+{"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;AAS/H,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA6E9D;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAwuBxB,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;IACnC;;;uBAGmB;IACnB,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACrC,EACD,GAAG,EAAE,eAAe;AACpB;;yEAEyE;AACzE,cAAc,CAAC,EAAE,OAAO,EAAE,GACxB,OAAO,CAqBT;AAED,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACxC;;8DAE0D;IAC1D,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACrC;;;;2EAIuE;IACvE,WAAW,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,wBAA6B,GAAG,mBAAmB,CAoNhG;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAA+C,CAAC"}

package/dist/config.js

@@ -6,6 +6,10 @@ import { BREADCRUMB_AUTO_SENTINEL } 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 { registerDrawers, resolveAutoDrawerTitleLevels } from './drawer-pipeline.js';
+import { applyOutlineScopeWalkers } from './outline-scope.js';
+import { resolveExpands } from './expand-pipeline.js';
 // ─── Budget postTransform helpers ───
 const BUDGET_CURRENCY_SYMBOLS = {
     USD: '$', EUR: '€', GBP: '£', JPY: '¥', CNY: '¥',
@@ -134,6 +138,18 @@ export const coreConfig = {
         },
         PageSection: { block: 'page-section' },
         TableOfContents: { block: 'toc' },
+        /* Snippet doesn't have a normal schema transform — its preprocess
+         * hook replaces the tag with a `fence` node, and the standalone
+         * wrap step adds `<figure class="rf-snippet">` post-transform.
+         * The engine never sees a `Snippet` tag, but we still need an
+         * entry in the theme config so `computeUsedCssBlocks` includes
+         * `snippet.css` in CSS tree-shaking when the figure is rendered. */
+        Snippet: { block: 'snippet' },
+        /* Expand emits a placeholder during transform; the postProcess hook
+         * substitutes the entity content wrapped in `<section
+         * class="rf-expand" data-rune="expand">`. Engine config provides the
+         * block name for CSS tree-shaking. */
+        Expand: { block: 'expand' },
         Embed: {
             block: 'embed',
             defaultDensity: 'compact',
@@ -307,6 +323,17 @@ export const coreConfig = {
                 },
             },
         },
+        Drawer: {
+            block: 'drawer',
+            defaultDensity: 'compact',
+            modifiers: {
+                side: { source: 'meta', default: 'right' },
+                size: { source: 'meta', default: 'md' },
+                shortcut: { source: 'meta', noBemClass: true },
+            },
+            sections: { header: 'header', body: 'body' },
+            editHints: { title: 'inline', body: 'none', close: 'none' },
+        },
         Figure: {
             block: 'figure',
             defaultDensity: 'compact',
@@ -2006,101 +2033,140 @@ navSearchScope) {
     // item href set is final.
     result = applyNavActiveState(result, pageUrl);
     result = resolveBlogPosts(result, coreData.allPosts, ctx, pageUrl);
-    result = resolveXrefs(result, pageUrl, coreData.registry, ctx);
+    result = resolveXrefs(result, pageUrl, coreData.registry, coreData.xrefPatterns ?? [], ctx);
     return result;
 }
 /**
- * Core cross-page pipeline hooks.
- * Run for every site, before any plugin hooks.
- * Registers page and heading entities, aggregates the page tree and breadcrumb paths,
- * and resolves blog post listings.
+ * Build core cross-page pipeline hooks parameterized by build-time options.
+ *
+ * Most callers (existing adapters, tests) use the {@link corePipelineHooks}
+ * default below — equivalent to `createCorePipelineHooks()` with no patterns
+ * configured. The content-loader bootstrap passes compiled
+ * {@link CompiledXrefPattern}s when `refrakt.config.json#/xrefs` is set.
  */
-export const corePipelineHooks = {
-    register(pages, registry, ctx) {
-        for (const page of pages) {
-            const parentUrl = deriveParentUrl(page.url);
-            const existingPage = registry.getById('page', page.url);
-            if (existingPage && existingPage.sourceUrl !== page.url) {
-                ctx.warn(`Page '${page.url}' already registered from '${existingPage.sourceUrl}'`, page.url);
-            }
-            registry.register({
-                type: 'page',
-                id: page.url,
-                sourceUrl: page.url,
-                data: {
-                    title: page.title,
-                    url: page.url,
-                    parentUrl,
-                    draft: page.frontmatter.draft ?? false,
-                    description: page.frontmatter.description,
-                    date: page.frontmatter.date,
-                    order: page.frontmatter.order,
-                    icon: page.frontmatter.icon,
-                },
-            });
-            for (const h of page.headings) {
-                const headingId = `${page.url}#${h.id}`;
-                const existingHeading = registry.getById('heading', headingId);
-                if (existingHeading && existingHeading.sourceUrl !== page.url) {
-                    ctx.warn(`Heading '${headingId}' already registered from '${existingHeading.sourceUrl}'`, page.url);
+export function createCorePipelineHooks(opts = {}) {
+    const xrefPatterns = opts.xrefPatterns ?? [];
+    const embedConfig = opts.embedConfig;
+    return {
+        preprocess: preprocessSnippets,
+        register(pages, registry, ctx) {
+            for (const page of pages) {
+                const parentUrl = deriveParentUrl(page.url);
+                const existingPage = registry.getById('page', page.url);
+                if (existingPage && existingPage.sourceUrl !== page.url) {
+                    ctx.warn(`Page '${page.url}' already registered from '${existingPage.sourceUrl}'`, page.url);
                 }
                 registry.register({
-                    type: 'heading',
-                    id: headingId,
+                    type: 'page',
+                    id: page.url,
                     sourceUrl: page.url,
-                    data: { level: h.level, text: h.text, headingId: h.id, url: page.url },
+                    data: {
+                        title: page.title,
+                        url: page.url,
+                        parentUrl,
+                        draft: page.frontmatter.draft ?? false,
+                        description: page.frontmatter.description,
+                        date: page.frontmatter.date,
+                        order: page.frontmatter.order,
+                        icon: page.frontmatter.icon,
+                    },
                 });
+                for (const h of page.headings) {
+                    const headingId = `${page.url}#${h.id}`;
+                    const existingHeading = registry.getById('heading', headingId);
+                    if (existingHeading && existingHeading.sourceUrl !== page.url) {
+                        ctx.warn(`Heading '${headingId}' already registered from '${existingHeading.sourceUrl}'`, page.url);
+                    }
+                    registry.register({
+                        type: 'heading',
+                        id: headingId,
+                        sourceUrl: page.url,
+                        data: { level: h.level, text: h.text, headingId: h.id, url: page.url },
+                    });
+                }
             }
-        }
-    },
-    aggregate(registry, ctx) {
-        const pageEntities = registry.getAll('page');
-        const pages = pageEntities.map(e => ({
-            url: e.data.url,
-            title: e.data.title,
-            parentUrl: e.data.parentUrl,
-            description: e.data.description,
-            icon: e.data.icon,
-            order: e.data.order,
-        }));
-        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]));
-        // 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 => ({
-            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__'];
-        if (!coreData)
-            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)
-            return page;
-        return { ...page, renderable };
-    },
-};
+            // SPEC-060 — register every drawer rune as a page-scoped entity so
+            // `{% ref "drawer-id" /%}` resolves to the drawer's address.
+            registerDrawers(pages, registry, ctx);
+        },
+        aggregate(registry, ctx) {
+            const pageEntities = registry.getAll('page');
+            const pages = pageEntities.map(e => ({
+                url: e.data.url,
+                title: e.data.title,
+                parentUrl: e.data.parentUrl,
+                description: e.data.description,
+                icon: e.data.icon,
+                order: e.data.order,
+            }));
+            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]));
+            // 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 => ({
+                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, xrefPatterns, embedConfig };
+        },
+        postProcess(page, aggregated, ctx) {
+            const coreData = aggregated['__core__'];
+            if (!coreData)
+                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);
+            // SPEC-060 — rewrite `data-drawer-title-auto` placeholders to the
+            // appropriate `h{n}` based on outline depth. Runs before xref
+            // resolution so the rewritten title doesn't carry the sentinel
+            // attribute into the rendered HTML.
+            renderable = resolveAutoDrawerTitleLevels(renderable);
+            // SPEC-066 expand resolution — substitutes embedded entity content
+            // before xref runs so refs inside substituted content are resolved
+            // by the same pass as host-page refs.
+            renderable = resolveExpands(renderable, page.url, coreData.registry, coreData.xrefPatterns ?? [], coreData.embedConfig, ctx);
+            renderable = resolveXrefs(renderable, page.url, coreData.registry, coreData.xrefPatterns ?? [], ctx);
+            // SPEC-062 standalone snippet wrap: turn `<pre data-snippet-source>`
+            // into `<figure class="rf-snippet">` when not inside a fence-consuming
+            // container (codegroup, diff). The wrap is a no-op when the page
+            // has no snippet-derived fences.
+            const wrappedPage = wrapStandaloneSnippets(renderable === page.renderable ? page : { ...page, renderable }, aggregated, ctx);
+            // SPEC-066 outline-scope walkers: prefix heading IDs and drop TOC
+            // items inside any `data-outline-scope` subtree. Generic — any rune
+            // can set the attribute and get the behaviour. Runs last so it can
+            // see the final tree (including expand-substituted content once
+            // that lands in v0.15.0).
+            applyOutlineScopeWalkers(wrappedPage.renderable);
+            return wrappedPage;
+        },
+    };
+}
+/**
+ * Core cross-page pipeline hooks (no xref patterns configured).
+ *
+ * Equivalent to `createCorePipelineHooks()`. The content loader bootstrap
+ * uses {@link createCorePipelineHooks} directly when
+ * `refrakt.config.json#/xrefs` is configured so the resolver can use the
+ * compiled patterns as a URL-resolution fallback. Run for every site,
+ * before any plugin hooks. Registers page and heading entities, aggregates
+ * the page tree and breadcrumb paths, and resolves blog post listings.
+ */
+export const corePipelineHooks = createCorePipelineHooks();
 //# sourceMappingURL=config.js.map