kandev/docs/plans/markdown-math/task-01-render-math.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-render-math	Render math across shared Markdown	done	1		plan.md	REQ-UI-MARKDOWN-MATH-001 REQ-UI-MARKDOWN-MATH-002	AC-UI-MARKDOWN-MATH-001.1 AC-UI-MARKDOWN-MATH-001.2 AC-UI-MARKDOWN-MATH-001.3 AC-UI-MARKDOWN-MATH-001.4 AC-UI-MARKDOWN-MATH-001.5 AC-UI-MARKDOWN-MATH-001.6 AC-UI-MARKDOWN-MATH-002.1 AC-UI-MARKDOWN-MATH-002.2 AC-UI-MARKDOWN-MATH-002.3 AC-UI-MARKDOWN-MATH-002.4 AC-UI-MARKDOWN-MATH-002.5	../../specs/ui/system-design/markdown-math.md

Task 01: Render Math Across Shared Markdown

Summary

Integrate KaTeX throughout the shared Markdown pipeline. Preserve ordinary text, sanitizer safety, source positions, and phone readability.

In scope

• Install the requested packages through pnpm and update the workspace lockfile.
• Add stylesheet assets, shared plugins, and narrowly scoped syntax compatibility where required.
• Wire every shared-plugin consumer listed in the system design.
• Preserve preview sanitization and comment task-link behavior.
• Add meaningful unit, component, desktop, and phone coverage through TDD.
• Add the public syntax reference and record validation results.

Out of scope

• Editor extensions, specialized Markdown pipelines, backend changes, and new settings.
• Unrelated renderer refactoring or broader sanitizer changes.

Acceptance

• All mapped formula and compatibility criteria pass with the real rendering pipelines.
• Desktop and phone render readable formulas without page overflow or executable untrusted content.
• Required checks pass, documentation matches the implementation, and durable statuses reflect the results.

ASCII UI preview

UI-01: Formula reading, desktop and phone

Energy: E = mc^2

         a
        ---
         b

Cost: $100 and $200

See the full preview. Inline math stays in prose. Display math occupies its own region. Phone overflow stays local to that region. The existing view owns vertical scrolling. Spacing is illustrative. Applies to AC-UI-MARKDOWN-MATH-001.1 through 001.6 and 002.1.

Verification

Run from the repository root unless the command changes directories. If dependencies are absent, install them before running pnpm checks.

cd apps && pnpm install --frozen-lockfile

Install feature dependencies during the implementation phase:

cd apps/web && pnpm add remark-math rehype-katex katex
cd apps/web && pnpm add -D @types/katex

Run each command from a fresh repository-root shell:

cd apps/web && pnpm vitest run components/shared/markdown-components.test.tsx
cd apps/web && pnpm vitest run components/shared/markdown-math-renderers.test.tsx components/shared/memoized-markdown.test.tsx components/shared/chat-markdown-motion.test.tsx components/task/markdown-preview-content.test.ts components/task/markdown-preview-content.external-link.test.tsx
cd apps/web && pnpm run typecheck
cd apps/web && pnpm run lint
cd apps/web && pnpm e2e:run --project chromium e2e/tests/chat/markdown-math.spec.ts e2e/tests/chat/markdown-preview.spec.ts
cd apps/web && pnpm e2e:run --project mobile-chrome e2e/tests/chat/mobile-markdown-math.spec.ts
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
git diff --check

If compatibility code is required, also run its focused tests:

cd apps/web && pnpm vitest run lib/markdown/remark-math-compat.test.ts

Record the failing test before implementation, then the passing result. The E2E runner rebuilds production assets. Run suites sequentially with the configured worker budget. Inspect desktop and phone screenshots in both themes. Record any unavailable runtime dependency as a blocker. Do not claim browser validation from component snapshots alone.

Files likely touched

• apps/web/package.json, apps/pnpm-lock.yaml, apps/web/app/globals.css.
• apps/web/components/shared/markdown-components.tsx and its test file.
• The eleven consumers listed in the system design, including the four primary renderers.
• Proposed apps/web/lib/markdown/remark-math-compat.ts and its test file, if parser gaps require them.
• Proposed apps/web/lib/markdown/math-sanitize-schema.ts, if needed to share exact marker allowances.
• apps/web/lib/markdown/chat-text-motion-plugin.ts, only if motion integration tests require a subtree exclusion.
• apps/web/components/shared/{markdown-math-renderers,memoized-markdown,chat-markdown-motion}.test.tsx.
• apps/web/components/task/markdown-preview-content.test.ts and .external-link.test.tsx.
• apps/web/e2e/tests/chat/{markdown-math,mobile-markdown-math}.spec.ts.
• docs/public/sessions-and-review.md and this design package's statuses/results.

Dependencies

None. Implementation is authorized by the current user request.

Risks

See the plan risks. Preserve existing schema attributes when extending the class allowlist. Do not weaken the currency assertion to accept KaTeX output.

Parallelism

sequential

Inputs

• Requirements.
• System design.
• apps/web/AGENTS.md and apps/web/components/task/chat/AGENTS.md.
• Existing markdown-components.test.tsx, mobile-markdown-wrap.spec.ts, and markdown-preview.spec.ts patterns.
• Repository /tdd, /e2e, /mobile-parity, and /docs-maintainer skills.

Results

Implemented shared KaTeX Markdown rendering across the shared plugin consumers. Added parsed-node compatibility for currency literals and single-line display formulas, preserved sanitizer ordering and chat motion boundaries, bundled KaTeX fonts through the Vite entry, added local phone overflow styling, and documented the supported syntax.

TDD RED was recorded before plugin wiring. The final focused suite passed 10 files and 63 tests, including preview source/comment mapping, raw delimiter whitespace, and sanitizer marker regressions. Typecheck, lint, production build, Chromium coverage (11 tests across light and dark themes), mobile Chromium coverage (2 tests for chat and the native file preview viewer), specification validation, public docs validation, and whitespace checks all passed on 2026-09-22.