@refrakt-md/runes 0.14.4 → 0.16.0

package/dist/drawer-pipeline.js

@@ -0,0 +1,206 @@
+/**
+ * Drawer pipeline hooks (SPEC-060, WORK-257).
+ *
+ * - **Register** walks each page's renderable for drawer tags
+ *   (`data-rune="drawer"`), and adds each as a page-scoped entity
+ *   (`type: 'drawer'`, `scope: 'page'`, `sourceUrl: "${pageUrl}#drawer-${id}"`).
+ *   Page scope means two pages can both declare `id="auth"` without
+ *   colliding in the site-wide registry (WORK-256).
+ *
+ * - **postProcess** resolves drawer title heading levels for drawers that
+ *   were authored without an explicit `headingLevel`. The title carries
+ *   a `data-drawer-title-auto` marker emitted by the schema; the walk
+ *   tracks document outline depth (the most recent `<h{n}>` seen) and
+ *   rewrites the marked tag to `h{n+1}` (clamped 1..6, default h2 when
+ *   no preceding heading exists).
+ */
+import Markdoc from '@markdoc/markdoc';
+import { DRAWER_TITLE_AUTO_MARKER } from './tags/drawer.js';
+const { Tag } = Markdoc;
+const HEADING_TAG_RE = /^h([1-6])$/;
+/** Read a `data-*` attribute from a tag, treating undefined as undefined. */
+function readDataAttr(tag, key) {
+    const v = tag.attributes?.[key];
+    return typeof v === 'string' ? v : undefined;
+}
+/** Read the `content` of a property meta tag (`<meta data-field="...">`)
+ *  immediately under the drawer tag. The schema emits side/size/shortcut as
+ *  meta tags; the identity-transform engine consumes them later and stamps
+ *  them as `data-side` etc. on the wrapper. The register hook runs before
+ *  the engine, so we have to read directly from the meta tags. */
+function readPropertyMeta(drawerTag, field) {
+    for (const child of drawerTag.children ?? []) {
+        if (!Tag.isTag(child))
+            continue;
+        const c = child;
+        if (c.name !== 'meta')
+            continue;
+        if (c.attributes?.['data-field'] !== field)
+            continue;
+        const content = c.attributes?.['content'];
+        return typeof content === 'string' ? content : undefined;
+    }
+    return undefined;
+}
+/**
+ * Walk the renderable tree of every page and register each drawer rune
+ * as a page-scoped entity. Each drawer surfaces in the registry as
+ * `{ type: 'drawer', id, scope: 'page', sourceUrl: '<pageUrl>#drawer-<id>' }`
+ * with `data.title`, `data.side`, `data.size`, `data.shortcut` for
+ * downstream consumers (xref resolver, registry-driven tooling).
+ */
+export function registerDrawers(pages, registry, ctx) {
+    for (const page of pages) {
+        const drawersOnPage = [];
+        const seenIds = new Set();
+        walkForDrawers(page.renderable, (tag) => {
+            const id = readDataAttr(tag, 'data-drawer-id');
+            if (!id) {
+                ctx.error('drawer rune is missing required `id` attribute', page.url);
+                return;
+            }
+            if (seenIds.has(id)) {
+                ctx.warn(`drawer id="${id}" is declared more than once on this page — last declaration wins`, page.url);
+            }
+            seenIds.add(id);
+            drawersOnPage.push({
+                id,
+                title: extractTitleText(tag),
+                side: readPropertyMeta(tag, 'side') ?? 'right',
+                size: readPropertyMeta(tag, 'size') ?? 'md',
+                shortcut: readPropertyMeta(tag, 'shortcut'),
+            });
+        });
+        for (const d of drawersOnPage) {
+            registry.register({
+                type: 'drawer',
+                id: d.id,
+                scope: 'page',
+                sourceUrl: `${page.url}#drawer-${d.id}`,
+                data: {
+                    title: d.title,
+                    side: d.side,
+                    size: d.size,
+                    shortcut: d.shortcut,
+                },
+            });
+        }
+    }
+}
+/** Walk the renderable looking for drawer-rune tags. Visits each drawer's
+ *  shell exactly once (we don't recurse into a drawer's body, drawer-in-drawer
+ *  is out of scope). */
+function walkForDrawers(node, visit) {
+    if (Array.isArray(node)) {
+        for (const c of node)
+            walkForDrawers(c, visit);
+        return;
+    }
+    if (!Tag.isTag(node))
+        return;
+    const tag = node;
+    if (tag.attributes?.['data-rune'] === 'drawer') {
+        visit(tag);
+        // Don't recurse — drawer-in-drawer isn't supported and skipping the
+        // body avoids treating a future inner-drawer descendant as a sibling
+        // of the outer one.
+        return;
+    }
+    if (!tag.children)
+        return;
+    for (const c of tag.children)
+        walkForDrawers(c, visit);
+}
+/** Pull the drawer's title text out of its header → title element. Returns
+ *  `undefined` when the drawer has no title (the rune renders headerless
+ *  in that case). String concatenation of leaf text nodes is good enough —
+ *  drawer titles are short. */
+function extractTitleText(drawerTag) {
+    const titleTag = findByDataName(drawerTag, 'title');
+    if (!titleTag)
+        return undefined;
+    const text = collectText(titleTag);
+    return text.length > 0 ? text : undefined;
+}
+function findByDataName(root, name) {
+    if (root.attributes?.['data-name'] === name) {
+        return root;
+    }
+    for (const c of root.children ?? []) {
+        if (Tag.isTag(c)) {
+            const hit = findByDataName(c, name);
+            if (hit)
+                return hit;
+        }
+    }
+    return undefined;
+}
+function collectText(node) {
+    if (typeof node === 'string')
+        return node;
+    if (Array.isArray(node))
+        return node.map(collectText).join('');
+    if (Tag.isTag(node)) {
+        const tag = node;
+        return (tag.children ?? []).map(collectText).join('');
+    }
+    return '';
+}
+/**
+ * postProcess walk: rewrite each `data-drawer-title-auto` heading to the
+ * level computed from the outline depth at that position on the page.
+ * Returns the same renderable identity when no drawer titles needed
+ * rewriting, so downstream postProcess steps can skip a no-op pass.
+ */
+export function resolveAutoDrawerTitleLevels(renderable) {
+    const state = { lastHeadingLevel: 0, mutated: false };
+    const next = walkAndRewriteTitles(renderable, state);
+    return state.mutated ? next : renderable;
+}
+function walkAndRewriteTitles(node, state) {
+    if (typeof node === 'string' || typeof node === 'number' || node == null)
+        return node;
+    if (Array.isArray(node)) {
+        let mutated = false;
+        const next = node.map((c) => {
+            const w = walkAndRewriteTitles(c, state);
+            if (w !== c)
+                mutated = true;
+            return w;
+        });
+        return mutated ? next : node;
+    }
+    if (!Tag.isTag(node))
+        return node;
+    const tag = node;
+    const headingMatch = HEADING_TAG_RE.exec(tag.name);
+    // Auto-title placeholder: rewrite this node's tag name based on the
+    // last heading level we saw. Default to h2 when no heading has been
+    // encountered yet (the page-title h1 lives in layout, so the next
+    // reasonable level inside the body is h2).
+    const isAutoTitle = tag.attributes?.[DRAWER_TITLE_AUTO_MARKER] === 'true';
+    if (isAutoTitle) {
+        const base = state.lastHeadingLevel === 0 ? 1 : state.lastHeadingLevel;
+        const targetLevel = Math.min(6, Math.max(1, base + 1));
+        state.mutated = true;
+        const newAttrs = { ...tag.attributes };
+        delete newAttrs[DRAWER_TITLE_AUTO_MARKER];
+        return new Tag(`h${targetLevel}`, newAttrs, tag.children);
+    }
+    if (headingMatch) {
+        state.lastHeadingLevel = Number(headingMatch[1]);
+    }
+    if (!tag.children || tag.children.length === 0)
+        return tag;
+    let mutated = false;
+    const newChildren = tag.children.map((c) => {
+        const w = walkAndRewriteTitles(c, state);
+        if (w !== c)
+            mutated = true;
+        return w;
+    });
+    if (!mutated)
+        return tag;
+    return new Tag(tag.name, tag.attributes, newChildren);
+}
+//# sourceMappingURL=drawer-pipeline.js.map

package/dist/drawer-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drawer-pipeline.js","sourceRoot":"","sources":["../src/drawer-pipeline.ts"],"names":[],"mappings":"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"}

package/dist/expand-pipeline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Expand pipeline (SPEC-066, WORK-260).
+ *
+ * Post-process resolver that finds `{% expand %}` placeholder tags
+ * (`data-rune="expand-pending"`) in a page's renderable tree, looks
+ * each up in the registry, reads + parses the entity's `sourceFile`
+ * (cached per build), calls the plugin's `extract()` to grab the
+ * embeddable AST subtree, optionally shifts heading levels, transforms
+ * the subtree using the build's full tags+nodes config, and substitutes
+ * the result in place wrapped in `<section class="rf-expand"
+ * data-rune="expand" data-outline-scope="${id}">`.
+ *
+ * The wrapper's `data-outline-scope` attribute is picked up by the
+ * WORK-259 walkers — heading IDs inside get prefixed, TOC items
+ * pointing at them get dropped — without expand needing to coordinate.
+ *
+ * Per-build caches:
+ *   - `sourceFile → parsedAst` (one parse per file regardless of how
+ *     many pages embed it)
+ *
+ * Per-page state:
+ *   - resolution stack (`(type, id)` tuples) for cycle detection
+ */
+import type { Node } from '@markdoc/markdoc';
+import type { EntityRegistry, PipelineContext } from '@refrakt-md/types';
+import type { CompiledXrefPattern } from './xref-patterns.js';
+export interface ExpandResolveContext {
+    pageUrl: string;
+    registry: Readonly<EntityRegistry>;
+    patterns: CompiledXrefPattern[];
+    embedConfig?: {
+        tags: Record<string, unknown>;
+        nodes: Record<string, unknown>;
+        projectRoot?: string;
+    };
+    ctx: PipelineContext;
+    /** Per-build source-file cache. Shared across calls within one build,
+     *  so a file embedded on twenty pages is parsed once. */
+    parseCache: Map<string, Node>;
+}
+/** Reset the per-build cache. Tests call this between cases; production
+ *  builds rely on the cache living for the build's lifetime (each build
+ *  starts fresh because the runes package is imported anew). */
+export declare function __resetExpandCache(): void;
+/**
+ * Walk a renderable tree, replace every `expand-pending` placeholder
+ * with the substituted entity content. Returns the same renderable
+ * reference when no placeholders were found.
+ */
+export declare function resolveExpands(renderable: unknown, pageUrl: string, registry: Readonly<EntityRegistry>, patterns: CompiledXrefPattern[], embedConfig: ExpandResolveContext['embedConfig'], ctx: PipelineContext): unknown;
+//# sourceMappingURL=expand-pipeline.d.ts.map

package/dist/expand-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand-pipeline.d.ts","sourceRoot":"","sources":["../src/expand-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAsB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG7F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAI9D,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACnC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,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;IACF,GAAG,EAAE,eAAe,CAAC;IACrB;6DACyD;IACzD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC9B;AAOD;;gEAEgE;AAChE,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAClC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,WAAW,EAAE,oBAAoB,CAAC,aAAa,CAAC,EAChD,GAAG,EAAE,eAAe,GAClB,OAAO,CAUT"}

package/dist/expand-pipeline.js

@@ -0,0 +1,314 @@
+/**
+ * Expand pipeline (SPEC-066, WORK-260).
+ *
+ * Post-process resolver that finds `{% expand %}` placeholder tags
+ * (`data-rune="expand-pending"`) in a page's renderable tree, looks
+ * each up in the registry, reads + parses the entity's `sourceFile`
+ * (cached per build), calls the plugin's `extract()` to grab the
+ * embeddable AST subtree, optionally shifts heading levels, transforms
+ * the subtree using the build's full tags+nodes config, and substitutes
+ * the result in place wrapped in `<section class="rf-expand"
+ * data-rune="expand" data-outline-scope="${id}">`.
+ *
+ * The wrapper's `data-outline-scope` attribute is picked up by the
+ * WORK-259 walkers — heading IDs inside get prefixed, TOC items
+ * pointing at them get dropped — without expand needing to coordinate.
+ *
+ * Per-build caches:
+ *   - `sourceFile → parsedAst` (one parse per file regardless of how
+ *     many pages embed it)
+ *
+ * Per-page state:
+ *   - resolution stack (`(type, id)` tuples) for cycle detection
+ */
+import Markdoc from '@markdoc/markdoc';
+import { EXPAND_PLACEHOLDER_MARKER } from './tags/expand.js';
+import { readWholeSandboxedFile, SnippetSandboxError } from './lib/read-file.js';
+const { Tag } = Markdoc;
+/** Per-build source-file parse cache. Lives outside the resolve context
+ *  so a single build's runs reuse the same instance — the resolver is
+ *  invoked per page, but the cache is per build. */
+const buildParseCache = new Map();
+/** Reset the per-build cache. Tests call this between cases; production
+ *  builds rely on the cache living for the build's lifetime (each build
+ *  starts fresh because the runes package is imported anew). */
+export function __resetExpandCache() {
+    buildParseCache.clear();
+}
+/**
+ * Walk a renderable tree, replace every `expand-pending` placeholder
+ * with the substituted entity content. Returns the same renderable
+ * reference when no placeholders were found.
+ */
+export function resolveExpands(renderable, pageUrl, registry, patterns, embedConfig, ctx) {
+    const rc = {
+        pageUrl,
+        registry,
+        patterns,
+        embedConfig,
+        ctx,
+        parseCache: buildParseCache,
+    };
+    return walk(renderable, rc, []);
+}
+function walk(node, rc, stack) {
+    if (Array.isArray(node)) {
+        let mutated = false;
+        const next = node.map((c) => {
+            const w = walk(c, rc, stack);
+            if (w !== c)
+                mutated = true;
+            return w;
+        });
+        return mutated ? next : node;
+    }
+    if (!Tag.isTag(node))
+        return node;
+    const tag = node;
+    const dataRune = tag.attributes?.['data-rune'];
+    if (dataRune === EXPAND_PLACEHOLDER_MARKER) {
+        return resolveOnePlaceholder(tag, rc, stack);
+    }
+    if (!tag.children || tag.children.length === 0)
+        return tag;
+    let mutated = false;
+    const newChildren = tag.children.map((c) => {
+        const w = walk(c, rc, stack);
+        if (w !== c)
+            mutated = true;
+        return w;
+    });
+    if (!mutated)
+        return tag;
+    return new Tag(tag.name, tag.attributes, newChildren);
+}
+function resolveOnePlaceholder(tag, rc, stack) {
+    const attrs = tag.attributes;
+    const id = String(attrs['data-expand-id'] ?? '');
+    const typeHint = attrs['data-expand-type'];
+    const levelAttr = attrs['data-expand-level'];
+    const canonical = attrs['data-expand-canonical'] === 'true';
+    const authoredLabel = attrs['data-expand-label'];
+    if (!id) {
+        rc.ctx.error(`expand placeholder is missing \`primary\`/id attribute on ${rc.pageUrl}`, rc.pageUrl);
+        return errorNode(id, 'missing id attribute');
+    }
+    const level = levelAttr !== undefined ? Number(levelAttr) : undefined;
+    const entity = findEmbeddableEntity(rc.registry, id, rc.pageUrl, typeHint);
+    if (!entity) {
+        rc.ctx.error(`expand "${id}" on ${rc.pageUrl} — entity not found`, rc.pageUrl);
+        return errorNode(id, 'entity not found');
+    }
+    // Embeddable via embed() OR (sourceFile + extract) — SPEC-069.
+    if (!entity.embed && !(entity.sourceFile && entity.extract)) {
+        rc.ctx.error(`expand "${id}" on ${rc.pageUrl} — entity type "${entity.type}" does not support embedding (no embed() or sourceFile/extract)`, rc.pageUrl);
+        return errorNode(id, `entity type "${entity.type}" does not support embedding`);
+    }
+    // Cycle detection. The stack is per-page-render — embedding the same
+    // entity on two different pages is fine; embedding it inside itself
+    // transitively is the bug we catch.
+    if (stack.some(s => s.type === entity.type && s.id === entity.id)) {
+        const cyclePath = [...stack, { type: entity.type, id: entity.id }]
+            .map(s => `${s.id} (${s.type})`)
+            .join(' → ');
+        rc.ctx.error(`expand cycle detected on ${rc.pageUrl}. Cycle: ${cyclePath}`, rc.pageUrl);
+        return errorNode(id, 'cycle detected');
+    }
+    // Resolve the entity's content: embed() (in-memory) takes precedence; else
+    // read + extract from the source file (requires a project root).
+    let extracted;
+    if (entity.embed) {
+        extracted = entity.embed();
+    }
+    else {
+        const projectRoot = rc.embedConfig?.projectRoot;
+        if (!projectRoot) {
+            rc.ctx.error(`expand "${id}" — no project root configured (embedConfig.projectRoot is unset)`, rc.pageUrl);
+            return errorNode(id, 'no project root configured');
+        }
+        let parsed;
+        try {
+            parsed = parseSourceFile(entity.sourceFile, projectRoot, rc.parseCache);
+        }
+        catch (err) {
+            const msg = err instanceof SnippetSandboxError ? err.message : err.message;
+            rc.ctx.error(`expand "${id}" — failed to read source file "${entity.sourceFile}": ${msg}`, rc.pageUrl);
+            return errorNode(id, msg);
+        }
+        extracted = entity.extract(parsed);
+    }
+    if (!extracted) {
+        rc.ctx.error(`expand "${id}" — extractor returned no content; the entity may be out-of-sync with the registry`, rc.pageUrl);
+        return errorNode(id, 'extractor returned no content');
+    }
+    // Heading processing — `level=N` shifts headings by `N - 1`. Without
+    // `level=` the embed stays in peer-document mode; the outline-scope
+    // walkers (WORK-259) handle ID namespacing + TOC isolation downstream.
+    let processed = extracted;
+    if (level !== undefined && level !== 1) {
+        const shift = level - 1;
+        const clampedHeadings = [];
+        processed = shiftHeadings(extracted, shift, clampedHeadings);
+        if (clampedHeadings.length > 0) {
+            rc.ctx.warn(`expand "${id}" at ${rc.pageUrl} — heading demotion (level=${level}) would push ${clampedHeadings.length} heading(s) past H6. Clamped to H6: ${clampedHeadings.map(t => `"${t}"`).join(', ')}`, rc.pageUrl);
+        }
+    }
+    if (!rc.embedConfig) {
+        rc.ctx.error(`expand "${id}" — no embedConfig threaded through the pipeline`, rc.pageUrl);
+        return errorNode(id, 'no embed transform config');
+    }
+    // Transform the extracted subtree using the build's full tags+nodes
+    // config so embedded plan runes (or any other plugin-contributed
+    // schemas) execute normally. A nested walk handles any expand placeholders
+    // inside the embedded content (e.g. an embedded spec that references
+    // other specs).
+    const childStack = [...stack, { type: entity.type, id: entity.id }];
+    const transformed = Markdoc.transform(processed, rc.embedConfig);
+    const recursivelyResolved = walk(transformed, rc, childStack);
+    // Canonical-link affordance — resolve via the same chain xref uses.
+    const canonicalHref = resolveCanonicalHref(entity, rc.patterns);
+    // The engine's identity transform adds `class="rf-expand"` from the
+    // `Expand: { block: 'expand' }` config entry; don't set it here or it
+    // renders duplicated.
+    const wrapperAttrs = {
+        'data-rune': 'expand',
+        'data-entity-id': entity.id,
+        'data-entity-type': entity.type,
+        'data-source': 'registry',
+    };
+    // Outline-scope marker only when `level=` is unset (peer-document mode).
+    if (level === undefined) {
+        wrapperAttrs['data-outline-scope'] = entity.id;
+    }
+    if (canonicalHref) {
+        wrapperAttrs['data-canonical-href'] = canonicalHref;
+    }
+    const children = [];
+    if (Array.isArray(recursivelyResolved)) {
+        children.push(...recursivelyResolved);
+    }
+    else {
+        children.push(recursivelyResolved);
+    }
+    if (canonical) {
+        const label = authoredLabel || canonicalLinkDefault(entity);
+        const linkAttrs = {
+            class: canonicalHref
+                ? 'rf-expand__canonical-link'
+                : 'rf-expand__canonical-link rf-xref--unresolved',
+        };
+        if (canonicalHref)
+            linkAttrs.href = canonicalHref;
+        children.push(new Tag('a', linkAttrs, [label]));
+    }
+    return new Tag('section', wrapperAttrs, children);
+}
+/** Resolve an entity by id and (optional) type hint. Uses the same
+ *  registry surface as xref. */
+function findEmbeddableEntity(registry, id, pageUrl, typeHint) {
+    const types = typeHint ? [typeHint] : registry.getTypes();
+    for (const type of types) {
+        const e = registry.getById(type, id, pageUrl);
+        if (e)
+            return e;
+    }
+    // Name-match fallback (same algorithm as xref).
+    const idLower = id.toLowerCase();
+    for (const type of types) {
+        for (const e of registry.getAll(type)) {
+            const name = e.data.name ?? '';
+            const title = e.data.title ?? '';
+            if (name.toLowerCase() === idLower || title.toLowerCase() === idLower)
+                return e;
+        }
+    }
+    return undefined;
+}
+/** Resolve an entity's canonical URL using the same chain as xref: the
+ *  registered `sourceUrl` first, then pattern matching against the id. */
+function resolveCanonicalHref(entity, patterns) {
+    const sourceUrl = entity.sourceUrl;
+    const dataUrl = entity.data.url;
+    const baseUrl = dataUrl || sourceUrl;
+    if (baseUrl) {
+        const headingId = entity.data.headingId;
+        return headingId ? `${baseUrl}#${headingId}` : baseUrl;
+    }
+    for (const p of patterns) {
+        const m = p.match.exec(entity.id);
+        if (!m)
+            continue;
+        const groups = (m.groups ?? {});
+        const PLACEHOLDER_RE = /\{([a-zA-Z_$][a-zA-Z0-9_$]*)\}/g;
+        return p.template.replace(PLACEHOLDER_RE, (_match, name) => {
+            const value = name === 'id' ? entity.id : (groups[name] ?? '');
+            return value.split('/').map(encodeURIComponent).join('/');
+        });
+    }
+    return undefined;
+}
+function canonicalLinkDefault(entity) {
+    const title = entity.data.title;
+    const name = entity.data.name;
+    if (title)
+        return `View ${entity.type}: ${title}`;
+    if (name)
+        return `View ${entity.type}: ${name}`;
+    return `View ${entity.type} ${entity.id}`;
+}
+/** Parse a source file, caching per build. The path is resolved through
+ *  the same sandbox as snippet so absolute paths and traversal escapes
+ *  are rejected. File-system access lives behind a helper in
+ *  `lib/read-file.ts` so the `node:fs` import stays out of this module
+ *  and Vite can tree-shake it from browser bundles. */
+function parseSourceFile(sourceFile, projectRoot, cache) {
+    const cached = cache.get(sourceFile);
+    if (cached)
+        return cached;
+    const raw = readWholeSandboxedFile({ relativePath: sourceFile, projectRoot });
+    const ast = Markdoc.parse(raw);
+    cache.set(sourceFile, ast);
+    return ast;
+}
+/** Recursively shift heading levels in a Markdoc AST subtree. Tracks
+ *  headings that would push past H6 so the caller can warn. */
+function shiftHeadings(node, shift, clampedHeadings) {
+    if (node.type === 'heading') {
+        const originalLevel = node.attributes.level;
+        const newLevel = originalLevel + shift;
+        if (newLevel > 6) {
+            const text = collectHeadingText(node);
+            clampedHeadings.push(text);
+            node.attributes.level = 6;
+        }
+        else {
+            node.attributes.level = newLevel;
+        }
+    }
+    for (const child of node.children ?? []) {
+        shiftHeadings(child, shift, clampedHeadings);
+    }
+    return node;
+}
+function collectHeadingText(node) {
+    const parts = [];
+    for (const child of node.walk()) {
+        if (child.type === 'text' && typeof child.attributes.content === 'string') {
+            parts.push(child.attributes.content);
+        }
+    }
+    return parts.join('');
+}
+/** Build a visible error placeholder for an expand resolution that
+ *  failed. The build also surfaces the error via `ctx.error` — the
+ *  inline rendering exists so the failure shows up on the page. */
+function errorNode(id, message) {
+    // Engine adds `rf-expand` from the block config. Error variant gets a
+    // static modifier via the engine config; we only set the data attrs.
+    return new Tag('section', {
+        'data-rune': 'expand',
+        'data-entity-id': id,
+        'data-expand-error': message,
+    }, [`expand "${id}" — ${message}`]);
+}
+//# sourceMappingURL=expand-pipeline.js.map

package/dist/expand-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand-pipeline.js","sourceRoot":"","sources":["../src/expand-pipeline.ts"],"names":[],"mappings":"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"}

package/dist/field-match.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared field-match grammar (SPEC-070 canonical).
+ *
+ * One parser + matcher for the `field:value` selector used by `collection`'s
+ * `filter`, `entityRoutes`' `filter` (SPEC-069), and `backlog`.
+ *
+ *   filter   := clause (WS clause)*
+ *   clause   := field ":" value        // split on the FIRST colon
+ *   value    := bareword | '"' .* '"'  // double-quotes carry spaces
+ *
+ * Operator is selected by the value's shape:
+ *   - exact (default):  status:ready
+ *   - glob:             url:/blog/*     ( * → any run of chars, anchored full-match )
+ *   - regex:            id:/^SPEC-\d+$/  ( wrapped in slashes + optional flags )
+ *
+ * Same field repeated → OR; different fields → AND. Matching is case-sensitive.
+ */
+/** Minimal entity shape the matcher resolves fields from. */
+export interface MatchableEntity {
+    id: string;
+    type: string;
+    sourceUrl?: string;
+    sourceFile?: string;
+    data: Record<string, unknown>;
+}
+export interface FieldMatchClause {
+    field: string;
+    /** Values OR'd together for this field. */
+    values: string[];
+}
+export interface ParsedFieldMatch {
+    clauses: FieldMatchClause[];
+    warnings: string[];
+}
+/** Parse a filter expression into clauses, collecting warnings for malformed input. */
+export declare function parseFieldMatch(expr: string | undefined | null): ParsedFieldMatch;
+/** Resolve a field name against an entity: top-level first, then `data`; `url` is an alias. */
+export declare function resolveEntityField(entity: MatchableEntity, field: string): unknown;
+/** Test whether an entity matches all clauses (AND across fields, OR within a field). */
+export declare function matchesFieldMatch(entity: MatchableEntity, parsed: ParsedFieldMatch): boolean;
+/** Convenience: parse + match in one call. */
+export declare function matchesFilterExpr(entity: MatchableEntity, expr: string | undefined | null): boolean;
+//# sourceMappingURL=field-match.d.ts.map

package/dist/field-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-match.d.ts","sourceRoot":"","sources":["../src/field-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,MAAM,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AA2BD,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,gBAAgB,CA0BjF;AAED,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAIlF;AA+BD,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAO5F;AAED,8CAA8C;AAC9C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAEnG"}