@refrakt-md/runes 0.16.0 → 0.17.0

package/dist/config.d.ts

@@ -57,6 +57,13 @@ export interface CorePipelineHooksOptions {
      *  through `aggregate` into the postProcess `coreData` shape so the xref
      *  resolver can use them as a URL-resolution fallback. */
     xrefPatterns?: CompiledXrefPattern[];
+    /** Canonical GitHub (or compatible) repository URL — `SiteConfig.repoUrl`
+     *  threaded through to the file-ref resolver (SPEC-078) so it can build
+     *  deep-link source URLs of the form `{repoUrl}/blob/{ref}/{path}#L{...}`. */
+    repoUrl?: string;
+    /** Git ref appended to GitHub source URLs (branch / tag / commit SHA).
+     *  Defaults to `"main"` when omitted. */
+    repoBranch?: string;
     /** 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

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;AAS/H,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAgF9D;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAswBxB,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,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC;;;yEAGiE;QACjE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,WAAW,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,wBAA6B,GAAG,mBAAmB,CAiQhG;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAA+C,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;AAkF9D;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAgxBxB,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;;kFAE8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;6CACyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;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,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC;;;yEAGiE;QACjE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,WAAW,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,wBAA6B,GAAG,mBAAmB,CA0ShG;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAA+C,CAAC"}

package/dist/config.js

@@ -7,7 +7,9 @@ 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 { 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';
 import { resolveExpands } from './expand-pipeline.js';
 import { resolveCollections } from './collection-resolve.js';
@@ -120,19 +122,20 @@ export const coreConfig = {
             block: 'codegroup',
             defaultDensity: 'compact',
             modifiers: { title: { source: 'meta', noBemClass: true }, overflow: { source: 'meta', default: 'scroll' } },
-            structure: {
-                topbar: {
-                    tag: 'div', before: true,
-                    children: [
-                        { tag: 'span', ref: 'dot' },
-                        { tag: 'span', ref: 'dot' },
-                        { tag: 'span', ref: 'dot' },
-                        { tag: 'span', ref: 'title', metaText: 'title', condition: 'title' },
-                    ],
-                },
+            // 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.
+            // `renderWhenEmpty` lets `title=""` still project the topbar (window
+            // chrome, no filename); an absent title renders no topbar.
+            metaFields: {
+                title: { metaType: 'code', condition: 'title', renderWhenEmpty: true },
             },
-            sections: { topbar: 'header', title: 'title' },
-            editHints: { panel: 'code', title: 'none' },
+            blocks: {
+                topbar: { fields: ['title'], layout: 'bar' },
+            },
+            layout: { root: ['topbar'] },
+            sections: { topbar: 'header' },
+            editHints: { panel: 'code' },
             postTransform(node) {
                 // Opt in to the highlight transform's `theme.code.colorScheme`
                 // cascade so the topbar + tab chrome flip with the inner code.
@@ -158,11 +161,24 @@ export const coreConfig = {
          * still needs an entry in the theme config so `computeUsedCssBlocks`
          * includes `badge.css` in CSS tree-shaking when a badge is rendered. */
         Badge: { block: 'badge' },
+        /* SPEC-079 composable rune handles — render the same DOM as the
+         * engine's `split` / `definition-list` layout primitives. CSS comes
+         * from the universal `[data-zone-layout=…]` selectors; per-rune
+         * blocks exist so CSS tree-shaking includes them. */
+        Bar: { block: 'bar' },
+        Deflist: { block: 'deflist' },
         /* Collection emits a sentinel during transform; the postProcess hook
          * (`resolveCollections`) fills it with queried entities. Engine config
          * provides the block name for CSS tree-shaking. */
         Collection: { block: 'collection' },
         Relationships: { block: 'relationships' },
+        /* file-ref emits a sentinel during transform; resolveFileRefs in
+         * the postProcess chain binds it to a GitHub URL anchor (and to
+         * a hoist sentinel for the drawer pipeline when preview="drawer").
+         * Engine config entry exists so the BEM block / data-rune are
+         * registered and CSS tree-shaking includes file-ref.css when
+         * authors use the rune. */
+        FileRef: { block: 'file-ref' },
         /* Aggregate emits a sentinel during transform; the postProcess hook
          * (`resolveAggregates`) fills it with either a single integer (no-body
          * form) or a body-zoned breakdown. Engine config provides the block
@@ -256,29 +272,25 @@ export const coreConfig = {
         Budget: {
             block: 'budget',
             defaultDensity: 'full',
-            sections: { header: 'header', preamble: 'preamble', headline: 'title', footer: 'footer' },
-            editHints: { headline: 'inline', meta: 'none', 'meta-item': 'none' },
+            sections: { preamble: 'preamble', headline: 'title', footer: 'footer' },
+            editHints: { headline: 'inline' },
             modifiers: {
                 currency: { source: 'meta', default: 'USD' },
                 duration: { source: 'meta' },
                 showPerDay: { source: 'meta', default: 'true' },
                 variant: { source: 'meta', default: 'detailed' },
             },
-            structure: {
-                header: {
-                    tag: 'div', before: true,
-                    conditionAny: ['currency', 'duration'],
-                    children: [
-                        {
-                            tag: 'div', ref: 'meta',
-                            children: [
-                                { tag: 'span', ref: 'meta-item', metaText: 'currency', condition: 'currency', metaType: 'category', metaRank: 'primary' },
-                                { tag: 'span', ref: 'meta-item', metaText: 'duration', label: 'Duration:', condition: 'duration', metaType: 'temporal', metaRank: 'secondary' },
-                            ],
-                        },
-                    ],
-                },
+            // Duration reads first as a bare chip (self-evident, no label);
+            // currency is pushed to the right edge where it reads naturally
+            // against the budget breakdown below.
+            metaFields: {
+                duration: { metaType: 'category', condition: 'duration' },
+                currency: { metaType: 'category', condition: 'currency' },
+            },
+            blocks: {
+                meta: { fields: ['duration', { field: 'currency', align: 'end' }], layout: 'bar' },
             },
+            layout: { root: ['meta', 'preamble'] },
             postTransform(node) {
                 const block = 'rf-budget';
                 const catBlock = 'rf-budget-category';
@@ -345,16 +357,16 @@ export const coreConfig = {
             modifiers: { hintType: { source: 'meta', default: 'note' } },
             contextModifiers: { 'hero': 'in-hero', 'feature': 'in-feature' },
             sections: { header: 'header' },
-            editHints: { icon: 'none', title: 'none' },
-            structure: {
-                header: {
-                    tag: 'div', before: true,
-                    children: [
-                        { tag: 'span', ref: 'icon', icon: { group: 'hint', variant: 'hintType' } },
-                        { tag: 'span', ref: 'title', metaText: 'hintType' },
-                    ],
-                },
+            // Header is a single `hintType` field, icon-decorated: the value
+            // (note/warning/caution/check) selects both the glyph and the
+            // label text.
+            metaFields: {
+                hintType: { icon: { group: 'hint' } },
+            },
+            blocks: {
+                header: { fields: ['hintType'], layout: 'bar' },
             },
+            layout: { root: ['header'] },
         },
         Drawer: {
             block: 'drawer',
@@ -364,8 +376,8 @@ export const coreConfig = {
                 size: { source: 'meta', default: 'md' },
                 shortcut: { source: 'meta', noBemClass: true },
             },
-            sections: { header: 'header', body: 'body' },
-            editHints: { title: 'inline', body: 'none', close: 'none' },
+            sections: { header: 'header', body: 'body', footer: 'footer' },
+            editHints: { title: 'inline', body: 'none', close: 'none', footer: 'none' },
         },
         Figure: {
             block: 'figure',
@@ -2080,6 +2092,8 @@ navSearchScope) {
 export function createCorePipelineHooks(opts = {}) {
     const xrefPatterns = opts.xrefPatterns ?? [];
     const embedConfig = opts.embedConfig;
+    const repoUrl = opts.repoUrl;
+    const repoBranch = opts.repoBranch;
     return {
         preprocess: preprocessSnippets,
         register(pages, registry, ctx) {
@@ -2150,7 +2164,7 @@ export function createCorePipelineHooks(opts = {}) {
                 draft: e.data.draft || false,
                 frontmatter: e.data,
             }));
-            return { pageTree, breadcrumbPaths, pagesByUrl, headingIndex, allPosts, registry, xrefPatterns, embedConfig };
+            return { pageTree, breadcrumbPaths, pagesByUrl, headingIndex, allPosts, registry, xrefPatterns, embedConfig, repoUrl, repoBranch };
         },
         postProcess(page, aggregated, ctx) {
             const coreData = aggregated['__core__'];
@@ -2171,6 +2185,23 @@ export function createCorePipelineHooks(opts = {}) {
             // resolution so the rewritten title doesn't carry the sentinel
             // attribute into the rendered HTML.
             renderable = resolveAutoDrawerTitleLevels(renderable);
+            // SPEC-078 — bind file-ref sentinels to their GitHub URLs and emit
+            // the hoist sentinel when `preview="drawer"`. Must run before
+            // `hoistPreviewDrawers` (which consumes the hoist sentinel) and
+            // before xref resolution (so the file-ref's inline `<a>` carries
+            // its final href into the rendered tree).
+            renderable = resolveFileRefs(renderable, page.url, coreData.repoUrl, coreData.repoBranch, ctx);
+            // SPEC-078 — rewrite xref placeholders carrying `data-xref-preview=
+            // "drawer"` into an inline `<a href="#drawer-{id}">` + hoist
+            // sentinel. Non-preview xref placeholders pass through to
+            // resolveXrefs later in the chain.
+            renderable = resolveXrefPreviews(renderable, page.url, coreData.registry, ctx);
+            // SPEC-078 hoist mechanism — collect `preview="drawer"` sentinels
+            // from file-ref / xref / future reference runes and emit hoisted
+            // `<section class="rf-drawer">` at the page root. Runs before
+            // expand resolution so an xref-preview drawer's body (which uses
+            // the expand resolver internally) is resolved by the same pass.
+            renderable = hoistPreviewDrawers(renderable, page.url, coreData.registry, coreData.embedConfig?.projectRoot, ctx);
             // 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.