llm-message-react 0.1.2 → 0.3.0

package/README.md

@@ -14,8 +14,6 @@ A single React component that renders LLM markdown output the way a polished cha
 npm install llm-message-react
 ```
 
-`react` and `react-dom` (>=18) are peer dependencies.
-
 ## Usage
 
 ```tsx
@@ -114,6 +112,38 @@ Notes:
 
 `LLMMessage` repairs partially-streamed markdown/LaTeX by default, so unterminated tokens (`**bold`, `` `code ``, `[label](http`, `$E = mc^2`, `\[ ... `) don't flash as raw delimiters while a response streams in. Disable it with `completePartialTokens={false}`.
 
+### Turn repair off once streaming is done
+
+The repair only helps _while_ text is still arriving. On a finished message it can do harm: a single trailing `$` (or a stray `\`) that is really part of the content gets read as the start of an unterminated math token and "completed", so a final string like `Pay $12\at the door` is mistaken for LaTeX and mangled.
+
+If you know when a message has finished streaming, gate `completePartialTokens` on that. Keep it `true` while streaming, then flip it to `false` once the stream closes so the final, complete text is rendered verbatim:
+
+```tsx
+import { useEffect, useState } from "react";
+import { LLMMessage } from "llm-message-react";
+import "llm-message-react/styles.css";
+
+export function StreamedMessage({ messageId }: { messageId: string }) {
+  const [content, setContent] = useState("");
+  const [isStreaming, setIsStreaming] = useState(true);
+
+  useEffect(() => {
+    const stream = subscribeToMessage(messageId, {
+      onToken: (token) => setContent((prev) => prev + token),
+      onDone: () => setIsStreaming(false), // stream finished
+    });
+    return () => stream.close();
+  }, [messageId]);
+
+  // Repair partial tokens while streaming, render verbatim once done.
+  return (
+    <LLMMessage completePartialTokens={isStreaming}>{content}</LLMMessage>
+  );
+}
+```
+
+This way half-streamed tokens are still repaired mid-stream, but the completed message is never "fixed" into something it isn't.
+
 ### Unfinished block math
 
 By default, unterminated **block** math (`\[ ... `, `$$ ... `) is rendered _progressively_: the open environments/braces are closed and the largest prefix KaTeX accepts is shown, so a long aligned block reveals itself row by row instead of popping in only once the closing delimiter arrives.
@@ -124,15 +154,32 @@ This convenience has a cost: it runs a synchronous KaTeX parse on every streamed
 <LLMMessage showUnfinishedLatexBlocks={false}>{content}</LLMMessage>
 ```
 
-The repair function is also exported if you need it directly, alongside the LaTeX preprocessing helpers:
+### Smooth reveal
 
-```ts
-import {
-  completePartialTokens,
-  preprocessLaTeX,
-  escapeBrackets,
-  escapeMhchem,
-} from "llm-message-react";
+By default new text pops in as each chunk arrives. Set `smoothReveal` to fade it in instead — character by character for prose, and as a single unit for complex blocks (code, tables, images, rules). Box decorations (a blockquote's border, list bullets, an inline-code background) fade in together with the content they belong to. Block math (`$$ … $$`, `\[ … \]`) is the one exception: KaTeX only produces output once the whole formula has streamed in, so a fade would just be a flash — instead the block appears instantly the moment the wave reaches it:
+
+```tsx
+<LLMMessage smoothReveal>{content}</LLMMessage>
+```
+
+The reveal is purely visual: text is always in the DOM the moment it streams in, it just eases up from transparent as a single travelling wave. The wave is sized so it sweeps through the not-yet-revealed text within a short window (`smoothRevealDuration`, default `300` ms). When a new chunk arrives while the previous one is still fading, the leftover (not-yet-revealed) characters and the new ones reveal together over one fresh window, so the animation stays a single coherent wave that keeps pace with the stream instead of many overlapping fades.
+
+```tsx
+<LLMMessage smoothReveal smoothRevealDuration={200}>
+  {content}
+</LLMMessage>
+```
+
+Opacity is computed purely from each character's position relative to the reveal point, so it only ever increases (no flicker) regardless of how the stream re-renders, and it is disabled automatically for users who prefer reduced motion.
+
+### Block memoization
+
+While a long message streams in, each new chunk would otherwise re-parse and re-render the entire message — re-running KaTeX and code highlighting over text that has not changed. By default `LLMMessage` splits the message into top-level markdown blocks (paragraphs, headings, code fences, math blocks, lists, tables, …) and memoizes each one, so only the last (currently growing) block re-renders on each chunk. Earlier blocks stay mounted and untouched, which keeps streaming smooth regardless of message length.
+
+This is on by default and needs no configuration. The one trade-off is that constructs which resolve across blocks — footnotes and link reference definitions — cannot be split (a definition in one block could not be seen by a reference in another). Those are detected automatically and kept in a single block, but if you render content that relies on them and want to be certain, disable splitting:
+
+```tsx
+<LLMMessage blockMemoization={false}>{content}</LLMMessage>
 ```
 
 ## Theming
@@ -209,6 +256,9 @@ import { MyCheckbox, MyCodeBlock, MyLink } from "./ui";
 - `highlighter?: CodeHighlighter` — opt-in syntax highlighter for fenced code blocks (see [Syntax highlighting](#syntax-highlighting)). Omitted by default, so no highlighter bundle is pulled in.
 - `completePartialTokens?: boolean` — repair partially-streamed markdown/LaTeX. Defaults to `true`.
 - `showUnfinishedLatexBlocks?: boolean` — progressively render unterminated block math while it streams (costs a synchronous KaTeX parse per chunk); set to `false` to hide unfinished blocks until they close and skip that work. Defaults to `true`. Only relevant while `completePartialTokens` is enabled.
+- `smoothReveal?: boolean` — fade newly-streamed text in (per character for prose, whole-unit for code/tables/images; block math snaps in instantly since it can't fade progressively) instead of popping it in. Purely visual and respects `prefers-reduced-motion`. Defaults to `false`.
+- `smoothRevealDuration?: number` — reveal window in milliseconds for each freshly-arrived chunk. Defaults to `300`. Only relevant while `smoothReveal` is enabled.
+- `blockMemoization?: boolean` — split the message into top-level blocks and memoize each so a streaming chunk only re-renders the last block (see [Block memoization](#block-memoization)). Defaults to `true`.
 - All other `div` props are spread onto the root element.
 
 > Pass stable references for `classNames`, `components`, and `highlighter` (define them outside render or memoize them). They are dependencies of an internal `useMemo`, so new object/identity on every render defeats it.

package/dist/highlighters/shiki.d.cts

@@ -1,4 +1,4 @@
-import { C as CodeHighlighter } from '../types-Dz7GupgB.cjs';
+import { C as CodeHighlighter } from '../types-DETvxTAd.cjs';
 import 'react';
 
 /**

package/dist/highlighters/shiki.d.ts

@@ -1,4 +1,4 @@
-import { C as CodeHighlighter } from '../types-Dz7GupgB.js';
+import { C as CodeHighlighter } from '../types-DETvxTAd.js';
 import 'react';
 
 /**

package/dist/highlighters/shikiWeb.d.cts

@@ -1,4 +1,4 @@
-import { C as CodeHighlighter } from '../types-Dz7GupgB.cjs';
+import { C as CodeHighlighter } from '../types-DETvxTAd.cjs';
 import 'react';
 
 /**

package/dist/highlighters/shikiWeb.d.ts

@@ -1,4 +1,4 @@
-import { C as CodeHighlighter } from '../types-Dz7GupgB.js';
+import { C as CodeHighlighter } from '../types-DETvxTAd.js';
 import 'react';
 
 /**