AGENTS.md@packages/client/src/lib/preview git:20261018.81bcf4eA

Immutable. This exact content never changes and is served at /api/v1/blob/8acbf9dfbb23c37b.

# DOX — packages/client/src/lib/preview

Files in this directory. One row per source file. See change: fold-oversized-agents-directories.

| File | Purpose |
|------|---------|
| `adoc-diagram-splitter.ts` | Pure segment splitter over AsciiDoc rendered HTML (design D2): splits into raw HTML and typed diagram segments (`data-lang="mermaid"|"plantuml"`, `class="language-*"`, `@startuml` sentinel). See change: diagram-rendering. |
| `adoc-math.ts` | Pure `renderAdocMath(html, katex)`: asciidoctor latexmath `\(…\)` inline / `\[…\]` display → KaTeX (`trust:false`, `throwOnError:false`). DOM-aware: parses the sanitized HTML into a `<template>`, rewrites ONLY text nodes outside `pre`/`code`, inserts KaTeX as parsed nodes (attributes + code stay literal; a pair split across inline tags stays literal); returns input unchanged when no math. Needs a DOM (jsdom test project). See change: sanitize-untrusted-rendered-content. `hasAdocMath(html)` delimiter probe. katex injected → caller lazy-loads. |
| `extract-urls.ts` | Pure `extractRecentUrls(messages: ChatMessage[]): string[]`. → see `extract-urls.ts.AGENTS.md` |
| `file-icon.ts` | `fileIcon(pathOrName)` → `{ iconPath, colorClass }`. Extension-keyed `@mdi/js` glyph + accent color for… → see `file-icon.ts.AGENTS.md` |
| `markdown-remark-plugins.ts` | Exports `MARKDOWN_REMARK_PLUGINS` (gfm, math, frontmatter): one shared list so `MarkdownContent` and the apply-fix locator parse with the same grammar. See change: add-preview-apply-fix-to-file. |
| `markup-repair-md.ts` | `repairMarkdown(src)` → `{source, repairs[{rule M2\|M3, line}]}`. Runs on `unified().use(remarkParse).use(MARKDOWN_REMARK_PLUGINS)`; candidates = top-level fenced `code` nodes no later line closes. M2 replaces first look-alike closer (other char / shorter); M3 inserts closer before blank line preceding first ATX heading. Frontmatter/blockquote/list fences never touched. Idempotent; per-line terminators; original line numbers. File previews only (`MarkdownContent staticSource`). See change: add-md-adoc-markup-repair. |
| `math-engine.ts` | Lazy math engine. `loadMathEngine()` memoized one-per-page promise importing `katex` + `rehype-katex` + `katex/dist/katex.min.css` (single `katex` manual chunk); `useMathEngine(needed)` via `useSyncExternalStore` → engine or `null` (until loaded / forever after failed load, logged once). Shared by `MarkdownContent` + `AsciiDocPreview`. See change: shrink-client-entry-lazy-islands. |
| `mdi-icon-lookup.ts` | Extension UI System icon resolver. Exports `resolveMdiIcon(key)` — maps `"mdiCheckCircle"`-style key to… → see `mdi-icon-lookup.ts.AGENTS.md` Now a re-export shim over client-utils `mdi-by-key`: `resolveMdiIcon` = sync `resolveMdiIconSync` (`null` until the lazy set loads), plus `useMdiIconByKey`, `loadMdiIconSet`. Render sites use the hook. See change: harden-ios-safari-memory-and-ws-diagnostics. |
| `mermaid-block-locator.ts` | Pure locate/verify/splice of the Nth mermaid block of a raw file. `locateMermaidBlock(file,kind md|adoc|mmd,ordinal,{expectedCount?})` → `{ok,value,count,replace}`|`{ok:false,reason not-found|not-applicable}`; `verifyMermaidBlock(located,displayed)`; `spliceMermaidBlock`. md re-parses with `MARKDOWN_REMARK_PLUGINS`; adoc scans `[source,mermaid]` + `----`/`....` with count-parity guard; mmd = whole file. Touches only lines between fence/delimiter; keeps indent, EOL, BOM, final newline; rejects blockquote/list-marker fence, unclosed fence, fix that would close the block. Lazy-imported on apply click. See change: add-preview-apply-fix-to-file. |
| `mermaid-repair-config.ts` | Module-level store mirroring the resolved `mermaidRepair` block of `GET /api/config`. Exports `setMermaidRepairClientConfig`, `hydrateMermaidRepairConfig(response)` (called by `App.tsx` hydration), `getMermaidRepairClientConfig`, `useMermaidRepairClientConfig` (`useSyncExternalStore`). Default/unusable → `{enabled:false}`; enabled requires a model. See change: add-mermaid-ai-repair. |
| `mermaid-repair.ts` | Pure rule-based mermaid repair. Exports `repairMermaid(code) → {code, applied: RuleId[]}`, `RuleId` (`R1`…`R7`, no R8), `RepairResult`. Order R1 R2 R3 R6 R4 R5 R7, repeated to fixpoint (≤5 passes) → idempotent. R1 strip U+200B–200D/2060/FEFF + leading `mermaid` line; R2 seq keyword alias → `p_<alias>[_n]` collision-free, bare keyword lines untouched; R3 balance alt/loop/opt/par/critical/rect/break/box; R6 ER type `Mod$T`→`T`; R4 quote `|label|` attached to edge op; R5 quote special-char node labels (compound shapes first, label ≤500 chars); R7 `;`→`,` `#`→`no.` in quoted labels, keeps `#name;`. Kind skips frontmatter + `%%`; `flowchart-*`=flowchart. R4/R5 match on quote-masked line (`d` flag indices). Tests: `__tests__/mermaid-repair.test.ts` (+`.fixtures.ts`, `.parse.test.ts` real mermaid parse). See change: add-mermaid-auto-repair. |
| `mermaid-source-context.ts` | `MermaidSourceInfo` `{cwd,path,kind,reload,isDirty?,expectedCount?}` + `MermaidSourceContext` / `useMermaidSourceContext`. Null in chat → no apply-fix. See change: add-preview-apply-fix-to-file. `markupRepairActive?` (set by the document renderer while a markup repair is unapplied) disables per-diagram apply. See change: add-md-adoc-markup-repair. |
| `preview-dispatch.ts` | Pure `dispatchPreview(target: ViewTarget): RendererKind`. → see `preview-dispatch.ts.AGENTS.md` |
| `remark-mermaid-ordinal.ts` | `collectMermaidCodeNodes(tree)` (single definition of a file's mermaid blocks: fenced `code`, `lang==="mermaid"`, doc order), `remarkMermaidOrdinal` (stamps `dataMermaidOrdinal=<nonce>:<n>`), `parseOrdinalStamp`, `ORDINAL_STAMP_PATTERN` (sanitizer allowlist). Nonce is per page load so raw HTML cannot forge an ordinal. See change: add-preview-apply-fix-to-file. |
| `use-mermaid-source.tsx` | `LiveSessionCwdsProvider{cwdKey}` + `liveCwdKey(cwds)` + `useIsLiveSessionCwd` + `useMermaidSource({cwd,path,kind,reload,isDirty?,expectedCount?})` → memoized `MermaidSourceInfo` or null when cwd is not a live session cwd (md-read/write 403 otherwise). Provider mounted in `App.tsx`. See change: add-preview-apply-fix-to-file. |
| `wrap-ascii-tables.ts` | Pre-processes markdown to wrap raw ASCII/box-drawing table blocks in fenced code blocks so they render… → see `wrap-ascii-tables.ts.AGENTS.md` |