@functional-examples/documentation 0.0.0-alpha.1

package/dist/renderers/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/renderers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/renderers/types.ts"],"names":[],"mappings":""}

package/dist/schema.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import type { ValidationResult } from '@functional-examples/devkit';
+/**
+ * Zod schema for documentation-specific metadata.
+ */
+export declare const docsMetadataSchema: z.ZodObject<{
+    docs: z.ZodOptional<z.ZodObject<{
+        template: z.ZodOptional<z.ZodString>;
+        skip: z.ZodOptional<z.ZodBoolean>;
+        outputName: z.ZodOptional<z.ZodString>;
+        /** Descriptions for specific hunks/regions, keyed by hunk ID */
+        hunks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type DocsMetadataSchemaType = z.infer<typeof docsMetadataSchema>;
+/** JSON Schema for metadata plugin registration */
+export declare const DOCS_METADATA_JSON_SCHEMA: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    docs: z.ZodOptional<z.ZodObject<{
+        template: z.ZodOptional<z.ZodString>;
+        skip: z.ZodOptional<z.ZodBoolean>;
+        outputName: z.ZodOptional<z.ZodString>;
+        /** Descriptions for specific hunks/regions, keyed by hunk ID */
+        hunks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>>;
+/**
+ * Zod schema for documentation plugin options.
+ * Fields with defaults are resolved via `docsOptionsSchema.parse(...)`.
+ */
+export declare const docsOptionsSchema: z.ZodObject<{
+    outputDir: z.ZodDefault<z.ZodString>;
+    format: z.ZodDefault<z.ZodEnum<{
+        markdown: "markdown";
+        mdoc: "mdoc";
+    }>>;
+    templates: z.ZodOptional<z.ZodString>;
+    enableExtractor: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** JSON Schema for options plugin registration */
+export declare const DOCS_OPTIONS_JSON_SCHEMA: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    outputDir: z.ZodDefault<z.ZodString>;
+    format: z.ZodDefault<z.ZodEnum<{
+        markdown: "markdown";
+        mdoc: "mdoc";
+    }>>;
+    templates: z.ZodOptional<z.ZodString>;
+    enableExtractor: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>>;
+/**
+ * Validate documentation metadata using Zod schema.
+ */
+export declare function validateDocsMetadata(metadata: unknown): ValidationResult;
+/** Options for the documentation plugin factory (input — all optional). */
+export type DocumentationPluginOptions = z.input<typeof docsOptionsSchema>;
+/** Resolved options with defaults applied (output of parsing). */
+export type ResolvedDocumentationPluginOptions = z.output<typeof docsOptionsSchema>;
+/**
+ * Documentation-specific metadata that examples can declare.
+ */
+export interface DocsMetadata {
+    docs?: DocsMetadataSchemaType;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;QAMzB,gEAAgE;;;iBAIpE,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAExE,mDAAmD;AACnD,eAAO,MAAM,yBAAyB;;;;;QAThC,gEAAgE;;;kBASK,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;iBAK5B,CAAC;AAEH,kDAAkD;AAClD,eAAO,MAAM,wBAAwB;;;;;;;;kBAAoC,CAAC;AAW1E;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,gBAAgB,CAUxE;AAID,2EAA2E;AAC3E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE3E,kEAAkE;AAClE,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CACvD,OAAO,iBAAiB,CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,sBAAsB,CAAC;CAC/B"}

package/dist/schema.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/**
+ * Zod schema for documentation-specific metadata.
+ */
+export const docsMetadataSchema = z.object({
+    docs: z
+        .strictObject({
+        template: z.string().optional(),
+        skip: z.boolean().optional(),
+        outputName: z.string().optional(),
+        /** Descriptions for specific hunks/regions, keyed by hunk ID */
+        hunks: z.record(z.string(), z.string()).optional(),
+    })
+        .optional(),
+});
+/** JSON Schema for metadata plugin registration */
+export const DOCS_METADATA_JSON_SCHEMA = z.toJSONSchema(docsMetadataSchema);
+/**
+ * Zod schema for documentation plugin options.
+ * Fields with defaults are resolved via `docsOptionsSchema.parse(...)`.
+ */
+export const docsOptionsSchema = z.object({
+    outputDir: z.string().default('./docs/examples'),
+    format: z.enum(['markdown', 'mdoc']).default('markdown'),
+    templates: z.string().optional(),
+    enableExtractor: z.boolean().default(false),
+});
+/** JSON Schema for options plugin registration */
+export const DOCS_OPTIONS_JSON_SCHEMA = z.toJSONSchema(docsOptionsSchema);
+function mapZodIssue(zIssue) {
+    return {
+        path: zIssue.path.join('.'),
+        message: zIssue.message,
+    };
+}
+/**
+ * Validate documentation metadata using Zod schema.
+ */
+export function validateDocsMetadata(metadata) {
+    const result = docsMetadataSchema.safeParse(metadata);
+    if (result.success) {
+        return { success: true, errors: [] };
+    }
+    return {
+        success: false,
+        errors: result.error.issues.map(mapZodIssue),
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,CAAC;SACJ,YAAY,CAAC;QACZ,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACjC,gEAAgE;QAChE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;KACnD,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAIH,mDAAmD;AACnD,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,YAAY,CAAC,kBAAkB,CAAC,CAAC;AAE5E;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,iBAAiB,CAAC;IAChD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACxD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CAC5C,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;AAE1E,SAAS,WAAW,CAClB,MAAwB;IAExB,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAiB;IACpD,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACvC,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/templates/consumption-tracker.d.ts

@@ -0,0 +1,16 @@
+import type { ExampleFile } from '@functional-examples/devkit';
+/**
+ * Tracks which example files have been "consumed" by prose template helpers
+ * (e.g. `file()` or `region()`). Consumed files are excluded from the
+ * "remaining files" section in the rendered output.
+ */
+export declare class ConsumptionTracker {
+    private consumed;
+    /** Mark a file as consumed by its relative path. */
+    consume(relativePath: string): void;
+    /** Check whether a file has been consumed. */
+    isConsumed(relativePath: string): boolean;
+    /** Return only those files that have NOT been consumed. */
+    getUnconsumedFiles(files: ExampleFile[]): ExampleFile[];
+}
+//# sourceMappingURL=consumption-tracker.d.ts.map

package/dist/templates/consumption-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumption-tracker.d.ts","sourceRoot":"","sources":["../../src/templates/consumption-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAqB;IAErC,oDAAoD;IACpD,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAInC,8CAA8C;IAC9C,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAIzC,2DAA2D;IAC3D,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE;CAGxD"}

package/dist/templates/consumption-tracker.js

@@ -0,0 +1,21 @@
+/**
+ * Tracks which example files have been "consumed" by prose template helpers
+ * (e.g. `file()` or `region()`). Consumed files are excluded from the
+ * "remaining files" section in the rendered output.
+ */
+export class ConsumptionTracker {
+    consumed = new Set();
+    /** Mark a file as consumed by its relative path. */
+    consume(relativePath) {
+        this.consumed.add(relativePath);
+    }
+    /** Check whether a file has been consumed. */
+    isConsumed(relativePath) {
+        return this.consumed.has(relativePath);
+    }
+    /** Return only those files that have NOT been consumed. */
+    getUnconsumedFiles(files) {
+        return files.filter((f) => !this.consumed.has(f.relativePath));
+    }
+}
+//# sourceMappingURL=consumption-tracker.js.map

package/dist/templates/consumption-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumption-tracker.js","sourceRoot":"","sources":["../../src/templates/consumption-tracker.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IACrB,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,oDAAoD;IACpD,OAAO,CAAC,YAAoB;QAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;IAED,8CAA8C;IAC9C,UAAU,CAAC,YAAoB;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAED,2DAA2D;IAC3D,kBAAkB,CAAC,KAAoB;QACrC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IACjE,CAAC;CACF"}

package/dist/templates/engine.d.ts

@@ -0,0 +1,123 @@
+import type { Example, ExampleFile } from '@functional-examples/devkit';
+import { type TemplateHelpers } from './helpers.js';
+/**
+ * Template data model passed to Eta per-item templates as `it`.
+ */
+export interface TemplateData {
+    /** Example unique identifier */
+    id: string;
+    /** Example title */
+    title: string;
+    /** Example description */
+    description?: string;
+    /** Full metadata object */
+    metadata: Record<string, unknown>;
+    /** Example files */
+    files: ExampleFile[];
+    /** Template helper functions */
+    helpers: TemplateHelpers;
+    /** Prose files rendered through Eta (with file/region helpers expanded) */
+    renderedProse: string[];
+    /** Files not consumed by prose helpers — the "remaining" code files */
+    unconsumedFiles: ExampleFile[];
+}
+/** Data model for aggregate (index) templates. */
+export interface IndexTemplateData {
+    examples: {
+        id: string;
+        title: string;
+        description?: string;
+    }[];
+    format: string;
+    helpers: TemplateHelpers;
+}
+/** Parsed template file descriptor. */
+export interface TemplateDescriptor {
+    /** Absolute path to the .template source file */
+    sourcePath: string;
+    /** Filename minus '.template', e.g. '@slug.md' */
+    outputPattern: string;
+    /** File extension, e.g. '.md' or '.mdoc' */
+    format: string;
+    /** Whether the filename contains an @var placeholder */
+    perItem: boolean;
+    /** Variable name (e.g. 'slug') when perItem is true */
+    variable?: string;
+    /** Raw Eta template content */
+    content: string;
+}
+/** Rendered output ready to write. */
+export interface RenderedFile {
+    /** Relative path for the output file */
+    relativePath: string;
+    /** Rendered content */
+    content: string;
+}
+/** Result of rendering prose files through Eta. */
+export interface ProseRenderResult {
+    /** Rendered prose content strings (one per prose file). */
+    renderedProse: string[];
+    /** Files not consumed by prose file/region helpers. */
+    unconsumedFiles: ExampleFile[];
+}
+/**
+ * Render prose files through Eta, expanding `file()` and `region()` helpers,
+ * and return which files remain unconsumed.
+ */
+export declare function renderProseFiles(files: ExampleFile[], metadata: Record<string, unknown>): ProseRenderResult;
+/**
+ * Build the template data model from an Example.
+ */
+export declare function buildTemplateData(example: Example): TemplateData;
+/**
+ * Resolve the built-in templates directory relative to this file.
+ * At runtime, this file lives at `dist/templates/engine.js`.
+ * The templates directory is at `packages/documentation/templates/`
+ * — two levels up from `dist/templates/`.
+ */
+export declare function getBuiltinTemplatesDir(): string;
+/**
+ * Parse a template's relative path into its descriptor fields.
+ *
+ * The `@var` convention can appear in any path segment — either in the
+ * filename itself or in a directory name:
+ * - `@slug.md.template` → variable `slug` (flat, filename)
+ * - `examples/@example/index.md.template` → variable `example` (nested, directory)
+ *
+ * @param relativePath - Path relative to the templates root, e.g. `examples/@example/index.md.template`
+ */
+export declare function parseTemplateName(relativePath: string): Pick<TemplateDescriptor, 'outputPattern' | 'format' | 'perItem' | 'variable'>;
+/**
+ * Replace `@var` placeholders in a pattern with values from a vars map.
+ *
+ * Example: `substituteVars('@slug.md', { slug: 'getting-started' })` → `getting-started.md`
+ */
+export declare function substituteVars(pattern: string, vars: Record<string, string>): string;
+/**
+ * Load all `.template` files from a directory (recursively) and parse their paths.
+ *
+ * Supports nested directory structures like:
+ * ```
+ * templates/
+ *   index.md.template
+ *   examples/@example/index.md.template
+ * ```
+ */
+export declare function loadTemplates(dir?: string): Promise<TemplateDescriptor[]>;
+/**
+ * Render a per-item template for a single example.
+ */
+export declare function renderItemTemplate(template: TemplateDescriptor, example: Example): Promise<RenderedFile>;
+/**
+ * Render an aggregate template with all examples.
+ */
+export declare function renderIndexTemplate(template: TemplateDescriptor, examples: Example[]): Promise<RenderedFile>;
+/**
+ * Render an example using the default or a custom template file.
+ *
+ * @param example - The example to render
+ * @param templatePath - Optional path to a custom .eta template file
+ * @returns Rendered string
+ */
+export declare function renderTemplate(example: Example, templatePath?: string): Promise<string>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/templates/engine.d.ts.map

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

package/dist/templates/engine.js

@@ -0,0 +1,212 @@
+import { Eta } from 'eta';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ConsumptionTracker } from './consumption-tracker.js';
+import { isProseFile, templateHelpers } from './helpers.js';
+import { createProseHelpers } from './prose-helpers.js';
+const eta = new Eta({ autoEscape: false, autoTrim: false });
+/**
+ * Separate Eta instance for prose files.
+ * Uses `functionHeader` to inject short helper names into template scope
+ * so authors write `<%= file('utils.ts') %>` instead of `<%= it.file('utils.ts') %>`.
+ */
+const proseEta = new Eta({
+    autoEscape: false,
+    autoTrim: false,
+    functionHeader: 'var file = it.file, region = it.region, files = it.files, helpers = it.helpers;',
+});
+/**
+ * Render prose files through Eta, expanding `file()` and `region()` helpers,
+ * and return which files remain unconsumed.
+ */
+export function renderProseFiles(files, metadata) {
+    const tracker = new ConsumptionTracker();
+    const helpers = createProseHelpers(files, tracker);
+    const proseFiles = files.filter(isProseFile);
+    const renderedProse = [];
+    // Prose files themselves are always consumed (they render inline)
+    for (const pf of proseFiles) {
+        tracker.consume(pf.relativePath);
+    }
+    for (const pf of proseFiles) {
+        const content = pf.parsed ?? pf.raw ?? '';
+        const rendered = proseEta.renderString(content, {
+            ...helpers,
+            metadata,
+        });
+        renderedProse.push(rendered);
+    }
+    return {
+        renderedProse,
+        unconsumedFiles: tracker.getUnconsumedFiles(files),
+    };
+}
+/**
+ * Build the template data model from an Example.
+ */
+export function buildTemplateData(example) {
+    const metadata = example.metadata;
+    const { renderedProse, unconsumedFiles } = renderProseFiles(example.files, metadata);
+    return {
+        id: example.id,
+        title: example.title,
+        description: example.description,
+        metadata,
+        files: example.files,
+        helpers: templateHelpers,
+        renderedProse,
+        unconsumedFiles,
+    };
+}
+/**
+ * Resolve the built-in templates directory relative to this file.
+ * At runtime, this file lives at `dist/templates/engine.js`.
+ * The templates directory is at `packages/documentation/templates/`
+ * — two levels up from `dist/templates/`.
+ */
+export function getBuiltinTemplatesDir() {
+    const thisFile = fileURLToPath(import.meta.url);
+    return path.resolve(path.dirname(thisFile), '../../templates');
+}
+/**
+ * Parse a template's relative path into its descriptor fields.
+ *
+ * The `@var` convention can appear in any path segment — either in the
+ * filename itself or in a directory name:
+ * - `@slug.md.template` → variable `slug` (flat, filename)
+ * - `examples/@example/index.md.template` → variable `example` (nested, directory)
+ *
+ * @param relativePath - Path relative to the templates root, e.g. `examples/@example/index.md.template`
+ */
+export function parseTemplateName(relativePath) {
+    const outputPattern = relativePath.replace(/\.template$/, '');
+    const format = path.extname(outputPattern);
+    // Scan all path segments for an @-prefixed name
+    const segments = outputPattern.split('/');
+    let variable;
+    for (const segment of segments) {
+        if (segment.startsWith('@')) {
+            // '@slug.md' → 'slug', '@example' → 'example'
+            const ext = path.extname(segment);
+            variable = ext ? segment.slice(1, -ext.length) : segment.slice(1);
+            break;
+        }
+    }
+    const perItem = variable !== undefined;
+    const result = {
+        outputPattern,
+        format,
+        perItem,
+    };
+    if (perItem) {
+        result.variable = variable;
+    }
+    return result;
+}
+/**
+ * Replace `@var` placeholders in a pattern with values from a vars map.
+ *
+ * Example: `substituteVars('@slug.md', { slug: 'getting-started' })` → `getting-started.md`
+ */
+export function substituteVars(pattern, vars) {
+    let result = pattern;
+    for (const [key, value] of Object.entries(vars)) {
+        result = result.replace(`@${key}`, value);
+    }
+    return result;
+}
+/**
+ * Recursively collect all `.template` files under a directory.
+ * Returns paths relative to `root`.
+ */
+async function collectTemplateFiles(root, current = root) {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        const fullPath = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await collectTemplateFiles(root, fullPath)));
+        }
+        else if (entry.name.endsWith('.template')) {
+            results.push(path.relative(root, fullPath));
+        }
+    }
+    return results;
+}
+/**
+ * Load all `.template` files from a directory (recursively) and parse their paths.
+ *
+ * Supports nested directory structures like:
+ * ```
+ * templates/
+ *   index.md.template
+ *   examples/@example/index.md.template
+ * ```
+ */
+export async function loadTemplates(dir) {
+    const templatesDir = dir ?? getBuiltinTemplatesDir();
+    const relativePaths = await collectTemplateFiles(templatesDir);
+    const descriptors = [];
+    for (const relPath of relativePaths) {
+        const sourcePath = path.join(templatesDir, relPath);
+        const content = await fs.readFile(sourcePath, 'utf-8');
+        const parsed = parseTemplateName(relPath);
+        descriptors.push({
+            sourcePath,
+            content,
+            ...parsed,
+        });
+    }
+    return descriptors;
+}
+/**
+ * Render a per-item template for a single example.
+ */
+export async function renderItemTemplate(template, example) {
+    const data = buildTemplateData(example);
+    const content = eta.renderString(template.content, data);
+    const vars = {};
+    if (template.variable) {
+        vars[template.variable] = example.id;
+    }
+    const relativePath = substituteVars(template.outputPattern, vars);
+    return { relativePath, content };
+}
+/**
+ * Render an aggregate template with all examples.
+ */
+export async function renderIndexTemplate(template, examples) {
+    const data = {
+        examples: examples.map((e) => ({
+            id: e.id,
+            title: e.title,
+            description: e.description,
+        })),
+        format: template.format,
+        helpers: templateHelpers,
+    };
+    const content = eta.renderString(template.content, data);
+    return { relativePath: template.outputPattern, content };
+}
+/**
+ * Render an example using the default or a custom template file.
+ *
+ * @param example - The example to render
+ * @param templatePath - Optional path to a custom .eta template file
+ * @returns Rendered string
+ */
+export async function renderTemplate(example, templatePath) {
+    const data = buildTemplateData(example);
+    if (templatePath) {
+        const absPath = path.resolve(templatePath);
+        const templateStr = await fs.readFile(absPath, 'utf-8');
+        return eta.renderString(templateStr, data);
+    }
+    // Fall back to built-in markdown template
+    const builtinDir = getBuiltinTemplatesDir();
+    const defaultTemplate = path.join(builtinDir, '@slug.md.template');
+    const templateStr = await fs.readFile(defaultTemplate, 'utf-8');
+    return eta.renderString(templateStr, data);
+}
+//# sourceMappingURL=engine.js.map

package/dist/templates/engine.js.map

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

package/dist/templates/guide-renderer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Guide hydration renderer — expands example references in standalone
+ * markdown guides that reference files/regions from *any* scanned example.
+ *
+ * Unlike prose helpers (scoped to a single example), the guide renderer
+ * creates a cross-example lookup so authors can write:
+ *
+ * ```markdown
+ * <%= example('basic-usage').file('scan.ts') %>
+ * <%= example('basic-usage').region('config-setup') %>
+ * ```
+ */
+import type { ExampleFile, ScannedExample } from '@functional-examples/devkit';
+/**
+ * A renderer that expands example references in guide markdown.
+ */
+export interface GuideRenderer {
+    /** Render a markdown string, expanding example references. */
+    render(markdown: string): string;
+    /** Read a markdown file and render it, expanding example references. */
+    renderFile(filePath: string): Promise<string>;
+}
+/**
+ * Scoped API returned by `example(id)` inside guide templates.
+ */
+export interface ExampleAccessor {
+    /** Render a file as a fenced code block. */
+    file(relativePath: string): string;
+    /** Render a region/hunk as a fenced code block. */
+    region(regionId: string): string;
+    /** All files in the example. */
+    files: ExampleFile[];
+    /** The example's metadata. */
+    metadata: Record<string, unknown>;
+    /** The example's title. */
+    title: string;
+    /** The example's description. */
+    description?: string;
+}
+/**
+ * Create a guide renderer bound to a set of scanned examples.
+ *
+ * Guide templates can reference any example by ID:
+ * ```markdown
+ * <%= example('basic-usage').file('scan.ts') %>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createGuideRenderer } from '@functional-examples/documentation';
+ * import { scan } from 'functional-examples';
+ *
+ * const { examples } = await scan({ root: workspaceRoot });
+ * const renderer = createGuideRenderer(examples);
+ * const html = await renderer.renderFile('docs/guides/getting-started.md');
+ * ```
+ */
+export declare function createGuideRenderer(examples: ScannedExample[]): GuideRenderer;
+//# sourceMappingURL=guide-renderer.d.ts.map

package/dist/templates/guide-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-renderer.d.ts","sourceRoot":"","sources":["../../src/templates/guide-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAM/E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,wEAAwE;IACxE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,mDAAmD;IACnD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,gCAAgC;IAChC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,aAAa,CAwE7E"}