@oml/cli 0.7.0

package/src/commands/render.ts

@@ -0,0 +1,1021 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import chalk from 'chalk';
+import * as url from 'node:url';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { createHash } from 'node:crypto';
+import {
+    MarkdownHandlerRegistry,
+    MarkdownPreviewRuntime,
+    extractLeadingFrontMatter,
+    stripLeadingFrontMatter,
+    type MdBlockExecutionResult,
+    type MdBlockKind,
+    type MdExecutableBlock
+} from '@oml/markdown';
+import { STATIC_MARKDOWN_RUNTIME_BUNDLE_FILE, STATIC_MARKDOWN_RUNTIME_CSS } from '@oml/markdown/static';
+import { normalizeFormatExtension } from '../backend/reasoned-output.js';
+import { createBackend } from '../backend/create-backend.js';
+import type { CliBackend } from '../backend/backend-types.js';
+import { formatDuration } from '../util.js';
+import type { ReasonOptions } from './reason.js';
+import { reasonAction } from './reason.js';
+import { resolveCompileOutputRoot, resolveCompileWorkspaceRoot } from './compile.js';
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
+const markdownRuntime = new MarkdownPreviewRuntime(new MarkdownHandlerRegistry());
+const SUPPORTED_MD_BLOCK_KINDS = new Set<MdBlockKind>([
+    'table',
+    'tree',
+    'graph',
+    'chart',
+    'diagram',
+    'list',
+    'text',
+    'matrix',
+    'table-editor'
+]);
+const LINK_ATTRIBUTE_KEYS = new Set(['href', 'src', 'xlinkHref', 'xlink:href']);
+const RENDER_PROFILE = process.env.OML_RENDER_PROFILE === '1';
+
+export type RenderOptions = {
+    workspace?: string,
+    md: string,
+    web: string,
+    owl?: string,
+    format?: string,
+    context?: string,
+    clean?: boolean,
+    only?: boolean,
+    pretty?: boolean,
+    uniqueNamesAssumption?: boolean,
+    explanations?: boolean,
+    profile?: boolean
+};
+
+export const renderAction = async (
+    opts: RenderOptions
+): Promise<void> => {
+    const workspaceRoot = resolveCompileWorkspaceRoot(opts.workspace);
+    const owlOutputRoot = resolveCompileOutputRoot(workspaceRoot, opts.owl);
+    const rdfFormat = normalizeFormatExtension(opts.format);
+    if (!opts.only) {
+        const reasonOpts: ReasonOptions = {
+            workspace: workspaceRoot,
+            owl: owlOutputRoot,
+            format: rdfFormat,
+            clean: opts.clean,
+            pretty: opts.pretty,
+            only: false,
+            checkOnly: false,
+            uniqueNamesAssumption: opts.uniqueNamesAssumption,
+            explanations: opts.explanations,
+            profile: opts.profile,
+        };
+        await reasonAction(reasonOpts);
+    }
+    const backend = createBackend({
+        owlOutputRoot,
+        rdfFormat,
+    });
+    try {
+        const renderStartedAt = Date.now();
+        const markdownRoot = path.resolve(workspaceRoot, opts.md);
+        const output = path.resolve(opts.web);
+        const workspaceStat = await fs.stat(workspaceRoot).catch(() => undefined);
+        if (!workspaceStat || !workspaceStat.isDirectory()) {
+            console.error(chalk.red(`Workspace folder does not exist: ${workspaceRoot}`));
+            process.exit(1);
+        }
+        const markdownStat = await fs.stat(markdownRoot).catch(() => undefined);
+        if (!markdownStat || !markdownStat.isDirectory()) {
+            console.error(chalk.red(`Markdown folder does not exist: ${markdownRoot}`));
+            process.exit(1);
+        }
+
+        if (isSameOrDescendant(markdownRoot, output)) {
+            console.error(chalk.red('Web output folder cannot be inside the markdown folder.'));
+            process.exit(1);
+        }
+
+        if (opts.clean) {
+            await fs.rm(output, { recursive: true, force: true });
+        }
+
+        const renderableMarkdownFiles = await discoverRenderableMarkdownFiles(markdownRoot, output);
+        const discoveredWorkspaceMarkdownFiles = await discoverMarkdownFiles(workspaceRoot, output);
+        const templateFiles = await discoverTemplateMarkdownFiles(discoveredWorkspaceMarkdownFiles);
+        const templateCatalog = buildTemplateCatalog(templateFiles);
+        const explicitContextModelUri = resolveModelUriOption(opts.context, workspaceRoot);
+        const templateGenerationEnabled = explicitContextModelUri !== undefined;
+        const wikiPageIndex = buildWikiPageIndex(renderableMarkdownFiles, markdownRoot, output);
+        const generatedInstancePages = new Set<string>();
+        const instancePageByIri = new Map<string, string>();
+        const attemptedInstanceIris = new Set<string>();
+        const workspaceAssetFiles = new Set<string>();
+        const staticAssets = await writeStaticAssets(output);
+        let blockArtifactFiles = 0;
+        for (const file of renderableMarkdownFiles) {
+            const relative = path.relative(markdownRoot, file);
+            const outputFile = path.join(output, relative.replace(/\.md$/i, '.html'));
+            const rendered = await renderMarkdownFile(
+                backend,
+                workspaceRoot,
+                markdownRoot,
+                output,
+                file,
+                outputFile,
+                staticAssets.runtimeScriptFile,
+                staticAssets.stylesheetFile,
+                templateGenerationEnabled,
+                explicitContextModelUri,
+                wikiPageIndex,
+                templateCatalog,
+                generatedInstancePages,
+                instancePageByIri
+                ,
+                attemptedInstanceIris
+            );
+            const referencedWorkspaceAssets = rendered.workspaceAssets;
+            for (const asset of referencedWorkspaceAssets) {
+                workspaceAssetFiles.add(asset);
+            }
+            blockArtifactFiles += rendered.blockArtifactFiles;
+        }
+        for (const file of workspaceAssetFiles) {
+            const workspaceRelative = path.relative(workspaceRoot, file);
+            if (workspaceRelative.startsWith('..') || path.isAbsolute(workspaceRelative)) {
+                continue;
+            }
+            if (workspaceRelative.toLowerCase().endsWith('.md')) {
+                continue;
+            }
+            const markdownRelative = path.relative(markdownRoot, file);
+            const isInsideMarkdownRoot = !markdownRelative.startsWith('..') && !path.isAbsolute(markdownRelative);
+            const outputRelative = isInsideMarkdownRoot ? markdownRelative : workspaceRelative;
+            const target = path.join(output, outputRelative);
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.copyFile(file, target);
+        }
+
+        if (renderableMarkdownFiles.length === 0) {
+            console.log(chalk.yellow(`No markdown files found under ${markdownRoot}.`));
+        }
+        console.log(chalk.green(`render: ${renderableMarkdownFiles.length} markdown file(s) rendered in ${path.relative(process.cwd(), output) || output} [${formatDuration(Date.now() - renderStartedAt)}]`));
+        logRenderTiming('render.total', renderStartedAt, `${renderableMarkdownFiles.length} markdown file(s)`);
+    } finally {
+        await backend.dispose();
+    }
+};
+
+function isSameOrDescendant(parent: string, candidate: string): boolean {
+    const relative = path.relative(parent, candidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+type TemplateFile = {
+    filePath: string;
+    typeIri: string;
+    priority: number;
+};
+
+type TemplateCatalog = {
+    byType: Map<string, TemplateFile[]>;
+};
+
+async function discoverTemplateMarkdownFiles(markdownFiles: ReadonlyArray<string>): Promise<TemplateFile[]> {
+    const templateFiles: TemplateFile[] = [];
+    for (const filePath of markdownFiles) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const frontMatter = extractLeadingFrontMatter(content);
+        const rawType = frontMatter?.data?.type;
+        if (typeof rawType === 'string' && rawType.trim().length > 0) {
+            const priorityValue = frontMatter?.data?.priority;
+            const priority = typeof priorityValue === 'number'
+                ? priorityValue
+                : Number.parseInt(String(priorityValue ?? '0'), 10);
+            templateFiles.push({
+                filePath,
+                typeIri: normalizeTemplateTypeIri(rawType),
+                priority: Number.isFinite(priority) ? priority : 0
+            });
+        }
+    }
+    return templateFiles;
+}
+
+function normalizeTemplateTypeIri(value: string): string {
+    return value.trim().replace(/^<|>$/g, '');
+}
+
+function buildTemplateCatalog(templateFiles: ReadonlyArray<TemplateFile>): TemplateCatalog {
+    const byType = new Map<string, TemplateFile[]>();
+    for (const template of templateFiles) {
+        const list = byType.get(template.typeIri) ?? [];
+        list.push(template);
+        byType.set(template.typeIri, list);
+    }
+    for (const list of byType.values()) {
+        list.sort((left, right) => (left.priority - right.priority) || left.filePath.localeCompare(right.filePath));
+    }
+    return { byType };
+}
+
+function resolveModelUriOption(value: string | undefined, workspaceRoot: string): string | undefined {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (trimmed.startsWith('workspace:/')) {
+        const resolved = resolveWorkspacePath(workspaceRoot, trimmed);
+        return resolved ? url.pathToFileURL(resolved).toString() : undefined;
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
+        return trimmed;
+    }
+    const absolute = path.isAbsolute(trimmed)
+        ? trimmed
+        : path.resolve(workspaceRoot, trimmed);
+    return url.pathToFileURL(absolute).toString();
+}
+
+async function discoverRenderableMarkdownFiles(root: string, outputRoot: string): Promise<string[]> {
+    const markdownFiles = await discoverMarkdownFiles(root, outputRoot);
+    const renderableFiles: string[] = [];
+    for (const filePath of markdownFiles) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const frontMatter = extractLeadingFrontMatter(content);
+        const rawType = frontMatter?.data?.type;
+        if (typeof rawType === 'string' && rawType.trim().length > 0) {
+            continue;
+        }
+        renderableFiles.push(filePath);
+    }
+    return renderableFiles;
+}
+
+async function discoverMarkdownFiles(root: string, outputRoot: string): Promise<string[]> {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const markdownFiles: string[] = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+                continue;
+            }
+            if (isSameOrDescendant(outputRoot, fullPath)) {
+                continue;
+            }
+            markdownFiles.push(...await discoverMarkdownFiles(fullPath, outputRoot));
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (entry.name.toLowerCase().endsWith('.md')) {
+            markdownFiles.push(fullPath);
+        }
+    }
+    return markdownFiles;
+}
+
+async function renderMarkdownFile(
+    backend: CliBackend,
+    workspaceRoot: string,
+    inputRoot: string,
+    outputRoot: string,
+    inputFile: string,
+    outputFile: string,
+    runtimeScriptFile: string,
+    stylesheetFile: string,
+    templateGenerationEnabled: boolean,
+    defaultContextModelUri: string | undefined,
+    wikiPageIndex: ReadonlyMap<string, string>,
+    templateCatalog: TemplateCatalog,
+    generatedInstancePages: Set<string>,
+    instancePageByIri: Map<string, string>,
+    attemptedInstanceIris: Set<string>,
+    currentPageStack: Set<string> = new Set<string>(),
+    explicitMarkdown?: string,
+    forcedModelUri?: string
+): Promise<{ workspaceAssets: Set<string>; blockArtifactFiles: number }> {
+    const pageStartedAt = Date.now();
+    const markdown = explicitMarkdown ?? await fs.readFile(inputFile, 'utf-8');
+    const prepared = markdownRuntime.prepare(markdown);
+    const rewriteResult = rewriteRenderedLinks(prepared.renderedHtml, {
+        workspaceRoot,
+        inputRoot,
+        inputFile,
+        outputRoot,
+        outputFile,
+    });
+    const executableBlocks = toExecutableBlocks(prepared.codeBlocks);
+    const optionsByBlockId = new Map(prepared.codeBlocks.map((block) => [block.id, block.options] as const));
+    const modelUri = forcedModelUri ?? resolveContextModelUri(inputFile, prepared.contextUri, workspaceRoot) ?? defaultContextModelUri;
+    const blockResults = executableBlocks.length === 0
+        ? []
+        : (await backend.executeMarkdownBlocks({
+            documentUri: url.pathToFileURL(path.resolve(inputFile)).toString(),
+            modelUri,
+            blocks: executableBlocks
+        }, workspaceRoot)).results;
+    logRenderTiming('render.page.blocks', pageStartedAt, path.relative(workspaceRoot, inputFile));
+    const renderedBlockResults: RenderedBlockResult[] = blockResults.map((result) => ({
+        ...result,
+        options: optionsByBlockId.get(result.blockId)
+    }));
+    const blockRewriteResult = rewriteBlockResultLinks(renderedBlockResults, {
+        workspaceRoot,
+        inputRoot,
+        inputFile,
+        outputRoot,
+        outputFile,
+    });
+    const blockArtifacts = await writeBlockArtifacts(outputFile, blockRewriteResult.results);
+    const pageWikilinkIris = collectWikilinkIrisFromHtml(rewriteResult.html);
+    const iriAliasHrefByIri = templateGenerationEnabled && modelUri
+        ? await generateInstanceTemplatePages(
+            backend,
+            workspaceRoot,
+            inputRoot,
+            outputRoot,
+            outputFile,
+            runtimeScriptFile,
+            stylesheetFile,
+            templateGenerationEnabled,
+            modelUri,
+            pageWikilinkIris,
+            renderedBlockResults,
+            wikiPageIndex,
+            templateCatalog,
+            generatedInstancePages,
+            instancePageByIri,
+            attemptedInstanceIris,
+            currentPageStack
+        )
+        : {};
+    logRenderTiming('render.page.templates', pageStartedAt, path.relative(workspaceRoot, inputFile));
+    const runtimeScriptRelative = toRelativeWebPath(path.dirname(outputFile), runtimeScriptFile);
+    const stylesheetRelative = toRelativeWebPath(path.dirname(outputFile), stylesheetFile);
+    const wikiLinkHrefByKey = buildWikiLinkHrefMapForPage(wikiPageIndex, outputFile);
+    const resolvedInstanceLinks = Object.fromEntries(
+        [...instancePageByIri.entries()].map(([iri, absolute]) => [iri, toRelativeWebPath(path.dirname(outputFile), absolute)])
+    );
+    const html = wrapHtml(
+        rewriteResult.html,
+        runtimeScriptRelative,
+        stylesheetRelative,
+        blockArtifacts.manifest,
+        blockRewriteResult.results,
+        wikiLinkHrefByKey,
+        { ...resolvedInstanceLinks, ...iriAliasHrefByIri },
+        templateGenerationEnabled && Boolean(modelUri)
+    );
+    await fs.mkdir(path.dirname(outputFile), { recursive: true });
+    await fs.writeFile(outputFile, html, 'utf-8');
+    const workspaceAssets = new Set<string>(rewriteResult.workspaceAssets);
+    for (const asset of blockRewriteResult.workspaceAssets) {
+        workspaceAssets.add(asset);
+    }
+    logRenderTiming('render.page.total', pageStartedAt, path.relative(workspaceRoot, inputFile));
+    return { workspaceAssets, blockArtifactFiles: blockArtifacts.count };
+}
+
+type RenderedBlockResult = MdBlockExecutionResult & {
+    options?: Record<string, unknown>;
+};
+
+function toExecutableBlocks(codeBlocks: ReadonlyArray<{
+    id: string;
+    language: string;
+    content: string;
+    meta?: string;
+    options?: Record<string, unknown>;
+    lineStart: number;
+    lineEnd: number;
+}>): MdExecutableBlock[] {
+    const executable: MdExecutableBlock[] = [];
+    for (const block of codeBlocks) {
+        const kind = toMdBlockKind(block.language);
+        if (!kind) {
+            continue;
+        }
+        executable.push({
+            id: block.id,
+            kind,
+            source: block.content,
+            meta: block.meta,
+            options: block.options,
+            lineStart: block.lineStart,
+            lineEnd: block.lineEnd
+        });
+    }
+    return executable;
+}
+
+function toMdBlockKind(language: string): MdBlockKind | undefined {
+    return SUPPORTED_MD_BLOCK_KINDS.has(language as MdBlockKind) ? (language as MdBlockKind) : undefined;
+}
+
+function resolveContextModelUri(documentFile: string, contextUri: string | undefined, workspaceRoot: string): string | undefined {
+    if (!contextUri) {
+        return undefined;
+    }
+    const trimmed = contextUri.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (trimmed.startsWith('workspace:/')) {
+        const resolved = resolveWorkspacePath(workspaceRoot, trimmed);
+        return resolved ? url.pathToFileURL(resolved).toString() : undefined;
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
+        return trimmed;
+    }
+    if (trimmed.startsWith('/')) {
+        return url.pathToFileURL(path.resolve(workspaceRoot, trimmed.replace(/^\/+/, ''))).toString();
+    }
+    return url.pathToFileURL(path.resolve(path.dirname(documentFile), trimmed)).toString();
+}
+
+async function writeStaticAssets(outputRoot: string): Promise<{
+    runtimeScriptFile: string;
+    stylesheetFile: string;
+}> {
+    const runtimeBundle = await loadStaticRuntimeBundle();
+    const sourceStylesheet = await loadCodeBlockStylesheet();
+    const mergedStylesheet = `${sourceStylesheet}\n\n${STATIC_MARKDOWN_RUNTIME_CSS}\n`;
+    const runtimeVersion = createHash('sha1').update(runtimeBundle).digest('hex').slice(0, 12);
+    const stylesheetVersion = createHash('sha1').update(mergedStylesheet).digest('hex').slice(0, 12);
+    const runtimeFile = path.join(outputRoot, '_oml', `markdown-static-${runtimeVersion}.js`);
+    const stylesheetFile = path.join(outputRoot, '_oml', `markdown-webview-${stylesheetVersion}.css`);
+    await fs.mkdir(path.dirname(runtimeFile), { recursive: true });
+    await fs.writeFile(runtimeFile, runtimeBundle, 'utf-8');
+    await fs.writeFile(stylesheetFile, mergedStylesheet, 'utf-8');
+    return { runtimeScriptFile: runtimeFile, stylesheetFile };
+}
+
+async function loadStaticRuntimeBundle(): Promise<string> {
+    const require = createRequire(import.meta.url);
+    const staticEntry = require.resolve('@oml/markdown/static');
+    const bundlePath = path.join(path.dirname(staticEntry), STATIC_MARKDOWN_RUNTIME_BUNDLE_FILE);
+    try {
+        return await fs.readFile(bundlePath, 'utf-8');
+    } catch {
+        throw new Error(
+            `Unable to load markdown static runtime bundle at '${bundlePath}'. `
+            + 'Run the markdown package build to generate it.'
+        );
+    }
+}
+
+async function loadCodeBlockStylesheet(): Promise<string> {
+    const candidates = [
+        path.resolve(__dirname, '..', '..', '..', 'extension', 'src', 'webview', 'markdown-webview.css'),
+        path.resolve(__dirname, '..', '..', '..', 'extension', 'out', 'webview', 'markdown-webview.css'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            return await fs.readFile(candidate, 'utf-8');
+        } catch {
+            // Try next candidate.
+        }
+    }
+    return '';
+}
+
+async function writeBlockArtifacts(outputFile: string, results: ReadonlyArray<RenderedBlockResult>): Promise<{
+    count: number;
+    manifest: Array<{ blockId: string; path: string }>;
+}> {
+    if (results.length === 0) {
+        return { count: 0, manifest: [] };
+    }
+    const blockDirName = `${path.basename(outputFile, '.html')}.blocks`;
+    const blockDir = path.join(path.dirname(outputFile), blockDirName);
+    await fs.mkdir(blockDir, { recursive: true });
+    const manifest: Array<{ blockId: string; path: string }> = [];
+    for (const result of results) {
+        const safeId = sanitizeBlockId(result.blockId);
+        const fileName = `${safeId}.json`;
+        const filePath = path.join(blockDir, fileName);
+        await fs.writeFile(filePath, JSON.stringify(result, null, 2), 'utf-8');
+        manifest.push({
+            blockId: result.blockId,
+            path: `./${blockDirName}/${fileName}`
+        });
+    }
+    return { count: results.length, manifest };
+}
+
+function rewriteBlockResultLinks(
+    results: ReadonlyArray<RenderedBlockResult>,
+    context: {
+        workspaceRoot: string;
+        inputRoot: string;
+        inputFile: string;
+        outputRoot: string;
+        outputFile: string;
+    }
+): {
+    results: RenderedBlockResult[];
+    workspaceAssets: Set<string>;
+} {
+    const workspaceAssets = new Set<string>();
+    const rewrittenResults = results.map((result) => rewriteLinkValue(result, context, workspaceAssets));
+    return { results: rewrittenResults, workspaceAssets };
+}
+
+function rewriteLinkValue<T>(
+    value: T,
+    context: {
+        workspaceRoot: string;
+        inputRoot: string;
+        inputFile: string;
+        outputRoot: string;
+        outputFile: string;
+    },
+    workspaceAssets: Set<string>,
+    parentKey?: string
+): T {
+    if (typeof value === 'string') {
+        if (parentKey && LINK_ATTRIBUTE_KEYS.has(parentKey)) {
+            return rewriteHref(value, context, workspaceAssets) as T;
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => rewriteLinkValue(entry, context, workspaceAssets)) as T;
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const source = value as Record<string, unknown>;
+    const rewritten: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(source)) {
+        rewritten[key] = rewriteLinkValue(entry, context, workspaceAssets, key);
+    }
+    return rewritten as T;
+}
+
+function sanitizeBlockId(value: string): string {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return 'block';
+    }
+    return trimmed.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+function rewriteRenderedLinks(
+    content: string,
+    context: {
+        workspaceRoot: string;
+        inputRoot: string;
+        inputFile: string;
+        outputRoot: string;
+        outputFile: string;
+    }
+): {
+    html: string;
+    workspaceAssets: Set<string>;
+} {
+    const workspaceAssets = new Set<string>();
+    const html = content.replace(/(\b(?:href|src)\s*=\s*)(["'])([^"']+)\2/gi, (_match, prefix: string, quote: string, rawHref: string) => {
+        const rewritten = rewriteHref(rawHref, context, workspaceAssets);
+        return `${prefix}${quote}${rewritten}${quote}`;
+    });
+    return { html, workspaceAssets };
+}
+
+function rewriteHref(
+    href: string,
+    context: {
+        workspaceRoot: string;
+        inputRoot: string;
+        inputFile: string;
+        outputRoot: string;
+        outputFile: string;
+    },
+    workspaceAssets: Set<string>
+): string {
+    const parts = splitHref(href);
+    if (!parts.path) {
+        return href;
+    }
+
+    const trimmedPath = parts.path.trim();
+    if (!trimmedPath || trimmedPath.startsWith('#') || trimmedPath.startsWith('//')) {
+        return href;
+    }
+
+    if (trimmedPath.startsWith('workspace:/')) {
+        const resolved = resolveWorkspacePath(context.workspaceRoot, trimmedPath);
+        if (!resolved) {
+            return href;
+        }
+        if (!resolved.toLowerCase().endsWith('.md')) {
+            workspaceAssets.add(resolved);
+        }
+        const workspaceRelative = path.relative(context.workspaceRoot, resolved);
+        const inputRelative = path.relative(context.inputRoot, resolved);
+        const isInsideInput = !inputRelative.startsWith('..') && !path.isAbsolute(inputRelative);
+        const outputRelative = isInsideInput ? inputRelative : workspaceRelative;
+        const targetInOutput = path.join(
+            context.outputRoot,
+            resolved.toLowerCase().endsWith('.md')
+                ? outputRelative.replace(/\.md$/i, '.html')
+                : outputRelative
+        );
+        const rewrittenPath = toRelativeWebPath(path.dirname(context.outputFile), targetInOutput);
+        return `${rewrittenPath}${parts.query}${parts.fragment}`;
+    }
+
+    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmedPath)) {
+        return href;
+    }
+
+    if (!trimmedPath.startsWith('/')) {
+        const resolved = path.resolve(path.dirname(context.inputFile), trimmedPath);
+        const workspaceRelative = path.relative(context.workspaceRoot, resolved);
+        if (!workspaceRelative.startsWith('..') && !path.isAbsolute(workspaceRelative) && !resolved.toLowerCase().endsWith('.md')) {
+            workspaceAssets.add(resolved);
+        }
+    }
+
+    const rewrittenPath = trimmedPath.toLowerCase().endsWith('.md')
+        ? trimmedPath.slice(0, -3) + '.html'
+        : trimmedPath;
+    return `${rewrittenPath}${parts.query}${parts.fragment}`;
+}
+
+function resolveWorkspacePath(workspaceRoot: string, hrefPath: string): string | undefined {
+    const relative = hrefPath.slice('workspace:/'.length).replace(/^\/+/, '');
+    const resolved = path.resolve(workspaceRoot, relative);
+    const relativeToWorkspace = path.relative(workspaceRoot, resolved);
+    if (relativeToWorkspace.startsWith('..') || path.isAbsolute(relativeToWorkspace)) {
+        return undefined;
+    }
+    return resolved;
+}
+
+function splitHref(href: string): { path: string; query: string; fragment: string } {
+    const hashIndex = href.indexOf('#');
+    const pathAndQuery = hashIndex >= 0 ? href.slice(0, hashIndex) : href;
+    const fragment = hashIndex >= 0 ? href.slice(hashIndex) : '';
+    const queryIndex = pathAndQuery.indexOf('?');
+    return {
+        path: queryIndex >= 0 ? pathAndQuery.slice(0, queryIndex) : pathAndQuery,
+        query: queryIndex >= 0 ? pathAndQuery.slice(queryIndex) : '',
+        fragment
+    };
+}
+
+function toRelativeWebPath(fromDir: string, toFile: string): string {
+    const relative = path.relative(fromDir, toFile).split(path.sep).join('/');
+    if (!relative || relative === '.') {
+        return '.';
+    }
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
+
+function normalizeWikiPathKey(raw: string): string {
+    const normalized = raw.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+/g, '/');
+    if (!normalized) {
+        return '';
+    }
+    const withoutHtml = normalized.replace(/\.html$/i, '');
+    return withoutHtml.replace(/^\.\//, '').toLowerCase();
+}
+
+function buildWikiPageIndex(markdownFiles: ReadonlyArray<string>, inputRoot: string, outputRoot: string): Map<string, string> {
+    const index = new Map<string, string>();
+    for (const markdownFile of markdownFiles) {
+        const relativeInput = path.relative(inputRoot, markdownFile).split(path.sep).join('/');
+        const normalizedRelative = normalizeWikiPathKey(relativeInput.replace(/\.md$/i, ''));
+        if (!normalizedRelative) {
+            continue;
+        }
+        const outputFile = path.join(outputRoot, relativeInput.replace(/\.md$/i, '.html'));
+        index.set(normalizedRelative, outputFile);
+    }
+    return index;
+}
+
+function buildWikiLinkHrefMapForPage(
+    wikiPageIndex: ReadonlyMap<string, string>,
+    outputFile: string
+): Record<string, string> {
+    const map: Record<string, string> = {};
+    for (const [key, targetFile] of wikiPageIndex.entries()) {
+        map[key] = toRelativeWebPath(path.dirname(outputFile), targetFile);
+    }
+    return map;
+}
+
+function collectFragmentIrisFromValue(value: unknown, collected: Set<string>): void {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length > 0) {
+            const iriPattern = /[a-z][a-z0-9+.-]*:[^\s<>"')\]]+/gi;
+            for (const match of trimmed.matchAll(iriPattern)) {
+                let iri = (match[0] ?? '').trim();
+                iri = iri.replace(/[.,;:!?]+$/, '');
+                if (/^[a-z][a-z0-9+.-]*:/i.test(iri)) {
+                    collected.add(iri);
+                }
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            collectFragmentIrisFromValue(entry, collected);
+        }
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const entry of Object.values(value)) {
+            collectFragmentIrisFromValue(entry, collected);
+        }
+    }
+}
+
+function collectWikilinkIrisFromResults(results: ReadonlyArray<RenderedBlockResult>): Set<string> {
+    const collected = new Set<string>();
+    for (const result of results) {
+        collectFragmentIrisFromValue(result, collected);
+    }
+    return collected;
+}
+
+function collectWikilinkIrisFromHtml(renderedHtml: string): Set<string> {
+    const collected = new Set<string>();
+    const pattern = /<a\b[^>]*\bclass=(["'])[^"']*\bwikilink\b[^"']*\1[^>]*\biri=(["'])([^"']+)\2/gi;
+    for (const match of renderedHtml.matchAll(pattern)) {
+        const iri = (match[3] ?? '').trim();
+        if (iri) {
+            collected.add(iri);
+        }
+    }
+    return collected;
+}
+
+function sanitizePathSegment(value: string): string {
+    const decoded = decodeURIComponent(value);
+    const trimmed = decoded.trim();
+    if (!trimmed) {
+        return 'instance';
+    }
+    return encodeURIComponent(trimmed);
+}
+
+function resolveInstanceOutputFile(outputRoot: string, iri: string): string | undefined {
+    let parsed: URL;
+    try {
+        parsed = new URL(iri);
+    } catch {
+        return undefined;
+    }
+    if (!parsed.hostname) {
+        return undefined;
+    }
+    const host = parsed.hostname.toLowerCase();
+    const pathSegments = parsed.pathname
+        .split('/')
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0)
+        .map((segment) => sanitizePathSegment(segment));
+    const fragment = parsed.hash.replace(/^#/, '').trim();
+    const fileSegments = [host, ...pathSegments];
+    if (fragment.length > 0) {
+        fileSegments.push(sanitizePathSegment(fragment));
+    } else if (fileSegments.length === 1) {
+        fileSegments.push('index');
+    }
+    if (fileSegments.length === 0) {
+        return undefined;
+    }
+    return path.join(outputRoot, ...fileSegments) + '.html';
+}
+
+function selectTemplateForTypes(catalog: TemplateCatalog, typeIris: ReadonlySet<string>): TemplateFile | undefined {
+    const candidates: TemplateFile[] = [];
+    for (const typeIri of typeIris) {
+        const templates = catalog.byType.get(typeIri);
+        if (!templates || templates.length === 0) {
+            continue;
+        }
+        candidates.push(...templates);
+    }
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    candidates.sort((left, right) => (left.priority - right.priority) || left.filePath.localeCompare(right.filePath));
+    return candidates[0];
+}
+
+async function queryRdfTypesForIris(
+    backend: CliBackend,
+    workspaceRoot: string,
+    modelUri: string,
+    iris: ReadonlyArray<string>
+): Promise<Map<string, Set<string>>> {
+    const startedAt = Date.now();
+    const byIri = new Map<string, Set<string>>();
+    if (iris.length === 0) {
+        return byIri;
+    }
+    const valuesClause = iris.map((iri) => `<${iri}>`).join(' ');
+    const query = `PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+SELECT ?s ?type
+WHERE {
+  VALUES ?s { ${valuesClause} }
+  GRAPH ?g { ?s rdf:type ?type . }
+}`;
+    const result = await backend.executeMarkdownBlocks({
+        documentUri: 'file:///__oml_cli_wikilink_types__.md',
+        modelUri,
+        blocks: [{
+            id: '__oml_cli_wikilink_types__',
+            kind: 'table',
+            source: query,
+            lineStart: 0,
+            lineEnd: 0,
+        }]
+    }, workspaceRoot);
+    const block = result.results[0];
+    if (!block || block.status !== 'ok' || block.format !== 'table' || !block.payload) {
+        return byIri;
+    }
+    const subjectIndex = block.payload.columns.findIndex((column) => column === 's');
+    const typeIndex = block.payload.columns.findIndex((column) => column === 'type');
+    const left = subjectIndex >= 0 ? subjectIndex : 0;
+    const right = typeIndex >= 0 ? typeIndex : 1;
+    for (const row of block.payload.rows) {
+        const subject = (row[left] ?? '').trim();
+        const typeIri = (row[right] ?? '').trim().replace(/^<|>$/g, '');
+        if (!subject || !typeIri) {
+            continue;
+        }
+        const types = byIri.get(subject) ?? new Set<string>();
+        types.add(typeIri);
+        byIri.set(subject, types);
+    }
+    logRenderTiming('render.types', startedAt, `${iris.length} iri(s)`);
+    return byIri;
+}
+
+function buildTemplatePageMarkdown(templateMarkdown: string, focusIri: string, queryContextOption: string): string {
+    const body = stripLeadingFrontMatter(templateMarkdown).split('${contextIri}').join(focusIri);
+    const escapedContext = JSON.stringify(queryContextOption);
+    return `---
+contextUri: ${escapedContext}
+---
+${body}`;
+}
+
+async function generateInstanceTemplatePages(
+    backend: CliBackend,
+    workspaceRoot: string,
+    inputRoot: string,
+    outputRoot: string,
+    pageOutputFile: string,
+    runtimeScriptFile: string,
+    stylesheetFile: string,
+    templateGenerationEnabled: boolean,
+    queryContextModelUri: string,
+    pageWikilinkIris: ReadonlySet<string>,
+    results: ReadonlyArray<RenderedBlockResult>,
+    wikiPageIndex: ReadonlyMap<string, string>,
+    templateCatalog: TemplateCatalog,
+    generatedInstancePages: Set<string>,
+    instancePageByIri: Map<string, string>,
+    attemptedInstanceIris: Set<string>,
+    currentPageStack: Set<string>
+): Promise<Record<string, string>> {
+    const startedAt = Date.now();
+    const iriToHref: Record<string, string> = {};
+    if (!templateGenerationEnabled) {
+        return iriToHref;
+    }
+    const wikilinkIris = [...new Set<string>([
+        ...pageWikilinkIris,
+        ...collectWikilinkIrisFromResults(results),
+    ])];
+    const unresolved = wikilinkIris.filter((iri) => !attemptedInstanceIris.has(iri));
+    for (const iri of unresolved) {
+        attemptedInstanceIris.add(iri);
+    }
+    const typesByIri = await queryRdfTypesForIris(backend, workspaceRoot, queryContextModelUri, unresolved);
+    for (const iri of unresolved) {
+        const types = typesByIri.get(iri) ?? new Set<string>();
+        const template = selectTemplateForTypes(templateCatalog, types);
+        if (!template) {
+            continue;
+        }
+        const instanceOutputFile = resolveInstanceOutputFile(outputRoot, iri);
+        if (!instanceOutputFile) {
+            continue;
+        }
+        instancePageByIri.set(iri, instanceOutputFile);
+        if (generatedInstancePages.has(instanceOutputFile) || currentPageStack.has(instanceOutputFile)) {
+            continue;
+        }
+        generatedInstancePages.add(instanceOutputFile);
+        const templateMarkdown = await fs.readFile(template.filePath, 'utf-8');
+        const instantiatedMarkdown = buildTemplatePageMarkdown(templateMarkdown, iri, queryContextModelUri);
+        const nextStack = new Set(currentPageStack);
+        nextStack.add(instanceOutputFile);
+        await renderMarkdownFile(
+            backend,
+            workspaceRoot,
+            inputRoot,
+            outputRoot,
+            template.filePath,
+            instanceOutputFile,
+            runtimeScriptFile,
+            stylesheetFile,
+            templateGenerationEnabled,
+            queryContextModelUri,
+            wikiPageIndex,
+            templateCatalog,
+            generatedInstancePages,
+            instancePageByIri,
+            attemptedInstanceIris,
+            nextStack,
+            instantiatedMarkdown,
+            queryContextModelUri
+        );
+    }
+    for (const iri of wikilinkIris) {
+        const absolute = instancePageByIri.get(iri);
+        if (!absolute) {
+            continue;
+        }
+        iriToHref[iri] = toRelativeWebPath(path.dirname(pageOutputFile), absolute);
+    }
+    logRenderTiming('render.wikilinks', startedAt, `${unresolved.length} unresolved iri(s)`);
+    return iriToHref;
+}
+
+function logRenderTiming(label: string, startedAt: number, detail: string): void {
+    if (!RENDER_PROFILE) {
+        return;
+    }
+    const elapsed = Date.now() - startedAt;
+    console.log(chalk.gray(`[render-profile] ${label} ${elapsed}ms ${detail}`));
+}
+
+function wrapHtml(
+    content: string,
+    runtimeScriptPath: string,
+    stylesheetPath: string,
+    blockManifest: Array<{ blockId: string; path: string }>,
+    blockResults: ReadonlyArray<RenderedBlockResult>,
+    wikiLinkHrefByKey: Record<string, string>,
+    iriAliasHrefByIri: Record<string, string>,
+    linkingEnabled: boolean
+): string {
+    const escapedManifest = escapeJsonForScript(JSON.stringify(blockManifest));
+    const inlineResults = Object.fromEntries(blockResults.map((result) => [result.blockId, result]));
+    const escapedInlineResults = escapeJsonForScript(JSON.stringify(inlineResults));
+    const escapedWikiIndex = escapeJsonForScript(JSON.stringify(wikiLinkHrefByKey));
+    const escapedIriAliasIndex = escapeJsonForScript(JSON.stringify(iriAliasHrefByIri));
+    const escapedLinkingConfig = escapeJsonForScript(JSON.stringify({ linkingEnabled }));
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>OML Markdown</title>
+  <link rel="stylesheet" href="${escapeAttribute(stylesheetPath)}">
+</head>
+<body>
+${content}
+<script id="oml-md-block-manifest" type="application/json">${escapedManifest}</script>
+<script id="oml-md-block-inline-results" type="application/json">${escapedInlineResults}</script>
+<script id="oml-md-wikilink-index" type="application/json">${escapedWikiIndex}</script>
+<script id="oml-md-wikilink-iri-aliases" type="application/json">${escapedIriAliasIndex}</script>
+<script id="oml-md-wikilink-config" type="application/json">${escapedLinkingConfig}</script>
+<script src="${escapeAttribute(runtimeScriptPath)}"></script>
+</body>
+</html>
+`;
+}
+
+function escapeAttribute(value: string): string {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+function escapeJsonForScript(value: string): string {
+    return value.replace(/</g, '\\u003c');
+}