@refrakt-md/content 0.14.4 → 0.16.0

package/dist/entity-routes.d.ts

@@ -0,0 +1,4 @@
+import type { PluginPipelineHooks } from '@refrakt-md/types';
+/** Build the contributePages hook for a site's entityRoutes config. */
+export declare function createEntityRoutesHooks(resolvePartial: (name: string) => string | undefined): PluginPipelineHooks;
+//# sourceMappingURL=entity-routes.d.ts.map

package/dist/entity-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-routes.d.ts","sourceRoot":"","sources":["../src/entity-routes.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAKX,mBAAmB,EAEnB,MAAM,mBAAmB,CAAC;AAsC3B,uEAAuE;AACvE,wBAAgB,uBAAuB,CACtC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAClD,mBAAmB,CA+CrB"}

package/dist/entity-routes.js

@@ -0,0 +1,91 @@
+/**
+ * Built-in entityRoutes config-rules adapter (SPEC-069 / WORK-268).
+ *
+ * Turns `site.entityRoutes` into a `contributePages` hook: selects entities by
+ * `type` + `filter` (shared field-match grammar), substitutes `{name}`
+ * placeholders, renders the inline `render` string (or a `render-template`
+ * partial) per entity with `$item` bound, and back-fills each matched entity's
+ * `sourceUrl` so refs prefer the on-site page.
+ */
+import { parseFieldMatch, matchesFieldMatch } from '@refrakt-md/runes';
+/** Fields available to `{name}` substitution: top-level + everything in `data`. */
+function substitutionFields(e) {
+    return { id: e.id, type: e.type, sourceUrl: e.sourceUrl, ...e.data };
+}
+/** Interpolate `{name}` placeholders from a field set. Missing → '' (with the
+ *  caller deciding whether to warn). Optionally per-segment URL-encode. */
+function substitute(template, fields, encode) {
+    return template.replace(/\{([^}]+)\}/g, (_m, name) => {
+        const raw = fields[name];
+        const value = raw == null ? '' : String(raw);
+        return encode ? value.split('/').map(encodeURIComponent).join('/') : value;
+    });
+}
+function substituteFrontmatter(fm, fields) {
+    if (!fm)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(fm)) {
+        out[k] = typeof v === 'string' ? substitute(v, fields, false) : v;
+    }
+    return out;
+}
+function project(e) {
+    const data = (e.data ?? {});
+    // Spread `data` so render templates can reference `$item.<field>` for the
+    // same fields available to URL `{name}` substitution. `id`, `type`, and
+    // `url` are canonical; `data` is preserved for templates that want the
+    // raw payload.
+    return { ...data, id: e.id, type: e.type, url: e.sourceUrl || String(data.url ?? ''), data };
+}
+/** Build the contributePages hook for a site's entityRoutes config. */
+export function createEntityRoutesHooks(resolvePartial) {
+    return {
+        contributePages(ctx) {
+            const site = ctx.siteConfig;
+            const rules = site?.entityRoutes;
+            if (!rules || rules.length === 0)
+                return [];
+            const pages = [];
+            for (const rule of rules) {
+                const inline = rule.render;
+                const templateName = rule['render-template'];
+                if (inline && templateName) {
+                    ctx.error(`entityRoutes: rule for type "${rule.type}" sets both render and render-template`);
+                    continue;
+                }
+                let content = inline ?? '';
+                if (templateName) {
+                    const loaded = resolvePartial(templateName);
+                    if (loaded == null) {
+                        ctx.error(`entityRoutes: render-template "${templateName}" could not be resolved`);
+                        continue;
+                    }
+                    content = loaded;
+                }
+                const types = rule.type.split(',').map((s) => s.trim()).filter(Boolean);
+                const parsed = rule.filter ? parseFieldMatch(rule.filter) : undefined;
+                if (parsed)
+                    for (const w of parsed.warnings)
+                        ctx.warn(`entityRoutes filter: ${w}`);
+                let entities = [];
+                for (const type of types)
+                    entities.push(...ctx.registry.getAll(type));
+                if (parsed)
+                    entities = entities.filter((e) => matchesFieldMatch(e, parsed));
+                for (const entity of entities) {
+                    const fields = substitutionFields(entity);
+                    const url = substitute(rule.url, fields, true);
+                    const title = rule.title ? substitute(rule.title, fields, false) : undefined;
+                    const frontmatter = substituteFrontmatter(rule.frontmatter, fields);
+                    pages.push({ url, title, frontmatter, content, variables: { item: project(entity) } });
+                    // Back-fill sourceUrl so refs/expands prefer the on-site page.
+                    // The registry stores live registration objects (pre-aggregate).
+                    entity.sourceUrl = url;
+                }
+            }
+            return pages;
+        },
+    };
+}
+//# sourceMappingURL=entity-routes.js.map

package/dist/entity-routes.js.map

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

package/dist/file-roots.d.ts

@@ -0,0 +1,70 @@
+/**
+ * File-roots scanning and resolution.
+ *
+ * A file root is a named directory that file-reading runes can reach via the
+ * `namespace:filename` syntax. The v1 consumer is Markdoc partials —
+ * `{% partial file="shared:footer.md" /%}` resolves from whatever directory
+ * is registered under `shared`. Snippet (SPEC-062 v2) and future file-reading
+ * runes plug into the same resolver.
+ *
+ * File roots originate from two sources:
+ * - **User config** — `refrakt.config.json#/fileRoots`, paths relative to the
+ *   config file's directory.
+ * - **Plugins** — `Plugin.fileRoots` field, paths relative to the plugin's
+ *   package directory (resolved by `loadPlugin` before reaching this layer).
+ *
+ * Plugin-vs-plugin collisions throw at merge time. User-vs-plugin collisions
+ * let the user win (see {@link mergeFileRoots}).
+ */
+import type { PartialFile } from './content-tree.js';
+export type FileRoots = Record<string, string>;
+/** Result of merging user-config + plugin file roots. */
+export interface MergedFileRoots {
+    /** Final namespace → absolute directory path map (user wins collisions). */
+    roots: FileRoots;
+    /** Soft diagnostics: warnings about plugin namespaces shadowed by user
+     *  config. Adapters can surface these alongside other build warnings. */
+    warnings: string[];
+}
+/**
+ * Resolve user-config file roots against the config-file directory.
+ *
+ * Each value in `userFileRoots` is interpreted relative to `configDir`.
+ * Validates namespace names (rejects reserved + empty) and that each
+ * resolved directory exists.
+ */
+export declare function resolveUserFileRoots(userFileRoots: FileRoots | undefined, configDir: string): FileRoots;
+/**
+ * Merge plugin-registered file roots with user-config-resolved ones.
+ *
+ * Precedence: **user wins** any collision. Plugins whose namespaces are
+ * shadowed by user config are still loaded (the runes etc.) but their
+ * file-root contribution is silently dropped, with a soft warning so the
+ * shadowing is visible during development.
+ */
+export declare function mergeFileRoots(userRoots: FileRoots, pluginRoots: FileRoots): MergedFileRoots;
+/**
+ * Scan every registered file root, returning `namespace:filename` →
+ * `PartialFile`.
+ *
+ * Each root is validated to exist (throws otherwise — broken config should
+ * fail loud at load time). Inside each root, all `.md` files are picked up
+ * recursively; subdirectory paths flow through as part of the filename
+ * (`shared:legal/terms.md`).
+ */
+export declare function readFileRoots(roots: FileRoots): Promise<Map<string, PartialFile>>;
+/** Validate a `namespace:filename` reference against the registered roots.
+ *
+ *  Returns the absolute file path for valid references; throws on:
+ *  - Unknown namespace (listing the available ones).
+ *  - Empty namespace (`:foo.md`).
+ *  - Absolute paths (`shared:/abs.md`).
+ *  - Traversal escapes (`shared:../escape.md`).
+ *
+ *  Note: this validation runs at scan time (above), so by the time content
+ *  authors hit a problem they see it at build, not at render. The function
+ *  is exported for runes (like the snippet rune's v2) that need to validate
+ *  ad-hoc references against the same rules.
+ */
+export declare function validateNamespacedReference(ref: string, roots: FileRoots): string;
+//# sourceMappingURL=file-roots.d.ts.map

package/dist/file-roots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-roots.d.ts","sourceRoot":"","sources":["../src/file-roots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC/B,4EAA4E;IAC5E,KAAK,EAAE,SAAS,CAAC;IACjB;6EACyE;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,aAAa,EAAE,SAAS,GAAG,SAAS,EACpC,SAAS,EAAE,MAAM,GACf,SAAS,CAsBX;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC7B,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,SAAS,GACpB,eAAe,CAYjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAmBvF;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAC1C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,GACd,MAAM,CAgCR"}

package/dist/file-roots.js

@@ -0,0 +1,146 @@
+/**
+ * File-roots scanning and resolution.
+ *
+ * A file root is a named directory that file-reading runes can reach via the
+ * `namespace:filename` syntax. The v1 consumer is Markdoc partials —
+ * `{% partial file="shared:footer.md" /%}` resolves from whatever directory
+ * is registered under `shared`. Snippet (SPEC-062 v2) and future file-reading
+ * runes plug into the same resolver.
+ *
+ * File roots originate from two sources:
+ * - **User config** — `refrakt.config.json#/fileRoots`, paths relative to the
+ *   config file's directory.
+ * - **Plugins** — `Plugin.fileRoots` field, paths relative to the plugin's
+ *   package directory (resolved by `loadPlugin` before reaching this layer).
+ *
+ * Plugin-vs-plugin collisions throw at merge time. User-vs-plugin collisions
+ * let the user win (see {@link mergeFileRoots}).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Resolve user-config file roots against the config-file directory.
+ *
+ * Each value in `userFileRoots` is interpreted relative to `configDir`.
+ * Validates namespace names (rejects reserved + empty) and that each
+ * resolved directory exists.
+ */
+export function resolveUserFileRoots(userFileRoots, configDir) {
+    if (!userFileRoots || Object.keys(userFileRoots).length === 0)
+        return {};
+    const resolved = {};
+    for (const [namespace, relativePath] of Object.entries(userFileRoots)) {
+        if (namespace.length === 0) {
+            throw new Error(`refrakt.config.json#/fileRoots: namespace name is empty — namespaces must be non-empty strings.`);
+        }
+        if (namespace === 'site') {
+            throw new Error(`refrakt.config.json#/fileRoots: namespace "${namespace}" is reserved. Pick a different name.`);
+        }
+        if (typeof relativePath !== 'string' || relativePath.length === 0) {
+            throw new Error(`refrakt.config.json#/fileRoots["${namespace}"] must be a non-empty string path.`);
+        }
+        resolved[namespace] = path.resolve(configDir, relativePath);
+    }
+    return resolved;
+}
+/**
+ * Merge plugin-registered file roots with user-config-resolved ones.
+ *
+ * Precedence: **user wins** any collision. Plugins whose namespaces are
+ * shadowed by user config are still loaded (the runes etc.) but their
+ * file-root contribution is silently dropped, with a soft warning so the
+ * shadowing is visible during development.
+ */
+export function mergeFileRoots(userRoots, pluginRoots) {
+    const merged = { ...pluginRoots };
+    const warnings = [];
+    for (const [namespace, absPath] of Object.entries(userRoots)) {
+        if (merged[namespace] && merged[namespace] !== absPath) {
+            warnings.push(`File-root namespace "${namespace}" is registered by both user config and a plugin. User config wins.`);
+        }
+        merged[namespace] = absPath;
+    }
+    return { roots: merged, warnings };
+}
+/**
+ * Scan every registered file root, returning `namespace:filename` →
+ * `PartialFile`.
+ *
+ * Each root is validated to exist (throws otherwise — broken config should
+ * fail loud at load time). Inside each root, all `.md` files are picked up
+ * recursively; subdirectory paths flow through as part of the filename
+ * (`shared:legal/terms.md`).
+ */
+export async function readFileRoots(roots) {
+    const map = new Map();
+    for (const [namespace, absPath] of Object.entries(roots)) {
+        let stat;
+        try {
+            stat = await fs.promises.stat(absPath);
+        }
+        catch {
+            throw new Error(`File root "${namespace}" — directory does not exist: ${absPath}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`File root "${namespace}" — expected a directory, got a file: ${absPath}`);
+        }
+        await scanRoot(absPath, absPath, namespace, map);
+    }
+    return map;
+}
+async function scanRoot(dirPath, rootPath, namespace, map) {
+    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            await scanRoot(fullPath, rootPath, namespace, map);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            const raw = await fs.promises.readFile(fullPath, 'utf-8');
+            // Use POSIX-style slashes in the key regardless of host OS so that
+            // authoring stays consistent across platforms.
+            const relative = path.relative(rootPath, fullPath).split(path.sep).join('/');
+            const key = `${namespace}:${relative}`;
+            map.set(key, { name: key, filePath: fullPath, raw });
+        }
+    }
+}
+/** Validate a `namespace:filename` reference against the registered roots.
+ *
+ *  Returns the absolute file path for valid references; throws on:
+ *  - Unknown namespace (listing the available ones).
+ *  - Empty namespace (`:foo.md`).
+ *  - Absolute paths (`shared:/abs.md`).
+ *  - Traversal escapes (`shared:../escape.md`).
+ *
+ *  Note: this validation runs at scan time (above), so by the time content
+ *  authors hit a problem they see it at build, not at render. The function
+ *  is exported for runes (like the snippet rune's v2) that need to validate
+ *  ad-hoc references against the same rules.
+ */
+export function validateNamespacedReference(ref, roots) {
+    const colonIdx = ref.indexOf(':');
+    if (colonIdx <= 0) {
+        throw new Error(`File-root reference "${ref}" is missing a namespace prefix. Expected "<namespace>:<path>".`);
+    }
+    const namespace = ref.slice(0, colonIdx);
+    const relative = ref.slice(colonIdx + 1);
+    if (relative.length === 0) {
+        throw new Error(`File-root reference "${ref}" is missing a path after the colon.`);
+    }
+    const root = roots[namespace];
+    if (!root) {
+        const available = Object.keys(roots).join(', ') || '(none registered)';
+        throw new Error(`Unknown file-root namespace "${namespace}" in reference "${ref}". Available: ${available}.`);
+    }
+    if (relative.startsWith('/')) {
+        throw new Error(`File-root reference "${ref}" uses an absolute path; namespaced references must be relative to the root.`);
+    }
+    const resolved = path.resolve(root, relative);
+    const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+    if (!resolved.startsWith(rootWithSep) && resolved !== root) {
+        throw new Error(`File-root reference "${ref}" escapes its root directory. Paths must stay within "${root}".`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=file-roots.js.map

package/dist/file-roots.js.map

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

package/dist/index.d.ts

@@ -14,4 +14,5 @@ export { EntityRegistryImpl } from './registry.js';
 export { createRefraktLoader, createVirtualRefraktLoader, buildHighlightOptions, type RefraktLoader, type RefraktLoaderOptions, type VirtualRefraktLoaderOptions } from './refract-loader.js';
 export { runPipeline, type HookSet, type PipelineResult, type PipelineStats } from './pipeline.js';
 export { formatPipelineSummary } from './format.js';
+export { readFileRoots, resolveUserFileRoots, mergeFileRoots, validateNamespacedReference, type FileRoots, type MergedFileRoots, } from './file-roots.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7H,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,eAAe,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,KAAK,0BAA0B,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5I,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAChJ,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC9G,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAC9L,OAAO,EAAE,WAAW,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7H,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,eAAe,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,KAAK,0BAA0B,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5I,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAChJ,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC9G,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAC9L,OAAO,EAAE,WAAW,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,2BAA2B,EAC3B,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -14,4 +14,5 @@ export { EntityRegistryImpl } from './registry.js';
 export { createRefraktLoader, createVirtualRefraktLoader, buildHighlightOptions } from './refract-loader.js';
 export { runPipeline } from './pipeline.js';
 export { formatPipelineSummary } from './format.js';
+export { readFileRoots, resolveUserFileRoots, mergeFileRoots, validateNamespacedReference, } from './file-roots.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA+E,MAAM,mBAAmB,CAAC;AAC7H,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAoB,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,MAAM,EAAc,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AAC/E,OAAO,EACL,kBAAkB,GAGnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,eAAe,EAA6C,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAiF,MAAM,WAAW,CAAC;AAC5I,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAA0E,MAAM,aAAa,CAAC;AAChJ,OAAO,EAAE,eAAe,EAAqB,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAwB,MAAM,cAAc,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAuB,MAAM,iBAAiB,CAAC;AAC9G,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,qBAAqB,EAAmF,MAAM,qBAAqB,CAAC;AAC9L,OAAO,EAAE,WAAW,EAAyD,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA+E,MAAM,mBAAmB,CAAC;AAC7H,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAoB,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,MAAM,EAAc,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AAC/E,OAAO,EACL,kBAAkB,GAGnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,eAAe,EAA6C,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAiF,MAAM,WAAW,CAAC;AAC5I,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAA0E,MAAM,aAAa,CAAC;AAChJ,OAAO,EAAE,eAAe,EAAqB,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAwB,MAAM,cAAc,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAuB,MAAM,iBAAiB,CAAC;AAC9G,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,qBAAqB,EAAmF,MAAM,qBAAqB,CAAC;AAC9L,OAAO,EAAE,WAAW,EAAyD,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,2BAA2B,GAG5B,MAAM,iBAAiB,CAAC"}

package/dist/loader.d.ts

@@ -1,7 +1,9 @@
 import type { Schema } from '@markdoc/markdoc';
 import type { Plugin, SecurityPolicy } from '@refrakt-md/types';
+import type { CompiledXrefPattern } from '@refrakt-md/runes';
 import { type Site, type VirtualReader } from './site.js';
 import type { ContentTree } from './content-tree.js';
+import type { FileRoots } from './file-roots.js';
 export interface SiteLoaderOptions {
     dirPath: string;
     basePath?: string;
@@ -13,6 +15,22 @@ export interface SiteLoaderOptions {
     variables?: Record<string, unknown>;
     /** Security policy for untrusted author content. Default: `'trusted'`. */
     securityPolicy?: SecurityPolicy;
+    /** Absolute path to the project root (where `refrakt.config.json` lives).
+     *  Used to compute `$file.path` as a project-root-relative POSIX path.
+     *  When omitted, defaults to `dirPath`'s parent — adapters that resolve a
+     *  config file should pass `dirname(configPath)` explicitly. */
+    projectRoot?: string;
+    /** Compiled xref patterns from `refrakt.config.json#/xrefs`. Adapters
+     *  that read the config should compile via `compileXrefPatterns` and
+     *  pass the result here. */
+    xrefPatterns?: CompiledXrefPattern[];
+    /** Registered file roots — namespace → absolute directory path. */
+    fileRoots?: FileRoots;
+    /** Per-site config slice — passed to contributePages hooks so the built-in
+     *  entityRoutes adapter can read `entityRoutes` and other site-scoped
+     *  config. Without this, `entityRoutes` rules in the project's config
+     *  silently produce no pages. */
+    siteConfig?: unknown;
     /** When true, every load() call re-reads from disk (no caching). Default: false. */
     dev?: boolean;
 }
@@ -38,6 +56,16 @@ export interface VirtualSiteLoaderOptions {
     /** Optional async reader for ad-hoc lookups. Forward-compatibility hook —
      *  see `LoadContentFromTreeOptions.reader` for details. */
     reader?: VirtualReader;
+    /** Absolute path to the project root (where `refrakt.config.json` lives).
+     *  Used to compute `$file.path` as a project-root-relative POSIX path. */
+    projectRoot?: string;
+    /** Compiled xref patterns from `refrakt.config.json#/xrefs`. */
+    xrefPatterns?: CompiledXrefPattern[];
+    /** Registered file roots — namespace → absolute directory path. */
+    fileRoots?: FileRoots;
+    /** Per-site config slice — passed to contributePages hooks. See
+     *  {@link SiteLoaderOptions.siteConfig}. */
+    siteConfig?: unknown;
     /** When true, every load() call re-runs the pipeline against the current
      *  tree (no caching). Use when the host swaps the tree's contents in place. */
     dev?: boolean;

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAoC,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,0EAA0E;IAC1E,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,oFAAoF;IACpF,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IAC1B,0DAA0D;IAC1D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,sEAAsE;IACtE,UAAU,IAAI,IAAI,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAuBvE;AAED,MAAM,WAAW,wBAAwB;IACxC;uDACmD;IACnD,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;+DAC2D;IAC3D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,UAAU,CAsBrF"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAoC,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,0EAA0E;IAC1E,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;oEAGgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;gCAE4B;IAC5B,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACrC,mEAAmE;IACnE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;qCAGiC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oFAAoF;IACpF,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IAC1B,0DAA0D;IAC1D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,sEAAsE;IACtE,UAAU,IAAI,IAAI,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CA2BvE;AAED,MAAM,WAAW,wBAAwB;IACxC;uDACmD;IACnD,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;+DAC2D;IAC3D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;8EAC0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACrC,mEAAmE;IACnE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;gDAC4C;IAC5C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,UAAU,CA0BrF"}

package/dist/loader.js

@@ -5,7 +5,7 @@ export function createSiteLoader(options) {
         load() {
             if (!options.dev && cached)
                 return cached;
-            const promise = loadContent(options.dirPath, options.basePath, options.icons, options.additionalTags, options.plugins, options.sandboxExamplesDir, options.variables, options.securityPolicy);
+            const promise = loadContent(options.dirPath, options.basePath, options.icons, options.additionalTags, options.plugins, options.sandboxExamplesDir, options.variables, options.securityPolicy, options.projectRoot, options.xrefPatterns, options.fileRoots, options.siteConfig);
             if (!options.dev)
                 cached = promise;
             return promise;
@@ -35,6 +35,10 @@ export function createVirtualSiteLoader(options) {
                 variables: options.variables,
                 securityPolicy: options.securityPolicy,
                 reader: options.reader,
+                projectRoot: options.projectRoot,
+                xrefPatterns: options.xrefPatterns,
+                fileRoots: options.fileRoots,
+                siteConfig: options.siteConfig,
             });
             if (!options.dev)
                 cached = promise;

package/dist/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAiC,MAAM,WAAW,CAAC;AAyB5F,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IAC1D,IAAI,MAAM,GAAyB,IAAI,CAAC;IAExC,OAAO;QACN,IAAI;YACH,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAC1C,MAAM,OAAO,GAAG,WAAW,CAC1B,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,KAAK,EACb,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,kBAAkB,EAC1B,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,cAAc,CACtB,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,GAAG;gBAAE,MAAM,GAAG,OAAO,CAAC;YACnC,OAAO,OAAO,CAAC;QAChB,CAAC;QACD,UAAU;YACT,MAAM,GAAG,IAAI,CAAC;QACf,CAAC;KACD,CAAC;AACH,CAAC;AAsBD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAiC;IACxE,IAAI,MAAM,GAAyB,IAAI,CAAC;IAExC,OAAO;QACN,IAAI;YACH,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAC1C,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,EAAE;gBACjD,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,MAAM,EAAE,OAAO,CAAC,MAAM;aACtB,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,GAAG;gBAAE,MAAM,GAAG,OAAO,CAAC;YACnC,OAAO,OAAO,CAAC;QAChB,CAAC;QACD,UAAU;YACT,MAAM,GAAG,IAAI,CAAC;QACf,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAiC,MAAM,WAAW,CAAC;AA0C5F,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IAC1D,IAAI,MAAM,GAAyB,IAAI,CAAC;IAExC,OAAO;QACN,IAAI;YACH,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAC1C,MAAM,OAAO,GAAG,WAAW,CAC1B,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,KAAK,EACb,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,kBAAkB,EAC1B,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,WAAW,EACnB,OAAO,CAAC,YAAY,EACpB,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,UAAU,CAClB,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,GAAG;gBAAE,MAAM,GAAG,OAAO,CAAC;YACnC,OAAO,OAAO,CAAC;QAChB,CAAC;QACD,UAAU;YACT,MAAM,GAAG,IAAI,CAAC;QACf,CAAC;KACD,CAAC;AACH,CAAC;AAgCD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAiC;IACxE,IAAI,MAAM,GAAyB,IAAI,CAAC;IAExC,OAAO;QACN,IAAI;YACH,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAC1C,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,EAAE;gBACjD,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,UAAU,EAAE,OAAO,CAAC,UAAU;aAC9B,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,GAAG;gBAAE,MAAM,GAAG,OAAO,CAAC;YACnC,OAAO,OAAO,CAAC;QAChB,CAAC;QACD,UAAU;YACT,MAAM,GAAG,IAAI,CAAC;QACf,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/pipeline.d.ts

@@ -1,10 +1,20 @@
-import type { PluginPipelineHooks, AggregatedData, PipelineWarning } from '@refrakt-md/types';
+import type { PluginPipelineHooks, AggregatedData, PipelineWarning, ContributedPage } from '@refrakt-md/types';
 import type { SitePage } from './site.js';
 /** A package and its pipeline hooks, ready to run */
 export interface HookSet {
     pluginName: string;
     hooks: PluginPipelineHooks;
 }
+/** Options for the contribution phase (SPEC-069). */
+export interface RunPipelineOptions {
+    /** Render a contributed page's source into a full SitePage (provided by the
+     *  content loader, which owns the parse + transform machinery). */
+    renderContributed?: (cp: ContributedPage) => SitePage;
+    /** Absolute project root, passed to contributePages hooks. */
+    projectRoot?: string;
+    /** Per-site config slice, passed to contributePages hooks. */
+    siteConfig?: unknown;
+}
 /** Build-phase statistics from the pipeline run */
 export interface PipelineStats {
     /** Total pages processed */
@@ -36,5 +46,5 @@ export interface PipelineResult {
  * Errors in individual hooks are caught, converted to PipelineWarning entries,
  * and the pipeline continues with the next hook / page.
  */
-export declare function runPipeline(pages: SitePage[], hookSets: HookSet[]): Promise<PipelineResult>;
+export declare function runPipeline(pages: SitePage[], hookSets: HookSet[], options?: RunPipelineOptions): Promise<PipelineResult>;
 //# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,mBAAmB,EAGnB,cAAc,EACd,eAAe,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,qDAAqD;AACrD,MAAM,WAAW,OAAO;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,CAAC;CAC3B;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC7B,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC9B,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,6EAA6E;IAC7E,UAAU,EAAE,cAAc,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,sCAAsC;IACtC,KAAK,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAChC,KAAK,EAAE,QAAQ,EAAE,EACjB,QAAQ,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,cAAc,CAAC,CAqEzB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,mBAAmB,EAGnB,cAAc,EACd,eAAe,EAEf,eAAe,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,qDAAqD;AACrD,MAAM,WAAW,OAAO;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IAClC;uEACmE;IACnE,iBAAiB,CAAC,EAAE,CAAC,EAAE,EAAE,eAAe,KAAK,QAAQ,CAAC;IACtD,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC7B,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC9B,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,6EAA6E;IAC7E,UAAU,EAAE,cAAc,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,sCAAsC;IACtC,KAAK,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAChC,KAAK,EAAE,QAAQ,EAAE,EACjB,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE,kBAAuB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAqIzB"}

package/dist/pipeline.js

@@ -10,11 +10,13 @@ import { EntityRegistryImpl } from './registry.js';
  * Errors in individual hooks are caught, converted to PipelineWarning entries,
  * and the pipeline continues with the next hook / page.
  */
-export async function runPipeline(pages, hookSets) {
+export async function runPipeline(pages, hookSets, options = {}) {
     const warnings = [];
     const registry = new EntityRegistryImpl();
+    // Working page set — grows as plugins contribute pages (SPEC-069).
+    const allPages = [...pages];
     // Convert SitePage[] → TransformedPage[] (lightweight view, no deep copy)
-    const transformedPages = pages.map(pageToTransformed);
+    const transformedPages = allPages.map(pageToTransformed);
     // ─── Phase 2: Register ───
     for (const { pluginName, hooks } of hookSets) {
         if (!hooks.register)
@@ -27,6 +29,66 @@ export async function runPipeline(pages, hookSets) {
             ctx.error(err.message);
         }
     }
+    // ─── Phase 2.5: Contribute pages (SPEC-069) ───
+    // Plugins synthesize virtual pages (often from registered entities). They run
+    // after register so the registry is populated; contributed pages then flow
+    // through register (a second pass, for their own entities) → aggregate →
+    // postProcess like file pages. Contributed pages cannot trigger another
+    // contribution phase (the graph is one level deep, by design).
+    if (options.renderContributed) {
+        const fileUrls = new Set(allPages.map((p) => p.route.url));
+        const contributedUrls = new Map();
+        const newPages = [];
+        for (const { pluginName, hooks } of hookSets) {
+            if (!hooks.contributePages)
+                continue;
+            const ctx = makeContext(warnings, 'contribute', pluginName);
+            try {
+                const contributed = await hooks.contributePages({
+                    ...ctx,
+                    registry: registry,
+                    projectRoot: options.projectRoot,
+                    siteConfig: options.siteConfig,
+                });
+                contributed.forEach((cp, ruleIndex) => {
+                    if (fileUrls.has(cp.url)) {
+                        ctx.warn(`contributed page "${cp.url}" collides with a file-backed page; the file wins`, cp.url);
+                        return;
+                    }
+                    const prior = contributedUrls.get(cp.url);
+                    if (prior) {
+                        ctx.error(`contributed page "${cp.url}" collides with one from "${prior}"`, cp.url);
+                        return;
+                    }
+                    contributedUrls.set(cp.url, pluginName);
+                    const sp = options.renderContributed({ ...cp, source: { plugin: pluginName, ruleIndex } });
+                    newPages.push(sp);
+                });
+            }
+            catch (err) {
+                ctx.error(err.message);
+            }
+        }
+        if (newPages.length > 0) {
+            const newTransformed = newPages.map(pageToTransformed);
+            allPages.push(...newPages);
+            transformedPages.push(...newTransformed);
+            // Second register pass: index entities the contributed pages themselves
+            // declare (so refs/expands elsewhere resolve them). They do not trigger
+            // another contribution round.
+            for (const { pluginName, hooks } of hookSets) {
+                if (!hooks.register)
+                    continue;
+                const ctx = makeContext(warnings, 'register', pluginName);
+                try {
+                    hooks.register(newTransformed, registry, ctx);
+                }
+                catch (err) {
+                    ctx.error(err.message);
+                }
+            }
+        }
+    }
     // ─── Phase 3: Aggregate ───
     const aggregated = {};
     const frozenRegistry = registry;
@@ -57,17 +119,22 @@ export async function runPipeline(pages, hookSets) {
             }
         });
     }
-    // Merge post-processed renderables back into the original SitePage objects.
-    // Cast from unknown back to RenderableTreeNodes — postProcess hooks are responsible
-    // for returning the same AST node type they received.
-    const resultPages = pages.map((page, i) => ({
+    // Merge post-processed renderables back into the SitePage objects (file +
+    // contributed). Cast from unknown back to RenderableTreeNodes — postProcess
+    // hooks are responsible for returning the same AST node type they received.
+    const resultPages = allPages.map((page, i) => ({
         ...page,
         renderable: working[i].renderable,
+        // `postProcess` can refresh headings (e.g. expand `level=N` inlines
+        // new headings that parse-time `extractHeadings` couldn't see). Merge
+        // the latest version back so the layout TOC builder sees what's in
+        // the final renderable.
+        headings: working[i].headings,
     }));
     // Tally entity count across all registered types
     const entityCount = registry.getTypes().reduce((sum, type) => sum + registry.getAll(type).length, 0);
     const stats = {
-        pageCount: pages.length,
+        pageCount: allPages.length,
         entityCount,
         packageCount: hookSets.filter(hs => hs.hooks.register || hs.hooks.aggregate || hs.hooks.postProcess).length,
     };

package/dist/pipeline.js.map

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