Skip to content

Commit 0dc122a

Browse files
committed
docs(web): document chat math parsing and rendering
1 parent 389a916 commit 0dc122a

4 files changed

Lines changed: 17 additions & 0 deletions

File tree

‎apps/web/src/components/ChatMarkdown.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -516,9 +516,11 @@ const CHAT_MARKDOWN_REMARK_PLUGINS_WITH_BREAKS = [
516516
remarkNormalizeLinksAndTagInlineCode,
517517
] satisfies NonNullable<ReactMarkdownOptions["remarkPlugins"]>;
518518

519+
/** Parse raw HTML while reserving math rendering and copy metadata for parser-owned nodes. */
519520
function rehypeRawMath() {
520521
const parseRaw = rehypeRaw({ passThrough: ["chatMath"] });
521522
return (...[tree, file]: Parameters<typeof parseRaw>) => {
523+
/** Carry parsed math through HTML processing using a node type HTML cannot create. */
522524
const protect = (node: MarkdownImageHastNode) => {
523525
if (
524526
node.type === "element" &&
@@ -532,6 +534,7 @@ function rehypeRawMath() {
532534
};
533535
protect(tree);
534536
const parsed = parseRaw(tree, file);
537+
/** Restore parsed math and remove math metadata supplied by raw HTML. */
535538
const restore = (node: MarkdownImageHastNode) => {
536539
if (node.type === "chatMath") {
537540
node.type = "element";
@@ -3141,6 +3144,7 @@ const CHAT_MARKDOWN_COMPONENTS = {
31413144
normalizedHref,
31423145
);
31433146
},
3147+
/** Render parsed math, inline file links, or code with the appropriate copy behavior. */
31443148
code: function MarkdownCode({ node, children, className, ...props }) {
31453149
const { cwd, imageBaseDir, inlineCodeFileLinkMetaByText, fileLinkChip } = use(
31463150
ChatMarkdownRendererContext,

‎apps/web/src/components/chat/MarkdownMath.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import katex from "katex";
22
import { memo, useMemo } from "react";
33
import "katex/dist/katex.min.css";
44

5+
/** Typeset a formula while retaining authored TeX for copying and invalid-expression fallback. */
56
export default memo(function MarkdownMath({
67
math,
78
source,

‎apps/web/src/markdown-clipboard.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -378,6 +378,7 @@ function sanitizedHtmlFrom(container: Element): string {
378378
return `<meta charset="utf-8">${container.innerHTML}`;
379379
}
380380

381+
/** Serialize selected content as Markdown and HTML, preserving whole code blocks and math sources. */
381382
export function chatMarkdownClipboardPayload(
382383
selection: Selection,
383384
): MarkdownClipboardPayload | null {

‎apps/web/src/markdown-math.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ function latexMath(flow: boolean): Construct {
1515
return {
1616
name: flow ? "latexMathFlow" : "latexMathText",
1717
...(flow ? { concrete: true } : {}),
18+
/** Tokenize a TeX-delimited expression while preserving Markdown source positions. */
1819
tokenize(effects, ok, nok) {
1920
const math = flow ? "mathFlow" : "mathText";
2021
const fence = flow ? "mathFlowFence" : "mathTextSequence";
@@ -23,6 +24,7 @@ function latexMath(flow: boolean): Construct {
2324
let inValue = false;
2425
const closingDelimiter: Construct = {
2526
partial: true,
27+
/** Probe for the matching closing delimiter without consuming a failed match. */
2628
tokenize(checkEffects, yes, no) {
2729
return (code) => {
2830
checkEffects.enter("mathTextSequence");
@@ -39,13 +41,15 @@ function latexMath(flow: boolean): Construct {
3941

4042
return start;
4143

44+
/** Begin the math token at the opening backslash. */
4245
function start(code: number | null): State | undefined {
4346
effects.enter(math);
4447
effects.enter(fence);
4548
effects.consume(code);
4649
return opening;
4750
}
4851

52+
/** Select the matching delimiter, allowing only brackets in flow mode. */
4953
function opening(code: number | null): State | undefined {
5054
if (code !== 91 && (flow || code !== 40)) return nok(code);
5155
closing = code === 91 ? 93 : 41;
@@ -54,6 +58,7 @@ function latexMath(flow: boolean): Construct {
5458
return inside;
5559
}
5660

61+
/** Consume formula content until a matching delimiter or an incomplete ending. */
5762
function inside(code: number | null): State | undefined {
5863
if (code === null) return nok(code);
5964
if (markdownLineEnding(code)) {
@@ -73,6 +78,7 @@ function latexMath(flow: boolean): Construct {
7378
return inside;
7479
}
7580

81+
/** Keep escaped characters inside the formula instead of treating them as delimiters. */
7682
function escape(code: number | null): State | undefined {
7783
if (!inValue) effects.enter(value);
7884
inValue = true;
@@ -85,6 +91,7 @@ function latexMath(flow: boolean): Construct {
8591
};
8692
}
8793

94+
/** Finish the formula and check trailing content when parsing a display block. */
8895
function close(code: number | null): State | undefined {
8996
if (inValue) effects.exit(value);
9097
effects.enter(fence);
@@ -97,6 +104,7 @@ function latexMath(flow: boolean): Construct {
97104
};
98105
}
99106

107+
/** Accept a display block only when the rest of its line is whitespace. */
100108
function after(code: number | null): State | undefined {
101109
// A display formula with surrounding prose belongs to the paragraph.
102110
if (code === null || markdownLineEnding(code)) return ok(code);
@@ -107,6 +115,7 @@ function latexMath(flow: boolean): Construct {
107115
return nok(code);
108116
}
109117

118+
/** Consume trailing display-block whitespace before checking the line ending. */
110119
function trailingSpace(code: number | null): State | undefined {
111120
if (markdownSpace(code)) {
112121
effects.consume(code);
@@ -129,6 +138,7 @@ export const remarkChatMath: Plugin<[], Root> = function () {
129138
if (dollarSyntax && dollar && !Array.isArray(dollar)) {
130139
dollarSyntax[36] = {
131140
...dollar,
141+
/** Reject spaced single-dollar expressions so prices do not swallow later math. */
132142
tokenize(effects, ok, nok) {
133143
return dollar.tokenize.call(
134144
this,
@@ -156,6 +166,7 @@ export const remarkChatMath: Plugin<[], Root> = function () {
156166
if (!parse) return;
157167
this.parser = (source, file) => {
158168
const tree = parse(source, file) as Root;
169+
/** Attach rendering and copy metadata, removing container prefixes from copied formulas. */
159170
const visit = (node: Root | RootContent, inContainer = false) => {
160171
if (node.type === "math" || node.type === "inlineMath") {
161172
const start = node.position?.start.offset;

0 commit comments

Comments
 (0)