@refrakt-md/content 0.14.3 → 0.15.0

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/format.d.ts

@@ -0,0 +1,27 @@
+import type { PipelineWarning } from '@refrakt-md/types';
+import type { PipelineStats } from './pipeline.js';
+/**
+ * Format the cross-page pipeline's Phase 1/2/3/4 stats and the collected
+ * warnings as a single multi-line string suitable for writing to stderr.
+ *
+ * Adapters call this after `loadContent` (or equivalent) completes so users
+ * see the same build summary across every framework — currently the
+ * SvelteKit plugin prints this; other adapters were silent.
+ *
+ * The function is pure — caller decides where to write. Empty / minimal
+ * builds produce a single status line; builds with warnings interleave
+ * each warning on its own line.
+ *
+ * ```
+ *   Phase 1: Parse                 162 pages
+ *   Phase 2: Register              847 entities
+ *   Phase 3: Aggregate             14 packages
+ *   Phase 4: Post-process          162 pages
+ *
+ *   ⚠  warn   some message  /some/url
+ *
+ *   ✓  Build complete (0 errors, 1 warning)
+ * ```
+ */
+export declare function formatPipelineSummary(stats: PipelineStats, warnings: PipelineWarning[]): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAUnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,eAAe,EAAE,GACzB,MAAM,CAyBR"}

package/dist/format.js

@@ -0,0 +1,50 @@
+const ICON = {
+    error: '✗  error',
+    warning: '⚠  warn ',
+    info: 'ℹ  info ',
+};
+const pad = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
+/**
+ * Format the cross-page pipeline's Phase 1/2/3/4 stats and the collected
+ * warnings as a single multi-line string suitable for writing to stderr.
+ *
+ * Adapters call this after `loadContent` (or equivalent) completes so users
+ * see the same build summary across every framework — currently the
+ * SvelteKit plugin prints this; other adapters were silent.
+ *
+ * The function is pure — caller decides where to write. Empty / minimal
+ * builds produce a single status line; builds with warnings interleave
+ * each warning on its own line.
+ *
+ * ```
+ *   Phase 1: Parse                 162 pages
+ *   Phase 2: Register              847 entities
+ *   Phase 3: Aggregate             14 packages
+ *   Phase 4: Post-process          162 pages
+ *
+ *   ⚠  warn   some message  /some/url
+ *
+ *   ✓  Build complete (0 errors, 1 warning)
+ * ```
+ */
+export function formatPipelineSummary(stats, warnings) {
+    const lines = [];
+    lines.push(`  ${pad('Phase 1: Parse', 30)} ${stats.pageCount} pages`);
+    lines.push(`  ${pad('Phase 2: Register', 30)} ${stats.entityCount} entities`);
+    lines.push(`  ${pad('Phase 3: Aggregate', 30)} ${stats.packageCount} packages`);
+    lines.push(`  ${pad('Phase 4: Post-process', 30)} ${stats.pageCount} pages`);
+    const errorCount = warnings.filter(w => w.severity === 'error').length;
+    const warnCount = warnings.filter(w => w.severity === 'warning').length;
+    for (const w of warnings) {
+        const icon = ICON[w.severity];
+        const location = w.url ? `  ${w.url}` : '';
+        lines.push('');
+        lines.push(`  ${icon}  ${w.message}${location}`);
+    }
+    const status = errorCount > 0 ? '✗' : '✓';
+    lines.push('');
+    lines.push(`  ${status}  Build complete (${errorCount} error${errorCount !== 1 ? 's' : ''}, ${warnCount} warning${warnCount !== 1 ? 's' : ''})`);
+    lines.push('');
+    return lines.map(l => l + '\n').join('');
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAGA,MAAM,IAAI,GAAG;IACZ,KAAK,EAAE,UAAU;IACjB,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,UAAU;CACP,CAAC;AAEX,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,qBAAqB,CACpC,KAAoB,EACpB,QAA2B;IAE3B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,gBAAgB,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,SAAS,QAAQ,CAAC,CAAC;IACtE,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,mBAAmB,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,WAAW,WAAW,CAAC,CAAC;IAC9E,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,oBAAoB,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,YAAY,WAAW,CAAC,CAAC;IAChF,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,uBAAuB,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,SAAS,QAAQ,CAAC,CAAC;IAE7E,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IACvE,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC;IAExE,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CACT,KAAK,MAAM,qBAAqB,UAAU,SAAS,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,WAAW,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CACpI,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -13,4 +13,6 @@ export { getGitTimestamps, getStatTimestamps, resolveTimestamps, type FileTimest
 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"}
+{"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

@@ -13,4 +13,6 @@ export { getGitTimestamps, getStatTimestamps, resolveTimestamps } from './timest
 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"}
+{"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;
@@ -11,6 +13,19 @@ export interface SiteLoaderOptions {
     sandboxExamplesDir?: string;
     /** Site-wide Markdoc variables available in content via {% $name %} syntax. */
     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;
     /** When true, every load() call re-reads from disk (no caching). Default: false. */
     dev?: boolean;
 }
@@ -36,6 +51,13 @@ 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;
     /** 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,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,CAsBvE;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,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,CA0BvE;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;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,UAAU,CAyBrF"}

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);
+            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);
             if (!options.dev)
                 cached = promise;
             return promise;
@@ -35,6 +35,9 @@ export function createVirtualSiteLoader(options) {
                 variables: options.variables,
                 securityPolicy: options.securityPolicy,
                 reader: options.reader,
+                projectRoot: options.projectRoot,
+                xrefPatterns: options.xrefPatterns,
+                fileRoots: options.fileRoots,
             });
             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;AAuB5F,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,CACjB,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;AAqC5F,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,CACjB,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;AA6BD;;;;;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;aAC5B,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/refract-loader.d.ts

@@ -1,4 +1,5 @@
-import type { SiteConfig } from '@refrakt-md/types';
+import type { SiteConfig, SecurityPolicy, XrefPattern } from '@refrakt-md/types';
+import { type FileRoots } from './file-roots.js';
 import type { ContentTree } from './content-tree.js';
 import type { Site, VirtualReader } from './site.js';
 export interface RefraktLoaderOptions {
@@ -9,6 +10,11 @@ export interface RefraktLoaderOptions {
     site?: string;
     /** Markdoc variables available in content via {% $name %} syntax. */
     variables?: Record<string, unknown>;
+    /** Security policy for untrusted author content. Defaults to `'trusted'`
+     *  — no sanitisation. Set to `'strict'` (or a custom `SecurityPolicy` object)
+     *  when authoring content comes from untrusted sources (hosted product,
+     *  external editors, etc.). Forwarded to `loadContent`'s `securityPolicy`. */
+    security?: SecurityPolicy;
     /** Skip caching — re-read on every load(). Default: false. */
     dev?: boolean;
 }
@@ -54,8 +60,22 @@ export interface VirtualRefraktLoaderOptions {
     reader?: VirtualReader;
     /** Markdoc variables available in content via {% $name %} syntax. */
     variables?: Record<string, unknown>;
+    /** Security policy for untrusted author content. Defaults to `'trusted'`. */
+    security?: SecurityPolicy;
     /** URL base path for the Router. Default: `'/'`. */
     basePath?: string;
+    /** Absolute path to the project root (where `refrakt.config.json` lives, or
+     *  the conceptual root in a virtual environment). Used to compute
+     *  `$file.path`. When omitted, `$file.path` falls back to the page's
+     *  content-root-relative path. */
+    projectRoot?: string;
+    /** Xref patterns to compile and use as URL-resolution fallback. */
+    xrefs?: XrefPattern[];
+    /** File roots — namespace → absolute directory path. Hosts that have a
+     *  conceptual project root should resolve their fileRoots config against
+     *  it before passing the result here (the virtual loader doesn't read a
+     *  config file). Plugin-declared roots merge in automatically. */
+    fileRoots?: FileRoots;
     /** Skip caching — re-run the pipeline on every load(). Default: false. */
     dev?: boolean;
 }

package/dist/refract-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refract-loader.d.ts","sourceRoot":"","sources":["../src/refract-loader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAU,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAS5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACpC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;2DACuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,8DAA8D;IAC9D,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC7B,wDAAwD;IACxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,yDAAyD;IACzD,YAAY,IAAI,OAAO,CAAC,CAAC,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,qBAAqB,IAAI,OAAO,CAAC;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,uEAAuE;IACvE,cAAc,IAAI,IAAI,CAAC;CACvB;AASD;;;;;sDAKsD;AACtD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,UAAU;;;;;;EAQrD;AAiHD,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAwDjF;AAED,MAAM,WAAW,2BAA2B;IAC3C;;;;iFAI6E;IAC7E,IAAI,EAAE,UAAU,CAAC;IACjB;uCACmC;IACnC,IAAI,EAAE,WAAW,CAAC;IAClB;iCAC6B;IAC7B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,aAAa,CAkD9F"}
+{"version":3,"file":"refract-loader.d.ts","sourceRoot":"","sources":["../src/refract-loader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAU,UAAU,EAAE,cAAc,EAAiB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKxG,OAAO,EAAwC,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACpC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;2DACuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;kFAG8E;IAC9E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,8DAA8D;IAC9D,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC7B,wDAAwD;IACxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,yDAAyD;IACzD,YAAY,IAAI,OAAO,CAAC,CAAC,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,qBAAqB,IAAI,OAAO,CAAC;QAAE,CAAC,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,uEAAuE;IACvE,cAAc,IAAI,IAAI,CAAC;CACvB;AA6BD;;;;;sDAKsD;AACtD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,UAAU;;;;;;EAQrD;AAoHD,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAmGjF;AAED,MAAM,WAAW,2BAA2B;IAC3C;;;;iFAI6E;IAC7E,IAAI,EAAE,UAAU,CAAC;IACjB;uCACmC;IACnC,IAAI,EAAE,WAAW,CAAC;IAClB;iCAC6B;IAC7B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;sCAGkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB;;;sEAGkE;IAClE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,aAAa,CAkF9F"}

package/dist/refract-loader.js

@@ -2,7 +2,23 @@ import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { getThemePackage } from '@refrakt-md/types';
 import { normalizeRefraktConfig, resolveSite, loadPresets } from '@refrakt-md/transform/node';
+import { compileXrefPatterns } from '@refrakt-md/runes';
+import { mergeFileRoots, resolveUserFileRoots } from './file-roots.js';
 import { createSiteLoader, createVirtualSiteLoader, } from './loader.js';
+/** Compile xref patterns from a raw config, logging any diagnostics to
+ *  stderr so the build surface remains visible. Errors don't throw — they
+ *  produce a permissively-empty pattern set so the rest of the load
+ *  succeeds and the user can fix the config without losing the whole site. */
+function compileConfiguredXrefPatterns(patterns) {
+    const result = compileXrefPatterns(patterns);
+    for (const warning of result.warnings) {
+        process.stderr.write(`refrakt: xref pattern warning — ${warning}\n`);
+    }
+    for (const error of result.errors) {
+        process.stderr.write(`refrakt: xref pattern error — ${error}\n`);
+    }
+    return result.patterns;
+}
 /** Compose the options bag handed to `createHighlightTransform`. Merges the
  *  site's `highlight.*` block with theme-level code settings (`theme.code.*`)
  *  so a single object reaches the transform — keeps adapter call sites tidy
@@ -83,6 +99,7 @@ async function assembleSiteContext(site, opts = {}) {
                 communityTags: undefined,
                 communityPackages: undefined,
                 icons,
+                pluginFileRoots: {},
             };
         }
         const { config: assembledConfig } = assembleThemeConfig({
@@ -95,6 +112,7 @@ async function assembleSiteContext(site, opts = {}) {
             communityTags: undefined,
             communityPackages: undefined,
             icons,
+            pluginFileRoots: {},
         };
     }
     const { loadPlugin, mergePlugins, runes: coreRunes } = await import('@refrakt-md/runes');
@@ -116,6 +134,7 @@ async function assembleSiteContext(site, opts = {}) {
         communityTags: Object.keys(merged.tags).length > 0 ? merged.tags : undefined,
         communityPackages: merged.plugins,
         icons,
+        pluginFileRoots: merged.fileRoots,
     };
 }
 export function createRefraktLoader(options) {
@@ -127,6 +146,15 @@ export function createRefraktLoader(options) {
     const normalized = normalizeRefraktConfig(rawConfig, { configDir });
     const { site } = resolveSite(normalized, options?.site);
     const contentDir = resolve(site.contentDir);
+    // Compile xref patterns once at loader construction. Diagnostics
+    // (invalid regex, unknown placeholders, etc.) are surfaced via
+    // stderr — adapters can intercept via their own pipeline-warnings
+    // formatter once SPEC-058 wiring is fully in place.
+    const xrefPatterns = compileConfiguredXrefPatterns(rawConfig.xrefs);
+    // Resolve user-config file roots against the config-file directory.
+    // Plugin-contributed roots are merged in at init time (after plugins
+    // load); user roots win any namespace collision (warning surfaced).
+    const userFileRoots = resolveUserFileRoots(rawConfig.fileRoots, configDir);
     let _initPromise = null;
     let _transform = null;
     let _loader = null;
@@ -137,6 +165,30 @@ export function createRefraktLoader(options) {
         _initPromise = (async () => {
             const ctx = await assembleSiteContext(site, { configDir });
             _transform = ctx.transform;
+            // Run each plugin's `configure` lifecycle hook before any pipeline
+            // phases. Plugins that need build-time config (e.g. plan reading
+            // plan.dir for its unconditional-scan path) wire it up here. The
+            // `registerFileRoot` callback lets plugins dynamically register
+            // file-root namespaces whose paths depend on user config (the
+            // plan plugin uses this to expose the user's plan.dir as `plan:`).
+            const dynamicFileRoots = {};
+            const registerFileRoot = (namespace, absolutePath) => {
+                dynamicFileRoots[namespace] = absolutePath;
+            };
+            for (const pkg of ctx.communityPackages ?? []) {
+                if (pkg.pipeline?.configure) {
+                    await pkg.pipeline.configure({
+                        config: rawConfig,
+                        configDir,
+                        registerFileRoot,
+                    });
+                }
+            }
+            const pluginRoots = { ...ctx.pluginFileRoots, ...dynamicFileRoots };
+            const { roots: fileRoots, warnings: fileRootWarnings } = mergeFileRoots(userFileRoots, pluginRoots);
+            for (const warning of fileRootWarnings) {
+                process.stderr.write(`refrakt: ${warning}\n`);
+            }
             _loader = createSiteLoader({
                 dirPath: contentDir,
                 basePath: '/',
@@ -144,6 +196,10 @@ export function createRefraktLoader(options) {
                 additionalTags: ctx.communityTags,
                 plugins: ctx.communityPackages,
                 variables: options?.variables,
+                securityPolicy: options?.security,
+                projectRoot: configDir,
+                xrefPatterns,
+                fileRoots: Object.keys(fileRoots).length > 0 ? fileRoots : undefined,
                 dev: options?.dev ?? false,
             });
         })();
@@ -187,7 +243,9 @@ export function createRefraktLoader(options) {
  * dependencies in the host environment.
  */
 export function createVirtualRefraktLoader(options) {
-    const { site, tree, reader, variables, basePath, dev } = options;
+    const { site, tree, reader, variables, security, basePath, projectRoot, xrefs, fileRoots: userFileRootsOption, dev } = options;
+    const xrefPatterns = compileConfiguredXrefPatterns(xrefs);
+    const userFileRoots = userFileRootsOption ?? {};
     let _initPromise = null;
     let _transform = null;
     let _loader = null;
@@ -198,6 +256,27 @@ export function createVirtualRefraktLoader(options) {
         _initPromise = (async () => {
             const ctx = await assembleSiteContext(site);
             _transform = ctx.transform;
+            // Plugin `configure` lifecycle — same as in createRefraktLoader.
+            // Virtual hosts pass the pre-resolved SiteConfig directly; plugins
+            // see the per-site config object rather than a full RefraktConfig.
+            const dynamicFileRoots = {};
+            const registerFileRoot = (namespace, absolutePath) => {
+                dynamicFileRoots[namespace] = absolutePath;
+            };
+            for (const pkg of ctx.communityPackages ?? []) {
+                if (pkg.pipeline?.configure) {
+                    await pkg.pipeline.configure({
+                        config: site,
+                        configDir: projectRoot ?? '',
+                        registerFileRoot,
+                    });
+                }
+            }
+            const pluginRoots = { ...ctx.pluginFileRoots, ...dynamicFileRoots };
+            const { roots: fileRoots, warnings: fileRootWarnings } = mergeFileRoots(userFileRoots, pluginRoots);
+            for (const warning of fileRootWarnings) {
+                process.stderr.write(`refrakt: ${warning}\n`);
+            }
             _loader = createVirtualSiteLoader({
                 tree,
                 basePath: basePath ?? '/',
@@ -205,7 +284,11 @@ export function createVirtualRefraktLoader(options) {
                 additionalTags: ctx.communityTags,
                 plugins: ctx.communityPackages,
                 variables,
+                securityPolicy: security,
                 reader,
+                projectRoot,
+                xrefPatterns,
+                fileRoots: Object.keys(fileRoots).length > 0 ? fileRoots : undefined,
                 dev: dev ?? false,
             });
         })();