agentscope-ai / agentscope-ai/QwenPaw

[Design Proposal] Render LaTeX math with KaTeX in the Console (#5453)

Aperta
#5,921 1 commento 0 reazioni 1 assegnatario Rivendicata da @zhaozhuang521 Vedi su GitHub
Lingua principale
Python
Stelle
34.9k
Fork
3.1k
Merge medio
1g 15h
PR unite (30g)
225

Descrizione

## Summary

Design proposal for **#5453** — render LaTeX math formulas in the QwenPaw Console using **KaTeX**. Opened to confirm the design before submitting a PR, per the contributing guide. Claim comment: [#5453 comment](https://github.com/agentscope-ai/QwenPaw/issues/5453#issuecomment-4932219523).

## Current state

- Markdown rendering uses `react-markdown@^10.1.0` + `remark-gfm@^4.0.1` (`console/package.json`).
- **No math/katex dependency exists** — `$...$` and `$$...$$` are currently rendered as literal text.
- Three render sites, all using ``:
- `console/src/layouts/Header.tsx` (update-notes modal)
- `console/src/pages/Inbox/index.tsx`
- `console/src/pages/Coding/FilePreview.tsx`
- Global stylesheets are imported in `console/src/App.tsx` (`./styles/layout.css`, `./styles/form-override.css`).

## Goal

Render both **inline** (`$...$`) and **block** (`$$...$$`) LaTeX as beautifully typeset math, with good performance (KaTeX is synchronous and fast) and zero new runtime dependencies beyond the two plugins + the `katex` CSS.

## Proposed design

1. **Dependencies** (versions chosen for react-markdown v10 compatibility — ESM-only ecosystem):
- `remark-math@^6` — parses `$...$` / `$$...$$` into math nodes.
- `rehype-katex@^7` — renders math nodes to KaTeX HTML.
- (`katex` comes transitively with `rehype-katex` and ships the stylesheet.)

2. **Wire plugins at the render sites**:
```tsx
import remarkMath from "remark-math";
import rehypeKatex from "rehype-katex";


```
Applied to all three sites so behavior is consistent (or, if preferred, centralized behind a shared `` component — see "Open question" below).

3. **Stylesheet**: import `"katex/dist/katex.min.css"` once globally in `App.tsx`, next to the existing CSS imports. No CDN, works fully offline (important for the desktop/Tauri build).

4. **Delimiters**: standard `$...$` (inline) and `$$...$$` (block) — the `remark-math` defaults. Escaping literal dollars via `\$`.

5. **Tests**: add cases asserting that an inline expression and a block expression render into elements with KaTeX's expected output (e.g. a `.katex` class), and that plain markdown is unchanged.

## Out of scope (intentionally)

- MathJax (heavier, async) — KaTeX is the conventional, lighter choice for chat UIs.
- Copy-to-clipboard / per-equation actions.
- Editor/autocomplete for formulas.
- Server-side rendering of math (channels send text; rendering stays client-side).

## Open question

The three render sites currently each construct their own `` config. Two options:

- **A (minimal):** add the plugins at each of the 3 sites directly. Smallest diff, lowest risk.
- **B (refactor):** extract a shared `Markdown` wrapper component so all sites share one config (easier to extend later, e.g. for link handling). Slightly larger diff and touches the existing custom `components` overrides.

I lean **A** for this PR (keeps it focused and low-risk) and can do **B** as a follow-up if maintainers prefer. Feedback welcome.

## Test plan

- Unit: inline `$E=mc^2$` and block `$$\int_0^1 x\,dx$$` render to KaTeX output; surrounding markdown (lists, code, links) unchanged.
- Manual: agent replies containing math render correctly in Chat, Inbox, and the Coding file preview; works in light and dark mode; selection/copy still works.
- No regression: messages without math render byte-for-byte the same as today.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.