cli-jaw 2.0.3 → 2.0.5

package/public/js/render/highlight.ts

@@ -0,0 +1,83 @@
+// ── Highlight.js language registry and helpers ──
+import hljs from 'highlight.js/lib/core';
+import javascript from 'highlight.js/lib/languages/javascript';
+import typescript from 'highlight.js/lib/languages/typescript';
+import python from 'highlight.js/lib/languages/python';
+import bash from 'highlight.js/lib/languages/bash';
+import shell from 'highlight.js/lib/languages/shell';
+import json from 'highlight.js/lib/languages/json';
+import css from 'highlight.js/lib/languages/css';
+import xml from 'highlight.js/lib/languages/xml';
+import markdown from 'highlight.js/lib/languages/markdown';
+import yaml from 'highlight.js/lib/languages/yaml';
+import sql from 'highlight.js/lib/languages/sql';
+import rust from 'highlight.js/lib/languages/rust';
+import go from 'highlight.js/lib/languages/go';
+import java from 'highlight.js/lib/languages/java';
+import cpp from 'highlight.js/lib/languages/cpp';
+import diff from 'highlight.js/lib/languages/diff';
+import plaintext from 'highlight.js/lib/languages/plaintext';
+import { escapeHtml } from './html.js';
+
+let highlightLanguagesReady = false;
+
+export function ensureHighlightLanguages(): void {
+    if (highlightLanguagesReady) return;
+    highlightLanguagesReady = true;
+    hljs.registerLanguage('javascript', javascript);
+    hljs.registerLanguage('js', javascript);
+    hljs.registerLanguage('typescript', typescript);
+    hljs.registerLanguage('ts', typescript);
+    hljs.registerLanguage('python', python);
+    hljs.registerLanguage('py', python);
+    hljs.registerLanguage('bash', bash);
+    hljs.registerLanguage('shell', shell);
+    hljs.registerLanguage('sh', shell);
+    hljs.registerLanguage('json', json);
+    hljs.registerLanguage('css', css);
+    hljs.registerLanguage('xml', xml);
+    hljs.registerLanguage('html', xml);
+    hljs.registerLanguage('markdown', markdown);
+    hljs.registerLanguage('md', markdown);
+    hljs.registerLanguage('yaml', yaml);
+    hljs.registerLanguage('yml', yaml);
+    hljs.registerLanguage('sql', sql);
+    hljs.registerLanguage('rust', rust);
+    hljs.registerLanguage('rs', rust);
+    hljs.registerLanguage('go', go);
+    hljs.registerLanguage('java', java);
+    hljs.registerLanguage('cpp', cpp);
+    hljs.registerLanguage('c', cpp);
+    hljs.registerLanguage('diff', diff);
+    hljs.registerLanguage('plaintext', plaintext);
+    hljs.registerLanguage('text', plaintext);
+}
+
+export function highlightCode(text: string, lang?: string): string {
+    ensureHighlightLanguages();
+    if (lang && hljs.getLanguage(lang)) {
+        try { return hljs.highlight(text, { language: lang }).value; }
+        catch { return escapeHtml(text); }
+    }
+    try { return hljs.highlightAuto(text).value; }
+    catch { return escapeHtml(text); }
+}
+
+// ── Rehighlight all code blocks ──
+export function rehighlightAll(scope?: HTMLElement | Document): void {
+    ensureHighlightLanguages();
+    const root = scope || document;
+    root.querySelectorAll('.code-block pre code, .code-block-wrapper pre code').forEach(el => {
+        if ((el as HTMLElement).dataset['highlighted'] === 'yes') return;
+        const lang = [...el.classList].find(c => c.startsWith('language-'))?.replace('language-', '');
+        const raw = el.textContent || '';
+        try {
+            if (lang && hljs.getLanguage(lang)) {
+                el.innerHTML = hljs.highlight(raw, { language: lang }).value;
+            } else {
+                el.innerHTML = hljs.highlightAuto(raw).value;
+            }
+            (el as HTMLElement).dataset['highlighted'] = 'yes';
+        } catch { /* ignore */ }
+    });
+}

package/public/js/render/html.ts

@@ -0,0 +1,26 @@
+// ── HTML and orchestration helpers ──
+export function escapeHtml(str: string): string {
+    return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+// ── Orchestration JSON stripping ──
+// Only strip JSON blocks that contain orchestration-specific keys, not all JSON blocks
+// Require keys unique to orchestration payloads (avoid generic words like "phase")
+const ORCH_KEYS = /["'](?:subtasks|employee_config|agent_phases|orchestration_plan)["']\s*:/;
+const PROMPT_LEAK_START = /(^|\n)(?:## Approved Plan \((?:authoritative|auto-injected by orchestrator)[^\n]*\)|\[PABCD — [A-Z]:[^\n]*\]|\[PLANNING MODE[^\n]*\]|\[PLAN AUDIT[^\n]*\]|The approved plan is already injected above)/m;
+
+export function stripPromptLeakage(text: string): string {
+    const match = PROMPT_LEAK_START.exec(text);
+    if (!match || match.index < 0) return text;
+    return text.slice(0, match.index).trim();
+}
+
+export function stripOrchestration(text: string): string {
+    // Strip fenced JSON blocks only if they contain orchestration keys
+    let cleaned = text.replace(/```json\n([\s\S]*?)\n```/g, (_match, inner) =>
+        ORCH_KEYS.test(inner) ? '' : _match);
+    // Strip inline orchestration objects containing subtasks array
+    cleaned = cleaned.replace(/\{[^{}]*"subtasks"\s*:\s*\[[\s\S]*?\]\s*\}/g, '').trim();
+    return stripPromptLeakage(cleaned);
+}

package/public/js/render/markdown.ts

@@ -0,0 +1,84 @@
+// ── Markdown rendering pipeline ──
+import { marked, Renderer } from 'marked';
+import { t } from '../features/i18n.js';
+import { fixCjkPunctuationBoundary } from '../cjk-fix.js';
+import { shieldCodeFenceSvg, unshieldCodeFenceSvg, extractTopLevelSvg } from '../diagram/types.js';
+import { escapeHtml, stripOrchestration } from './html.js';
+import { shieldMath, unshieldMath } from './math.js';
+import { sanitizeHtml } from './sanitize.js';
+import { unshieldSvgBlocks } from './svg-actions.js';
+import { highlightCode, ensureHighlightLanguages } from './highlight.js';
+import { schedulePostRender } from './post-render.js';
+import { ensureRenderDelegations } from './delegations.js';
+
+// ── marked.js configuration (ES module — always available) ──
+let markedReady = false;
+
+function ensureMarked(): boolean {
+    if (markedReady) return true;
+
+    const renderer = new Renderer();
+
+    // Code blocks: highlight.js + mermaid + diagram-html detection
+    renderer.code = function ({ text, lang }: { text: string; lang?: string }) {
+        if (lang === 'mermaid') {
+            // Phase 127-F1: store raw source in data attribute, render a skeleton
+            // placeholder so users never see raw Mermaid syntax while the diagram loads.
+            const encodedCode = encodeURIComponent(text);
+            return `<div class="mermaid-container mermaid-pending" data-mermaid-code-raw="${encodedCode}" role="status" aria-label="Diagram loading">
+                <div class="mermaid-skeleton">
+                    <div class="mermaid-skeleton-spinner"></div>
+                    <div class="mermaid-skeleton-text">Rendering diagram…</div>
+                </div>
+            </div>`;
+        }
+        // diagram-html: encode as base64, Phase 2 activateWidgets() inflates to sandboxed iframe
+        if (lang?.trim().toLowerCase() === 'diagram-html') {
+            const encoded = btoa(unescape(encodeURIComponent(text)));
+            return `<div class="diagram-widget-pending" data-diagram-html="${encoded}"
+                role="status" aria-label="Interactive widget loading">
+                <div class="diagram-spinner"></div>
+            </div>`;
+        }
+        const highlighted = highlightCode(text, lang);
+        const langDisplay = lang ? escapeHtml(lang) : '';
+        const copyLabel = t('code.copy') || 'Copy';
+        return `<div class="code-block"><div class="code-header"><span class="code-lang">${langDisplay}</span><button class="code-copy-btn" type="button" aria-label="${escapeHtml(copyLabel)}">${escapeHtml(copyLabel)}</button></div><pre><code class="hljs${lang ? ` language-${escapeHtml(lang)}` : ''}">${highlighted}</code></pre></div>`;
+    };
+
+    marked.setOptions({
+        renderer,
+        gfm: true,
+        breaks: false,
+    });
+
+    markedReady = true;
+    return true;
+}
+
+export function renderMarkdown(text: string, isStreaming = false): string {
+    const rawCleaned = stripOrchestration(text);
+    if (!rawCleaned) return '<em class="text-dim orchestrate-placeholder">' + escapeHtml(t('orchestrator.dispatching')) + '</em>';
+    const cleaned = rawCleaned.replace(/\n{3,}/g, '\n\n');
+
+    const { text: fenceShielded, fences } = shieldCodeFenceSvg(cleaned);
+    const { text: svgShielded, blocks: svgBlocks } = extractTopLevelSvg(fenceShielded, isStreaming);
+    const restored = unshieldCodeFenceSvg(svgShielded, fences);
+    const { text: shielded, blocks: mathBlocks } = shieldMath(restored);
+
+    ensureHighlightLanguages();
+    ensureMarked();
+    const fixed = fixCjkPunctuationBoundary(shielded);
+    let html = marked.parse(fixed) as string;
+    html = html.replace(/<table/g, '<div class="table-wrapper"><table').replace(/<\/table>/g, '</table></div>');
+    html = unshieldMath(html, mathBlocks, isStreaming);
+    html = sanitizeHtml(html);
+    html = unshieldSvgBlocks(html, svgBlocks);
+
+    if (!isStreaming) {
+        schedulePostRender();
+    }
+    ensureRenderDelegations();
+
+    return html;
+}

package/public/js/render/math.ts

@@ -0,0 +1,76 @@
+// ── KaTeX math shield/unshield ──
+import katex from 'katex';
+import { escapeHtml } from './html.js';
+
+// ── KaTeX math shield/unshield ──
+// Shield: marked 전에 수식을 플레이스홀더로 치환 (marked가 $를 파괴하는 것 방지)
+// Unshield: marked 후에 플레이스홀더를 KaTeX 렌더링으로 복원
+
+export interface MathBlock { tex: string; displayMode: boolean; }
+
+export function shieldMath(text: string): { text: string; blocks: MathBlock[] } {
+    const blocks: MathBlock[] = [];
+    // 1. 코드 블록/인라인 코드 보존 (수식 추출 대상에서 제외)
+    const preserved: string[] = [];
+    let processed = text
+        .replace(/```[\s\S]*?```/g, (m) => {
+            preserved.push(m); return `\x00C${preserved.length - 1}\x00`;
+        })
+        .replace(/`[^`]+`/g, (m) => {
+            preserved.push(m); return `\x00C${preserved.length - 1}\x00`;
+        });
+
+    // 2. Block math: $$...$$ (먼저 — greedy 방지)
+    processed = processed.replace(/\$\$([\s\S]+?)\$\$/g, (_, tex: string) => {
+        blocks.push({ tex: tex.trim(), displayMode: true });
+        return `\x00MATH-${blocks.length - 1}\x00`;
+    });
+
+    // 3. GPT-style block math: \[...\]
+    processed = processed.replace(/\\\[([\s\S]+?)\\\]/g, (_, tex: string) => {
+        blocks.push({ tex: tex.trim(), displayMode: true });
+        return `\x00MATH-${blocks.length - 1}\x00`;
+    });
+
+    // 4. Inline math: $...$ (통화 $10 제외)
+    processed = processed.replace(/(?<!\$)\$(?!\$)([^\n$]+?)\$(?!\$)/g, (_, tex: string) => {
+        blocks.push({ tex: tex.trim(), displayMode: false });
+        return `\x00MATH-${blocks.length - 1}\x00`;
+    });
+
+    // 5. GPT-style inline math: \(...\)
+    processed = processed.replace(/\\\((.+?)\\\)/g, (_, tex: string) => {
+        blocks.push({ tex: tex.trim(), displayMode: false });
+        return `\x00MATH-${blocks.length - 1}\x00`;
+    });
+
+    // 4. 코드 블록 복원
+    processed = processed.replace(/\x00C(\d+)\x00/g, (_, i) => preserved[Number(i)]);
+
+    return { text: processed, blocks };
+}
+
+export function unshieldMath(html: string, blocks: MathBlock[], isStreaming = false): string {
+    return html.replace(/\x00MATH-(\d+)\x00/g, (_, i) => {
+        const block = blocks[Number(i)];
+        if (!block) return `<code title="math placeholder error">[math error]</code>`;
+
+        // During streaming: lightweight placeholder, defer KaTeX to finalize
+        if (isStreaming) {
+            return block.displayMode
+                ? `<div class="math-placeholder">${escapeHtml(block.tex)}</div>`
+                : `<code class="math-placeholder">${escapeHtml(block.tex)}</code>`;
+        }
+
+        try {
+            return katex.renderToString(block.tex, {
+                displayMode: block.displayMode,
+                throwOnError: false,
+            });
+        } catch {
+            return block.displayMode
+                ? `<pre><code>${escapeHtml(block.tex)}</code></pre>`
+                : `<code>${escapeHtml(block.tex)}</code>`;
+        }
+    });
+}

package/public/js/render/mermaid-preprocess.ts

@@ -0,0 +1,77 @@
+// Mermaid code preprocessor — pure string functions, no DOM dependencies.
+// Handles common AI-generated syntax that breaks mermaid.render().
+
+/** Layer 1: always-on static cleanup before every render attempt. */
+export function preprocessMermaid(code: string): string {
+    let result = code.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    result = result.replace(/;\s*$/gm, '');
+    if (/^\s*(flowchart|graph)\b/m.test(result)) {
+        result = normalizeFlowchartNodeIds(result);
+    }
+    return result;
+}
+
+const RESERVED_NODE_IDS = new Set(['end', 'default', 'class', 'style']);
+
+function normalizeNodeId(id: string): string {
+    let next = id.replace(/[/.:-]+/g, '_');
+    if (RESERVED_NODE_IDS.has(next.toLowerCase())) next = `node_${next}`;
+    return next;
+}
+
+function normalizeFlowchartNodeIds(code: string): string {
+    return code.replace(
+        /(^|[\s;])([A-Za-z_][\w/.:-]*)(?=\s*(?:\[|\(|\{|>))/gm,
+        (match, prefix: string, id: string) => {
+            const next = normalizeNodeId(id);
+            return next === id ? match : `${prefix}${next}`;
+        },
+    );
+}
+
+/**
+ * Layer 2: retry-phase aggressive fix — quote all unquoted flowchart/graph
+ * node labels so shape-delimiter characters ([[, ((, {{, etc.) inside text
+ * are treated as literal content instead of Mermaid shape syntax.
+ *
+ * Returns transformed code, or null if the diagram type is not flowchart/graph
+ * (other diagram types don't use bracket-based shape syntax).
+ */
+export function sanitizeMermaidForRetry(code: string): string | null {
+    if (!/^\s*(flowchart|graph)\b/m.test(code)) return null;
+
+    const lines = code.split('\n');
+    const out: string[] = [];
+
+    for (const line of lines) {
+        let result = '';
+        let i = 0;
+
+        while (i < line.length) {
+            const rest = line.slice(i);
+            const nodeMatch = rest.match(/^([A-Za-z_]\w*)\[(?!")/);
+            if (nodeMatch) {
+                const nodeId = nodeMatch[1];
+                result += nodeId + '["';
+                i += nodeMatch[0].length;
+
+                let depth = 1;
+                let label = '';
+                while (i < line.length && depth > 0) {
+                    const ch = line[i];
+                    if (ch === '[') depth++;
+                    else if (ch === ']') depth--;
+                    if (depth > 0) label += ch;
+                    i++;
+                }
+                label = label.replace(/"/g, '#quot;');
+                result += label + '"]';
+            } else {
+                result += line[i];
+                i++;
+            }
+        }
+        out.push(result);
+    }
+    return out.join('\n');
+}

package/public/js/render/mermaid.ts

@@ -0,0 +1,267 @@
+// ── Mermaid deferred rendering ──
+import { t } from '../features/i18n.js';
+import { ICONS } from '../icons.js';
+import { escapeHtml } from './html.js';
+import { preprocessMermaid, sanitizeMermaidForRetry } from './mermaid-preprocess.js';
+import { sanitizeMermaidSvg } from './sanitize.js';
+import { appendMermaidActionBtns, bindDiagramZoom } from './svg-actions.js';
+
+interface MermaidApi {
+    initialize(config: Record<string, unknown>): void;
+    render(id: string, code: string): Promise<{ svg: string }>;
+}
+
+// Lazy mermaid: loaded on first diagram encounter
+let mermaidModule: MermaidApi | null = null;
+
+// Serialise all Mermaid render calls — concurrent renders corrupt shared internal state.
+let mermaidQueue: Promise<void> = Promise.resolve();
+
+function getMermaidThemeVars() {
+    const isLight = document.documentElement.getAttribute('data-theme') === 'light';
+    return isLight ? {
+        primaryColor: '#e2e8f0',
+        primaryTextColor: '#1a202c',
+        primaryBorderColor: '#a0aec0',
+        lineColor: '#718096',
+        secondaryColor: '#ebf8ff',
+        tertiaryColor: '#f7fafc',
+        background: 'transparent',
+        mainBkg: '#e2e8f0',
+        nodeBorder: '#a0aec0',
+        clusterBkg: '#f7fafc',
+        clusterBorder: '#cbd5e0',
+        titleColor: '#1a202c',
+        edgeLabelBackground: '#f7fafc',
+    } : {
+        primaryColor: '#2d3748',
+        primaryTextColor: '#e2e8f0',
+        primaryBorderColor: '#4a5568',
+        lineColor: '#718096',
+        secondaryColor: '#1a365d',
+        tertiaryColor: '#1a202c',
+        background: 'transparent',
+        mainBkg: '#2d3748',
+        nodeBorder: '#4a5568',
+        clusterBkg: '#1a202c',
+        clusterBorder: '#2d3748',
+        titleColor: '#e2e8f0',
+        edgeLabelBackground: '#1a202c',
+    };
+}
+
+async function ensureMermaidLoaded() {
+    if (!mermaidModule) {
+        const loader = await import('../mermaid-loader.js');
+        mermaidModule = loader.loadMermaid();
+    }
+    return mermaidModule;
+}
+
+// Re-apply theme config immediately before every render() call.
+// Mermaid's internal config can drift after parse()/render() due to
+// directive resets — never cache, always re-initialise.
+function applyMermaidTheme() {
+    mermaidModule!.initialize({
+        startOnLoad: false,
+        theme: 'base',
+        htmlLabels: false,
+        themeVariables: getMermaidThemeVars(),
+        securityLevel: 'strict',
+        suppressErrorRendering: true,
+    });
+}
+
+// ── Mermaid deferred rendering (lazy-loaded) ──
+let mermaidId = 0;
+
+/** Re-render all existing Mermaid diagrams (call on theme toggle). */
+export async function rerenderMermaidDiagrams(): Promise<void> {
+    const rendered = document.querySelectorAll('.mermaid-rendered');
+    if (!rendered.length) return;
+    mermaidQueue = mermaidQueue.then(async () => {
+        const mm = await ensureMermaidLoaded();
+        for (const el of rendered) {
+            const htmlEl = el as HTMLElement;
+            const rawCode = htmlEl.dataset['mermaidCode'];
+            if (!rawCode || !htmlEl.isConnected) continue;
+            const code = preprocessMermaid(rawCode);
+            const id = `mermaid-${++mermaidId}`;
+            try {
+                applyMermaidTheme();
+                let svg: string;
+                try {
+                    ({ svg } = await mm.render(id, code));
+                } catch {
+                    const retryCode = sanitizeMermaidForRetry(code);
+                    if (!retryCode) continue;
+                    applyMermaidTheme();
+                    ({ svg } = await mm.render(`${id}-retry`, retryCode));
+                }
+                if (!htmlEl.isConnected) continue;
+                htmlEl.innerHTML = sanitizeMermaidSvg(svg);
+                appendMermaidActionBtns(htmlEl);
+                bindDiagramZoom(htmlEl);
+            } catch { /* keep existing render on failure */ }
+        }
+    }).catch(err => {
+        console.error('[mermaid:queue] rerender failed, keeping queue alive:', err);
+    });
+    await mermaidQueue;
+}
+
+// Lazy Mermaid rendering — only render blocks near the viewport
+let mermaidObserver: IntersectionObserver | null = null;
+
+function ensureMermaidObserver(): void {
+    if (mermaidObserver) return;
+    mermaidObserver = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (!entry.isIntersecting) continue;
+            const el = entry.target as HTMLElement;
+            if (!el.classList.contains('mermaid-pending')) continue;
+            mermaidObserver!.unobserve(el);
+            renderSingleMermaid(el);
+        }
+    }, { rootMargin: '200px' }); // pre-render 200px before visible
+}
+
+function renderMermaidError(el: HTMLElement, code: string, errMsg: string): void {
+    el.classList.remove('mermaid-rendered');
+    el.innerHTML = `
+        <div class="mermaid-error">
+            <div class="mermaid-error-title">${ICONS.warning} ${escapeHtml(t('mermaid.renderFail') || 'Mermaid render failed')}</div>
+            <div class="mermaid-error-msg">${escapeHtml(errMsg.slice(0, 200))}</div>
+            <pre class="mermaid-error-code"><code>${escapeHtml(code)}</code></pre>
+        </div>`;
+}
+
+async function renderSingleMermaidImpl(el: HTMLElement): Promise<void> {
+    if (!el.isConnected) {
+        delete el.dataset['mermaidQueued'];
+        delete el.dataset['mermaidInflight'];
+        return;
+    }
+    el.classList.remove('mermaid-pending');
+    // Phase 127-F1: raw source lives in data attribute (skeleton DOM has no source text).
+    const encoded = el.dataset['mermaidCodeRaw'] || '';
+    const rawCode = encoded ? decodeURIComponent(encoded) : (el.textContent || '');
+    const code = preprocessMermaid(rawCode);
+    el.dataset['mermaidCode'] = code;
+    const id = `mermaid-${++mermaidId}`;
+    el.dataset['mermaidInflight'] = '1';
+    try {
+        const mm = await ensureMermaidLoaded();
+        applyMermaidTheme();
+        let svg: string;
+        try {
+            ({ svg } = await mm.render(id, code));
+        } catch (firstErr: unknown) {
+            const retryCode = sanitizeMermaidForRetry(code);
+            if (!retryCode) throw firstErr;
+            applyMermaidTheme();
+            ({ svg } = await mm.render(`${id}-retry`, retryCode));
+        }
+        if (!el.isConnected) {
+            return;
+        }
+        el.innerHTML = sanitizeMermaidSvg(svg);
+        el.classList.add('mermaid-rendered');
+        delete el.dataset['mermaidCodeRaw'];
+        appendMermaidActionBtns(el);
+        bindDiagramZoom(el);
+    } catch (err: unknown) {
+        const errMsg = (err as { message?: string; str?: string })?.message
+            || (err as { str?: string })?.str || 'Unknown error';
+        renderMermaidError(el, code, errMsg);
+    } finally {
+        delete el.dataset['mermaidQueued'];
+        delete el.dataset['mermaidInflight'];
+    }
+}
+
+// Serialise renders to prevent concurrent Mermaid operations from
+// corrupting shared internal state (theme config, diagram registry).
+function renderSingleMermaid(el: HTMLElement): void {
+    // Phase 127-N2: synchronous queued guard prevents duplicate enqueueing when
+    // renderMermaidBlocks immediate mode fires repeatedly (e.g. VS onPostRender
+    // on every scroll). Class/dataset is set right away so the next pass skips.
+    if (el.dataset['mermaidQueued'] === '1') return;
+    el.dataset['mermaidQueued'] = '1';
+    // Phase 127-F6: .catch tail keeps the queue alive after any rejection so
+    // one bad render cannot permanently block subsequent diagrams.
+    mermaidQueue = mermaidQueue
+        .then(() => renderSingleMermaidImpl(el))
+        .catch(err => {
+            console.error('[mermaid:queue] render failed, keeping queue alive:', err);
+        });
+}
+
+/**
+ * Phase 127-F5: exposed so streaming finalize / virtual-scroll hooks can push
+ * new mermaid blocks through the pipeline without waiting for schedulePostRender.
+ *
+ * @param scope DOM subtree to scan (defaults to whole document)
+ * @param opts.immediate if true, render blocks already in (or near) viewport
+ *                       right now instead of waiting for the observer.
+ */
+export async function renderMermaidBlocks(
+    scope?: HTMLElement | Document,
+    opts: { immediate?: boolean } = {},
+): Promise<void> {
+    const root = scope || document;
+    const pending = root.querySelectorAll<HTMLElement>('.mermaid-pending');
+    if (!pending.length) return;
+    ensureMermaidObserver();
+    for (const el of pending) {
+        if (el.dataset['mermaidQueued'] === '1') continue;   // N2 guard
+        if (opts.immediate) {
+            const rect = el.getBoundingClientRect();
+            const vh = window.innerHeight || document.documentElement.clientHeight;
+            const inView = rect.bottom >= -200 && rect.top <= vh + 200;
+            if (inView) {
+                mermaidObserver!.unobserve(el);
+                renderSingleMermaid(el);
+                continue;
+            }
+        }
+        mermaidObserver!.observe(el);
+    }
+}
+
+export function releaseMermaidNodes(scope: HTMLElement): void {
+    if (!mermaidObserver) return;
+    const selector = [
+        '.mermaid-pending',
+        '[data-mermaid-queued="1"]',
+        '[data-mermaid-inflight="1"]',
+    ].join(',');
+    const nodes: HTMLElement[] = [];
+    if (scope.matches(selector)) nodes.push(scope);
+    scope.querySelectorAll<HTMLElement>(selector).forEach((el) => nodes.push(el));
+    for (const el of nodes) {
+        mermaidObserver.unobserve(el);
+        delete el.dataset['mermaidQueued'];
+        delete el.dataset['mermaidQueuedAt'];
+        delete el.dataset['mermaidInflight'];
+        if (!el.classList.contains('mermaid-rendered')
+            && (el.dataset['mermaidCodeRaw'] || el.dataset['mermaidCode'])) {
+            el.classList.add('mermaid-pending');
+        }
+    }
+}
+
+/**
+ * Phase 127-F2: prewarm Mermaid module at idle time so the first diagram's
+ * cold-start does not block rendering. Safe to call multiple times.
+ */
+export function prewarmMermaid(): void {
+    if (mermaidModule) return;
+    const run = () => { void ensureMermaidLoaded().catch(() => { /* silent */ }); };
+    if (typeof (window as unknown as { requestIdleCallback?: unknown }).requestIdleCallback === 'function') {
+        (window as unknown as { requestIdleCallback: (cb: () => void, opts?: { timeout?: number }) => void })
+            .requestIdleCallback(run, { timeout: 2000 });
+    } else {
+        setTimeout(run, 500);
+    }
+}

package/public/js/render/post-render.ts

@@ -0,0 +1,35 @@
+// ── Batched post-render scheduler ──
+import { renderMermaidBlocks } from './mermaid.js';
+import { rehighlightAll } from './highlight.js';
+import { bindDiagramZoom } from './svg-actions.js';
+import { linkifyFilePaths } from './file-links.js';
+
+let postRenderRAF: number | null = null;
+let postRenderTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function schedulePostRender(): void {
+    if (postRenderTimer) clearTimeout(postRenderTimer);
+    if (postRenderRAF) { cancelAnimationFrame(postRenderRAF); postRenderRAF = null; }
+    postRenderTimer = setTimeout(() => {
+        postRenderTimer = null;
+        postRenderRAF = requestAnimationFrame(() => {
+            postRenderRAF = null;
+            renderMermaidBlocks();
+            rehighlightAll();
+            bindDiagramZoom();
+            const msgContainer = document.getElementById('chatMessages');
+            if (msgContainer) linkifyFilePaths(msgContainer);
+        });
+    }, 100);
+}
+
+export function cancelPostRender(): void {
+    if (postRenderTimer) {
+        clearTimeout(postRenderTimer);
+        postRenderTimer = null;
+    }
+    if (postRenderRAF) {
+        cancelAnimationFrame(postRenderRAF);
+        postRenderRAF = null;
+    }
+}