claude-code-katex: Instructions file for Claude Code

Claude Code LaTeX Extension

Architecture

This extension patches Claude Code's webview to render LaTeX math via KaTeX.

(Display name is "Claude Code LaTeX"; the extension ID and repo name are still claude-code-katex for marketplace continuity.)

The extension injects a math pipeline into Claude Code's own react-markdown plugin chain, so math is tokenized during Markdown parsing — verbatim — instead of being repaired in the DOM afterward.

• applyPatch (in extension.js) locates the shared react-markdown processor with injectMathPlugins in markdown-patch.js. Acorn proves that plugin lists come from the same props parameter, enter one unified .use() chain in the correct order, and that exact processor parses and runs the Markdown. Injecting into the two .use() arguments covers every renderer, including callers with no plugin props. Getter reads stay unchanged; plugin arrays are copied with concat, and the original arguments remain when bundle loading fails. Multiple proven processors are rejected rather than guessed. On upstream builds with native math, the uniquely identified mathRenderingEnabled getter is guarded so only one pipeline owns the source. The full original getter body remains unchanged and runs whenever __KATEX_V2_LOADED is absent/false. This matters because native math tokenizers retain original-source offsets while our normalization can add line breaks. An unknown or ambiguous native gate rejects the entire patch. A fallback for older or isolated call shapes retains the existing output. Vendored Acorn parses JavaScript structure, accepting direct plugin props and helper-props spreads regardless of minified names, whitespace, comments, or property order. Helper definitions are resolved within their lexical scope; reassigned or shadowed helpers cannot establish an injection point. It adds rehypePlugins:[rehypeKatex] and remarkPlugins:[gfm, remarkBracketMath, remarkMath]. The injected references are guarded on window.__KATEX_V2_LOADED so a bundle-load failure cannot break Claude Code's Markdown. The spread form evaluates the original helper once and preserves its plugins and URL transform, including the Windows file-link plugin. Multiple candidate fallback call sites are rejected as unsupported. Structural rejection reasons are logged so compatibility failures can be diagnosed without guesswork.
• The complete patched JavaScript must compile before any files change. All assets are read first, then backups, fonts, CSS, and JS are staged and replaced with per-file renames. Ordinary write failures roll back prior replacements; a process crash between renames is not an atomic transaction across files. Fresh upstream files replace stale backups. If only JS was replaced, the existing CSS backup must match before its old patch is replaced. Disable and uninstall never restore an old backup over an unpatched upstream file.
• It prepends, in order, vendor/katex.min.js, the optional KaTeX contrib vendor/copy-tex.min.js (copying a selection of rendered math yields its LaTeX source), and vendor/remark-math-bundle.js to the webview bundle (Claude Code mounts its React app at the end of the bundle, so the globals must be defined first). A missing contrib file degrades gracefully — core math still renders. The contrib has a small local adaptation: its cloned selection drops hidden source blocks, hidden rendered equations and source-toggle buttons before serialization. Otherwise a selection across display math copies its hidden source too, duplicating the equation. Keep this adaptation when updating vendor/copy-tex.min.js.
• If the injection point is not found — a future Claude Code reshaped its bundle — applyPatch returns false, touches nothing, and the extension shows an "update / report an issue" notice. There is no fallback renderer.
• Display-math HAST nodes are wrapped after rehype-katex renders them with a source toggle and the application/x-tex annotation exposed as selectable $$-wrapped code (issue #18). One delegated click handler covers streamed equations; inline math is not decorated.